micropolis

# Micropolis > *"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: 1. `GLANCE.yml` — quick activation summary 2. `CARD.yml` — machine-readable interface and advertisements 3. `SKILL.md` — this operational protocol 4. `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 | `mooco` + future content skill | | 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): ```bash pnpm run micropolis -- <command> <subcommand> [options] ``` Important commands: ```bash 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: ```bash 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. - Terminal visualization: ASCII, emoji, mono, map. - Headless WASM `sim info` / `sim smoke`. - Command-bus list/preview/propose/dispatch/recording commands. - Current browser path: `MicropolisSimulator`, `MicropolisReactive.svelte.ts`, `WebGLTileRenderer`. - Tests for WASM load, reactive bridge, heap safety, CLI introspection, format helpers, and command metadata. Roadmap: - Renderer plugin contract and browser/headless-browser render route. - Canvas pixel-sampling renderer and WebGPU renderer parity. - Browser-first content management and approved catalog uploads. - GitHub branches/issues/PRs as multiplayer civic object store. - Semantic image pyramid for city/content packages. - SimObliterator/VitaMoo bridge into a unified Sims + Micropolis world. - Time-travel replay, computed layers, experiment branches, and classroom GitHub workflows. ## Unified CLI Surface | Branch | Purpose | |--------|---------| | `about` | Human/LLM summary of the CLI and module surface | | `api` | YAML/JSON module map and format summary | | `city` | Static `.cty`/`.mop` read, dump, info, analyze, export, edit, patch-scenario | | `visualize` | Terminal ASCII/emoji/mono/map renderings | | `sim` | Headless real WASM load/info/smoke stepping | | `bus` | Command list/preview/propose/dispatch/proposals/recordings | Formats: - Prefer `--format yaml` for LLM-facing structured output. - Use `--format json` for strict machine consumers. - Use `--format csv` for tabular exports and tile grids. - Use text/ASCII/emoji/mono when a human needs a quick look. ## LLM Workflow When an LLM needs Micropolis capabilities: 1. Identify whether the task is file/static or live/mutating. 2. Use `pnpm run micropolis -- about --format yaml` or `api --format yaml` when you need the command/module map. 3. Use `pnpm run micropolis -- city|visualize|sim|bus ...` for terminal work. 4. If multi-step simulation or comparison, delegate to `experiment`. 5. If GitHub-as-MMORPG, delegate Git operations to `github`. 6. Always explain why a tool call is being made. 7. Prefer YAML for LLM-facing structured output, JSON for strict machine consumers, and CSV for tabular export. ## MOOLLM Workflow MOOLLM characters and skills should treat Micropolis as a shared world, not an opaque tool. Default loop: ```text Observe -> Explain -> Preview -> Propose -> Approve -> Execute -> Log ``` Use this skill to gather facts and choose the correct route: 1. `micropolis` for city facts, CLI/API map, render/content architecture, and engine orientation. 2. `micropolis-command-bus` for live actions, proposals, approvals, and command recordings. 3. `experiment` / `simulation` for batch comparisons and replay-style studies. 4. `github` for branches, issues, PRs, and GitHub-as-MMORPG operations. 5. `constructionism` for learning goals and teaching stance. 6. `advertisement` for object-advertised actions and contextual affordances. 7. `mooco` for future orchestration, MCP adapters, and catalog services. 8. `sim-obliterator` / `character` / `mind-mirror` when the work crosses into Sims people, objects, or uplift/download. No ghost actions: world-changing work should create an inspectable command proposal, branch, issue, annotation, report, experiment, or catalog object. ## Static vs Live Boundary ### Static/File-Oriented Use `pnpm run micropolis -- city ...` or `visualize ...` when working with: - `.cty` and `.mop` files - Binary dumps - Map/history/metadata analysis - Export to YAML/JSON/CSV/tiles - ASCII/emoji/monospace visualization - Scenario metadata patching ### Live/Running-Simulation Use `pnpm run micropolis -- sim ...` or `bus ...` when working with: - Running WASM simulator actions - UI view commands - Pie menu commands - Keyboard shortcuts - Chat slash commands - LLM proposals - Approval/rejection of mutating actions ### Render/Content-Oriented Use this skill and `documentation/designs/renderer-plugin-roadmap.md` when working with: - Renderer plugin contracts. - Micropolis map previews. - Sims character/object previews. - Browser-side draft/edit/preview/approve/upload workflows. - Headless browser catalog generation. - WebGPU/WebGL/Canvas renderer capability selection. Principle: ```text render description -> browser renderer plugin -> WebGPU / WebGL / Canvas -> preview image or interactive view ``` 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`. Candidate sub-skills: - `micropolis-save-format` - `micropolis-overlays` - `micropolis-experiments` - `micropolis-github-multiverse` - `micropolis-ui-workspace` - `micropolis-ai-tutors` - `micropolis-renderers` - `micropolis-content-catalog` ## Engine Map | Area | Files | |------|-------| | C++ core | `packages/micropolis-engine/src/` | | Embind/WASM | `packages/micropolis-engine/src/emscripten.cpp` | | Save/load | `packages/micropolis-engine/src/fileio.cpp` | | Tools | `packages/micropolis-engine/src/tool.cpp` | | CLI entry | `apps/micropolis/cli/entry.ts` | | CLI modules | `apps/micropolis/cli/` | | Constants | `apps/micropolis/cli/constants/constants.js` | | WASM wrapper | `apps/micropolis/src/lib/MicropolisSimulator.ts` | | Svelte bridge | `apps/micropolis/src/lib/MicropolisReactive.svelte.ts` | | WASM loaders/helpers | `apps/micropolis/src/lib/wasm/` | | I18n keys | `apps/micropolis/src/lib/i18n/keys.ts` | | WebGL renderer | `apps/micropolis/src/lib/WebGLTileRenderer.ts` | | Canvas renderer | `apps/micropolis/src/lib/CanvasTileRenderer.ts` | | WebGPU renderer | `apps/micropolis/src/lib/WebGPUTileRenderer.ts` | | Pie menus | `apps/micropolis/src/lib/PieMenu.svelte` | | Renderer roadmap | `documentation/designs/renderer-plugin-roadmap.md` | | Collaboration lineage | `documentation/designs/collaborative-microworld-lineage.md` | | Multiplayer browser lessons | `documentation/designs/multiplayer-browser-lessons.md` | | Command path and collaboration modes | `documentation/designs/command-path-collaboration-modes.md` | | Naming conventions | `documentation/designs/naming-conventions.md` | | Callback interface roadmap | `documentation/designs/callback-interface-roadmap.md` | | Command timeline | `documentation/designs/command-timeline-git-branches.md` | | GitHub multiverse | `documentation/designs/github-as-mmorpg-multiverse.md` | | Filesystem object model | `documentation/designs/filesystem-object-model.md` | | MOOLLM integration | `documentation/designs/moollm-micropolis-integration.md` | ## Time Travel Roadmap 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. - Preview artifacts: rendered thumbnails, approved catalog images, visual diffs. - Experiment outputs: charts, sampled layers, frame sequences, replay checkpoints. Formats: - YAML/JSON for semantic metadata and manifests. - CSV for tabular grids and sparse samples. - 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: ```text 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: ```bash 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. - User-defined layers: chalk, notes, labels, signs, regions, routes, planned work. - Annotations linked to tiles, zones, neighborhoods, objects, branches, or chat messages. - Behavior definitions for tools, agents, zones, scenarios, and educational courseware. - Multiplayer state: proposals, votes, unresolved dialogs, role assignments, permissions. - LLM state: tutor messages, command proposals, explanations, approvals, and audit logs. - 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: 1. Load schemas/assets/render descriptions into the browser. 2. Let users edit objects, images, tiles, metadata, and scene descriptions locally. 3. Render previews locally with WebGPU, WebGL fallback, or Canvas fallback. 4. Store drafts locally until the user saves or publishes. 5. Upload source assets and rendered derivatives only after approval. 6. 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: ```text city_234234234234/ proposal_3423234/ issue_3423234/ experiment_2026-05-03_power-plant/ micropolis_43345345345/cities/2342342423423/ ``` Rules: - Branches are universes or object stores. - Directories are rooms/objects/containers. - Commits are durable decisions or observations. - Issues are civic discussion spaces. - PRs compare alternate timelines. - Evidence belongs in the repo, linked from the issue or proposal. - Experiments should write their inputs, outputs, render previews, and conclusions as files. Example workflow: 1. Player proposes building a nuclear plant at tile `(x,y)`.