Procedural Level Generation Design

Source: Extracted and expanded from master_gdd.md §6.
Status: DRAFT — grammar rules need prototyping to validate.

---

Table of Contents

1. Philosophy
2. Pipeline
3. Biome Palettes
4. Mission Templates
5. Grammar Rules
6. Enemy Placement
7. Solvability Validator
8. Dynamic Events
9. Hand-Crafted Content
10. MVP Scope
11. Open Questions

---

1. Philosophy

Template + Fill. Not random noise — procedural generation that creates tactical puzzles.

Every generated map must:

1. Be solvable (at least 2 valid opening moves)
2. Be readable (height differences, LOS, hazards are obvious)
3. Feel distinct (no two maps play identically)
4. Reward positioning (the map is the primary tactical challenge)

---

2. Pipeline

BIOME SELECT → TEMPLATE SELECT → GRAMMAR GENERATE → ENEMY PLACE → VALIDATE + POLISH

Stage Details

Stage	Input	Process	Output
1. Biome	Island number	Selects tile palette, hazard types, cover types, height constraints, dynamic events	BiomeConfig
2. Template	Node type	Selects deployment zones, objective markers, win/loss conditions, special rules	TemplateConfig
3. Grammar	Grid + Biome + Template	Applies generation rules in priority order	Populated grid
4. Enemies	Grid + Node difficulty	Places enemies with valid behaviors and LOS	Enemy placements
5. Validate	Complete map	Runs solvability checks, fixes or re-rolls on failure	Validated map

Generation Time Target

• < 2 seconds per map (non-blocking load screen)
• If validation fails: re-roll with new seed (max 5 attempts, then relax constraints)

---

3. Biome Palettes

Island 1: Fractured Plains

Element	Palette
Base tiles	Grass, dirt, cobblestone, wildflowers
Water	Shallow water (slows movement, conducts lightning +2 damage)
Height	Hills (+1), cliffs (+2 with ledge), occasional +3 watchtower
Cover	Crumbling walls (HP 3, blocks LOS), ruined archways, wooden barricades
Hazards	Shallow water, healing springs (+3 HP/tick), ancient obelisk (blesses adjacent tiles)
Atmosphere	Sunny, scattered clouds, birds

Island 2: Ashen Caldera

Element	Palette
Base tiles	Ash, scorched earth, obsidian, basalt
Water	None (replaced by lava, steam vents)
Height	Magma uplifts (+1,+2), caldera rim (+3)
Cover	Basalt pillars (HP 5, explodes on destruction: 3 damage AoE 1), smoke vents (blocks LOS)
Hazards	Lava (5 damage/tick), steam vent (launches unit +1 height, 3 damage), ember storm (random tile takes 3 fire damage every 3 ticks)
Atmosphere	Red-orange glow, ash particles, heat shimmer

Island 3: Spire of Echoes (v0.2 — deferred)

Full biome palette designed but deferred to post-MVP. Floating platforms, void pits, teleport pads, energy barriers, crystal spires, time rifts. Boss: Time Warden (manipulates CT timeline).

---

4. Mission Templates

4.1 Standard

Property	Value
Player deploy	Left 2 columns (x=0,1), all y, ground height (0)
Enemy deploy	Right 2 columns (x=6,7), all y, ground height (0)
Win condition	Defeat all enemies
Grid emphasis	Height variety, cover between deploy zones, 2+ routes
Grammar rules	Standard set (see §5)

4.2 Ambush

Property	Value
Player deploy	Center 4×4 area (x=2–5, y=4–7)
Enemy deploy	Perimeter — all tiles at distance ≥ 4 from center
Win condition	Survive 8 turns OR defeat all enemies
Lose condition	All units dead (not just surviving — must actively survive)
Grid emphasis	Cover near center, height disadvantage for player, multiple approach paths
Grammar rules	Player zone: cover-rich, flat. Enemy zone: height advantage, hazards.
Rewards	+50% gold, relic choice of 5 instead of 3

4.3 Escort

Property	Value
Player deploy	Left 2 columns (x=0,1)
NPC deploy	Center-left (x=2, y=6), ground height
Enemy deploy	Right 2 columns + reinforcement spawns at edges on turn 4
Win condition	NPC reaches exit tile (x=7, right edge)
Lose condition	NPC dies OR all player units dead
NPC behavior	Moves toward exit each turn (2 tiles/turn). Cannot be controlled by player.
NPC stats	HP 20, DEF 2, SPD 5. Will path around hazards if safe route exists.
Grid emphasis	Clear path to exit, enemies along route, cover for player to body-block
Grammar rules	Exit path must be walkable, no dead ends on route, at least 2 body-block positions

4.4 King of the Hill

Property	Value
Player deploy	Edge columns (x=0,7)
Enemy deploy	Edge columns (opposite side from player)
Objective	Central +3 height tile. At end of turn 5: team with most units on or adjacent to hill gains +50 CT for all units.
Win condition	Defeat all enemies (hill bonus is objective, not win condition)
Grid emphasis	Central hill with multiple approach paths, cover on approach, hazard barriers
Grammar rules	Hill must be reachable in 3 turns from any deploy. At least 3 approach paths.

