allienrpg_03_2026/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Accessible tabletop RPG gaming engine for the Alien RPG space station USCSS CETORHINA. Designed for blind/visually impaired players. Czech UI, English skill names. Runs as Emacs Lisp package within Doom Emacs — minibuffer completion, no file navigation.

## Architecture

**alien-rpg.el** (main engine, ~1660 lines, lexical-binding):

- **Data**: `alien-rpg-rooms` (112 rooms as connection graph), `alien-rpg-decks` (10 decks A-J), `alien-rpg-character` (mutable during session), `alien-rpg-state` (mutable, auto-saved). Station name in `alien-rpg-station-name`.
- **Room IDs**: ASCII slugs (e.g., `B-ridici-stredisko`). Display names use Czech diacritics (`Řídící středisko`).
- **Room data**: Each room has `:id`, `:deck`, `:name`, `:location`, `:note`, `:desc` (accessible description), `:connections`.
- **Navigation**: Graph-based. `alien-rpg-move` (adjacent), `alien-rpg-teleport` (any). `alien-rpg-find-path` uses BFS to find ALL shortest paths. Path display uses bullet points with room names.
- **Corridors as rooms**: Long corridors are modeled as rooms (e.g., `F-chodba` spans entire deck F from centrální šachta to cely). Side rooms connect to the corridor.
- **No průlez rooms**: Průlezy (hatches between decks) are NOT separate rooms. They are direct connections between the rooms they physically sit in. Cross-deck connections noted in room `:desc`.
- **Dice calculator**: `SPC G r` — black base dice (attribute + skill) + yellow stress dice. Player rolls physical dice.
- **Weapons/Armor**: Structured plists — weapons: `(:name :modifier :damage :range :ammo :weight)`, armor: `(:name :level :weight)`.
- **State**: Health, stress, resolve, story-points, injuries, conditions, weapons, armor, gear, tiny-items, notes, room-notes. Auto-saves via `alien-rpg--autosave`. No buddy/rival/xp (not used in this campaign).
- **Room notes**: Per-room notes stored as alist `((room-id note1 note2 ...) ...)` in `:room-notes`. Timestamped. Displayed in `where-am-i` and `find-room` output.
- **Sorting**: All `completing-read` candidate lists sorted alphabetically via `alien-rpg--sort-candidates`.
- **View mode**: `alien-rpg-view-mode` (derived from `special-mode`) applied to `*Alien RPG*` buffer with local keybindings.
- **Dispatch**: `alien-rpg-dispatch` lists all commands in completing-read for discoverability.
- **Inventory management**: Commands to remove/modify gear, weapons (including ammo), injuries, conditions, armor, tiny items.
- **Character**: prof. Héctor Navarre, biochemický inženýr, 74 let. Attributes and skills editable via `SPC G e`.
- **Output**: All commands output to `*Alien RPG*` buffer via `switch-to-buffer` (not `pop-to-buffer` — avoids Doom popup behavior that confuses screen readers).

**Keybindings** (`SPC G` prefix, Doom Emacs):

| Key | Command | Function |
|-----|---------|----------|
| `SPC` | Dispatch | `alien-rpg-dispatch` |
| `?` | Nápověda | `alien-rpg-help` |
| `w` | Kde jsem | `alien-rpg-where-am-i` |
| `m` | Přesun | `alien-rpg-move` |
| `t` | Teleport | `alien-rpg-teleport` |
| `f` | Najít místnost | `alien-rpg-find-room` |
| `p` | Najít cestu | `alien-rpg-find-path` |
| `d` | Přehled paluby | `alien-rpg-deck-overview` |
| `o` | Přehled stanice | `alien-rpg-station-overview` |
| `k` | Klíčová místa | `alien-rpg-key-locations` |
| `s` | Stav postavy (herní karta) | `alien-rpg-status` |
| `i` | Dovednosti (seřazené) | `alien-rpg-skills` |
| `h` | Health (+/-N) | `alien-rpg-set-health` |
| `S` | Stress (+/-N) | `alien-rpg-set-stress` |
| `r` | Kostky (dice calc) | `alien-rpg-dice` |
| `e` | Editovat cokoliv | `alien-rpg-set-stat` |
| `j` | Zranění | `alien-rpg-add-injury` |
| `g` | Výbava | `alien-rpg-add-gear` |
| `W` | Zbraň | `alien-rpg-add-weapon` |
| `a` | Brnění | `alien-rpg-add-armor` |
| `c` | Stav/condition | `alien-rpg-add-condition` |
| `n` | Poznámka k místnosti | `alien-rpg-add-room-note` |
| `N` | Poznámky | `alien-rpg-show-room-notes` |
| `x` | Globální poznámka | `alien-rpg-add-note` |
| `q` | Uložit | `alien-rpg-save-state` |
| `Q` | Načíst | `alien-rpg-load-state` |
| `v g` | Spravovat výbavu | `alien-rpg-manage-gear` |
| `v w` | Spravovat zbraně | `alien-rpg-manage-weapon` |
| `v a` | Spravovat brnění | `alien-rpg-manage-armor` |
| `v j` | Spravovat zranění | `alien-rpg-manage-injury` |
| `v c` | Spravovat podmínky | `alien-rpg-manage-condition` |
| `v t` | Spravovat drobné věci | `alien-rpg-manage-tiny-items` |

