/roguelike

name: roguelike
description: >
  Build a roguelike: turn-based grid movement, procedural dungeons, permadeath, field-of-view,
  and loot tables. Use for a roguelike/roguelite or turn-based grid dungeon crawler with procedural levels.

Roguelike

A playbook for roguelikes — the turn engine, procedural dungeons, field-of-view, permadeath, and run economy. This is a **compositional** skill: it orchestrates procedural generation, tilemaps, save handling, and AI into a run-based game. It does not re-teach noise/RNG or tilemap APIs; it defines the loop and the systems that make a *run* compelling.

When to use

• Use when building a **turn-based, grid-based** dungeon crawler where each death ends the

run and the world is regenerated — a roguelike or "roguelite" (with meta-progression).

• Use when designing procedural dungeons, FOV/fog-of-war, permadeath stakes, or loot tables.

**When *not* to use:** real-time action with roguelike *dressing* → build the action genre (`platformer`/`fps-shooter`) and layer `procedural-gen`. Deep stats/quests/dialogue without permadeath → `rpg`. Open-world needs/crafting → `survival-crafting`.

What makes it a roguelike (design anchor)

The community reference is the **Berlin Interpretation** (RogueBasin, IRDC 2008): a set of "roguelikeness" factors, not a checklist. The high-value ones are the design targets: **random environment generation, permadeath, turn-based, grid-based, non-modal** (all actions in one mode), **complexity** (many item/monster interactions), **resource management**, **hack-and-slash**, and **exploration & discovery**. Lean into these to feel roguelike; pick which to keep deliberately. "Roguelite" usually relaxes permadeath with meta-progression.

Core loop

**Take a turn (move / fight / use) → the world resolves its turn → see new state → descend / loot / survive → die and restart with a fresh dungeon.** Replayability comes from the *world* changing each run, not the player memorizing a fixed layout.

Must-have systems

1. **Turn scheduler** — energy/initiative system so fast actors act more often (Pattern 2). 2. **Grid map + movement** — tile coordinates; bump-to-attack; blocked/walkable queries. 3. **Procedural dungeon generator** — rooms + corridors, or BSP/cellular; guarantee connectivity. 4. **Field of view + explored memory** — what's visible now vs. seen-before (Pattern 3 / refs). 5. **Combat + entities** — HP, attack/defense, status; monsters obey the same rules as the player. 6. **Loot + drop tables** — weighted, depth-scaled item/monster spawning (refs). 7. **Permadeath + (optional) meta-progression** — wipe the run; persist only unlocks/score. 8. **Message log + clear UI** — the player reasons from text/state; surface numbers and events.

Design knobs

| Knob | Effect | Notes | |------|--------|-------| | Dungeon size / room count | run length, density | Scale with depth. | | Connectivity guarantee | no unreachable rooms | Always verify reachability after generation. | | Monster density / depth curve | difficulty ramp | Spawn by depth-weighted table. | | Loot rarity weights | power variance | Rarer = bigger swing; identify adds discovery. | | FOV radius / lighting | tension, information | Smaller radius = scarier, slower. | | Resource scarcity (food/HP/ammo) | pressure to descend | Core tension lever in classic RLs. | | Permadeath vs meta-progression | run stakes vs. retention | Roguelite softens the wall. | | Identification / unknowns | exploration value | Unidentified items reward experimentation. | | Seedable RNG | daily runs, debugging | Always allow a fixed seed (see `procedural-gen`). |

Patterns

1. Deterministic, seedable run RNG

# Pseudocode. One seeded RNG per run makes dungeons reproducible (daily runs, bug repro).
run_seed = chosen_seed or random_seed()
rng = Rng(run_seed)                 # use your engine's seedable RNG, not global random
dungeon = generate_dungeon(rng, depth)   # same seed + depth => same dungeon
# Persist run_seed in the save so a crash can resume the same world (see save-systems).

2. Energy-based turn scheduler (speeds differ)

# Pseudocode. Actors gain energy each tick and act when they have enough.
# Faster actors gain more per tick, so they act more often — no fixed "player then enemies".
TURN_COST = 100
def next_actor(actors):
    while True:
        for a in actors:                 # 1) serve anyone already ready, in a stable order
            if a.energy >= TURN_COST:
                a.energy -= TURN_COST    #    (or the cost of the action they choose)
                return a                 #    this actor takes exactly one action now
        for a in actors:                 # 2) nobody is ready: advance time for everyone at once
            a.energy += a.speed          #    e.g. speed 100 = normal, 150 = hasted, 50 = slowed

Grant energy to everyone in a separate pass. Adding it inside the same loop that returns the first ready actor starves every actor after it: with two speed-100 actors, the first one acts every time and the second never does.

3. Field of view + explored memory

# Pseudocode. Recompute visibility from the player each time they move.
visible = compute_fov(map, player.pos, radius=8)   # symmetric shadowcasting (see refs)
for cell in visible:
    explored.add(cell)                  # remember it forever (dim "fog of war")
# Render: visible -> lit; explored-but-not-visible -> dim; never-seen -> hidden.

Use symmetric shadowcasting (refs §3): if you can see a monster, it can see you. Classic recursive shadowcasting is fast but not symmetric, and a naive raycast per cell gives blind spots and "blinking" vision. If a library is available, use its symmetric mode (python-tcod's `compute_fov` takes `FOV_SYMMETRIC_SHADOWCAST` as its algorithm).

Pitfalls / failure modes

• **Disconnected dungeons** → rooms the player can't reach. Always run a connectivity/flood-fill

pass and carve corridor