4.5 Boss

Property	Value
Generation	None. 100% hand-crafted.
Grid	Fixed layout per boss.
Enemy deploy	Boss in predetermined position.
Win condition	Defeat boss.
Special	Boss arena hazards, phase transitions, unique terrain.

---

5. Grammar Rules

Rules are applied in priority order. Each rule can be deterministic or have random elements within constraints.

Height Grammar

HEIGHT-H1 (HILL_CLUSTER): Place 1–3 raised tiles (+1 or +2) in a connected cluster.
  Constraint: cluster must be ≥ 3 tiles from any deploy zone.
  Constraint: cluster must not block all paths between deploy zones.

HEIGHT-H2 (TOWER): Place 1 +3 tile.
  Constraint: tower must have at least 2 adjacent +2 or +1 tiles (ramp).
  Constraint: tower must be ≥ 4 tiles from enemy deploy (no enemy snipers on turn 1).

HEIGHT-H3 (PIT): Place 1–2 −1 water/lava/void tiles.
  Constraint: not within 2 tiles of any deploy zone.
  Constraint: not on the critical path between deploy zones (alternate route must exist).

HEIGHT-H4 (RAMP): Every +2 or higher tile must have an adjacent tile that is exactly 1 height lower.
  Ensures: no isolated pillars. Everything is reachable.

Cover Grammar

COVER-C1 (WALL_LINE): Place 2–4 cover objects in a line, spaced 1 tile apart.
  Primary axis: perpendicular to the line between deploy zones (create LOS breaks).

COVER-C2 (PILLAR_PAIR): Place 2 cover objects within 2 tiles of each other.
  Creates: "doorway" effect — two pillars with a gap between them.

COVER-C3 (SOLO_COVER): Place 1 cover object.
  Constraint: must create a valid LOS break between at least one enemy deploy tile and one player deploy tile.

COVER-C4 (NO_COVER_DEATH_TRAP): No cover within 2 tiles of any enemy deploy tile.
  Ensures: enemies don't spawn already protected.

Hazard Grammar

HAZARD-HZ1 (HAZARD_POOL): Place 2–3 hazard tiles in a cluster.
  Type: depends on biome (water, lava, void).
  Constraint: not within 2 tiles of any deploy zone.

HAZARD-HZ2 (HAZARD_LINE): Place 3–5 hazard tiles in a line (width 1).
  Creates: "river" or "lava flow" cutting across part of the map.
  Constraint: must have at least 2 crossing points (tiles where units can pass without stepping in hazard).

HAZARD-HZ3 (HAZARD_ADJACENT_COVER): If cover exists near hazard: 50% chance hazard extends to adjacent tile.
  Creates: tactical risk — using the cover means standing near danger.

Path Grammar

PATH-P1 (CONNECTIVITY): From any player deploy tile, flood-fill to verify all tiles are reachable (max 6 move).
  On failure: add ramp or remove blocker.

PATH-P2 (TWO_ROUTES): At least 2 non-overlapping paths must exist between player and enemy deploy zones.
  On failure: remove cover or hazard blocking one route.

PATH-P3 (NO_ISOLATION): No tile is surrounded by impassable terrain on all 4 sides.
  Exception: intentional dead-end created as a tactical choice (COVER-C1 wall ends).

PATH-P4 (MIN_MOVE_TO_CENTER): Center tile of map must be reachable from player deploy in ≤ 3 moves (base speed 5).
  Ensures: engagement by turn 2.

---

6. Enemy Placement

Placement Rules

Rule	Constraint
Deploy buffer	No enemies within 2 tiles of any player deploy tile.
LOS for casters	At least 1 enemy caster per fight must have LOS to player deploy from starting position.
Melee proximity	At least 1 melee enemy per fight within 4 tiles of player deploy (reachable in 2 turns).
Flanker placement	Flanker-type enemies placed on alternate routes (not the main path).
Cover usage	Guardian-type enemies placed adjacent to cover or objectives.
No first-turn kills	No enemy can target a player unit on turn 1 with damage > 50% of that unit's max HP.
Variety	At least 2 different enemy types per fight.

Placement Algorithm

1. Sort enemy list by type priority (Guardians first, then Artillery, then Brutes, then Flankers)
2. For each enemy:
   a. Find all tiles matching placement constraints for this enemy type
   b. Score each tile: proximity to intended target + terrain advantage + distance from other enemies
   c. Place at highest-scoring tile
3. Final sweep: if any deploy zone has no enemy within 4 tiles, place additional melee enemy

Enemy Count

Node Type	Common Enemies	Elite Enemies	Total
Fight (Island 1)	3–4	0	3–4
Fight (Island 2)	3–5	0–1	4–6
Fight (Island 3)	4–5	0–1	4–6
Hard Fight	3–4	2–3	5–7
Boss	0–2 (adds during fight)	0	1 boss + spawns

---

7. Solvability Validator

Checks (Run in Order)

