Brainstorm Level Design

Brainstorm: Level Design — build the space the mechanics live in

Mechanics are verbs; levels are the sentences you write with them. A level isn't decoration around gameplay — it's where the game teaches, tests, and rewards its mechanics. This mode designs levels that come from the game's own pillars and mechanics, then persists each one so the build (and the next session) has a plan.

The failure it prevents: levels that are arbitrary — a random maze of walls that ignores what the game is actually about, difficulty that spikes or flatlines, and new mechanics dumped on the player with no teaching. Plus the usual amnesia: a level designed in chat that the next session rebuilds differently.

Read the GDD first (always)

A level serves the game, so read game-design/GDD.md before designing any level — its pillars and mechanics are your material and your constraints. A level that violates a pillar is wrong even if it's fun in isolation. If there's no GDD yet, stop and run [brainstorm-game-design](../brainstorm-game-design/SKILL.md) first. Persistence contract: [../browser-engine/references/design-memory.md](../browser-engine/references/design-memory.md).

BANNED (arbitrary-level tells)

• Levels disconnected from mechanics — a layout that would be identical in any game. If you could paste this level into a different game unchanged, it's not designed, it's filler.
• No teaching — introducing a mechanic in a place where failing to understand it kills you. Teach in safety, test under pressure, later.
• Flat or spiky difficulty — every room the same, or a wall the player hits with no ramp. Design the curve, then place rooms on it.
• One golden path, no reading — a corridor with no decisions. Even linear levels should let the player see ahead, choose an approach, or spot a risk/reward.
• Ignoring collision reality — designing spaces the collision model can't honor: gaps narrower than the player's footprint, one-way ledges the platformer code doesn't support (see [../game-collision/SKILL.md](../game-collision/SKILL.md)).
• Secrets with no logic — a hidden room behind a random wall. Secrets should be earned by noticing, telegraphed to the observant.
• Designing tile-by-tile in prose — describe the space's beats and flow; the greybox is where exact geometry gets decided.

Process (per level)

1. State the level's job. Every level has ONE primary purpose: teach mechanic X, test the combination of X+Y, provide a breather, escalate to a boss, reward exploration. Name it before drawing anything.
2. Place it on the difficulty curve. Where does this sit relative to what came before/after? Sketch the intended tension curve across the whole game (calm → build → peak → release) and put this level on it.
3. Teach → test → twist. If it introduces a mechanic: first a safe space to try it, then a low-stakes test, then a real challenge, then a combination with an earlier mechanic. Never test before teaching.
4. Design the critical path + the reading. The intended route, plus what the player can see ahead to make choices. Give even linear levels a moment of "I chose that."
5. Set the beats. A level is a rhythm: tension and release, not one flat intensity. Mark the peaks (a hard fight, a tricky jump) and the valleys (loot, a view, a quiet stretch).
6. Risk/reward + secrets. Optional harder routes for better rewards; secrets telegraphed so the attentive feel clever, not lucky.
7. Honor the collision model. Gaps ≥ player footprint; platforms the code actually supports; solids that will get real bodies. Design what the [game-collision](../game-collision/SKILL.md) rules can deliver.
8. Greybox spec. Describe the layout as zones and connections + an ASCII sketch — enough for the build to lay out real geometry. Exact tiles come in engine.
9. Write it to game-design/levels/.md, log it in decisions.md, and if it changes the game's scope/progression, update the GDD + AGENTS.md summary.

Level archetypes (steal these, tie them to your mechanics)

• Tutorial-by-doing — teaches a mechanic through the environment, no text. The first Mario screen.
• Combination gate — requires using two taught mechanics together for the first time.
• Pressure test — a taught mechanic under time/enemy pressure.
• Breather / reward — low intensity, loot, story, a vista. Follows a peak.
• Boss arena — geometry designed for the boss fight, tests everything so far.
• Optional challenge — harder route, better reward, telegraphed risk.

Persist per-level (the template)

Level name · its job · position on the difficulty curve · mechanics used/taught · beats (tension map) · critical path + reading · risk/reward & secrets · collision/space notes · greybox (zones + ASCII). Template: [templates/level.md](templates/level.md).

The done check

• [ ] Read the GDD; the level serves a pillar and uses the game's actual mechanics
• [ ] The level has ONE stated job and a place on the difficulty curve
• [ ] New mechanics are taught in safety before being tested
• [ ] There's a critical path AND something to read/choose — not a blind corridor
• [ ] Beats alternate tension and release; the peak is intentional
• [ ] Spaces honor the collision model (footprint gaps, supported platforms)
• [ ] Written to game-design/levels/.md; logged in decisions.md; GDD/AGENTS updated if scope changed

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: StarchyBomb
• Source: StarchyBomb/browser-engine
• License: MIT

Install and usage instructions live in the source repository linked above.