**Local keybindings** (in `*Alien RPG*` buffer via `alien-rpg-view-mode`):
`m` přesun, `w` kde jsem, `t` teleport, `s` stav, `d` paluba, `r` kostky, `f` místnost, `p` cesta, `n` poznámka k místnosti, `N` poznámky, `SPC` dispatch, `?` nápověda, `q` zavřít.

**Reference docs** (org-mode, Czech):
- `paluby/paluba-{A..J}.org` + `paluba-GH.org` — deck descriptions
- `stanice.org` — station overview, communication tower
- `herni_karta.org` — character card
- `workflow.org` — gameplay tutorial

**Reference PDFs** (source of truth):
- `reference_pdf/{A..J}_*.pdf` — deck maps (ground truth for room connections)
- `reference_pdf/G+H_A2.pdf` — communication tower map
- `reference_pdf/bocni_pohled_A3.pdf` — side view
- `reference_pdf/karta.pdf` — character sheet (ground truth for character data)

## Key Design Constraints

- **Concise output**: Room descriptions 1-2 sentences. No emoji, no decorative borders. Room codes in brackets.
- **Screen reader friendly**: All output via `switch-to-buffer` to `*Alien RPG*` buffer. Minibuffer completion for selection. No popups.
- **Zero dependencies**: All data embedded in Elisp. No external files at runtime.
- **Doom Emacs required**: `map!` macro, `SPC` leader.
- **PDF-verified data**: Room names, connections, and character data verified against `reference_pdf/`. Thick red lines on maps = doors. Centrální šachta = round room with upside-down person icon.
- **State changes use setq**: All `plist-put` on `alien-rpg-state` wrapped in `setq` for reliability.

## Map Structure

- Decks A (top) to J (bottom), vertical station
- Central shaft: B-J (A is isolated, access from B only)
- F-chodba: main corridor spanning entire deck F, connects centrální šachta to cely. Zbrojnice, kuchyně, sklady, WC are side rooms.
- Cross-deck průlezy modeled as direct room-to-room connections (no průlez rooms):
  - F-chodba ↔ G-hangar-01 (F5/G5), G-hangar-02 (F6/G6), G-nakladovy-dok (F1/G1), G-opravarensky-dok (F2/G2)
  - F-cely-z ↔ G-nakladovy-dok (F7/G7), F-cely-v ↔ G-opravarensky-dok (F8/G8)
  - G-nastupni-hala ↔ H-nadrz-toxickych (G3/H3, G4/H4)
  - G-nakladovy-dok ↔ H-plasma-jz (G7/H7), G-opravarensky-dok ↔ H-plasma-jv (G8/H8)
  - G-shromazdiste ↔ GH-komunikacni-vez (G9), H-ridici-centrum ↔ GH-komunikacni-vez (H9)
- G9 connects via Nouzové shromaždiště (top of G), NOT centrální šachta
- GH-komunikacni-vez connects to H-ridici-centrum (NOT H-centrální šachta)

## Development

No build system, tests, or CI. Load via `(load! "~/alienrpg/alien-rpg")` in `~/.doom.d/config.el`. Internal helpers use `alien-rpg--` double-dash prefix. Verify parentheses with Python script after edits.