gamedev-skills/awesome-gamedev-agent-skills / skills/disciplines/level-design
level-design
VerifiedEngine-neutral level design with Godot checks: player metrics from the real controller, key and ability gating with a soft-lock check, and pacing. Use when laying out a level or metroidvania gates, or players get lost or a key sits behind its own door. Not for generation (`procedural-gen`), painting tiles (`godot-tilemap`, `unity-tilemap-2d`) or jump tuning (`platformer`).
Level design
A level is a sequence of intended experiences delivered through space. The order that works:
measure the character, block out with primitives, check reachability and pacing, get playtest
reports, then dress. This skill is engine-neutral with Godot 4.7 checks. Painting the grid is
godot-tilemap or unity-tilemap-2d; generating layouts is procedural-gen.
When to use
- Planning a level's structure: critical path, optional branches, gating order, encounters, and where a mechanic is taught versus tested.
- Building a blockout and checking that every required jump and gate is possible.
- Reviewing a level that confuses, bores or soft-locks players.
Not this skill: layout generators and dungeon algorithms (procedural-gen), jump and
movement tuning (platformer, the engine movement skill), enemy behaviour in the space
(game-ai), camera framing (camera-systems).
Core workflow
- Measure the metrics from the game, not from memory. Read the movement constants from the player script, then run the jump measurement (Pattern 1) to get the real apex, reach and airtime. Size every gap, ledge and corridor in those units.
- Block out the whole level with untextured primitives at true scale: Godot
CSGBox3Dand friends withuse_collisionon, Unity ProBuilder (com.unity.probuilder), Unreal Modeling Mode, or a plain grey tileset in 2D. CSG is for prototyping only; bake it withbake_static_mesh()andbake_collision_shape()before shipping. - Write the room graph (rooms, exits, what each exit needs, what each room grants) and the beat list next to the level. Both are small data files the checks below read.
- Lay the critical path, then the golden path (the route most players will take), then optional branches that rejoin it.
- Pace and teach. Intensity rises in a sawtooth with a rest before each spike. Each mechanic appears first where failure is cheap, then under pressure.
- Gate with intent using keys, abilities and one-way drops. Guide with light, leading lines and landmarks rather than walls.
- Run the checks (see "Check it"), fix the blockout, and only then ask the user for a playtest with specific questions.
- Dress last, and re-run the checks after any geometry change.
Patterns
1. Measure the real jump (headless)
# tools/measure_jump.gd: godot --headless --path . --script res://tools/measure_jump.gd
# Runs the real player scene on flat ground with run + jump held and prints the reach.
extends SceneTree
const PLAYER := "res://player.tscn" # the game's player scene
const RUN := &"move_right"
const JUMP := &"jump"
func _initialize() -> void:
var ground := StaticBody2D.new()
var shape := CollisionShape2D.new()
shape.shape = WorldBoundaryShape2D.new() # infinite floor at y = 0, normal up
ground.add_child(shape)
root.add_child(ground)
var player: CharacterBody2D = load(PLAYER).instantiate()
player.position = Vector2(0, -64)
root.add_child(player)
for i in 30: # let the player land and settle
await physics_frame
Input.action_press(RUN)
for i in 30: # reach full run speed
await physics_frame
var start := player.position
Input.action_press(JUMP)
var apex := 0.0
var ticks := 0
var airborne := false
while ticks < 600:
await physics_frame
ticks += 1
apex = maxf(apex, start.y - player.position.y)
if not player.is_on_floor():
airborne = true
elif airborne:
break # landed back on the same height
Input.action_release(JUMP)
Input.action_release(RUN)
var dt := 1.0 / Engine.physics_ticks_per_second
print("JUMP apex=%.1f distance=%.1f airtime=%.3fs" % [apex, player.position.x - start.x, ticks * dt])
quit(0 if airborne else 1)
Holding jump measures the full jump; release it after one tick to measure the short hop if the
controller has variable height. The formulas h = v² / 2g and d = run_speed * 2v / g are
only the ideal arc: a controller with RUN_SPEED 240, JUMP_VELOCITY 420 and gravity 980 gives
90 px and 206 px on paper and measured 93.6 px apex and 212 px reach here, because the fixed
step integrates in whole ticks. Fall gravity, air acceleration, collider width and landing
higher all change the number again. Size required gaps at about 0.7 of the measured reach and
keep gaps near 0.95 for optional challenges. For 3D, swap in StaticBody3D,
WorldBoundaryShape3D and CharacterBody3D.
2. Pacing as data, with a check
# Author the level as beats with an intended intensity (0..1), then check the curve.
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 },
]
# Returns the pacing problems in a beat list; empty means it passes.
func pacing_problems(beats: Array, high := 0.7, max_high_run := 2) -> PackedStringArray:
var problems := PackedStringArray()
var run := 0
for i in beats.size():
var beat: Dictionary = beats[i]
run = run + 1 if beat["intensity"] >= high else 0
if run > max_high_run:
problems.append("%s: %d high-intensity beats in a row" % [beat["room"], run])
if beat["type"] == "climax" and (i == 0 or beats[i - 1]["type"] != "rest"):
problems.append("%s: no rest beat right before the climax" % beat["room"])
if not beats.is_empty() and beats[0]["type"] != "teach":
problems.append("%s: the level does not open with a teach beat" % beats[0]["room"])
return problems
The thresholds are a starting point for the user's game. Drive spawn density and music intensity from the same table so the built level matches the plan.
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" } ] },
}
# Search (room, held keys) states: keys from mutually exclusive one-way branches
# must not be combined. Keys are never consumed and doors never re-lock; model
# consumable keys as counts and persistent door changes as additional state.
# States grow exponentially with distinct keys; fine for hand-built room graphs.
func goal_reachable(rooms: Dictionary, start: String, goal: String) -> bool:
var pending: Array[Dictionary] = [{"room": start, "keys": {}}]
var visited := {} # "room|sorted keys" -> true
while not pending.is_empty():
var state: Dictionary = pending.pop_back()
var room: String = state["room"]
var have: Dictionary = state["keys"].duplicate()
var info: Dictionary = rooms.get(room, {})
var grant = info.get("grants")
if grant != null:
have[grant] = true
var names := PackedStringArray(have.keys())
names.sort()
var id := room + "|" + ",".join(names)
if visited.has(id):
continue # cycles stop only at an equivalent state
visited[id] = true
if room == goal:
return true
for exit in info.get("exits", []):
var open: bool = not exit.has("needs") or have.has(exit["needs"])
if open:
pending.append({"room": exit["to"], "keys": have})
return false
# 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.
Exits are one-way: write both directions for a normal door and one direction for a drop. Also
call goal_reachable from every room the player can reach back to the start or a save point if
the level must never trap them; a one-way drop into a dead end fails that call.
Check it
- Reachability: run
goal_reachablefor start to goal in a headless test (followgodot-gdscript-headless-testing), plus from each one-way drop's landing room back to a save or exit. Anyfalseis a soft-lock to fix before anything else. - Metrics: run Pattern 1 after every movement change. List each required gap and ledge in the blockout and compare it to the measured reach; anything above about 0.7 of the reach on the critical path needs a reason.
- Pacing:
pacing_problems(BEATS)returns empty, or each remaining line is a deliberate choice you can explain to the user. - Playtest by proxy. You cannot watch players, so ask the user for specific reports, for example: "Play from the start to the boss once without help. Tell me where you were unsure where to go, any jump you failed more than three times, any room that felt like a chore, and how long the run took." Map each report to the room graph and fix the blockout, not the art.
Gotchas
- Dressing before it plays. Art on an unvalidated blockout is the most expensive work on the layout most likely to change.
- Metrics from formulas only. The ideal arc overstates or understates the real reach depending on the step, fall gravity and collider. Measure the real controller.
- Validating connectivity but not order. A flood fill says every room is connected while the key still sits behind its own door. Track held keys, as Pattern 3 does.
- Two-way edges written as one-way (or the reverse) make the check pass on a level that traps players, or fail on one that does not. Write each exit as the player can use it.
- Flat pacing. Wall-to-wall combat or wall-to-wall calm numbs players. Alternate, and put a rest and a save before the climax.
- Testing a mechanic before teaching it. The first meeting with a hazard should be safe.
- Guidance by wall. Lost players usually need a sightline, light or landmark, not a barrier.
- One-way drops with no signposting strand or surprise players. Telegraph irreversible moves.
- Authored pacing expected from a generator. Generation gives variety, not intent; use
procedural-genfor variety and author the beats that need intent.
References
references/pacing-and-flow.md: read when shaping the tension curve, designing the introduce-develop-twist-test loop for a new mechanic, choosing gating tools, guiding players through 2D or 3D space, or running a blockout review.
Related skills
platformer: jump tuning that produces the metrics; re-measure after it changes.procedural-gen: generated layouts that complement authored structure.godot-tilemap,unity-tilemap-2d: painting the 2D grid.game-ai: enemies that navigate the space;camera-systems: what the player can see.
Version notes
Last verified: 2026-11-11.
- Godot 4.7:
CSGShape3Ddocs say CSG has a significant CPU cost and is meant for prototyping;bake_static_mesh()andbake_collision_shape()turn it into static resources (https://github.com/godotengine/godot/blob/4.7-stable/modules/csg/doc_classes/CSGShape3D.xml). - The jump measurement, pacing check and reachability check were run on Godot 4.7.2 headless.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |