Coir — Cocos asset dependency topology

Coir (coconut fibre): comb a project's tangled asset dependencies apart, like combing interwoven coconut fibres — it shares a root with Cocos (the coconut genus).

▶ Try it online (Chrome / Edge): https://aaronhg.github.io/coir/ — open it and pick your Cocos project directory; everything runs inside the browser, no files are uploaded.

▶ No install — see an example first: open a topology snapshot — no project needed, works in any browser (Firefox / Safari / mobile included); the data lives entirely in the URL hash, and the link opens straight into Topology + Size map so you can see what coir looks like.

Load a Cocos Creator 3.8.x project and build an asset usage + dependency topology view — images, atlases (TexturePacker plist / Spine), bitmap fonts (fnt), prefabs, scenes, and Cocos component scripts. One DOM-free core, four surfaces: the browser (pure frontend, no backend, no build step), a headless CLI, an MCP server (for AI agents), and a Cocos Creator editor extension.

What it answers

Your question	Where to look
Is this image / prefab still used? Will deleting it break something?	the Topology's "used where" popup, the List's Used by∑, the Unused report; coir uses art/coin.png --where
Why is this scene so heavy?	the Size map (à la Unreal's Size Map: the centre's dependency closure as a treemap); coir closure, coir analyze size
Are the bundles cut cleanly? Any cycles or double-packed assets?	the Cross-bundle report, red-outlined cells in the Size map; coir analyze bundles
Which assets are duplicates?	coir duplicates (byte-/structure-identical), coir atlas-dup / coir spine-dup (the same art in several atlases) + thumbnail comparison in Reports
How do I gate all this in CI?	coir check (declarative rules, exit code fails CI) + coir verify --all (project-wide structural validation)
Can a script / AI agent edit prefabs safely?	coir edit (in-place editing + the verify/native-verify chain) + coir mcp (zero-dependency MCP server)

Requirements

