Parent MicropolisCore skill exposing the unified CLI, C++/WASM simulator, save-file tools, renderer/content workflows, command bus, and MOOLLM integration protocols. Use for city inspection, analysis, visualization, export, editing, headless simulation, content preview/catalog design, and routing work to Micropolis sub-skills.
Parent MicropolisCore skill exposing the unified CLI, C++/WASM simulator, save-file tools, renderer/content workflows, command bus, and MOOLLM integration protocols. Use for city inspection, analysis, visualization, export, editing, headless simulation, content preview/catalog design, and routing work to Micropolis sub-skills.
"The engine is the microworld. The CLI is the public gate."
Role
This is the parent skill for MicropolisCore itself. It owns the broad engine/save-file/CLI/render/content surface and delegates specialized capabilities to sub-skills.
It should not try to do everything. It should route work to the right skill, script, module, or protocol.
Semantic Image Pyramid
Read in this order:
GLANCE.yml — quick activation summary
CARD.yml — machine-readable interface and advertisements
SKILL.md — this operational protocol
README.md — human rationale and map
What This Skill Owns
Micropolis engine orientation
Save-file CLI usage
City file inspection and analysis
City visualization and export
Engine/WASM/frontend bridge map
Renderer and content-management orientation
Browser/headless-browser render workflow
MOOLLM protocol routing
Capability factoring decisions
Delegation to narrower Micropolis sub-skills
What This Skill Delegates
Capability
Delegate
Live simulator/UI mutation
micropolis-command-bus
Pie menus/keyboard/chat/LLM action dispatch
micropolis-command-bus
CLI structure and doc-first automation
pnpm run micropolis -- api --format yaml
Batch simulation and evaluation loops
experiment + simulation
Git branches, issues, PRs, commits
github
Educational framing
constructionism
Object-advertised actions
advertisement
Skill security/audit
skill-snitch
Future smart orchestration/MCP hosting
mooco
Catalog services and adapters
+ future content skill
mooco
Sims save/object/person bridge
sim-obliterator
Character identity/personality
character, incarnation, mind-mirror, needs
Object/place/action composition
object, room, advertisement, action-queue
Primary CLI
Run from MicropolisCore/apps/micropolis (or use pnpm --filter micropolis run micropolis -- … from the repo root):
pnpm run micropolis -- <command> <subcommand> [options]
Important commands:
pnpm run micropolis -- about --format yaml
pnpm run micropolis -- api --format yaml
pnpm run micropolis -- city info ../../content/micropolis/cities/scenario_tokyo.cty
pnpm run micropolis -- city analyze ../../content/micropolis/cities/scenario_boston.cty
pnpm run micropolis -- city export --format yaml --include-map ../../content/micropolis/cities/radial.cty
pnpm run micropolis -- city export --format csv --include-map ../../content/micropolis/cities/radial.cty
pnpm run micropolis -- visualize ascii ../../content/micropolis/cities/radial.cty
pnpm run micropolis -- visualize emoji ../../content/micropolis/cities/scenario_tokyo.cty
pnpm run micropolis -- sim smoke --ticks 10 --format yaml
pnpm run micropolis -- bus list --format yaml
For command dispatch:
pnpm run micropolis -- bus preview <command-id> --actor llm --reason "why" --format yaml
pnpm run micropolis -- bus propose <command-id> --actor llm --reason "why" --format yaml
Status Boundary
Implemented:
Unified CLI: about, api, city, visualize, sim, bus.
YAML/JSON/CSV output helpers.
Static city file inspection, analysis, export, edit, patch-scenario.
The same render description should work in a user browser and in a hosted headless browser worker. Prefer user hardware for expensive previews, and upload only intentionally approved outputs.
Capability Factoring Rule
If a capability grows its own:
CLI commands
TypeScript modules
data formats
persistence schema
MCP tools
protocols
safety policy
then it should become a sub-skill with its own GLANCE.yml, CARD.yml, SKILL.md, and optional README.md.
Do not implement yet, but design with this constraint in mind:
Some runtime overlay maps are integrated over time. Exact regeneration may require rewinding to an earlier checkpoint and replaying the edit/command history, not just loading a final .cty snapshot.
Future CLI should support:
Differential snapshots.
Persistent command/edit leaves from the command bus.
Universe branch points at human/LLM/tool edit commands.
Git branches named like <type>_<id> such as micropolis_971987439573945.
Coalesced commits that preserve internal command boundaries for later split/replay.
Ex-post-facto attribution sidecars that map command indices to the Git commit that contains their effects.
Ephemeral overlay sidecars for runtime/computed maps, annotations, previews, and experiment outputs.
Fast replay from checkpoints.
Pausing at edit points and forking alternate histories.
Regenerating runtime maps by replaying enough simulator phases.
This is the "TiVo for Micropolis" model described in documentation/notes/MultiPlayerIdeas.txt.
See documentation/designs/command-timeline-git-branches.md for the command leaf and commit policy.
Sidecar Data Protocol
Sidecars store data adjacent to city packages without forcing it into classic .cty bytes.
Use cases:
Runtime overlays: traffic, pollution, crime, land value, police/fire coverage.
User overlays: chalk marks, labels, regions, routes, lesson annotations.
Binary for dense rasters, typed arrays, and videos.
Binary sidecars must declare:
schema_version
width, height, optional frames
element_type such as u8, u16, f32, rgba8
channels and channel order
row_stride_bytes
optional frame_stride_bytes
All multi-byte numeric values in binary sidecars use network byte order (big-endian). Byte order is not configurable. Single-byte formats such as u8 and rgba8 have no endian concern.
Raw video sidecars can use rgba8 with layout:
frame * row * col * 4
Computed Layer Roadmap
Do not implement yet, but design the CLI so computed runtime layers become as easy to request as saved layers.
The future interface should let humans and LLMs ask for a layer by name without caring whether it comes from:
Saved bytes in .cty/.mop.
Derived tile IDs or tile flags.
Simulator analysis scans.
Historical replay from a checkpoint.
Planned shape:
pnpm run micropolis -- layer list ../../content/micropolis/cities/haight.cty
pnpm run micropolis -- layer dump ../../content/micropolis/cities/haight.cty --layer traffic --compute
pnpm run micropolis -- layer export ../../content/micropolis/cities/haight.cty --layer pollution --format json --compute
pnpm run micropolis -- layer visualize ../../content/micropolis/cities/haight.cty --layer landvalue --style ascii --compute
The CLI should infer the minimum required simulator scans from the requested layer. For exact reconstruction of history-integrated layers, it may need time-travel replay.
The future save format should also support extended layers beyond classic .cty/.mop:
Dynamic simulator analysis maps captured directly at save time.
Metadata for authorship, provenance, branch ancestry, replay checkpoints, and learning goals.
Treat this as an extensible layered document format around the city, not just a binary save file.
Content Management Protocol
Browser-first content editing should avoid unnecessary server round-trips:
Load schemas/assets/render descriptions into the browser.
Let users edit objects, images, tiles, metadata, and scene descriptions locally.
Render previews locally with WebGPU, WebGL fallback, or Canvas fallback.
Store drafts locally until the user saves or publishes.
Upload source assets and rendered derivatives only after approval.
Server catalogs store approved versions, provenance, permissions, and render descriptions.
For batch catalog generation or SSR snapshots, use a headless browser worker that opens the same renderer route and consumes the same render description.
GitHub MMORPG Protocol
Treat GitHub as durable civic infrastructure, not only source control.
Object trees can live in branches and nested directory packages:
Micropolis Canvas rendering should iterate destination pixels and sample tile data like a shader, not draw tile quads, so zoomed output has no seams and can support far-zoom filtering.
Output Discipline
For humans:
Short explanation
Concrete command
What it returns
For LLM/tool consumption:
Prefer --format yaml
Use --format json for strict consumers
Use --format csv for tabular/tile-grid exports
Use region bounds to control output size
Include relevant file path and command used
Do not dump full maps unless requested
Dovetails
micropolis-command-bus: live command and LLM proposal gate
cli/: CLI should be compact, self-documenting, and module-oriented
tool-calling-protocol: every tool call needs a reason/why
constructionism: every tool should help users build and understand
