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.