• Browser UI: a Chromium browser (Chrome / Edge) — it needs the File System Access API; serve from a secure context (http://localhost or https), not file://. The #topo= snapshot viewer works in any browser.
• CLI / MCP / editor extension: Node.js (the CLI has zero runtime dependencies, nothing to build).
• Target: Cocos Creator 3.8.x projects (3.5 is serialization-compatible; 2.x is not supported).

Getting started (browser)

npm install       # webpack toolchain + typescript (all dev-only, no third-party runtime deps), first time only
npm run dev       # dev server: http://localhost:8080 (hot reload on save)
# production build: npm run build → dist/app.bundle.js (pure DOM ~95KB, deployable on any static server)

Open http://localhost:8080 → click "Choose Cocos project folder" → choose the game project root (the level containing assets/; picking assets/ directly works too). Or just use the hosted version at https://aaronhg.github.io/coir/ (built + deployed by GitHub Actions; dist/ is not committed).

The four tabs and every interaction — List / Topology / Size map / Reports, the / quick-open, keyboard controls, Asset Bundle analysis — are documented in docs/UI.md.

Getting started (CLI)

One-line install (zero runtime deps — no npm install, no build: it downloads the source and symlinks the bin onto your PATH):

curl -fsSL https://raw.githubusercontent.com/aaronhg/coir/main/install.sh | sh

coir find Coin                                   # locate an asset by name
coir uses art/coin.png --where                   # who references it + exactly where (paste-able edit selectors)
coir deps scene/Main.scene --type prefab         # which prefabs the scene pulls in
coir analyze                                     # project-wide audit: unused/orphans/atlas utilization/size/bundles
coir duplicates                                  # redundant assets (merge with edit --all swap-uuid)
coir check                                       # declarative CI gate (coir.rules.json, exit code fails CI)
coir edit Shop.prefab set "Title:cc.Label._string" --str "Start" --backup   # in-place edit
coir verify --all                                # project-wide structural validation (CI gate)
coir mcp                                         # MCP server (for AI agents; see docs/MCP.md)
claude mcp add -s user coir -- coir mcp          # register ONCE, user-scope — the floating server resolves the target project per call

Editing is guarded, not hopeful. Every coir edit write is atomic and mtime-guarded (refused if Cocos touched the file since coir read it), previewable with --dry-run / --diff, and backed up with --backup. Gate the result on --verify (offline structural validation) or the live native-verify chain — the running Cocos editor reimports the file and confirms the engine builds exactly what coir wrote. Anything it can't do safely (structural edits inside a nested prefab instance) is refused, never mis-written. This is what makes coir edit / coir mcp safe to point at a real project — see docs/EDITING.md.

Run inside your Cocos project, or point elsewhere with -C <projectDir>; -o json for machine-readable output; coir --help prints every command, the selector grammar, and the exit codes. The full CLI documentation (queries / audits / in-place prefab·scene editing / validation / CI rules) is docs/CLI.md; the edit-engine design is in docs/EDITING.md.

Plugins

Asset types, dependency edges, CLI+MCP commands, CI checkers, and editor context menus are all pluggable — a plugin is a plain object (zero build step, uses only ctx, imports nothing). Drop one into <your project>/coir.plugins.mjs and it takes effect in the browser, the CLI, MCP, and the editor extension at once. Dynamic loads (resources.load('x') and friends, invisible to static analysis) are recovered exactly this way — the core is deliberately zero-heuristic. Authoring and registration: docs/PLUGINS.md; ready-made example plugins (audio-call, resources-load, anim/skel, …): aaronhg/coir-plugins.

Embedding / integration

• #topo= snapshot links: an asset's neighbourhood subgraph packed into the URL hash — no install, any browser, straight into Topology + Size map (the example link at the top of this page is one). Produced by the topology bar's link button, coir share <asset>, or the editor extension.
• import('coir'): one import gives a Node host scanProject / encodeTopo and the rest of the embedding API.
• Cocos Creator 3.5–3.8 extension (cocos-extension/): right-click an asset for its dependencies/dependents, the Coir Goto panel (nodePath ⇄ live-scene node), and the native-verify endpoint.

See docs/EMBEDDING.md and cocos-extension/README.md.

Known limitations

• Dynamic loading is a plugin's job (by design, not a gap): run-time loads by string path (resources.load('x'), director.loadScene('x'), bundle.load('x'), …) are deliberately not chased by the static scan — the core stays zero-heuristic and predictable. Coir therefore treats every bundle's assets (resources and custom bundles alike) as dynamic-load roots (never reported unused; their zero-referrer assets are listed as candidates only). To turn a specific pattern back into a real edge, write a plugin that parses literal load strings (ready-made template resources-load in docs/DYNAMIC-EDGES.md); computed paths (load('ui/'+name)) must be declared explicitly inside the plugin.
• When an atlas is consumed whole as a SpriteAtlas, per-frame usage cannot be determined statically (flagged "whole-atlas dynamic use").
• Targets the 3.8.x format; 3.5.2 serialization is compatible, so the core applies as-is (tweak meta.js / scan.js if a field differs). No 2.x support (.fire scenes, the old meta layout).
• Editing: structural edits inside a nested prefab instance (mountedChildren/removedComponents) are not supported yet (correctly refused today, never mis-written); the browser UI has no a11y support yet.

Documentation

Document	Contents
docs/UI.md	The four browser tabs (List / Topology / Size map / Reports), search & keyboard, Asset Bundle analysis
docs/CLI.md	The headless CLI: queries / audits / in-place editing / validation / CI rules (coir check)
docs/PLUGINS.md	Plugins: types, edges, commands, CI checkers, context menus; registration & trust model
docs/EMBEDDING.md	The #topo= snapshot viewer, import('coir'), the Cocos editor extension
docs/ARCHITECTURE.md	The data model (nodes/edges), source layout, the FileProvider interface
docs/EDITING.md	The in-place edit engine's full design (selectors, guards, nested instances, the verification chain)
docs/SERIALIZATION.md	The Cocos scene/prefab serialization contract (which fields coir relies on / ignores)
docs/NESTED-PREFABS.md	The nested-prefab machinery (PrefabInstance / overrides / fileId)
docs/MCP.md	The MCP server: host setup, tool list, security
docs/DYNAMIC-EDGES.md	Writing plugins for dynamic-load edges (the resources-load template)
DEVELOPMENT.md	Development history, technical decisions, and the pitfalls along the way