# Cocos Creator 3.8 Conversion Rules - Stage 1 World Camera And Visible Lands

## Scope

- Stage 1A reconstructs the Cocos design/window size, `root/scene`, `farm_scene_v3` world-map root, background map nodes, and main camera source values.
- Stage 1B reconstructs the 24 visible land nodes under `farm_scene_v3/Scaled/Rotate/GridOrigin`.
- The 36-cell `farm_scene_v3_sprite` grid is not used as visible-land authority for Stage 1B.
- Target runtime is Cocos Creator 3.8.

## Source Evidence

- Startup scene: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/source_raw/6A3BB7D3D4349E2050E7B701AAD51600_726750140f8084ebcbe5190fe9c198c9/assets/main/import/ee/ee605885-16e1-4a63-bf4b-d9663c5764b2.2fd9c.json`
- World prefab: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw/remote/extraRes/import/0e/0ec3b3100.19268.json`
- Runtime environment config: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw/remote/delayRes/import/12/12fc59f2-1411-4cf8-bd1c-c92f6a8f0251.7ff67.json`
- Extracted source inventory: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/source_first/out/main_scene_elements.json`

## Window And Canvas

- Source Cocos design resolution: `720 x 1280`.
- Source Cocos `root` size: `720 x 1280`.
- Source Cocos `root/scene` size: `3320 x 2560`.
- Cocos Creator 3.8 project settings must preserve the same design resolution for this pass.
- Source `startup.scene` Canvas component is the compact row `[15,-6,-5]`. In Cocos compiled-json refs, `_cameraComponent=-5` resolves by `~(-5)=4`; refs record `4` is `[0,3,7]`, so the Canvas camera target is instance `7`, the `root/ui/uiCamera` `cc.Camera` component.
- The generated Creator 3.8 Canvas must bind `root/ui/uiCamera`, not `root/scene/Camera`. The world camera is therefore not a Canvas-bound camera. Its serialized Camera height is `640`, and startup applies the source camera-controller `minZoom=0.8`, producing runtime `orthoHeight=640 / 0.8 = 800`.

## World Map Position

- `farm_scene_v3` local position is `(0, -43.566, 0)`.
- `farm_scene_v3/Scene/BgLayer/defaultbg` local position is `(0, 1248.749, 0)`, size `3320 x 1404`.
- `farm_scene_v3/Scene/FgLayer/default` local position is `(0, -316.229, 0)`, size `3320 x 2472`.
- Cocos Creator 3.8 receives these local positions and sizes directly from source-backed generated data.

## Visible Land Grid

- Visible land source prefab: `farm_scene_v3`.
- Visible land root chain:
  - `farm_scene_v3/Scaled` local position `(-490.399, -225.906, 0)`, scale `(1, 1, 1)`.
  - `farm_scene_v3/Scaled/Rotate` local position `(0, 0, 0)`, euler `(0, 0, 0)`.
  - `farm_scene_v3/Scaled/Rotate/GridOrigin` local position `(0, 0, 0)`, scale `(1, 1, 1)`.
- Each source `grid_*` node is generated as a Cocos Creator node under `GridOrigin`.
- Each source `grid_*` node keeps source local position, scale, euler, UITransform size `196.021 x 110`, and anchor `(0, 0)`.
- Each `grid_*/icon` child keeps source local position `(98.011, 0, 0)`, UITransform size `161.32 x 96.02`, and anchor approximately `(0.494, 0.503)`.
- Render order follows the source `visual_land_cell` source indexes from `farm_scene_v3`, not the `Land.id` business order.
- `Land.grid_x/grid_y` maps directly to `farm_scene_v3/Scaled/Rotate/GridOrigin/grid_{grid_x}_{grid_y}`.
- `farm_scene_v3_sprite/Scaled/Rotate/GridOrigin` contains 36 static cells and uses a different transform chain: `Scaled.y=0.5`, `Rotate.z=-45`, `GridOrigin.x=1.07`. This chain is recorded as excluded evidence and must not be used to place the 24 visible lands.

## Land Asset And Level Rules

