cat / miau-is-true
clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / docs / worlds / README.md
README.md 4.6K source

Worlds program: brief

Owner: design (Claude session miau-is-true-9e), managing a small team of world-builder subagents. Engine questions go through docs/worlds-inbox.md.

Why

Baba Is You's modding scene works because a creator can package a world: a themed collection of levels that explores one idea, with or without custom tiles and custom rules. Miau Is True should support the same pattern. This program is the proof of that pattern. We build a few real worlds, ship the good ones as default packs, and write down every point of friction a creator or player hits along the way.

Worlds in flight

World Pack id Explores Custom tiles Custom rules
Crate Works crate-works Sokoban pushing: crates, goals, dead ends, rules that change what can be pushed yes no (documents what a real Sokoban goal would need)
Tidewater tidewater Hazards and identity: SINK, DEFEAT, and becoming something else to cross them yes no
Crossword crossword Pure grammar: shared words across axes, AND chains, scarce words, stacked words no (core nouns only) no
Clockwork clockwork Custom rules: new properties a mod defines (for example MOVE, OPEN/SHUT) yes yes (drafted against a proposed mod behavior API)

Status (2026-09-23)

World Levels Verified by design Bundling
Crate Works 7 (15 to 48 steps) yes, mustForm proven on 3 ready, in CI and green
Crossword 7 (16 to 35 steps) yes, reworked for W6, mustForm proven on 6 ready (handed off for CI and bundling)
Tidewater 7 (9 to 26 steps) yes, mustForm proven on 3 ready. W8 fixed (c3537ca) and re-solved green
Clockwork 6 (10 to 29 steps) yes (mouse-keeps-time has allowBypass) in CI and green. W11 landed; bundling after W12 (custom property tiles and the beat strip). OPEN/SHUT waits on W13

The engine asks W1 to W13 are in docs/worlds-inbox.md, and the design decisions from this program are D20 and D23 to D24 in docs/design.md.

Files

  • mods/worlds/<pack-id>.cjs is the pack. It must load with loadMod (see modding.md).
  • docs/worlds/<pack-id>.md is the world bible: the theme, the mechanic, and a level table (id, what it teaches, solver length, flags), plus design notes.
  • docs/worlds/friction.md is the shared friction log. It's append-only; use its entry template.
  • Do not edit src/, tests/, index.html, openspec/, or other people's files. The engine team owns them. Scratch experiments go in /tmp.

Tools

  • node tools/solve.mjs mods/worlds/<pack-id>.cjs runs a breadth-first solve on the real engine. It prints the shortest solution and flags BYPASS (the level is winnable without moving any word) and TRIVIAL (under 6 steps). Use --level <id> for one level and --max <n> to raise the search cap.
  • node tools/solve.mjs core solves the built-in levels.

Quality bar for a world

  1. 6 to 8 levels, ordered to teach, then twist, then combine. Mark each level's category as required, optional, or challenge, and fill in introduces.
  2. Every level solves. The solver output goes in the world bible.
  3. No accidental bypass. A BYPASS is allowed only when it's the point of the level (for example "you don't need to touch anything"), and the bible has to say so.
  4. One idea per level. The first level of an idea is small and safe; a later level makes the player use it. Include at least one challenge level of 25 steps or more with a non-obvious rule edit.
  5. Board size: at most 14×10 (it has to read on a phone), and keep blank rows between stacked sentences where possible (design's spacing rule).
  6. Titles and hints follow the design copy deck: sentence-case titles, a hint that nudges without giving the answer, no ·, and no "garden".
  7. Palette: every custom noun gets an emoji that reads at 60% of a cell on a near-black board. Directional actors can declare facing: { glyph, faces: 'left' }.

Friction: what to log

Log anything that made authoring or playing harder than it should be. That includes coordinates you had to count by hand, missing helpers, validation messages that didn't help, vocabulary you needed but didn't have, presentation that would confuse a player, and engine behaviour that surprised you. Log it the moment you hit it, including small things. Every friction entry needs a proposed fix and a suggested owner (engine, design, or content).