roguelike

# Roguelike generation, FOV, and loot (depth)

Algorithms behind the systems in `SKILL.md`. Engine-neutral pseudocode. For the noise/RNG
primitives and seeding, defer to `procedural-gen`; this file is the roguelike-specific glue.

## 1. Dungeon generation approaches

Pick by the *texture* you want. All must end with a **connectivity pass** (§2).

### Rooms-and-corridors (classic, readable)

```python
# Place non-overlapping rooms, then connect their centers with L-shaped tunnels.
rooms = []
for _ in range(MAX_ROOMS):
    r = random_rect(rng, min=4, max=10)
    if any(r.intersects(other.expand(1)) for other in rooms):
        continue                      # reject overlaps (expand by 1 to keep walls between)
    carve_room(map, r)
    if rooms:                         # connect to the previous room
        carve_h_then_v(map, rooms[-1].center, r.center, rng)
    rooms.append(r)
# First room = player spawn; last/farthest room = stairs down.
```

### BSP (binary space partition — tidy, building-like)

Recursively split the map rectangle into sub-rectangles; place one room per leaf; connect
sibling rooms as you unwind the recursion. Produces evenly distributed, non-overlapping rooms.

### Cellular automata (organic caves)

```python
# Random fill, then smooth with the "4-5 rule": a cell is wall in the next map if 5 or more of
# the 9 cells in its 3x3 block (itself included) are walls. Same thing: a wall stays a wall with
# 4+ wall neighbours; a floor becomes wall with 5+.
fill_random(map, wall_chance=0.45, rng=rng)
for _ in range(5):                         # 4–5 passes is typical
    new_map = copy(map)                    # read the old map, write a new one
    for cell in map:
        walls = count_walls_3x3(map, cell) # out-of-bounds cells count as walls (solid border)
        new_map[cell] = WALL if walls >= 5 else FLOOR
    map = new_map
# Then keep only the largest connected floor region (discard isolated pockets).
```

Updating the map in place while scanning it makes earlier cells influence later ones in the same
pass, which smears caves in the scan direction. Always write to a second buffer.

### Drunkard's walk (cheap, winding)

Start at a point and random-walk, carving floor, until a target floor percentage is reached.
Guaranteed connected (one continuous path) but can be too snaky without tuning.

## 2. Connectivity (never skip this)

```python
# Flood-fill from the player's start; any walkable cell not reached must be connected or removed.
reached = flood_fill(map, player_start)
regions = find_disconnected_floor_regions(map, reached)
for region in regions:
    carve_corridor(map, nearest_cell(reached), nearest_cell(region), rng)
# Re-flood and assert: every floor cell is now reachable.
```

For caves, the common shortcut is to keep only the single largest region and discard the rest.

## 3. Field of view — symmetric shadowcasting

Properties you want: **symmetric** (if floor tile A sees floor tile B, B sees A), no blind
corners, and walls that light up as you walk along them. Classic recursive shadowcasting (eight
octants, tiles shown if they touch the visible slope range) is fast but breaks symmetry.
*Symmetric shadowcasting* (Albert Ford, 2021) fixes it with one rule: a **floor** tile is
visible only if its **centre** lies inside the visible slope range; a **wall** tile is visible
if any part of it does.

```python
# Pseudocode. Scan each of the 4 quadrants (N, E, S, W) row by row, moving away from the origin.
# Slopes are col/depth; keep them as exact fractions (rationals), not floats, so the edge
# tests do not wobble. (depth, col) is mapped to (x, y) per quadrant by a small transform.
def scan(quadrant, depth, start, end):           # first call: depth=1, start=-1, end=+1
    prev_wall = None
    for col in range(round_half_up(depth * start), round_half_down(depth * end) + 1):
        wall = is_wall(quadrant, depth, col)
        centre_inside = depth * start <= col <= depth * end
        if wall or centre_inside:
            mark_visible(quadrant, depth, col)
        if prev_wall is True and not wall:        # leaving a wall: narrow the start
            start = Fraction(2 * col - 1, 2 * depth)
        if prev_wall is False and wall:           # hitting a wall: scan the gap before it
            scan(quadrant, depth + 1, start, Fraction(2 * col - 1, 2 * depth))
        prev_wall = wall
    if prev_wall is False:                        # row ended on floor: continue outward
        scan(quadrant, depth + 1, start, end)
```