- `Land` JsonAsset defines exactly 24 business lands. Land ids `1..6` have no `preceding_land_id`; land id `7` is the first expandable land with `preceding_land_id=6`, `unlocked_res=model/v3/land_extend/spriteFrame`, `level_need=5`, and `gold_need=5000`.
- `farm_scene_v3` serializes every visible `grid_*/icon` as `sp.Skeleton`, not as `cc.Sprite`.
- The source `scene_land` `sp.SkeletonData` is embedded in the compact prefab with atlasText, textureNames, skeletonJson, and source texture refs.
- Cocos Creator 3.8 conversion must generate an external Spine asset:
  - `assets/spine/stage1/scene_land.json` from source skeletonJson.
  - `assets/spine/stage1/scene_land.atlas` from source atlasText.
  - `assets/spine/stage1/scene_land.png` from the source atlas PNG.
  - `scene_land.json.meta` importer `spine-data`, with `userData.atlasUuid` pointing to `scene_land.atlas.meta`.
- Each generated `grid_*/icon` must keep `sp.Skeleton`, source `_preCacheMode`, `_cacheMode`, `_enableBatch`, source `defaultSkin`, and `_skeletonData` referencing the external `scene_land` spine-data UUID.
- `Level` JsonAsset is the authority for land-level animations and source resource mapping:
  - level 1 `普通土地`: `land_spine_res=spine/v2/scene/scene_land/scene_land`, `merge_anim=land_valid1`, dry `land_dry1`.
  - level 2 `红土地`: `merge_anim=land_valid2`, dry `land_dry2`.
  - level 3 `黑土地`: `merge_anim=land_valid3`, dry `land_dry3`.
  - level 4 `金土地`: `merge_anim=land_valid4`, dry `land_dry4`.
  - level 5 `紫晶土地`: `merge_anim=land_valid4`, dry `land_dry4`.
- `Weather` JsonAsset id `1` is the sunny default and maps locked land to `model/v3/land_locked/spriteFrame`.
- Local mock state may select a skeleton default animation, but it must not redefine land-level resource mapping. Without runtime player land-level state, unlocked lands default to `land_valid1` only.
- The first expandable land uses `land_extend` from `Land.id=7.unlocked_res` as a separate overlay child; its source `icon` remains `sp.Skeleton` and uses `land_locked` in the current mock state.
- The world-map text rendered on top of that board is not generated until its runtime node/font/offset evidence is recovered.

## Empty Land Interaction

- Interaction prefab source: `extraRes/import/03/032791d54.4866b.json`.
- `plant_interactive_v2` is generated inactive under `root/ui` because the source prefab layer is `33554432` (`UI_2D`) and the startup scene has `root/ui/uiCamera` with priority `1`, `_orthoHeight=640`, `clearFlags=0`, and visibility `34603008`.
- Interaction nodes keep source local positions, active states, UITransform sizes, label strings, and sprite references from the prefab evidence.
- Component field evidence defines `detailInteractionNode=plant_interactive_v2/followNode/detailNode`, so the land detail bubble is mounted to `followNode/detailNode` at runtime instead of being shown directly from `land_detail/land`.
- Component field evidence defines `landTargetNode=plant_interactive_v2/landTarget`. The `landTarget` node is the source mount target for the selected-land visual; the compact prefab does not serialize `land_valid_selected` as a static child.
- Do not generate `landTarget/gold`; `gui/texture/plantinteractive/gold` is a coin image and is not a selected-land border.
- The selected-land frame uses the original source SpriteFrame `model/v3/land_valid_selected/spriteFrame`, rect/original size `150 x 89`, pivot `(0.5, 0.5)`, and is generated as the runtime visual `plant_interactive_v2/landTarget/land_valid_selected` at local `(0, 0, 0)`.
- The source click path does not move the `plant_interactive_v2` root to the clicked land. The land icon touch event emits the source land position, then the `plant_interactive_v2` handler converts it through `worldToScreen`, `screenToWorld`, and `convertToNodeSpaceAR` and sets the target nodes (`landTargetNode`, `followInteractionNode`, and related guide target). The generated root therefore stays at `(0,0,0)` under `root/ui`, while `landTarget` follows the land and `followNode` follows the land only when the visible seed/tool slot count is three or fewer.
- `farm_scene_v3/PrePlant` and `farm_scene_v3/PostPlant` remain recovered source nodes with local positions `(0, 52, 0)` and `(0, 0, 0)`.
- Do not trust parent `grid_*` hitboxes as visual land hitboxes. Source `grid_*` nodes have UITransform `196.021 x 110` with anchor `(0, 0)`, while the visual land is the child `grid_*/icon` with size `161.32 x 96.02`, anchor `(0.494, 0.503)`, and local `(98.011, 0)`.
- Click response resolves the intended land from the touch location against visible `grid_*/icon` world centers, then applies mock state gating. This matches the visible land center and avoids overlapping parent-hitbox dispatch.
- Interaction popup and seed-list nodes keep source scale `(1, 1, 1)`. SpriteFrame/UITransform sizes are not multiplied by a hidden layout factor; their final screen projection must come only from the active camera and current Cocos view scale.
- Source active-state evidence for the seed-list background is `bg_node3.active=true` and `bg_node5.active=false`. Runtime keeps `bg_node3` for three or fewer visible slots and switches to `bg_node5` only when more than three slots are visible.
- Click response is mock-state gated only: `unlocked_normal` activates `plant_interactive_v2`; `first_expandable` and `locked_unplowed` return without activation.
- Seed mock data must live under `assets/scripts/mock/` and must not change recovered layout nodes.

