Skip to content

t1k:cocos:omarchy:pod-build

FieldValue
Moduleomarchy
Version0.4.2
Effortmedium
ToolsBash, Read

Keywords: build copy project, cocos headless build windows guest, cocos mcp guest launch, cocos web build guest, creator cli build, ebusy node_modules build, missing class build scene, pod build, pod sync, pull web-mobile build, stale build bundle, winpodx build

/t1k:cocos:omarchy:pod-build
[sync | launch | build | pull | verify-bundle | verify-stale | serve]

Pod build: host project -> guest Creator -> web build -> host

Section titled “Pod build: host project -> guest Creator -> web build -> host”

Cocos Creator runs in the winpodx Windows guest (t1k-cocos-omarchy-winpodx set it up). This skill is the repeatable loop on top of it: push the host working tree in, start Creator with the MCP extension, drive a CLI web build on a separate copy, pull the build back, prove it carries your change. Scripts are Python (winpodx is a Python package; the guest agent is reached through its AgentClient) and carry no project names: everything is an environment variable (scripts/pod_common.py documents each one).

Terminal window
S=.claude/skills/t1k-cocos-omarchy-pod-build/scripts
export POD_LOCAL_PROJECT=<host project root, the folder with assets/>
export POD_GUEST_PROJECT='C:\CocosProjects\<Name>' # authoring copy; the build copy defaults to <same>Build
export POD_START_SCENE=db://assets/<path>.scene # build only
  1. python3 -I $S/pod_sync.py - always first. Host -> guest authoring copy (chunked, sha256-verified, manifest-checked). It lists GUEST-ONLY: guest assets the project no longer has; --prune deletes them (a removed/renamed file otherwise survives and breaks the build). Resumable delta: a host state file (~/.cache/t1k/pod_sync/, POD_SYNC_STATE_DIR) records every file the guest confirmed, so a run sends only added/changed files in ~1 MiB batches and re-running the SAME command after a timeout, outage or Ctrl-C continues where it stopped; --full resends everything, --dry-run prints the mode:/plan: lines and writes nothing. Exit codes: 0 VERIFIED; 1 VERIFICATION FAILED (a real mismatch: only the mismatching entries leave the state, so the next run resends just those) or a failed --prune; 3 VERIFICATION UNKNOWN (the guest’s verify reply was empty, cut off or count=0/0, retried --retries times; the state is KEPT, re-run the same command once the host is quieter, it resends nothing). Never treat 3 as a pass or as a reason to --full. Details and the failure modes: gotchas (references/gotchas.md).
  2. python3 -I $S/pod_launch.py - Creator on the authoring copy with the MCP extension autostarting; wait for the port to answer. $S/mcp_call.py <tool> '<json>' then drives the editor (it refuses when the editor has another project open).
  3. Editor work (prefabs, scenes): see prefab authoring via MCP (references/prefab-authoring-via-mcp.md); save in the editor.
  4. python3 -I $S/pod_build.py sync - guest authoring copy -> guest build copy (never from the host). When robocopy purged anything (or its summary is unreadable, or with --wipe-library) it then runs clean-stale (wipes the build copy’s library\ and temp\, so the asset DB cannot keep a deleted asset); clean-stale also runs alone and refuses while a Creator holds the copy.
  5. python3 -I $S/pod_build.py build - headless build on the build copy; the editor on the authoring copy stays open (two Creators on one project corrupt it). Exit 0 only when the log, not Creator’s exit code, says it is good.
  6. python3 -I $S/pod_build.py pull <dir> then verify-bundle <dir> --token <symbol-or-component-id> ... - a token you know must be in the build (a symbol you just added; a component class id from the source scene). Then python3 -I $S/pod_build.py verify-stale <dir> --repo $POD_LOCAL_PROJECT [--bundle resources]: exit 0 clean, 1 lists built asset paths the repo no longer has, 2 could not verify (never a pass). Only then serve <dir>.

--dry-run on every pod_build.py subcommand prints the guest script without running it. Add POD_BUILD_PACKAGES='{"<pkg>":{...}}' for per-package build options. build --target <id> builds a platform target of the project’s extensions/platform-manager/dist/ci-targets.json (web-mobile rows only; an unknown id is an error; set POD_TARGET_PACKAGE to the build-config package key that takes the target); a non-local target then runs the page-injection post-step in the guest, because Creator writes index.html itself and without it a portal build ships without its vendor script. The guest node on PATH is unverified. Both the failure signatures and why each guard exists are in gotchas (references/gotchas.md): read it before trusting a green build.

  • Never print or read the winpodx agent token; the scripts do not. Never put a project name, token or keystore in these scripts or their tests (a test enforces the first two). *.keystore is excluded from the sync.
  • pod_build.py never kills a process and never writes to the authoring copy. A build that fails on script-load errors is retried once after clearing the build copy’s temp\programming (--retries 0 turns that off).
  • Tests: bun test tests/pod-build.test.cjs and bun test tests/pod-delta.test.cjs (no guest needed; they cover log parsing, config, dry-runs, sync filtering, prune, the resumable delta transport against a fake guest, clean-stale, verify-bundle and verify-stale). What needs a live guest (the chunk transfer, Creator itself) is NOT covered; say so when reporting.