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, ~1370 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 :bonus :damage :range :ammo :weight)`, armor: `(:name :rating :weight)`.
- **State**: Health, stress, resolve, story-points, injuries, conditions, weapons, armor, gear, tiny-items, notes. Auto-saves via `alien-rpg--autosave`. No buddy/rival/xp (not used in this campaign).
- **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 |
|-----|---------|----------|
| `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 | `alien-rpg-add-note` |
| `N` | Poznámky | `alien-rpg-show-notes` |
| `q` | Uložit | `alien-rpg-save-state` |
| `Q` | Načíst | `alien-rpg-load-state` |

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