Level designer

Level designer

Levels live in levels/*.json, one file per level. Every level Claude writes or edits is run through the validator before it is called done, so nobody ships a level with an exit behind a wall.

Level format

{
  "name": "1-2 Key and door",
  "tiles": [
    "#######",
    "#S..#E#",
    "#.#.#D#",
    "#K#...#",
    "#######"
  ]
}

If the user's engine already has a format, map it to this one in a small converter, or ask before changing the legend. Extra JSON keys (enemies, music, par time) are fine; the validator ignores them.

Steps

1. Ask for the brief if missing: how many levels, grid size (default 12x9 for phone screens), which tiles the game supports, and the difficulty curve (default: teach, test, twist).
2. Plan the set in a short table before drawing: level name, the one new idea it teaches, size, target shortest path. One new idea per level.

3. Draw each level in levels/NN-short-name.json. Rules of thumb:

   • Close the border with walls.
   • Show the goal early: the player should see the exit or the key within the first few moves.
   • Put a coin on the risky path and leave a safe path without it.
   • Make the shortest path grow 20 to 40% per level, not double.

4. Validate every level:

   node scripts/validate-levels.mjs levels --report out/level-report.json

   Exit code 1 means at least one level has errors. Add --exit-zero only when the user wants a report without failing (for example in a draft folder).

5. Fix and rerun until there are no errors. Treat warnings as questions for the user (an unreachable coin may be a deliberate tease).
6. Report with the table below, using shortest_path from the report as the difficulty number.

Output

| Level | Teaches | Size | Shortest path | Coins reachable | Status |
| ----- | ------- | ---- | ------------- | --------------- | ------ |
| 1-1 First steps | moving | 10x7 | 11 | 3/3 | ok |
| 1-2 Key and door | keys open doors | 7x5 | 12 | 0/0 | ok |

Then one line on the curve: "Paths grow 11, 12, 16, 21. Level 1-2 may feel like a breather; want it longer?"

What the validator checks

• Errors: invalid JSON, missing or ragged tiles, size outside 3 to 128, unknown tile, not exactly one S, no E, a door with no key, no exit reachable (breadth-first search over position and key state, four directions).
• Warnings: open border tiles, unreachable coins or keys, an exit fewer than 3 steps away, a missing name.

Guardrails

• Write only in levels/ and out/. Ask before overwriting a level the user made by hand; propose the change as a diff first.
• A level is not done until the validator passes it. Say so plainly if you could not make one pass.
• The validator proves reachability, not fun. Suggest a playtest (the playtest-feedback kit helps) after big changes.

Level designer

Design levels for tile-based 2D games as plain JSON files, and prove every one is beatable before a player finds out it is not. A small validator checks bounds, tiles, a single start, and that the exit can actually be reached, keys and doors included.

Who it is for: solo and jam developers making top-down, maze, puzzle, or roguelike games who want levels they can version, diff, and check automatically.

Example

You say:

Design three intro levels that teach keys and doors. Small enough for a phone.

You get levels/01-first-steps.json, levels/02-key-and-door.json, and levels/03-two-doors.json, a validator run, and a summary:

If a level is broken, the validator says exactly why, for example row 2 is 4 wide, expected 5 or no exit is reachable from the start, even after picking up a key. Try it on the samples in examples/levels/ and the deliberately broken examples/broken-level.json.

What it can access

• Runs its own script, node scripts/validate-levels.mjs.
• Reads and writes levels/, writes reports to out/.
• No network, no env vars.

Setup

None. Needs Node.js 18 or newer. The validator exits 1 when a level has errors, so you can run it in CI.