hy/cocos-farm
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cocos-farm/source_export/cocos_creator38_conversion_rules.md

20 KiB
Raw Permalink Blame History

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.