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

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.
• 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

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:

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:

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

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:

frame * row * col * 4