## Background Asset Selection

- `FarmEnv` id `6` binds `farm_scene_v3/Scene/BgLayer/defaultbg` to `delayRes/scene/bg/spriteFrame`, position `(0, 1248.749)`, size `3320 x 1404`.
- `FarmEnv` id `7` binds `farm_scene_v3/Scene/FgLayer/default` to `delayRes/scene/fg/spriteFrame`, position `(0, -316.229)`, size `3320 x 2472`.
- The lower-resolution `extraRes/model/v3/scene/bg` and `extraRes/model/v3/scene/fg` textures are not selected for this stage because `FarmEnv` does not bind them to the active default environment.

## Camera

- Source Cocos main camera path: `root/scene/Camera`.
- Source Cocos main camera local position: `(0, 0, 1000)`.
- Source Cocos projection: `0`.
- Source Cocos `_orthoHeight`: `640`.
- Source Cocos `_near`: `0`.
- Source Cocos `_far`: `2000`.
- Source Cocos camera-controller component `95c7akihY5GNYe9/Wanw0Ab` is on the same `root/scene/Camera` node and serializes `minZoom=0.8`, `maxZoom=2.4`, `minX=-360`, `maxX=360`, `minY=-320`, `maxY=320`, and `maxVisibleWidth=2300`.
- Generated startup world-camera rule: keep the source Camera component as the base value, then apply the source controller minimum zoom, so runtime `mainCamera.orthoHeight = 640 / 0.8 = 800`.
- Cocos Creator 3.8 camera conversion must be implemented as a public script or generation rule before producing final scene data. Do not apply camera compensation inside the editor by hand.

## UI Camera Viewport Sync

- Source Cocos UI camera path: `root/ui/uiCamera`.
- Source Cocos UI camera local position: `(360, 640, 1000)`.
- Source Cocos UI camera projection: `0`.
- Source Cocos UI camera serialized `_orthoHeight`: `640`.
- Source Cocos UI camera visibility: `34603008`; this includes the source `UI_2D` layer used by `main_ui_v2`, `plant_interactive_v2`, and later UI prefabs.
- Source UI roots also use `cc.Widget`: `main_ui_v2` has `_alignFlags=45`, `HeadInfo` has `_alignFlags=9`, and `Source` has `_alignFlags=33`. These Widget flags must remain layout authority for top-left and top-right HUD placement.
- Cocos Creator 3.8 can resize a Canvas-bound camera from the current screen visible size, but this project overrides the fixed UI layer back to the source Canvas coordinate system after resize events.
- The recovered `root/ui/uiCamera` is the source Canvas-bound camera. The runtime component on `root/ui` must keep `uiCamera.orthoHeight = SOURCE_DESIGN_HEIGHT / 2` and `root/ui` size `SOURCE_DESIGN_WIDTH x SOURCE_DESIGN_HEIGHT`.
- This fixed UI rule changes only the UI camera's runtime visible height and the root UI rectangle. It must not change the main world camera, source HUD node local positions, anchors, sizes, Widget flags, SpriteFrame metadata, or mock data.
- This rule also applies to `plant_interactive_v2`, because the empty-land bubble, seed list, and selected-land visual live under source layer `UI_2D` and are rendered by `root/ui/uiCamera`.
- Tall-viewport root-cause check:
  - The generated project previously bound Canvas to `root/scene/Camera`, so Creator 3.8 resized the world camera to `784.8387096774193` at `744 x 1622`, making the map, house, lands, and world-space objects smaller.
  - Source refs prove Canvas must bind `root/ui/uiCamera`; after this correction the world camera no longer receives Canvas resize and starts at `640 / 0.8 = 800`, while the fixed UI layer restores the source `720 x 1280` coordinate system.