`round_half_up(x)` is `floor(x + 1/2)` and `round_half_down(x)` is `ceil(x - 1/2)`. The origin
tile is always visible and treated as not blocking. Stop recursing at the map edge or at your
light radius, and use a circular check (`dx*dx + dy*dy <= R*R`) for a round light rather than a
square one.

Test it: on random maps, compute FOV from every floor tile and assert that whenever A sees B,
B sees A. This version passes that test; classic recursive shadowcasting does not.

Implementation notes:
- Keep `explored` separately; render explored-but-not-visible cells dimmed.
- Recompute only when the viewer moves or a door/wall changes, not every frame.

## 4. Weighted, depth-scaled loot and spawn tables

```python
# A drop table is a list of (entry, weight). Weight is relative, not a probability.
goblin_loot = [
    ("nothing",      60),
    ("gold_small",   25),
    ("healing_potion", 10),
    ("rare_scroll",   5),
]
def roll(table, rng):
    total = sum(w for _, w in table)
    pick  = rng.range(0, total)        # [0, total)
    upto  = 0
    for entry, w in table:
        upto += w
        if pick < upto:
            return entry

# Depth scaling: shift weights toward stronger entries as depth increases,
# e.g. add depth-gated entries or multiply rare weights by a depth factor.
```

Design guidance:
- Keep "nothing"/common as the bulk of weight so rares stay exciting.
- Gate powerful items behind a minimum depth so early runs can't snowball.
- Separate **monster** spawn tables from **item** drop tables; both scale with depth.
- For "exactly one of" results use weighted pick; for "each may drop" iterate independent rolls.

## 5. Run vs. profile state (permadeath + meta-progression)

- **Run state** (current dungeon, HP, inventory, seed): lives only during the run. For *true*
  permadeath, delete or invalidate this save the moment it is loaded so it cannot be reloaded.
- **Profile state** (unlocked items/classes, high scores, achievements, currency): persists
  across deaths. This is what a roguelite spends on meta-progression.
- Keep them in separate files/sections so wiping a run never touches the profile (see
  `save-systems` for slot/versioning details).

---
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

```python
# 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)

```python
# 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

```python
# 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 corridors until every walkable cell is reachable.
- **Naive FOV** → vision that flickers or is asymmetric (you see them, they don't see you).
  Use symmetric shadowcasting and test symmetry (refs §3).
- **One actor never gets a turn** → energy granted inside the "find who is ready" loop
  (Pattern 2). Advance energy for all actors in its own pass.
- **Real-time loop pretending to be turn-based** → input races and double-moves. Resolve one
  discrete turn at a time; queue input.
- **Flat difficulty** → no descent pressure. Scale monsters/loot by depth and keep resources scarce.
- **Permadeath that wipes meta-unlocks** → frustration. Separate *run* state (wiped) from
  *profile* state (unlocks, scores) when saving (see `save-systems`).
- **Save-scumming a "permadeath" game** → delete or invalidate the run save on load if you want
  true permadeath; keep only the profile.
- **Unreadable state** → the player can't plan. Show HP, turn results, and a message log.

## Composition (build it from these skills)

- **Generation:** `procedural-gen` (noise, seeded RNG, dungeon/room algorithms) — the engine of replayability.
- **Map rendering:** `godot-tilemap` / `unity-tilemap-2d` for the grid; `level-design` for set-piece rooms/vaults.
- **Enemies:** `game-ai` for monster decision-making (often simple on a grid: seek/flee/patrol).
- **Persistence:** `save-systems` for run-resume, profile/meta-progression, and true permadeath wipes.
- **Scripting/data:** `godot-resources` / `unity-scriptableobjects` to define items, monsters, and drop tables as data.
- **UI:** `godot-ui-control` for the message log, inventory, and HUD.
- **Feel:** `game-feel` for hit/death juice — screen shake and hit-stop that sell impacts on a turn-based grid.

## References

- For dungeon-generation algorithms (rooms-and-corridors, BSP, cellular automata, connectivity),
  FOV (shadowcasting), and weighted loot/spawn tables, read `references/generation-fov-loot.md`.