Level design
A level is a sequence of intentional experiences delivered through space.
Good level design is a process: define the metrics movement is built on, block
out geometry with primitives, play it, then dress it — never the reverse. This
skill is the engine-neutral practice; use godot-tilemap/unity-tilemap-2d to
lay out 2D grids and gridmaps for 3D.
When to use
- Use to plan a level's structure: critical path, pacing, gating, encounters,
and where the player learns vs is tested.
- Use the blockout → test → iterate → dress workflow to build a level that
plays well before any art exists.
- Use to derive level metrics from the character's movement so geometry is
reachable and fair.
When not to use: to generate levels algorithmically, use procedural-gen
(authored and procedural design are complementary). For the engine's tile/grid
painting tools, use godot-tilemap / unity-tilemap-2d. For the movement
abilities the metrics come from, that's the engine movement skill + input-systems.
Core workflow
- Derive metrics first. Measure the character: max jump height and distance,
run speed, reach, camera range. Every gap, ledge, and corridor is sized in
these units. Lock them before building geometry.
- Blockout (whitebox/greybox). Build the whole level from untextured
primitives at correct scale. Validate flow, sightlines, and reachability while
changes are cheap. No art yet. Tools: Godot
CSGBox3D and friends with
use_collision on (prototype only: the docs flag their CPU cost, so bake to
static meshes later), Unity's ProBuilder package (com.unity.probuilder),
Unreal's Modeling Mode (Cube Grid), and a plain grey tileset for 2D.
- Define the critical path (start → goal) and the golden path you expect
most players to take. Layer optional/secret paths off it.
- Pace the experience. Alternate tension and rest in a deliberate curve;
don't run combat-combat-combat. Give the player room to breathe and to
anticipate.
- Teach, then test. Introduce each mechanic in a safe space, let the player
practice, then test it under pressure. Difficulty rises in a sawtooth, not a
straight line.
- Gate with intent. Use locks/keys, abilities, and one-way drops to control
order and pacing; guide with light, lines, and landmarks rather than walls.
- Playtest and iterate. Watch real players: where do they get lost, stuck,
bored, or killed unfairly? Fix the blockout; only dress when it plays well.
Patterns
1. Player metrics drive every dimension
# Derive the metrics from the SAME constants the character controller uses, then
# size geometry in these units. If the jump changes, the numbers follow.
const RUN_SPEED := 240.0 # px/s (or m/s in 3D)
const JUMP_VELOCITY := 420.0 # initial upward speed of a full jump
const GRAVITY := 980.0 # px/s², the value the controller applies
const MAX_JUMP_H := JUMP_VELOCITY * JUMP_VELOCITY / (2.0 * GRAVITY) # 90: peak height
const AIR_TIME := 2.0 * JUMP_VELOCITY / GRAVITY # ~0.86 s, take-off to same height
const MAX_JUMP_DIST := RUN_SPEED * AIR_TIME # ~206: running jump, level ground
const SAFE_GAP := MAX_JUMP_DIST * 0.7 # comfortable, not pixel-perfect
const HARD_GAP := MAX_JUMP_DIST * 0.95 # a deliberate skill check
# Build platforms so required jumps use SAFE_GAP; reserve HARD_GAP for optional reward.
The formulas are the ideal arc. Variable jump height, a separate fall gravity,
air acceleration, the fixed physics step and the collider's width all move the
real numbers, and landing higher shortens the reach. Confirm them once in a
test room with a measured gap ladder, then treat the measured values as the
truth. A platform placed MAX_JUMP_DIST + 1 away is impossible; one at
SAFE_GAP is fair. Keep these constants beside the level data so designers and
code agree.
2. Encounter / pacing as data (a tension timeline)
# Author the level as a sequence of beats with an intended intensity (0..1).
# This makes the pacing curve explicit and reviewable before you build rooms.
const BEATS := [
{ "room": "entry", "type": "teach", "intensity": 0.1 },
{ "room": "hall_1", "type": "combat", "intensity": 0.5 },
{ "room": "vista", "type": "rest", "intensity": 0.1 }, # breather + reward
{ "room": "gauntlet", "type": "combat", "intensity": 0.8 },
{ "room": "save_room", "type": "rest", "intensity": 0.2 }, # before the boss
{ "room": "boss", "type": "climax", "intensity": 1.0 },
]
# Read the intensity column top-to-bottom: it should rise overall but dip for rests
# (a sawtooth), never flatline high. Drive spawns/music intensity from this.
3. Gating and the critical path (a small graph)
# Model the level as rooms + gated connections. Validate that the goal is
# reachable with the keys/abilities the player can actually obtain in order.
const ROOMS := {
"entry": { "exits": [ { "to": "hall_1" } ] },
"hall_1": { "exits": [ { "to": "vista", "needs": "double_jump" },
{ "to": "side_room" } ] }, # optional branch
"side_room": { "exits": [ { "to": "hall_1" } ], "grants": "double_jump" },
"vista": { "exits": [ { "to": "boss", "needs": "red_key" } ] },
}
# Grow the reachable set until nothing new opens: collect what each reached room
# grants, then follow every exit whose `needs` is already held. Assumes keys are
# never used up and doors never re-lock; model consumable keys as counts.
func goal_reachable(rooms: Dictionary, start: String, goal: String) -> bool:
var have := {} # keys/abilities collected
var reached := {start: true}
var changed := true
while changed:
changed = false
for room in reached.keys():
var info: Dictionary = rooms.get(room, {})
var grant = info.get("grants")
if grant != null and not have.has(grant):
have[grant] = true
changed = true
for exit in info.get("exits", []):
var open: bool = not exit.has("needs") or have.has(exit["needs"])
if open and not reached.has(exit["to"]):
reached[exit["to"]] = true
changed = true
return reached.has(goal)
# goal_reachable(ROOMS, "entry", "boss") is FALSE for the table above: no room
# grants "red_key". That is exactly the soft-lock this check exists to catch.
# Run it in a test or editor tool whenever the room graph changes.
Pitfalls
- Dressing before it plays. Detailing a blockout you haven't validated wastes
the most expensive work on a layout you'll change. Greybox and test first.
- Geometry that ignores metrics: gaps the jump can't clear, ledges below
reach, corridors narrower than the camera needs. Size everything in player units.
- Flat pacing. Wall-to-wall combat (or wall-to-wall calm) numbs the player.
Alternate tension and rest; place a breather and a save before the climax.
- Testing a mechanic before teaching it. Players meet a hazard for the first
time in a lethal spot. Introduce safely, let them practice, then test.
- Soft-locks and dead ends. A gate needs an ability/key obtainable only past
the gate. Validate the critical path's key/ability order, not just connectivity.
- No readability / guidance. Players get lost when nothing draws the eye. Use
light, leading lines, color, and landmarks to point toward the path.
- One-way drops with no signposting strand or surprise players. Telegraph
irreversible moves.
- Confusing procedural with authored. Generation gives variety, not
authored pacing. Use
procedural-gen for variety; hand-author for intent.
References
references/pacing-and-flow.md — the difficulty/tension curve in depth,
teaching-loop design (introduce→develop→twist→test), readability and guidance
techniques, 2D vs 3D layout considerations, and a blockout review checklist.
Related skills
godot-tilemap, unity-tilemap-2d — paint 2D level grids; gridmaps for 3D.
procedural-gen — generate variety to complement authored structure.
game-ai — encounter enemies that navigate the space you build.
platformer, puzzle, roguelike — genres that compose this skill.
1---2name: level-design3description: >4 Design and build playable levels — the blockout/whitebox-to-playable workflow,5 player metrics and grid layout, pacing and flow (tension/rest curve), gating6 and the critical path, and encounter design. Engine-neutral practice. Use when7 the user mentions level design, blockout/whitebox/greybox, level layout, level8 pacing, encounter design, or the critical path through a level.9metadata:10 source: https://skillmd.com/skills/junmystery/level-design11---1213# Level design1415A level is a **sequence of intentional experiences** delivered through space.16Good level design is a *process*: define the metrics movement is built on, block17out geometry with primitives, play it, then dress it — never the reverse. This18skill is the engine-neutral practice; use `godot-tilemap`/`unity-tilemap-2d` to19lay out 2D grids and gridmaps for 3D.2021## When to use2223- Use to plan a level's structure: critical path, pacing, gating, encounters,24 and where the player learns vs is tested.25- Use the **blockout → test → iterate → dress** workflow to build a level that26 plays well before any art exists.27- Use to derive level **metrics** from the character's movement so geometry is28 reachable and fair.2930**When *not* to use:** to *generate* levels algorithmically, use `procedural-gen`31(authored and procedural design are complementary). For the engine's tile/grid32painting tools, use `godot-tilemap` / `unity-tilemap-2d`. For the movement33abilities the metrics come from, that's the engine movement skill + `input-systems`.3435## Core workflow36371. **Derive metrics first.** Measure the character: max jump height and distance,38 run speed, reach, camera range. Every gap, ledge, and corridor is sized in39 these units. Lock them before building geometry.402. **Blockout (whitebox/greybox).** Build the whole level from untextured41 primitives at correct scale. Validate flow, sightlines, and reachability while42 changes are cheap. No art yet. Tools: Godot `CSGBox3D` and friends with43 `use_collision` on (prototype only: the docs flag their CPU cost, so bake to44 static meshes later), Unity's ProBuilder package (`com.unity.probuilder`),45 Unreal's Modeling Mode (Cube Grid), and a plain grey tileset for 2D.463. **Define the critical path** (start → goal) and the **golden path** you expect47 most players to take. Layer optional/secret paths off it.484. **Pace the experience.** Alternate tension and rest in a deliberate curve;49 don't run combat-combat-combat. Give the player room to breathe and to50 anticipate.515. **Teach, then test.** Introduce each mechanic in a safe space, let the player52 practice, then test it under pressure. Difficulty rises in a sawtooth, not a53 straight line.546. **Gate with intent.** Use locks/keys, abilities, and one-way drops to control55 order and pacing; guide with light, lines, and landmarks rather than walls.567. **Playtest and iterate.** Watch real players: where do they get lost, stuck,57 bored, or killed unfairly? Fix the blockout; only dress when it plays well.5859## Patterns6061### 1. Player metrics drive every dimension6263```gdscript64# Derive the metrics from the SAME constants the character controller uses, then65# size geometry in these units. If the jump changes, the numbers follow.66const RUN_SPEED := 240.0 # px/s (or m/s in 3D)67const JUMP_VELOCITY := 420.0 # initial upward speed of a full jump68const GRAVITY := 980.0 # px/s², the value the controller applies69const MAX_JUMP_H := JUMP_VELOCITY * JUMP_VELOCITY / (2.0 * GRAVITY) # 90: peak height70const AIR_TIME := 2.0 * JUMP_VELOCITY / GRAVITY # ~0.86 s, take-off to same height71const MAX_JUMP_DIST := RUN_SPEED * AIR_TIME # ~206: running jump, level ground72const SAFE_GAP := MAX_JUMP_DIST * 0.7 # comfortable, not pixel-perfect73const HARD_GAP := MAX_JUMP_DIST * 0.95 # a deliberate skill check74# Build platforms so required jumps use SAFE_GAP; reserve HARD_GAP for optional reward.75```7677The formulas are the ideal arc. Variable jump height, a separate fall gravity,78air acceleration, the fixed physics step and the collider's width all move the79real numbers, and landing higher shortens the reach. Confirm them once in a80test room with a measured gap ladder, then treat the measured values as the81truth. A platform placed `MAX_JUMP_DIST + 1` away is impossible; one at82`SAFE_GAP` is fair. Keep these constants beside the level data so designers and83code agree.8485### 2. Encounter / pacing as data (a tension timeline)8687```gdscript88# Author the level as a sequence of beats with an intended intensity (0..1).89# This makes the pacing curve explicit and reviewable before you build rooms.90const BEATS := [91 { "room": "entry", "type": "teach", "intensity": 0.1 },92 { "room": "hall_1", "type": "combat", "intensity": 0.5 },93 { "room": "vista", "type": "rest", "intensity": 0.1 }, # breather + reward94 { "room": "gauntlet", "type": "combat", "intensity": 0.8 },95 { "room": "save_room", "type": "rest", "intensity": 0.2 }, # before the boss96 { "room": "boss", "type": "climax", "intensity": 1.0 },97]98# Read the intensity column top-to-bottom: it should rise overall but dip for rests99# (a sawtooth), never flatline high. Drive spawns/music intensity from this.100```101102### 3. Gating and the critical path (a small graph)103104```gdscript105# Model the level as rooms + gated connections. Validate that the goal is106# reachable with the keys/abilities the player can actually obtain in order.107const ROOMS := {108 "entry": { "exits": [ { "to": "hall_1" } ] },109 "hall_1": { "exits": [ { "to": "vista", "needs": "double_jump" },110 { "to": "side_room" } ] }, # optional branch111 "side_room": { "exits": [ { "to": "hall_1" } ], "grants": "double_jump" },112 "vista": { "exits": [ { "to": "boss", "needs": "red_key" } ] },113}114115# Grow the reachable set until nothing new opens: collect what each reached room116# grants, then follow every exit whose `needs` is already held. Assumes keys are117# never used up and doors never re-lock; model consumable keys as counts.118func goal_reachable(rooms: Dictionary, start: String, goal: String) -> bool:119 var have := {} # keys/abilities collected120 var reached := {start: true}121 var changed := true122 while changed:123 changed = false124 for room in reached.keys():125 var info: Dictionary = rooms.get(room, {})126 var grant = info.get("grants")127 if grant != null and not have.has(grant):128 have[grant] = true129 changed = true130 for exit in info.get("exits", []):131 var open: bool = not exit.has("needs") or have.has(exit["needs"])132 if open and not reached.has(exit["to"]):133 reached[exit["to"]] = true134 changed = true135 return reached.has(goal)136# goal_reachable(ROOMS, "entry", "boss") is FALSE for the table above: no room137# grants "red_key". That is exactly the soft-lock this check exists to catch.138# Run it in a test or editor tool whenever the room graph changes.139```140141## Pitfalls142143- **Dressing before it plays.** Detailing a blockout you haven't validated wastes144 the most expensive work on a layout you'll change. Greybox and test first.145- **Geometry that ignores metrics**: gaps the jump can't clear, ledges below146 reach, corridors narrower than the camera needs. Size everything in player units.147- **Flat pacing.** Wall-to-wall combat (or wall-to-wall calm) numbs the player.148 Alternate tension and rest; place a breather and a save before the climax.149- **Testing a mechanic before teaching it.** Players meet a hazard for the first150 time in a lethal spot. Introduce safely, let them practice, then test.151- **Soft-locks and dead ends.** A gate needs an ability/key obtainable only past152 the gate. Validate the critical path's key/ability order, not just connectivity.153- **No readability / guidance.** Players get lost when nothing draws the eye. Use154 light, leading lines, color, and landmarks to point toward the path.155- **One-way drops with no signposting** strand or surprise players. Telegraph156 irreversible moves.157- **Confusing procedural with authored.** Generation gives variety, not158 authored pacing. Use `procedural-gen` for variety; hand-author for intent.159160## References161162- `references/pacing-and-flow.md` — the difficulty/tension curve in depth,163 teaching-loop design (introduce→develop→twist→test), readability and guidance164 techniques, 2D vs 3D layout considerations, and a blockout review checklist.165166## Related skills167168- `godot-tilemap`, `unity-tilemap-2d` — paint 2D level grids; gridmaps for 3D.169- `procedural-gen` — generate variety to complement authored structure.170- `game-ai` — encounter enemies that navigate the space you build.171- `platformer`, `puzzle`, `roguelike` — genres that compose this skill.