Initial Cocos farm project

This commit is contained in:
zhx 2026-06-19 17:26:43 +08:00
commit f8d9389c4f
7 changed files with 875 additions and 0 deletions

26
.gitignore vendored Normal file
View File

@ -0,0 +1,26 @@
#///////////////////////////
# Cocos Creator Project
#///////////////////////////
/library/
/temp/
/local/
/build/
/profiles/
/native/engine/android/**/*/assets
#//////////////////////////
# NPM
#//////////////////////////
node_modules/
#//////////////////////////
# VSCode
#//////////////////////////
.vscode/
#//////////////////////////
# WebStorm
#//////////////////////////
.idea/

5
.pink/settings.json Normal file
View File

@ -0,0 +1,5 @@
{
"cocos.engine.type": "official",
"cocos.engine.version": "4.0.0-alpha.22",
"cocos.engine.dirName": ""
}

434
AGENTS.md Normal file
View File

@ -0,0 +1,434 @@
# AGENTS.md
## Collaboration Rules
0. Do not blindly agree with the user. Challenge claims with evidence when they are wrong or incomplete.
1. Do not guess before doing work. Find the most direct source of truth and solve from there.
2. Every solved problem must be verified with concrete evidence.
3. Existing local changes are not a blocker. Continue working with them unless they make the task impossible.
4. API docs should be short and simple: address, parameters, response, and related IM behavior.
5. All Golang code changes must include dense, readable logic comments in normal sentence order.
## Goal
Rebuild the QQ Farm mini-game as a Cocos 4.0 project from the extracted original Cocos source package.
This project no longer follows the Godot reconstruction route and no longer targets Cocos Creator 3.8 as the primary toolchain. The target direction is Cocos 4.0 plus the Cocos 4.0 `cocos-cli` workflow.
The goal is not to redesign the game and not to approximate the UI. The goal is to recover the original Cocos scene structure, assets, prefabs, runtime state, and gameplay modules with source-backed evidence.
Returning to Cocos removes one major source of error: cross-engine coordinate conversion. It does not remove layout work. We still must restore the original `Canvas`, `Camera`, `UITransform`, `Widget`, parent-child transforms, SpriteFrame trim, Spine attachments, active states, and runtime script mutations.
## Source Package
Original extracted package root:
- `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616`
Key paths:
- Original mini-game source:
`/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/source_raw/6A3BB7D3D4349E2050E7B701AAD51600_726750140f8084ebcbe5190fe9c198c9`
- Remote raw assets:
`/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw`
- Converted PNG assets:
`/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/converted_png`
- Extracted SpriteFrame metadata and images:
`/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/spriteframes`
- Extracted Spine region images:
`/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/spine_regions`
## Toolchain Direction
Use Cocos 4.0 and Cocos 4.0 `cocos-cli` as the primary automation path.
Expected CLI capabilities:
```bash
cocos create --project ./my-game
cocos build --project ./my-game --platform web-mobile
cocos start-mcp-server --project ./my-game --port 9527
```
Treat the current Cocos 4.0 CLI/MCP flow as an alpha-stage headless toolchain. It is useful for project creation, build, run, and AI/MCP integration, but it should not be treated as a fully mature replacement for GUI inspection when CLI evidence is insufficient.
Before relying on CLI commands, verify the executable in this local shell:
```bash
command -v cocos
cocos --help
```
If `cocos` is not in `PATH`, locate the installed Cocos 4.0 CLI binary and use its absolute path in docs, scripts, and verification logs.
## Non-Negotiable Rules
1. The original extracted Cocos source is the only layout authority.
2. Do not use Godot coordinates, Godot nodes, Godot scenes, or Godot-derived normalized data.
3. Do not use screenshots to create positions, sizes, anchors, scales, or active states.
4. Screenshots are validation artifacts only. They can prove the reconstruction is wrong; they cannot define the fix.
5. Every rebuilt module must have source evidence before implementation.
6. Every implementation pass must produce a Cocos preview or build output and an ROI comparison report.
7. Do not manually drag editor nodes to fix positions unless the source evidence already proves the exact value being entered.
8. Runtime mocks are allowed, but mock data must be separated from recovered source layout.
9. If Cocos MCP is available, use it to inspect and edit Cocos scenes. If MCP is unavailable or insufficient, generate `.scene` / `.prefab` files plus CLI/editor verification.
## Authoritative Inputs
- Extracted Cocos scene JSON.
- Extracted Cocos prefab JSON.
- Extracted compact config JSON.
- Extracted asset manifests and bundle manifests.
- SpriteFrame metadata: rect, original size, offset, pivot, cap insets.
- Spine metadata: skeleton, atlas regions, skins, slots, bones, attachments, animations.
- AnimationClip metadata: curves, duration, events, target paths.
- Runtime script evidence from readable source, minified code analysis, component UUIDs, or serialized component fields.
- Original bundle loading order and resource paths.
## Non-Authoritative Inputs
- Godot project output.
- Old Godot `normalized/` data.
- Old generated coordinate audit files.
- Screenshots used as position references.
- Visual guesses based on color blocks, sand-area center, or semantic node names.
- Manually tuned offsets that cannot be traced to source evidence.
## Project Structure
Recommended local structure:
```text
assets/
scenes/
prefabs/
scripts/
resources/
bundles/
textures/
spine/
audio/
configs/
i18n/
source_export/
source_nodes.json
source_prefabs.json
source_assets.json
source_spriteframes.json
source_spine.json
source_animations.json
source_runtime_notes.md
source_blockers.md
tools/
extract_source_evidence.py
generate_cocos4_project.py
render_canvas_preview.py
compare_visual_rois.py
verify_cocos4_project.py
artifacts/
canvas_preview/
cocos_capture/
visual_compare/
docs/
cocos4_reconstruction_core.md
rebuild_list.md
rebuild_notes.md
rebuild_log.md
```
## Layer Responsibilities
### Source Export Layer
Path: `source_export/`
Purpose:
- Keep raw source evidence.
- Record exact source files, config indexes, prefab node paths, component UUIDs, and asset UUIDs.
- Record parent-chain transforms and runtime mutations.
Allowed:
- Cocos source field names.
- Raw Cocos positions and transforms.
- Compact JSON indexes.
- SpriteFrame and Spine metadata.
Not allowed:
- Editor guesses.
- Godot data.
- Screenshot-derived coordinates.
### Cocos Data Layer
Path: `assets/`
Purpose:
- Store Cocos 4.0 assets that can be opened, built, and verified through the Cocos 4.0 CLI/MCP flow.
- Preserve Cocos semantics directly: `Node`, `UITransform`, `Widget`, `Camera`, `Sprite`, `sp.Skeleton`, `Animation`, `Prefab`.
Allowed:
- Recovered `.scene` files.
- Recovered `.prefab` files.
- TypeScript components.
- Imported textures, SpriteFrames, Spine, audio, configs.
Not allowed:
- Cross-engine coordinate adapters.
- Godot coordinate names.
- Canvas-only layout constants.
- Debug offsets without source evidence.
### Runtime Mock Layer
Path: `assets/scripts/mock/`
Purpose:
- Provide deterministic local data for development and visual testing.
- Simulate user info, land state, seeds, crops, inventory, shop, friends, and task data.
Rules:
- Mock data may change visible state.
- Mock data must not change source layout.
- Mock data must be replaceable by real APIs without changing recovered scene nodes.
## Reconstruction Workflow
### Step 1. Define A Small Module
Each pass must target one module:
- main camera and scene root
- background layers
- 24 land plots
- house and doghouse
- bottom menu buttons
- land click interaction
- planting animation
- crop growth states
- crop info bubble
- warehouse
- shop
- pet
- dress up
- friends
Do not mix unrelated modules in one pass.
### Step 2. Extract Source Evidence
Before coding, find and record:
- Source file path.
- Bundle name.
- Scene or prefab node path.
- Parent chain.
- Local position.
- Scale.
- Rotation.
- Anchor or pivot.
- Content size.
- Active and visibility state.
- Component type and UUID.
- SpriteFrame or Spine reference.
- Runtime script or config that mutates the node.
If one of these is missing, the module is blocked.
### Step 3. Recover Cocos Nodes
Generate or edit Cocos 4.0 nodes using the source evidence.
Rules:
- Keep original node hierarchy where possible.
- Keep original node names where they help trace source behavior.
- Keep `UITransform`, `Widget`, and `Camera` semantics intact.
- Do not flatten the scene just because it is easier to render.
- Do not rewrite source layout into custom coordinate math.
### Step 4. Recover Assets
For every visual node, resolve:
- Asset UUID.
- Bundle.
- Texture or atlas.
- SpriteFrame rect.
- Original size.
- Offset.
- Pivot.
- Spine skeleton and atlas region if applicable.
- Animation name and default state if applicable.
If only a PNG is known but SpriteFrame metadata is missing, the asset gate fails.
### Step 5. Restore Runtime State
Some elements are not decided by prefab JSON alone. Runtime must be decoded for:
- Camera first-render position and zoom.
- Visible land count.
- Land locked/unlocked state.
- Current crop stage.
- Active menu icons.
- Weather and skin variant.
- Language and text replacement.
- Guide or task overlays.
Use mock APIs only after the runtime state contract is understood.
### Step 6. Canvas Preview
Render a diagnostic Canvas/PIL preview from the recovered Cocos evidence.
Purpose:
- Validate source extraction before touching Cocos scene behavior.
- Compare static layers quickly.
- Catch wrong camera, wrong asset, wrong active state, and wrong parent transform.
Rules:
- Canvas preview is diagnostic.
- Canvas preview cannot create final Cocos coordinates.
- If Canvas and source evidence disagree, fix the extractor.
### Step 7. Cocos Preview
Use Cocos 4.0 CLI/MCP to create, build, run, or inspect the project and capture a screenshot.
The screenshot must be produced by the Cocos scene, not by a manually assembled web page.
Required checks:
- Scene opens or builds without missing assets.
- No console errors.
- Main scene renders at the target viewport.
- Target module nodes exist in the scene tree.
- Interaction works if the module includes input.
Preferred commands when available:
```bash
cocos build --project . --platform web-mobile
cocos start-mcp-server --project . --port 9527
```
If the CLI or MCP cannot capture enough evidence, use the Cocos GUI/editor for inspection only and keep all edits reproducible through scripts.
### Step 8. ROI Validation
Compare Cocos capture against the reference screenshot.
Use fixed ROIs:
- `world_static`
- `land_area`
- `decor_area`
- `bottom_buttons`
- module-specific interaction or animation ROIs
Ignore:
- device status bar
- dynamic text
- balances
- usernames
- localization text unless the module is text-specific
Targets:
- Static bitmap ROI similarity should be at least `0.99`.
- Object center delta should be at most `2 px`.
- Object size delta should be at most `1%`.
If the ROI fails, do not drag nodes. Return to source evidence and identify the missing rule.
## Main Scene First Milestone
The first milestone must recover only:
1. `Canvas`
2. main `Camera`
3. root `scene`
4. background layers
5. 24 visible land plots
6. house
7. doghouse
8. bottom menu buttons
Do not implement warehouse, shop, pet, crop interaction, or planting until this first milestone passes ROI validation.
## Cocos CLI And MCP Usage
When Cocos 4.0 MCP is available:
1. Start MCP with `cocos start-mcp-server --project . --port 9527`.
2. Use MCP to open or inspect the Cocos 4.0 project.
3. Use MCP to inspect scene tree nodes.
4. Use MCP to verify component fields.
5. Use MCP to capture preview screenshots if supported.
6. Use MCP to avoid manual editor operations.
When Cocos MCP is unavailable or incomplete:
1. Generate `.scene` and `.prefab` files directly.
2. Build with `cocos build --project . --platform web-mobile`.
3. Open Cocos GUI/editor only for inspection when CLI evidence is insufficient.
4. Use CLI, browser, or editor screenshots for validation.
5. Keep all edits reproducible through scripts.
## Documentation Requirements
Every module pass must update:
- `docs/rebuild_list.md`
- `docs/rebuild_notes.md`
- `docs/rebuild_log.md`
- `source_export/source_blockers.md`
Each update must include:
- What source files were used.
- What nodes were recovered.
- What was verified.
- What failed.
- What source evidence is still missing.
- What exact command produced the screenshot or report.
## Failure Handling
When a mismatch appears, classify it before fixing:
1. Wrong source file.
2. Wrong bundle or asset UUID.
3. Wrong parent chain.
4. Missing `Widget` or `UITransform`.
5. Missing runtime camera logic.
6. Missing active-state logic.
7. Wrong SpriteFrame or Spine offset.
8. Wrong mock API state.
9. Real rendering difference.
Only item 9 can be handled with render settings. All other failures must be fixed in source extraction or recovered Cocos scene data.
## Done Definition
A module is done only when:
- Source evidence exists.
- Cocos nodes are generated or edited from source evidence.
- Assets resolve without missing references.
- Cocos project builds or opens without errors.
- Canvas preview is generated.
- Cocos screenshot is generated.
- ROI report passes or documents a real source blocker.
- The module documentation is updated.

0
assets/.gitkeep Normal file
View File

View File

@ -0,0 +1,391 @@
# Cocos Creator 3.8 Reconstruction Core Standard
## Goal
Rebuild the QQ Farm mini-game as a Cocos Creator 3.8 project from the extracted original source package.
This replaces the Godot reconstruction route. The goal is not to redesign the game and not to approximate the UI. The goal is to recover the original Cocos scene structure, assets, prefabs, runtime state, and gameplay modules with source-backed evidence.
Returning to Cocos Creator reduces one major source of error: cross-engine coordinate conversion. It does not remove layout work. We still must restore the original `Canvas`, `Camera`, `UITransform`, `Widget`, parent-child transforms, SpriteFrame trim, Spine attachments, active states, and runtime script mutations.
源码包在这里:
[qq_farm_godot_rebuild_20260616](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616)
关键目录:
原始小游戏源码:
[source_raw/6A3BB7D3D4349E2050E7B701AAD51600_726750140f8084ebcbe5190fe9c198c9](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/source_raw/6A3BB7D3D4349E2050E7B701AAD51600_726750140f8084ebcbe5190fe9c198c9)
远程资源原始包:
[downloads/raw](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw)
解出的 PNG 素材:
[downloads/converted_png](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/converted_png)
解出的 SpriteFrame
[downloads/spriteframes](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/spriteframes)
解出的 Spine 区域图:
[downloads/spine_regions](/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/spine_regions)
## Non-Negotiable Rules
1. Original extracted Cocos source is the only layout authority.
2. Do not use Godot coordinates, Godot nodes, or Godot-derived normalized data.
3. Do not use screenshots to create positions, sizes, anchors, scales, or active states.
4. Screenshots are validation artifacts only. They can prove the reconstruction is wrong; they cannot define the fix.
5. Every rebuilt module must have source evidence before implementation.
6. Every implementation pass must produce a Creator preview and ROI comparison report.
7. No manual editor dragging to fix positions unless the source evidence already proves the exact value being entered.
8. Runtime mocks are allowed, but mock data must be separated from recovered source layout.
9. If Cocos MCP is available, use it to inspect and edit Creator scenes. If it is unavailable, use generated `.scene` / `.prefab` files plus Creator CLI/editor verification.
## Authoritative Inputs
- Extracted Cocos scene JSON.
- Extracted Cocos prefab JSON.
- Extracted compact config JSON.
- Extracted asset manifests and bundle manifests.
- SpriteFrame metadata: rect, original size, offset, pivot, cap insets.
- Spine metadata: skeleton, atlas regions, skins, slots, bones, attachments, animations.
- AnimationClip metadata: curves, duration, events, target paths.
- Runtime script evidence from readable source, minified code analysis, component UUIDs, or serialized component fields.
- Original bundle loading order and resource paths.
## Non-Authoritative Inputs
- Godot project output.
- Old Godot `normalized/` data.
- Old generated coordinate audit files.
- Screenshots used as position references.
- Visual guesses based on color blocks, sand-area center, or semantic node names.
- Manually tuned offsets that cannot be traced to source evidence.
## Project Structure
Recommended current project:
```text
assets/
scenes/
prefabs/
scripts/
resources/
bundles/
textures/
spine/
audio/
configs/
i18n/
source_export/
source_nodes.json
source_prefabs.json
source_assets.json
source_spriteframes.json
source_spine.json
source_animations.json
source_runtime_notes.md
source_blockers.md
tools/
extract_source_evidence.py
generate_creator_project.py
render_canvas_preview.py
compare_visual_rois.py
verify_creator_project.py
artifacts/
canvas_preview/
creator_capture/
visual_compare/
docs/
cocos_creator38_reconstruction_core.md
rebuild_list.md
rebuild_notes.md
rebuild_log.md
```
## Layer Responsibilities
### Source Export Layer
Path: `source_export/`
Purpose:
- Keep raw source evidence.
- Record exact source files, config indexes, prefab node paths, component UUIDs, and asset UUIDs.
- Record parent-chain transforms and runtime mutations.
Allowed:
- Cocos source field names.
- Raw Cocos positions and transforms.
- Compact JSON indexes.
- SpriteFrame and Spine metadata.
Not allowed:
- Editor guesses.
- Godot data.
- Screenshot-derived coordinates.
### Creator Data Layer
Path: `assets/`
Purpose:
- Store Cocos Creator 3.8 assets that can be opened and edited in Creator.
- Preserve Cocos semantics directly: `Node`, `UITransform`, `Widget`, `Camera`, `Sprite`, `sp.Skeleton`, `Animation`, `Prefab`.
Allowed:
- Recovered `.scene` files.
- Recovered `.prefab` files.
- TypeScript components.
- Imported textures, SpriteFrames, Spine, audio, configs.
Not allowed:
- Cross-engine coordinate adapters.
- Godot coordinate names.
- Canvas-only layout constants.
- Debug offsets without source evidence.
### Runtime Mock Layer
Path: `assets/scripts/mock/`
Purpose:
- Provide deterministic local data for development and visual testing.
- Simulate user info, land state, seeds, crops, inventory, shop, friends, and task data.
Rules:
- Mock data may change visible state.
- Mock data must not change source layout.
- Mock data must be replaceable by real APIs without changing recovered scene nodes.
## Reconstruction Workflow
### Step 1. Define A Small Module
Each pass must target one module:
- main camera and scene root
- background layers
- 24 land plots
- house and doghouse
- bottom menu buttons
- land click interaction
- planting animation
- crop growth states
- crop info bubble
- warehouse
- shop
- pet
- dress up
- friends
Do not mix unrelated modules in one pass.
### Step 2. Extract Source Evidence
Before coding, find and record:
- Source file path.
- Bundle name.
- Scene or prefab node path.
- Parent chain.
- Local position.
- Scale.
- Rotation.
- Anchor or pivot.
- Content size.
- Active and visibility state.
- Component type and UUID.
- SpriteFrame or Spine reference.
- Runtime script or config that mutates the node.
If one of these is missing, the module is blocked.
### Step 3. Recover Cocos Nodes
Generate or edit Cocos Creator 3.8 nodes using the source evidence.
Rules:
- Keep original node hierarchy where possible.
- Keep original node names where they help trace source behavior.
- Keep `UITransform`, `Widget`, and `Camera` semantics intact.
- Do not flatten the scene just because it is easier to render.
- Do not rewrite source layout into custom coordinate math.
### Step 4. Recover Assets
For every visual node, resolve:
- Asset UUID.
- Bundle.
- Texture or atlas.
- SpriteFrame rect.
- Original size.
- Offset.
- Pivot.
- Spine skeleton and atlas region if applicable.
- Animation name and default state if applicable.
If only a PNG is known but SpriteFrame metadata is missing, the asset gate fails.
### Step 5. Restore Runtime State
Some elements are not decided by prefab JSON alone. Runtime must be decoded for:
- Camera first-render position and zoom.
- Visible land count.
- Land locked/unlocked state.
- Current crop stage.
- Active menu icons.
- Weather and skin variant.
- Language and text replacement.
- Guide or task overlays.
Use mock APIs only after the runtime state contract is understood.
### Step 6. Canvas Preview
Render a diagnostic Canvas/PIL preview from the recovered Cocos evidence.
Purpose:
- Validate source extraction before touching Creator scene behavior.
- Compare static layers quickly.
- Catch wrong camera, wrong asset, wrong active state, and wrong parent transform.
Rules:
- Canvas preview is diagnostic.
- Canvas preview cannot create final Creator coordinates.
- If Canvas and source evidence disagree, fix the extractor.
### Step 7. Creator Preview
Open or run the Cocos Creator 3.8 project and capture a screenshot.
The screenshot must be produced by the Creator scene, not by a manually assembled web page.
Required checks:
- Scene opens without missing assets.
- No console errors.
- Main scene renders at the target viewport.
- Target module nodes exist in the scene tree.
- Interaction works if the module includes input.
### Step 8. ROI Validation
Compare Creator capture against the reference screenshot.
Use fixed ROIs:
- `world_static`
- `land_area`
- `decor_area`
- `bottom_buttons`
- module-specific interaction or animation ROIs
Ignore:
- device status bar
- dynamic text
- balances
- usernames
- localization text unless the module is text-specific
Target:
- Static bitmap ROI similarity should be at least `0.99`.
- Object center delta should be at most `2 px`.
- Object size delta should be at most `1%`.
If the ROI fails, do not drag nodes. Return to source evidence and identify the missing rule.
## Main Scene First Milestone
The first milestone must recover only:
1. `Canvas`
2. main `Camera`
3. root `scene`
4. background layers
5. 24 visible land plots
6. house
7. doghouse
8. bottom menu buttons
Do not implement warehouse, shop, pet, crop interaction, or planting until this first milestone passes ROI validation.
## Cocos MCP Usage
When Cocos MCP is available:
1. Use MCP to open the Creator 3.8 project.
2. Use MCP to inspect scene tree nodes.
3. Use MCP to verify component fields.
4. Use MCP to capture preview screenshots.
5. Use MCP to avoid manual editor operations.
When Cocos MCP is unavailable:
1. Generate `.scene` and `.prefab` files directly.
2. Open Creator manually only for inspection.
3. Use CLI or editor screenshots for validation.
4. Keep all edits reproducible through scripts.
## Documentation Requirements
Every module pass must update:
- `docs/rebuild_list.md`
- `docs/rebuild_notes.md`
- `docs/rebuild_log.md`
- `source_export/source_blockers.md`
Each update must include:
- What source files were used.
- What nodes were recovered.
- What was verified.
- What failed.
- What source evidence is still missing.
- What exact command produced the screenshot or report.
## Failure Handling
When a mismatch appears, classify it before fixing:
1. Wrong source file.
2. Wrong bundle or asset UUID.
3. Wrong parent chain.
4. Missing `Widget` or `UITransform`.
5. Missing runtime camera logic.
6. Missing active-state logic.
7. Wrong SpriteFrame or Spine offset.
8. Wrong mock API state.
9. Real rendering difference.
Only item 9 can be handled with render settings. All other failures must be fixed in source extraction or recovered Creator scene data.
## Done Definition
A module is done only when:
- Source evidence exists.
- Creator nodes are generated or edited from source evidence.
- Assets resolve without missing references.
- Creator scene opens without errors.
- Canvas preview is generated.
- Creator screenshot is generated.
- ROI report passes or documents a real source blocker.
- The module documentation is updated.

13
package.json Normal file
View File

@ -0,0 +1,13 @@
{
"name": "farm",
"type": "3d",
"version": "1.0.0",
"uuid": "",
"creator": {
"version": "3.8.8"
},
"pink": {
"uuid": "d12ef9cc-e575-4262-80ae-40acca36a146",
"version": "1.110.1"
}
}

6
tsconfig.json Normal file
View File

@ -0,0 +1,6 @@
{
/* Base configuration. Do not edit this field. */
"extends": "./temp/cli/tsconfig.cocos.json"
/* Add your custom configuration here. */
}