> ## Documentation Index > Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt > Use this file to discover all available pages before exploring further. # Design level skill for AI agents > Design one level (layout, pacing, encounters, secrets) as a design doc plus a node-tree skeleton. A Summer Engine skill for AI agents. `design-level` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Design one level (layout, pacing, encounters, secrets) as a design doc plus a node-tree skeleton. | | | | - | - | | Status | Stable | | Domains | Level design, Game design | | Version | `1.0.3` | | Engine version | `>=4.6` | | Recommended set | Yes, installed by `--recommended` | ## When your agent uses it * Designing a single level — layout, pacing, encounters, secrets, reward gating * Turning a level idea into a layout with a critical path, encounters, secrets, and pacing beats ## Install `summer setup` installs every skill for your agent. To add only this one: ```bash theme={null} npx -y summer-engine@latest skills install design-level --agent claude-code ``` Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option. ## The skill ## Overview A level is a controlled sequence of player experiences in physical space. Layout, pacing, encounters, secrets, and reward gating must work together — a "fun layout" with a flat pacing curve still feels boring. This skill walks the six design beats of a single level and drops a node-tree skeleton ready for `summer_create_scene`. **Core principle:** A level has a *pacing curve* and a *teaching arc*. If you can't draw the tension graph and name what the player learned by the end, the level isn't designed yet. ## Steps ### 1. Pin the level type Ask exactly one question: > What kind of level? Pick one: tutorial / hub / combat encounter / boss / exploration / puzzle / stealth / platforming-challenge / mixed. Each type has different beats. Don't blend types in v1 — a "boss room with stealth and puzzles" is three levels poorly squeezed into one. ### 2. Read context If `.summer/GameSoul.md` exists, read it. The level must serve the brief's core loop and the three mechanics. ``` Read .summer/GameSoul.md ``` If `.summer/mechanics/` exists, list the mechanics. Quote them back: > Brief says mechanics are: dash, parry, double-jump. This level should *exercise* at least one and ideally combine two. ### 3. Define the teaching / experience goal Ask plain: > What does the player know by the end of this level that they didn't at the start? Tutorial-level answer: "How to dash." Combat-encounter answer: "That parrying converts damage to mana, and that big enemies need parry, not dodge." Exploration answer: "That this region's secrets are hidden behind double-jumpable gaps." If the user can't answer, the level has no purpose. Say it: > If there's no answer to that question, the level is filler. Either give it a teaching goal, give it a *failure-state* goal (the player must die here to progress), or merge it into the next level. ### 4. Sketch the pacing curve Draw it as text. Five beats, intensity 0-10: ``` Intro Build Peak Release Hook 2 → 5 → 8 → 3 → 6 ``` For a 5-minute encounter level: | Beat | Duration | Intensity | Player feels | Designer plants | | - | - | - | - | - | | Intro | 30s | 2 | Calm, oriented | Visual landmark for the goal direction | | Build | 90s | 5 | Tension rising, small pressure | First weak enemy / first puzzle clue | | Peak | 60s | 8 | Stakes high, mistakes hurt | Main encounter / hardest fight | | Release | 60s | 3 | Catharsis, loot | Reward + breath room | | Hook | 30s | 6 | Curiosity for next | Visible-but-locked secret or path | Show the curve. Ask: > Pacing above. Does the peak land where you want, or does the level need a second wave? ### 5. List encounters and secrets Encounters = explicit player tests (combat, puzzle, platforming). Secrets = optional rewards that respect the pacing curve. State them flat. For a combat encounter level: ``` Encounters (in player-traversal order): 1. E1 — Tutorial enemy (1 weak grunt) at 0:30, in the open atrium. Teaches the basic attack. 2. E2 — Forced parry (mid-tier enemy with telegraphed wind-up) at 1:30, in a corridor with no dodge room. Teaches parry. 3. E3 — Mixed wave (2 grunts + 1 parry-required) at 3:00, in the peak arena. Tests both. 4. E4 — Mini-boss at 4:00 in the chamber. Combines. Secrets (3 total — one per beat after intro): - S1 (build beat): Behind a breakable wall in the corridor, holds 50 currency. Teaches "walls can break". - S2 (peak beat): Visible from the arena, accessible only via parrying off an enemy. Rewards mastery. - S3 (hook beat): Locked door, key in a future level. Plants curiosity for next level. ``` ### 6. Define reward gating What's behind which gate? Levels feel cheap when they hand out rewards without respecting the difficulty curve. | Reward | Gate | Why | | - | - | - | | Heal pickup | After E2 | Player just learned parry; reward + safety net before the peak | | New ability unlock | After mini-boss | Mastery-pinned; player demonstrates parry before getting upgrade | | Currency cache | Behind S1 (breakable wall) | Optional; rewards observation | | Story note | At the calm intro | Free; orients the player to the level's narrative | Ask: > Reward gating above. Anything missing or mis-placed? ### 7. Define the layout primitives Every level is built from a small vocabulary of spaces. Name them. Most levels need 4-6 distinct spaces, no more. For a combat-encounter level: ``` Spaces (node-tree skeleton): World (Node3D) ├── Geometry (Node3D) │ ├── IntroAtrium (Node3D) # open, calm, well-lit │ ├── Corridor (Node3D) # tight, forces parry │ ├── PeakArena (Node3D) # large, multiple cover, exit visible │ └── BossChamber (Node3D) # contained, single exit, dramatic lighting ├── Spawns (Node3D) │ ├── PlayerSpawn (Node3D) # marker │ ├── E1_Spawn (Node3D) │ ├── E2_Spawn (Node3D) │ ├── E3_Wave_Spawns (Node3D) │ └── MiniBoss_Spawn (Node3D) ├── Triggers (Node3D) │ ├── E2_GateTrigger (Area3D) # locks door behind player on entry │ ├── PeakWaveTrigger (Area3D) │ └── BossDoorTrigger (Area3D) ├── Pickups (Node3D) │ ├── HealAfterE2 (Node3D) │ └── CurrencyS1 (Node3D) ├── Secrets (Node3D) │ ├── S1_BreakableWall (StaticBody3D) │ ├── S2_ParryLedge (StaticBody3D) │ └── S3_LockedDoor (StaticBody3D) └── Lighting (Node3D) # WorldEnvironment + DirectionalLight3D ``` Show the skeleton. Ask: > Tree above. May I create the level scene `levels/.tscn` with this skeleton? ### 8. Scaffold via MCP **Preferred (Summer MCP):** create the scene, then build the whole skeleton in one script. `summer_create_scene` takes `path`, `rootName` and `rootType` (default `Node3D`) and writes the new scene to disk without opening it. `summer_run_script` with that `scenePath` opens it, runs, and gives the user their tab back; the run is one undo step, so one Ctrl+Z removes the skeleton. ``` summer_create_scene(path="res://levels/level_01.tscn", rootName="World", rootType="Node3D") summer_run_script(scenePath="res://levels/level_01.tscn", source=""" func run(ctx): var skeleton = { "Geometry": [["Node3D", "IntroAtrium"], ["Node3D", "Corridor"], ["Node3D", "PeakArena"], ["Node3D", "BossChamber"]], "Spawns": [["Node3D", "PlayerSpawn"], ["Node3D", "E1_Spawn"], ["Node3D", "E2_Spawn"], ["Node3D", "E3_Wave_Spawns"], ["Node3D", "MiniBoss_Spawn"]], "Triggers": [["Area3D", "E2_GateTrigger"], ["Area3D", "PeakWaveTrigger"], ["Area3D", "BossDoorTrigger"]], "Pickups": [["Node3D", "HealAfterE2"], ["Node3D", "CurrencyS1"]], "Secrets": [["StaticBody3D", "S1_BreakableWall"], ["StaticBody3D", "S2_ParryLedge"], ["StaticBody3D", "S3_LockedDoor"]], "Lighting": [["WorldEnvironment", "WorldEnvironment"], ["DirectionalLight3D", "Sun"]], } for group in skeleton: var parent = ctx.add_node("Node3D", group) for child in skeleton[group]: ctx.add_node(child[0], child[1], parent) ctx.report("skeleton", ctx.summary()) ctx.save_scene() """) ``` Compare the `skeleton` report (node counts by class) with the tree you showed the user, then `summer_get_scene_tree` on the new scene. This is a **skeleton, not playable geometry**. Markers and Area3Ds, no meshes, no enemy scripts. Implementation in subsequent sessions / templates. **Fallback (no MCP):** Print the `.tscn` file contents for the user to save manually. ### 9. Save the level design doc Always write the design doc — it's the artifact that drives implementation. Path: `.summer/levels/.md`. ```markdown theme={null} # Level: **Type:** combat encounter **Duration target:** 5 min **Teaching goal:** Player learns parry and that parrying mid-tier enemies is required, not optional. **Pacing curve:** 2 → 5 → 8 → 3 → 6 **Beats:** Intro (30s) | Build (90s) | Peak (60s) | Release (60s) | Hook (30s) ## Encounters - E1 — Tutorial grunt @ 0:30 (IntroAtrium) - E2 — Forced parry @ 1:30 (Corridor) - E3 — Mixed wave @ 3:00 (PeakArena) - E4 — Mini-boss @ 4:00 (BossChamber) ## Secrets - S1 — Breakable wall (Corridor) → 50 currency - S2 — Parry-ledge (PeakArena) → cosmetic - S3 — Locked door (BossChamber) → next level ## Reward Gating - Heal pickup after E2 - Ability unlock after mini-boss ## Spaces 1. IntroAtrium — open, calm 2. Corridor — tight, forces parry 3. PeakArena — large with cover 4. BossChamber — contained, dramatic ## Open questions ``` Ask: > May I create `.summer/levels/.md` with this design doc? ### 10. Route to the next step End with: > Skeleton + design doc saved. Next: > > * `/design-mechanic` to design any mechanics this level requires that aren't designed yet. > * `/design-npc` to design the enemies (E1-E4) in detail. > * `/art-direction` if the visual style isn't pinned yet. > * Or open `levels/.tscn` and start blocking out geometry. ## Common mistakes | Mistake | Fix | | - | - | | No teaching goal | Every level teaches something or fails. State it explicitly. | | Flat pacing curve | If intensity stays at 5 the whole time, you have a hallway, not a level. | | Too many spaces | 4-6 distinct spaces max. More fragments the player's mental map. | | Encounters not tied to mechanics | E2 should *require* parry, not just allow it. Forced use teaches; optional use doesn't. | | Secrets ignore the pacing curve | Don't put a major secret in the calm intro — players aren't curious yet. | | Reward gating too generous | Free heals before the peak deflate the peak. Gate them after the test. | | Blending level types | Stealth + puzzle + boss in one level = three half-baked levels. Pick one. | | Building geometry before the skeleton | Skeleton-first lets you iterate on layout cheaply. Geometry comes after the design is locked. | | Calling SetResourceProperty before the property holds a resource | Explicit `resource is null` error, not a silent drop. Assign the resource first (`summer_set_prop key="mesh" value="BoxMesh"`), then set its sub-properties. Scene-embedded sub\_resources are fully supported targets. | ## Collaborative protocol This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. ## Want a working starter? This is a workflow that produces a skeleton scene. For runnable level examples, see: * `summer create 3d-fps-old-school` ships a sample arena. * `summer create 3d-third-person-controller` gives a jump-capable character to test level layouts against. The skeleton this skill produces is meant to be filled in via `/design-mechanic`, gridmap blockout, or a template merge. ## See also * `brainstorm-game` — produces `.summer/GameSoul.md` * `design-mechanic` — designs the verbs the level exercises * `design-npc` — designs the enemies the encounters reference * `3d-lighting` — sets the lighting in `WorldEnvironment` + lights * `art-direction` — defines the visual style the level expresses ## From a shell No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input ''`, and `summer ops describe ` prints the exact input. The `summer-cli` skill has the rest. | In this skill | Command | | - | - | | `summer_add_node` | `summer engine add-node` | | `summer_create_scene` | `summer engine create-scene` | | `summer_get_scene_tree` | `summer engine get-scene-tree` | | `summer_get_script_errors` | `summer engine get-script-errors` | | `summer_open_scene` | `summer engine open-scene` | | `summer_run_script` | `summer engine run-script` | | `summer_save_scene` | `summer engine save-scene` | | `summer_set_prop` | `summer engine set-prop` | ## Related skills * [`design-npc`](/skills/design-npc): Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub. * [`design-mechanic`](/skills/design-mechanic): Design one mechanic in detail (input, feedback, failure modes, tunables) as a doc plus a script stub. * [`3d-lighting`](/skills/3d-lighting): Light a 3D scene: sun, omni and spot lights, WorldEnvironment, sky, shadows and ambient. * [`art-direction`](/skills/art-direction): Define the game's visual style (palette, mood, lighting, post) as an art bible in .summer/art-bible.md. * [`brainstorm-game`](/skills/brainstorm-game): Turn a vague game idea into a 1-page brief (genre, scope, core loop, mechanics) in .summer/GameSoul.md. *** Source: [`library/skills/design-level/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/design-level/SKILL.md), rendered from `summer-engine@4.3.0` on npm. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.