## Compact UITransform Defaults

- Compact prefab nodes that serialize a `cc.UITransform` component but omit `_contentSize` and `_anchorPoint` still have a real Cocos UITransform at runtime.
- Cocos Creator 3.8 engine source `cocos/2d/framework/ui-transform.ts` initializes the default UITransform values as `contentSize = 100 x 100` and `anchorPoint = (0.5, 0.5)`.
- The generated Creator scene must therefore emit a `cc.UITransform` with `100 x 100` and anchor `(0.5, 0.5)` when source compact evidence has a `cc.UITransform` component and omits those two fields.
- This rule is required for Widget nodes. Runtime evidence showed `main_ui_v2/Source` has source `cc.Widget` alignment and a compact `cc.UITransform` component with omitted size/anchor fields. Without emitting the default UITransform, Cocos Creator 3.8 Widget alignment reads a null UITransform and the first frame fails before world rendering completes.
- This default rule must not be applied to nodes with no source `cc.UITransform` component. It only fills omitted fields on an existing source component.

## Layer And Visibility

- Source Cocos camera visibility is `1083179010` (`0x40900002`).
- The visibility mask includes source world layer bit `1073741824` and does not include Cocos Creator UI_2D layer bit `33554432`.
- Stage 1A generated world nodes must therefore use layer `1073741824` so the recovered source camera can see them without inventing a UI-layer conversion.
- Later UI modules must decode their own source cameras and visibility masks instead of inheriting the Stage 1A world layer rule.

## Camera Runtime Limits

- `minZoom`: `0.8`
- `maxZoom`: `2.4`
- `minX/maxX`: `-360 / 360`
- `minY/maxY`: `-320 / 320`
- `maxVisibleWidth`: `2300`

## Current Two-Layer Viewport Rule

- Current phase is a user-directed viewport architecture pass. Do not run `tools/generate_creator_project.py` to overwrite `CocosFarm/assets/scenes/stage1_world_camera.scene` during this pass.
- The project design resolution is the source Canvas resolution `720 x 1280`, policy `2`, recorded in `CocosFarm/settings/v2/packages/project.json`.
- The default project view must stay source-backed at `720 x 1280`; official preview device size must not replace recovered scene or UI coordinates.
- Cocos Creator 3.8 still requires `cc.Camera` render components. The valid conversion is not a zero-camera scene; the valid conversion is to keep render cameras and remove business-level viewport logic from the camera nodes.
- `root/scene` is the main map layer. Land, house, doghouse, crops, and later shop/world objects are rendered by `root/scene/Camera` and follow the map viewport.
- `root/ui` is the fixed UI layer. HUD, land info bubble, seed list, operation buttons, and future popups are rendered by `root/ui/uiCamera` and keep fixed Cocos design-coordinate size. Browser CSS pixels still follow `cc.view` scale.
- `Stage1MainWorldLayer` is attached to `root/scene` and controls only the main map view:
  - Assign `mainCamera.orthoHeight = sourceCameraInitialOrthoHeight()`.
  - `sourceCameraInitialOrthoHeight()` is `640 / 0.8 = 800`, from source Camera `_orthoHeight=640` and source camera-controller `minZoom=0.8`.
  - Keep `mainCamera.visibility = SOURCE_CAMERA_VISIBILITY`.
- `Stage1FixedUiLayer` is attached to `root/ui` and controls only the fixed UI view:
  - Assign `uiCamera.orthoHeight = SOURCE_DESIGN_HEIGHT / 2`.
  - Assign the `root/ui` UITransform size to `SOURCE_DESIGN_WIDTH x SOURCE_DESIGN_HEIGHT`.
  - Disable the root `Widget` on `root/ui` because this layer component owns the root visible rectangle.
  - Keep `root/ui` at `(0, 0, 0)`.
- Do not call `view.setDesignResolutionSize()` from these runtime layer components. Runtime verification showed resize-callback design changes trigger repeated design-resolution events and can render a black frame. The design resolution belongs in project settings for this pass.
- At a browser or phone logical viewport, Creator may still scale the outer canvas to fit the selected preview device. Fixed UI means fixed source design-coordinate layout, not replacing the source `720 x 1280` coordinate system with preview CSS pixels.
- Land click conversion under the two-layer rule:
  - Hit testing uses `mainCamera.worldToScreen(gridIcon.worldPosition)`.
  - Icon hitbox size is the original source icon size multiplied by the rendered main-camera projection scale.
  - Popup placement converts the selected world icon position from main-camera screen space into fixed-UI world space through `uiCamera.screenToWorld`, then into the interaction parent with `convertToNodeSpaceAR`.
- Runtime verification should report `mainCamera.orthoHeight=800`, `uiCamera.orthoHeight=640`, and design resolution `720 x 1280`; source UI node sizes remain source sizes in design coordinates.

## Render Order

- Preserve source hierarchy and sibling order unless source runtime code proves a mutation.
- Background layer and foreground layer must remain separate Cocos nodes because `FarmEnv` binds them independently.
- Do not derive sibling order by sorting exported source indexes. For compact prefabs, resolve `_children` order from the compact reference table first.

## Scene Decor - House And Doghouse

- Decor source prefab: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw/remote/extraRes/import/0e/0ec3b3100.19268.json`.
- Decor skin config: `/Users/hy/Documents/dev/qq_farm_godot_rebuild_20260616/downloads/raw/remote/delayRes/import/2d/2d201122-b5a7-4181-8f60-d67a399ec757.edfbe.json`.
- Compact sibling-order rule: read `data[5][1][2]`; for parent source index `N`, the sequence after `[0,N,0]` maps negative child keys to concrete node row indexes in exact sibling order.
- `Scene/FgLayer` source order is `default, fg, FarmSkin, Trees, DogLayer, DynamicDogLayer, Board, Tower, Storage`.
- `Scene/FgLayer/FarmSkin` source order is `Layer1, Layer2, Layer3, Layer4, Layer5, Layer6, Layer7`.
- Generate every recovered `FgLayer` sibling in this order. Empty siblings are source placeholders until their own module is recovered.
- House source:
  - `SkinCfg.id=201001`, `skin_type=1`, `skin_name=默认小屋`.
  - Parent node: `Scene/FgLayer/FarmSkin/Layer2`.
  - Local position: `(347.6, 179.8, 0)`.
  - Spine asset: `spine/v2/costume/house/201001`.
  - Cocos Creator asset output: `assets/spine/stage1/house_201001/201001.skel`, `201001.atlas`, `201001.png`.
  - Generated node: `Scene/FgLayer/FarmSkin/Layer2/house_201001` with `sp.Skeleton`, `defaultSkin=default`, `defaultAnimation=idle_01`.
- Doghouse source:
  - `SkinCfg.id=205001`, `skin_type=5`, `skin_name=默认狗屋`.
  - Spine asset: `spine/v2/costume/doghouse/205001`.
  - Visible prefab node: `Scene/FgLayer/DogLayer/dogHouse`.
  - Local position: `(24.266, 223.974, 0)`.
  - Anchor evidence: `(0.5, 0.2030596946602437)`.
  - Cocos Creator asset output: `assets/spine/stage1/doghouse_205001/205001.skel`, `205001.atlas`, `205001.png`.
  - Generated node: `Scene/FgLayer/DogLayer/dogHouse` with `sp.Skeleton`, `defaultSkin=default`, `defaultAnimation=idle_01`.
- Do not replace the house or doghouse with hand-drawn shapes or screenshot crops. Use the original Spine binary, atlas text, and atlas PNG.
- Canvas diagnostic preview is not a layout authority for binary Spine attachments until `tools/render_canvas_preview.py` can decode the full Spine attachment stack. Creator runtime Spine capture is the verification authority for Stage 1D decor visibility.