#	Check	Failure Action
1	No enemy can one-shot a player unit at full HP on turn 1.	Reduce enemy ATK or move enemy further from deploy.
2	At least 2 opening moves exist that negate ≥ 50% of turn-1 threats.	Add cover or reduce enemy count.
3	No unit can be surrounded (4 enemies on 4 sides) with zero escape options.	Move at least 1 enemy.
4	All caster enemies target tiles that are potentially occupied at spell-land time (not empty tiles, unless the caster targets AoE for zone denial).	Re-assign caster targets.
5	Map is fully connected (all tiles reachable from all deploy zones).	Add ramps, remove blockers.
6	At least 1 non-combat tile exists per 4 tiles of combat space (breathing room).	Remove clutter.
7	No height +3 tile has LOS to player deploy AND an enemy within 2 tiles of it.	Remove enemy or lower tile.
8	Escort NPC path to exit is clear of hazards and < 6 turns at NPC speed.	Clear path or add shortcuts.

Failure Handling

Attempt	Action
1	Re-roll with new seed.
2	Re-roll with relaxed constraints (deploy buffer reduced to 1 tile).
3	Re-roll with minimal constraints (only connectivity + no-one-shot).
4	Fix specific failure by modifying grid directly (remove blocker, add ramp, move enemy).
5	Fallback: load a hand-crafted backup map for this node type + biome.

Goal: 95%+ of maps pass on attempt 1 or 2.

---

8. Dynamic Events

Events that modify the grid mid-battle:

Event	Trigger Turn	Biome	Effect	Telegraph
Cave-in	3	Any	Destroy 3 random walls.	"⚠️ Unstable ceiling" on turn 1
Flood	5	Plains	Water rises +1 height on all ground tiles.	"⚠️ Dark skies" on turn 2
Eruption	4	Caldera	Geyser at marked tile launches unit to +3.	Geyser marker from turn 1
Reinforcements	4 or 6	Any	2–3 additional enemies spawn at map edges.	"⚠️ Reinforcements incoming" on turn 2

Spire dynamic events (Time Quake, Platform Shift) deferred to v0.2.

Event Rules

• Max 1 dynamic event per battle (except Boss fights, which can have multiple phase-based events).
• Events are telegraphed at least 1 turn before they occur.
• Events never kill a unit outright (damage can reduce to 1 HP, displacement lands on nearest safe tile).

---

9. Hand-Crafted Content

What's Always Hand-Crafted

Content	Reason
Boss maps	Fixed arenas with specific mechanics. Cannot procedurally generate a satisfying boss fight.
Event text	MYSTERY nodes are written, not generated. Flavor text is injected procedurally (character names, item names).
Island themes + palettes	Fixed. Procedural gen varies within the palette.
Tutorial	First fight of Island 1: hand-crafted to teach basic mechanics.

Hand-Crafted Backup Maps

• 2 per template per biome = 2 × 4 × 2 = 16 total for MVP.
• Used only as fallback when generation fails all attempts.
• Also used as curated "special" maps that can appear rarely.

---

10. MVP Scope

Included

• [x] 2 biomes: Plains + Caldera
• [x] 4 templates: Standard, Ambush, Escort, King of the Hill
• [x] Grammar engine: Height, Cover, Hazard, Path
• [x] Solvability validator (all 8 checks)
• [x] Dynamic events: Cave-in, Flood, Eruption, Reinforcements
• [x] Hand-crafted boss maps (2 bosses: Golem, Wyrm)
• [x] Backup hand-crafted maps (16 total: 2 per template × 4 templates × 2 biomes)
• [x] Tutorial map (hand-crafted)

Deferred to Post-MVP

• [ ] Island 3 biome (Spire of Echoes) + Spire dynamic events
• [ ] Ember Storm dynamic event
• [ ] Platform shift mechanics
• [ ] Echo crystal (spell-repeat) hazard
• [ ] Expanded backup map pool (add Spire: +8 maps)
• [ ] Map seed sharing (for community challenge runs)

---

11. Open Questions

1. Grammar engine approach: Rule-based (proposed) vs Wave Function Collapse vs pre-built tilesets. Rule-based is simplest to tune but may produce less organic maps. Prototype needed to validate.
2. Validation threshold: Is 95% first-attempt pass rate realistic for a rule-based grammar? Might need 80% + more fallback maps.
3. Dynamic event frequency: Should every battle have a dynamic event, or only 30–50%? Every battle = more variety but also more chaos. 50% = events feel special.
4. Escort NPC AI: Pathfinding to exit: direct route (shortest path) or safe route (avoid hazards)? Recommendation: safe route. Direct route would path NPC into lava and feel unfair.
5. King of the Hill timer: 5 turns to fight for the hill. Is this enough? Too much? Needs playtesting.
6. Procedural story injection: MYSTERY events are hand-written, but character names and item references are injected. How much procedural text do we need? Is "Brick" inserted into a template like "{Character} finds a {Item}." sufficient, or do we want more sophisticated Mad Libs?

---

Next: Enemy & AI Design