diff --git a/.claude/skills/update-docs/state.json b/.claude/skills/update-docs/state.json index 7787285a..37fd58ce 100644 --- a/.claude/skills/update-docs/state.json +++ b/.claude/skills/update-docs/state.json @@ -1,6 +1,6 @@ { - "last_run": "2026-07-10", + "last_run": "2026-07-12", "last_run_mode": "full", - "last_commit": "cb81afb", - "last_full_run": "2026-07-10" -} \ No newline at end of file + "last_commit": "7575bd3", + "last_full_run": "2026-07-12" +} diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 85e23d6f..99537b71 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -135,7 +135,7 @@ Round orchestrator (round.py): run_loop: while not stopped: update_activation → get active creatures - if none active → fast_forward to nearest wake_at or exit + if none active → fast_forward to nearest intent boundary or exit run_round → on_round_end callback Player input flow (service/, command-based): @@ -176,7 +176,7 @@ Calendar: 30 days/month, 12 months/year. ``` Entity (id, name, location_id, active, on_tick) -└── Creature (ability_scores, HP, AC, in_combat, is_dodging, is_disengaging, wake_at_seconds, brain, turn_budget, combat_position, equipped_weapon, equipped_armor, equipped_shield, equipped_head, equipped_feet, equipped_ring, resource_pools, faction_id, reputation, squad_id, xp_value, execute_action) +└── Creature (ability_scores, HP, AC, in_combat, is_dodging, is_disengaging, is_anchor, current_intent, brain, turn_budget, combat_position, equipment, resource_pools, faction_id, reputation, squad_id, xp_value, execute_action) └── Character (race, class, alignment, gold, appearance, class_features, level, experience, level_up_available, perceive_by_id, get_npc_data) ├── PlayerCharacter (interactive I/O, overrides take_turn directly) └── Npc (role, personality, schedule, memory: NpcMemory, ai_type — brain assigned by content_loader/adapter) @@ -184,7 +184,7 @@ Entity (id, name, location_id, active, on_tick) All tracked entities live on the `EntitiesLayer`. The layer's `tick()` is a no-op — the Round orchestrator calls `run_creature_turn` directly for both combat and peaceful turns. `Entity.on_tick(hour)` is called by the Round to update NPC activity based on daily schedule. -**Activation system:** `EntitiesLayer.update_activation(time)` runs at the start of each round. Players without `wake_at_seconds` are anchors; creatures at an anchor's location become active, all others go dormant. Creatures in combat stay active. NPCs are moved to their scheduled location when activated. The `wait` action sets `wake_at_seconds` on the creature and marks it dormant. When no active creatures exist, `Round.run_loop()` fast-forwards `World.advance_time()` to the nearest `wake_at`, re-runs activation, and continues. If nobody has a `wake_at`, the loop exits. +**Activation system:** `EntitiesLayer.update_activation(time)` runs at the start of each round. Any living creature with `is_anchor=True` and no `current_intent` holds its location active; creatures at an anchor's location become active, all others go dormant. Creatures in combat stay active. NPCs are moved to their scheduled location when activated. Wait and sleep use persisted `TimedIntent`; travel uses persisted `TravelIntent` with a destination, remaining route, and next edge-arrival boundary. `Round.run_loop()` fast-forwards to the nearest intent boundary when no creature needs a turn. Travel advances one graph edge per boundary and can be interrupted by damage, combat, or arrival in an occupied scene. `World.location_graph` (`LocationGraph`) provides a flat graph of all locations. Each `Location` node has a `region_id` tag (for weather/terrain lookups) and an optional `settlement_id` tag (for economy/NPC binding). Entities hold a `location_id` and the graph resolves which region/settlement they are in. Edges between locations carry distances in meters; `travel_seconds()` computes travel time. @@ -277,9 +277,9 @@ Centralized derived stat computation replacing ad-hoc logic scattered across com **Save format** (Sprint 021): one versioned Pydantic envelope — `SaveGame(schema_version=1, meta, world)` in `storage/save_schema.py`. `WorldSave` carries the world seed, dice RNG state, time, last tick times, and typed layer states: each layer owns a state model (`layers/*/state.py`, `layers/entities/save_models.py`) that is the authoritative format (`extra="forbid"`), while the `Layer` ABC keeps its dict-facing `get_state()/load_state()` signatures (core stays pydantic-free). Entity payloads are a discriminated union on `entity_type` (`PlayerSave`/`NpcSave`/`CreatureSave`/`ContainerSave`) built directly from live objects in `entity_serialization.py`; combat state persists turn order, round, battle map, and sides. `save_game()` and `autosave_session()` build the same envelope; `load_game()` validates it and rejects legacy saves without `schema_version`. -**Reproducibility**: `DND_WORLD_SEED` (env; random + logged when absent) seeds the world in `game_service` — per-layer seeds are derived deterministically and passed to layer constructors, which own their `random.Random` streams (weather, politics, ecology roam/retreat/lair depletion, entity encounters). The dice RNG (`rules/dice.py`, `DND_DICE_SEED`) is a separate stream. All RNG states are serialized into the save, so a loaded game continues the same random sequences — same seed, same content → identical world evolution (pinned by `tests/unit/test_world_seed.py`). +**Reproducibility**: `DND_WORLD_SEED` (env; random + logged when absent) seeds the world in `game_service`; per-layer seeds are derived deterministically and passed to layer-owned `random.Random` streams. Each `GameSession` owns its dice RNG (`DND_DICE_SEED` supplies the initial seed), so concurrent sessions cannot shift one another's rolls. All RNG states are serialized into the save, so a loaded game continues the same random sequences. Same seed plus the same content produces identical world evolution. -**Autosave**: per-action (create_player), on session evict, on shutdown, plus a periodic lifespan task every `DND_AUTOSAVE_SECONDS` (default 120, cancelled before the final shutdown autosave). Autosave failures are logged, never suppressed. +**Autosave and round lifecycle**: per-action (create_player), session evict, shutdown, and periodic autosave all take a session snapshot through the same world-mutation gate used by round actions. File I/O happens after the snapshot is built. Load stops the old round before replacing world/RNG state and resumes only after a player reconnects. Round shutdown has a bounded timeout (`DND_ROUND_STOP_TIMEOUT_SECONDS`, default 5); on timeout the session retains the live round/thread references and load or eviction aborts safely. Autosave failures are logged, never suppressed. ## Logging diff --git a/CLAUDE.md b/CLAUDE.md index c0dd42aa..06572cf6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,7 +99,7 @@ frontend/ — React + TypeScript SPA (Vite, shadcn/ui, Zustand) ### Entity Hierarchy -`Entity` (id, name, location_id, active, on_tick) → `Creature` (ability scores, HP, AC, speed, attacks, conditions, inventory, gold, in_combat, is_dodging, is_disengaging, wake_at_seconds, brain, turn_budget, combat_position, equipped_weapon, equipped_armor, equipped_shield, equipped_head, equipped_feet, equipped_ring, resource_pools, faction_id, reputation, xp_value) → `Character` (race, class, alignment, class_features, level, experience, level_up_available) → `PlayerCharacter` / `Npc`. Creature delegates decisions to `brain.choose_action()`. `Container` (`core/container.py`) is a separate `Entity` sibling of `Creature` — inventory + gold, no HP/turn/brain — used for lair treasuries and other lootable world objects (`EntityKind.CONTAINER`). The `perceive()` method controls what information an observer sees about a target — LLM prompts never receive raw character data. All tracked entities live on the `EntitiesLayer`. `World.location_graph` (`LocationGraph`) maps locations to regions/settlements; entities reference `location_id`, and the graph resolves which region/settlement a location belongs to. NPCs have structured memory (`NpcMemory`: tags, recent, inner_state, current_conversation) readable by both LLM and RuleBrain; a `MemorySummarizer` compresses events into memory via LLM after combat/conversation ends. Combat is managed via `CombatState` (initiative order, round tracking, combat sides, auto-exit after 2 idle rounds) and `BattleMap` (2D grid with positions, walls, and movement). Movement rules live in `rules/movement.py` (D&D 5e diagonal distance, wall collision, occupied-cell blocking). `move_to(x, y)` action uses BFS pathfinding (`find_path`) and budget-aware stepping (`step_cost`); player-only (frontend click-to-move), excluded from LLM action schemas via `provider_managed=True`. +`Entity` (id, name, location_id, active, on_tick) → `Creature` (physical stats, combat state, `is_anchor`, persisted `current_intent`, brain, turn budget, equipment and resources) → `Character` (race, class, alignment, class features, level and XP) → `PlayerCharacter` / `Npc`. Creature delegates decisions to `brain.choose_action()`. `Container` (`core/container.py`) is a separate `Entity` sibling of `Creature`: inventory + gold, no HP/turn/brain, used for lair treasuries and other lootable world objects (`EntityKind.CONTAINER`). The `perceive()` method controls what an observer sees; LLM prompts never receive raw character data. All tracked entities live on `EntitiesLayer`. `World.location_graph` maps locations to regions/settlements and supplies weighted routes for travel intents. NPCs have structured memory (`NpcMemory`) readable by both LLM and RuleBrain. Combat is managed via `CombatState` and `BattleMap`; grid movement rules live in `rules/movement.py`. ### Multi-Action Turns @@ -133,7 +133,7 @@ Centralized derived stat computation (`core/modifiers.py` data types, `rules/mod ### Activation & Fast-Forward -Proximity-based activation: `EntitiesLayer.update_activation(time)` runs at the start of each round. Players without `wake_at_seconds` are anchors — creatures at an anchor's location become active, all others go dormant. Creatures in combat stay active regardless. `wait` action sets `creature.wake_at_seconds` and marks it dormant. When no active creatures exist, `Round.run_loop()` fast-forwards time to the nearest `wake_at`, then re-checks activation. Content requires explicit locations — no auto-generation from regions. On entering a location with an encounter table, `ActivationManager` rolls encounters (see Lairs, Encounters & Loot). +Anchor-based activation: `EntitiesLayer.update_activation(time)` runs at the start of each round. Any living creature with `is_anchor=True` and no current intent holds its scene active; creatures at an anchor's location become active, all others go dormant. Creatures in combat stay active regardless. Wait, sleep, and travel are typed, persisted `current_intent` values. When no creature needs a turn, `Round.run_loop()` fast-forwards to the nearest timer or travel-leg boundary. Travel follows deterministic shortest paths one graph edge at a time and can be interrupted by damage, combat, or an occupied scene. Content requires explicit locations. On entering a location with an encounter table, `ActivationManager` rolls encounters (see Lairs, Encounters & Loot). ### Lairs, Encounters & Loot @@ -166,6 +166,7 @@ Kill reputation drop (`rules/reputation.py`): omniscient, delta scaled by victim - `DND_LANGUAGE` env var selects game language (default: `ru`); locale files in `src/dnd_simulator/locale/` - `DND_WORLD_SEED` env var seeds world simulation layers; when absent, `GameService` logs the generated seed. - `DND_AUTOSAVE_SECONDS` env var controls periodic autosave interval (default: `120`; must be greater than `0`). +- `DND_ROUND_STOP_TIMEOUT_SECONDS` bounds round-thread shutdown before load/eviction aborts safely (default: `5`). - Save files: `saves/` directory (JSON) - Backend API: `make serve` → http://localhost:8001/docs (Swagger UI) - Frontend: `make frontend` → http://localhost:5173 (entry point, proxies /api to :8001) diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 0e029e50..3ca6d822 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -15,8 +15,8 @@ Эпики новой модели из [simulation-core.md](brainstorms/simulation-core.md). Порядок зависимостей: `save-schema` → `anchor-as-property` + `intents` → `trigger-table` → `inner-self` → `detail-ladder` → `quest-system`. - [x] **must** `save-schema` — CLOSED Sprint 021: единая схема сейва (Pydantic по образцу контента) вместо рукописного формата в нескольких местах. Предусловие всей модели: «мир заморожен на полушаге» требует lossless-сейва (намерения, планы мозгов, триггеры, лог мыслей, зародыши субъектности). Стартовый кусок — «дедуп сериализации» в Sprint 020 phase 3, добивается отдельным спринтом -- [ ] **must** `anchor-as-property` — якорь материализации как свойство существа, не тип: активация без `isinstance(PlayerCharacter)`. Player-agnostic движок (идея 1 вижна). Дешёвый первый шаг, можно брать рано -- [ ] **must** `intents` — намерение как первоклассная сущность на Creature: спит/идёт/ждёт, каждое действие несёт длительность, встроенные прерывания (телесное, втягивание в сцену, прибытие, таймер), wake-точки как обобщение `wake_at_seconds`. Убивает travel-as-wait хак; входной таск — `travel-action-type` +- [x] **must** `anchor-as-property` — FIXED Sprint 022: `is_anchor` на любом Creature, активация больше не зависит от `PlayerCharacter` +- [x] **must** `intents` — FIXED Sprint 022: строгие сохраняемые wait/sleep/travel intent, встроенные прерывания и границы пробуждения/прибытия - [ ] **must** `trigger-table` — парные декларативные триггеры `{on, until}` на существе (YAML + ручка ГМ), матчинг при эмиссии событий, активация/гашение dormant↔active, самогашение «моя роль сыграна» как действие мозга. Требует типизированной таксономии событий (фундамент заложен Sprint 020 phase 2). Поглощает `spawn-event-trigger` - [ ] **should** `brain-gate-decide` — контракт Brain: дешёвый гейт (чистые ифы, «продолжаю намерение?», хоть каждый раунд) + дорогое решение (только границы: завершение, прерывание, триггер, ГМ). Инвариант: LLM никогда не вызывается на 6-секундном пути - [ ] **should** `llm-turn-plan` — план хода внутри LlmBrain: 1 вызов на ход вместо 3-5, шаги плана со сверкой awareness дешёвой проверкой, перепланирование при сюрпризе. Плюс иерархия командир/исполнитель для сцен: LLM-стратегия на входе, правила разыгрывают раунды, reassess-триггеры (союзник упал, HP < 1/2, враг сдаётся, появился поименованный) поднимают момент до сюжетного решения. Поглощает `combat-reassess`. Движок не меняется — всё внутренности мозга @@ -73,7 +73,7 @@ - [ ] **could** `drag-resize-panels` — Drag-and-drop / resizable панели на dashboard - [ ] **could** `mobile-layout` — Мобильная адаптация dashboard - [ ] **could** `log-filter-tabs` — Фильтрация лога табами (Все/Бой/Диалоги) -- [ ] **should** `attack-buttons-accessible-names` — кнопки Attack в nearby-списке и action bar имеют одинаковые accessible names: цели неразличимы для автоматизации и скринридеров — E2E-смоук бил не в ту цель (убил торговку Гретту). Добавить aria-label с именем цели. Побочная аномалия того прогона (не отрепрожена чисто): свежая сессия в том же процессе увидела пустой рынок и зависла в «Waiting for turn…» — если всплывёт снова, разбирать отдельно. E2E sprint 021 close +- [x] **should** `attack-buttons-accessible-names` — кнопки Attack/Talk/Inspect в nearby-списке и в inspect-модалке получили target-aware `aria-label` по уникальному `entity.id` (тот же контракт, что у action-bar `TargetDropdown`); SmiteChoice тоже именует цель по id. Закрыто в Sprint 022 phase 4 task 3: EN/RU уникальность подтверждена браузерным E2E (три NPC на рынке → три различимых имени) + компонентные тесты. E2E sprint 021 close - [ ] **should** `master-panel-creature-inventory` — `CreatureResponse` / `all_entities` query не включают inventory/equipped_weapon; мастер не видит предметы существ. Добавить поля в схему и query - [x] `master-give-item-ui` — ~~endpoint для give_item есть, кнопки нет~~ FIXED Sprint 007 phase 2: кнопка «Выдать предмет» в карточке существа - [x] `inspect-as-idle-param` — ~~inspect шёл как `Action(IDLE, {inspect_target})`~~ FIXED Sprint 009 phase 4: клиентская NpcInspectModal из awareness @@ -81,13 +81,13 @@ ## Engine & Session -- [ ] **should** `save-round-concurrency` — save/load/autosave снимают `session.world` без синхронизации с живым раунд-тредом (`commands_save.py`, `app.py` periodic autosave, `session.py`): `Round.run_loop()` мутирует мир в фоне, периодический автосейв (Sprint 021) сделал гонку регулярной — риск порванного сейва/`RuntimeError: dict changed size`. Нужна session-уровневая критическая секция сейва/загрузки, согласованная с round lifecycle (manual save, autosave, periodic, evict, load) + concurrency-тест. Audit 2026-07-10, top-кандидат ближайшего спринта -- [ ] **must** `travel-action-type` — Отдельный `ActionType.TRAVEL` с длительностью и по-рёберным движением по графу локаций: путешественник всегда в конкретной локации, пути активных пересекаются (дорожные встречи), прерывание — всегда в конкретной точке. Первый кирпич эпика `intents` (повышен should→must). Текущий хак: `LocationPanel` шлёт `Action(WAIT, {hours: 0, travel_to})` с телепортом в конце +- [x] **should** `save-round-concurrency` — FIXED Sprint 022 phase 1: snapshot и раундовые мутации используют единый session-level world gate; load, autosave и eviction согласованы с round lifecycle +- [x] **must** `travel-action-type` — FIXED Sprint 022 phase 3: `ActionType.TRAVEL` движется по рёбрам графа и сохраняет маршрут без телепорта - [ ] **should** `npc-instant-say-response` — dormant отвечает пассивно, не просыпаясь (simulation-core): после `say` дать существам в локации отреагировать в том же запросе (1 раунд). Сейчас NPC отвечают только при `advance_time` - [ ] **could** `list-npcs-iterate-entities` — `list_npcs` итерирует по регионам; NPC в несуществующем регионе выпадает из списка. Итерировать по entities напрямую - [x] **should** `periodic-autosave-scheduler` — FIXED Sprint 021 phase 3 (`DND_AUTOSAVE_SECONDS`, cancel до финального сейва): фоновый asyncio таск в FastAPI lifespan каждые ~2 мин вызывает `autosave_all_sessions()`; cancel на shutdown перед финальным autosave. Дополняет per-action и shutdown автосейв. Повышен could→should: «мир заморожен на полушаге» (simulation-core) требует надёжного автосейва - [ ] **could** `control-interfaces-donor` — Донор-ветка `sprint/020-control-interfaces` и PR #15: identity/roles, три линзы и admin park реализованы против до-thermo control-plane. При планировании control-interfaces использовать как референс задач и тестов; raw merge невозможен из-за конфликтов с thermo-sweep. Grace-period и spectator уже перенесены отдельно -- [ ] **should?** `wait-no-fastforward-with-npc` — **требует проверки: баг или медленно-но-корректно.** `wait` не делает fast-forward, когда в локации игрока сидит активный rule-NPC — вместо прыжка к `wake_at` раунд тикает по 6 c, и управление к игроку возвращается только через ~600 раундов (1 час игрового времени). Ожидание (playbook 2.3): время сдвигается на 1 час, ход быстро возвращается. **Repro (E2E sprint 020 phase 2):** мир «Долина Мечей», сессия 283d42a2, локация «Солёный Якорь» (`silverport_city_tavern`) с co-located rule-NPC «Марта»; игрок Grimwald QA (Fighter L1) жмёт «Ждать» → action bar застревает на «Ожидание хода…». Бэклог: `wait_sleep` hours=1, `wake_at=46326855600`, но `round_end` показывает `game_time` сдвинутым лишь на 6 c (`second=6`) — fast-forward «нет активных существ → прыжок к ближайшему wake_at» не срабатывает, т.к. Марта остаётся активной. Гипотеза: при `wait` игрок получает `wake_at` и перестаёт быть anchor'ом, значит co-located NPC тоже должен уйти в dormant и включить fast-forward — но не уходит. Проверить `ActivationManager.update_activation` / anchor-логику и путь fast-forward в `Round.run_loop`. NB: наблюдалось после evict→reconnect (см. `session-disconnect-debounce`), но поведение `wait` от этого не зависит. Смежно: `test-gap-ws-fastforward`. По simulation-core гипотеза корректна: расписание-NPC без якоря рядом не должен оставаться активным; тот самый путь, который перепишут `intents`/`anchor-as-property`, — но проверить/починить стоит уже сейчас +- [x] **should** `wait-no-fastforward-with-npc` — FIXED Sprint 022 phase 2: intent делает якорь dormant, соседний RuleBrain NPC больше не удерживает сцену, мир быстро доходит до ближайшей wake-точки - [ ] **could** `saved-session-accumulation` — тест-гигиена закрыта Sprint 021 phase 3 (интеграционный стек чистит saves/ через session fixture); остаётся UX-половина (пагинация/фильтр/TTL в Sessions-вкладке). Master → Sessions грузит ВСЕ сохранённые сессии без пагинации/очистки; за прогоны integration-тестов в общий `saves/` накопилось ~900 сессий (E2E sprint 020 phase 2), вкладка Sessions раздувается, ручной поиск конкретной сессии непрактичен (снимок дерева перевалил за токен-лимит). Две стороны: (1) тест-гигиена — integration-тесты не чистят созданные сейв-сессии в `saves/`; (2) UX/масштаб — в списке нет пагинации/фильтра/TTL. Мин. фикс: чистка `saves/` в teardown интеграционных тестов; долгий — пагинация + фильтр в Sessions-вкладке - [x] **should** `session-disconnect-debounce`: FIXED 2026-07-10. При уходе последнего player listener `GameSession` **сразу** ставит раунд на паузу (`stop_round`), а откладывает только выселение из реестра: ставится grace-period timer (default 1.5s, `DND_EVICT_GRACE_SECONDS`), reconnect в окне отменяет timer, а вернувшийся игрок перезапускает раунд через `start_round`. Раньше откладывались И stop_round, И evict — из-за этого player-less раунд-луп продолжал крутить ходы NPC в grace-окне (при сетевом блипе игрок молча терял боевые ходы), а поскольку все сессии тянут один процесс-глобальный RNG костей, пересекающиеся «осиротевшие» раунды делали seed-зависимые integration-тесты недетерминированными (`test_player_state_xp::test_rest_status_updated_after_kill` флакал в CI). Spectator listeners не держат сессию живой и не запускают round lifecycle. WS arena tests переведены на fresh session per test, поэтому больше не зависят от evict-reset и не накапливают arena combat до `game_over`. @@ -174,6 +174,7 @@ - [x] **should** `silent-failure-autosave` — FIXED Sprint 021 phase 3 (+ гвард на evict-после-DELETE): 3x contextlib.suppress(Exception) вокруг autosave. Логировать ошибки, не глушить - [x] `silent-failure-awareness` — ~~awareness_builder.py 6x broad except Exception~~ FIXED Sprint 012 phase 4: narrowed to KeyError/LookupError - [x] `silent-failure-movement` — ~~handle_wait except ValueError: pass~~ FIXED Sprint 020 phase 1 task 2: недостижимый/несуществующий travel-таргет → `ActionResult(success=False)` +- [ ] **should** `action-error-kills-round-loop` — ожидаемая ошибка параметров action не изолирована от игрового цикла: post-audit E2E Sprint 022 отправил `travel` без обязательного `destination_id`, `ActionDispatcher` выбросил `ValueError`, а `GameSession.run_round_loop()` завершил весь round loop и показал игроку `GAME OVER`. UI-путь исправлен в `ed32eff`, но malformed WS payload или будущая клиентская ошибка всё ещё могут убить сессию. Валидировать action до передачи в round либо преобразовывать ожидаемые dispatch/handler errors в неуспешный `ActionResult`; добавить WS/session regression, подтверждающий, что после отклонённого action следующий ход остаётся играбельным. Связан с `action-params-validation`, но тот пункт закрывает входную схему, а этот — failure containment. - [x] `schema-form-growing` — ~~frontend SchemaForm.tsx 488 строк, 30+ nested helpers~~ FIXED Sprint 020 phase 4: `FieldShell`, `schemaResolve.ts`, `localizedCodec.ts`, один `buildDefaults`; `SchemaForm.tsx` 373 строки - [ ] **should** `llm-imports-layer-models` — llm/brain.py и llm/summarizer.py импортируют из layers.entities.models (Npc, NpcMemory). llm не должен зависеть от layers - [ ] **should** `round-imports-entities-layer-v2` — round.py:31 напрямую импортирует EntitiesLayer (sprint 012 re-introduced coupling). Взаимодействовать через World/Layer interface @@ -226,7 +227,7 @@ - [ ] **should** `test-gap-save-commands` — autosave_all_sessions, delete_save, list_saves без unit-тестов (commands_save round-trip частично закрыт Sprint 019 phase 1) - [ ] **should** `test-gap-content-routes` — list_catalog_entries, list_schemas, get_schema, list_refs без тестов - [ ] **should** `test-gap-master-routes` — list_library_templates, fork_world_layer без тестов -- [ ] **could** `test-gap-ws-fastforward` — player wait → time skip → NPC resume не тестируется (см. живой repro в `wait-no-fastforward-with-npc`) +- [x] **could** `test-gap-ws-fastforward` — FIXED Sprint 022 phase 2: реальный websocket path проверяет wait → fast-forward → возврат хода без NPC flood - [ ] **could** `test-gap-ws-disconnect-npc` — disconnect during NPC turn + reconnect не тестируется - [ ] **could** `test-gap-ws-npc-combat-turn` — NPC full multi-action RuleBrain combat turn только indirect - [ ] **should** `test-gap-action-provider` — rules/action_provider.py без unit-тестов diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 77f1e4ef..94d474bd 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -29,7 +29,7 @@ BattleMap (2D grid), инициатива, auto-exit после 2 idle раун React + TypeScript + shadcn/ui, dark theme. Игровой экран (EventLog, BattleMap, ActionBar, Nearby/Location/Character панели) + мастер-панель (World/Creatures/Time/Saves). WebSocket для real-time взаимодействия. ### Level 0 — Фундамент game loop -Proximity-based активация существ: NPC рядом с игроком active, остальные dormant. Wait + fast-forward: `wake_at_seconds` на существе, Round.run_loop() мотает время до ближайшего пробуждения. Explicit locations — каждый мир обязан определить locations явно, убрана автогенерация из регионов. NPC перемещаются по расписанию при активации. Round lifecycle в GameSession. +Anchor-based активация существ: NPC рядом с бодрствующим якорем active, остальные dormant. Wait/sleep/travel хранятся как типизированные intent; Round.run_loop() мотает время до ближайшей границы намерения. Explicit locations — каждый мир обязан определить locations явно, убрана автогенерация из регионов. NPC перемещаются по расписанию при активации. Round lifecycle в GameSession. → [брейншторм](brainstorms/ecs-and-content.md) ### Level 1 — Conditions, BrainFactory, валидация @@ -127,6 +127,10 @@ Paladin L1-L2 как первый caster-класс. Phase 1: spell slots как Первый эпик цепочки simulation-core. Phase 1: единый `DND_WORLD_SEED` — слоевые сиды выводятся детерминированно в `game_service`, слои владеют своими `random.Random` (погода, политика, roam/retreat/деплит логова, encounter rolls), процесс-глобальный `random` из `layers/` убран, сквозной пин детерминизма (`test_world_seed.py`: один сид → идентичный `World.save()`). Phase 2: версионированная Pydantic-схема сейва — `SaveGame(schema_version=1)` в `storage/save_schema.py`, типизированные state-модели слоёв (`extra="forbid"`), entity-сейвы как discriminated union, построение напрямую из объектов, combat sides в сейве (закрыт lossless-пробел), состояние RNG (слоевые + dice) сериализуется и продолжает последовательности после load, legacy-форматы отклоняются. Phase 3: периодический автосейв (`DND_AUTOSAVE_SECONDS`, cancel до финального сейва), ошибки автосейва логируются вместо suppress, гвард на evict-после-DELETE (заодно закрыл воскрешение удалённой сессии), интеграционный стек чистит `saves/`. Закрыты backlog: `save-schema`, `layer-rng-threading`, `test-gap-world-rng-determinism`, `periodic-autosave-scheduler`, `silent-failure-autosave`. → [план спринта](sprints/021-save-schema/sprint.md) +### Sprint 022 — Intentions & Travel (фазы 1-5) +Второй эпик simulation-core. Якорь стал свойством любого существа; wait, sleep и travel представлены строгими сохраняемыми intent. Travel идёт по кратчайшему маршруту по рёбрам графа, сохраняется посреди пути и прерывается телесным событием, боем или встречей в активной сцене. Session-owned dice RNG, единый world-mutation gate и bounded round shutdown согласовали save/load/autosave с живым раундом. Post-audit E2E: 8/8, integration: 160/160. +→ [план спринта](sprints/022-intents-travel/sprint.md) + ## Planned ### Level 2 — Расходуемые ресурсы @@ -137,8 +141,8 @@ Spell slots, ki, rage. Дополнительные типы брони и ор Заклинания как YAML, интерактивные объекты (двери, сундуки). → [брейншторм](brainstorms/ecs-and-content.md) -### Simulation Core — намерения, триггеры, внутреннее я, лестница детализации -Заменяет прежний план «Phase 3 — Автономные тики» (периодические тики отброшены в пользу decision-точек). Первый эпик (единая схема сейва + воспроизводимость) закрыт Sprint 021. Цепочка эпиков: ~~единая схема сейва~~ → якорь-как-свойство + намерения (спит/идёт/ждёт, travel по рёбрам) → парные триггеры `{on, until}` активации/гашения → внутреннее я NPC (цели, отношения, живой alignment, переваривание + правиловый близнец) → лестница детализации поселений (событийная запись, храповик субъектности) → квесты как контент поверх целей и триггеров. +### Simulation Core — триггеры, внутреннее я, лестница детализации +Заменяет прежний план «Phase 3 — Автономные тики» (периодические тики отброшены в пользу decision-точек). Единая схема сейва и воспроизводимость закрыты Sprint 021, якоря и намерения закрыты Sprint 022. Цепочка эпиков: ~~единая схема сейва~~ → ~~якорь-как-свойство + намерения~~ → парные триггеры `{on, until}` активации/гашения → внутреннее я NPC (цели, отношения, живой alignment, переваривание + правиловый близнец) → лестница детализации поселений (событийная запись, храповик субъектности) → квесты как контент поверх целей и триггеров. → [брейншторм](brainstorms/simulation-core.md), эпики в [BACKLOG](BACKLOG.md#simulation-core-брейншторм-2026-07-04) ### World Builder (advanced) diff --git a/docs/STATUS.md b/docs/STATUS.md index 4ad8f9a9..49ef9354 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -2,9 +2,9 @@ Текущее состояние проекта. Один файл — быстрый ответ на "где мы сейчас". -**Last updated:** 2026-07-10 -**Position:** Sprint 020 закрыл thermo-sweep (корректность, чистота `rules/`, типизация границ, decomposition). Sprint 021 закрыл первый эпик simulation-core: версионированная Pydantic-схема сейва (`SaveGame`, schema_version=1), воспроизводимость мира от `DND_WORLD_SEED` (слоевые RNG, их состояние в сейве), периодический автосейв. Классовые механики на уровне D&D L2 (Fighter / Rogue / Paladin). -**Next:** активного спринта нет. Следующий `/new-sprint`: продолжение цепочки simulation-core (`anchor-as-property` / `intents` + `travel-action-type` → `trigger-table` → ...), при этом `save-round-concurrency` из свежего audit — top-кандидат на включение (сейв гоняется с живым раунд-тредом без синхронизации). Альтернатива — `control-interfaces`. `quest-system` планировать только после триггеров и целей. +**Last updated:** 2026-07-12 +**Position:** Sprint 022 закрыл второй эпик simulation-core: player-agnostic якоря, сохраняемые wait/sleep/travel intent, по-рёберное путешествие и согласованный с round lifecycle save/load/autosave. Классовые механики на уровне D&D L2 (Fighter / Rogue / Paladin). +**Next:** Активного спринта нет. Главный следующий кандидат: `trigger-table`; смежные кандидаты — `brain-gate-decide` и containment ожидаемых action errors. **Blockers:** нет. ## Current Sprint @@ -25,6 +25,7 @@ No active sprint. | Sprint | Goal | Started | Completed | |--------|------|---------|-----------| +| 022-intents-travel | Player-agnostic якоря и сохраняемые wait/sleep/travel intent; travel по рёбрам; согласованный lifecycle save/load/autosave | 2026-07-10 | 2026-07-12 | | 021-save-schema | Версионированная Pydantic-схема сейва (schema_version=1, RNG в сейве, combat sides), воспроизводимость мира от DND_WORLD_SEED, периодический автосейв | 2026-07-10 | 2026-07-10 | | 020-thermo-sweep | Закрыть структурный долг из термоядерного ревью: корректность + чистота rules, типизация границ, backend/frontend decomposition, сверка с simulation-core | 2026-06-30 | 2026-07-10 | | 019-control-plane-prep | Отвердить control-plane под разрез на роли: GameService 1044→357 (миксины WorldBuilderCommands/PlayerCommands), тест-сетка на session, развязка core/adapter (action_parsing seam, public World query API), видимые дырки (combat-log i18n, encounter-перцептор, труп-кнопки) | 2026-06-28 | 2026-06-29 | diff --git a/docs/audit.md b/docs/audit.md index 2506e462..e6648dc3 100644 --- a/docs/audit.md +++ b/docs/audit.md @@ -1,91 +1,86 @@ # Code Audit -> **Date**: 2026-07-10 -> **Scope**: full codebase, post Sprint 021 (`b5cfc5d`) +> **Date**: 2026-07-12 +> **Scope**: full codebase, post Sprint 022 Phase 5 (`9f84fd4`) > Transient snapshot. Canonical tracking lives in [BACKLOG.md](BACKLOG.md); known backlog items are marked `known` and should not be duplicated during triage. ## Summary - Dead code: 0 issues -- Code smells: 5 issues +- Code smells: 4 issues - Security: 4 issues - Architecture violations: 0 issues - Convention violations: 3 issues - Layer contract: 0 issues -- Test gaps: 4 issues +- Test gaps: 2 issues - Vision drift: 0 issues -**Total: 16 issues.** Sprint 021 closed the important Sprint 020 audit risk: world randomness is now owned by per-layer RNGs, layer and dice RNG state are in the versioned `SaveGame` envelope, legacy saves are rejected, and periodic autosave logs failures instead of suppressing them. The remaining fresh risk is concurrency around save/load/autosave while a round thread can mutate the same session world. +**Total: 13 issues.** Phase 5 closed the previous audit's only fresh operational risk: round shutdown now uses a bounded deadline, preserves live lifecycle references after timeout, and prevents disconnect, load, or eviction from continuing an unsafe operation. Focused unit tests cover timeout, retry, reconnect, load, and deferred eviction; Phase 5 E2E is green. No new sprint blocker was found. ## Dead Code | File | Issue | Action | |------|-------|--------| -| none | `uv run ruff check src/ --select F401` is clean. No `TODO/FIXME/HACK/XXX` in `src/`. | none | +| none | `uv run ruff check src/ --select F401` is clean. No `TODO/FIXME/HACK/XXX` in `src/`; no Phase 5 lifecycle branch is orphaned. | none | ## Code Smells | File | Issue | Suggestion | |------|-------|------------| -| `src/dnd_simulator/service/commands_save.py:18`, `src/dnd_simulator/adapters/api/app.py:50`, `src/dnd_simulator/service/session.py:461` | `fresh`: saves and autosaves snapshot `session.world` without taking a session/world lock, while `Round.run_loop()` can mutate the same world on a background thread. The new periodic autosave makes this path regular, not just shutdown/evict. | Add one session-level save/load critical section or a world snapshot API that coordinates with the round lifecycle. Cover manual save, autosave, periodic autosave, evict autosave, and load. | -| `src/dnd_simulator/service/session.py` (606 lines) | `known`: grew from 521 to 606 lines after spectator/grace/autosave lifecycle hardening. It now owns listener lifecycle, thread lifecycle, payload construction, player status helpers, movement resolution, and eviction timers. | Continue `long-func-start-round` / `test-gap-session`; avoid adding new session behavior until lifecycle and payload builders are split. | -| `src/dnd_simulator/layers/entities/layer.py` (584 lines), `layers/entities/perception.py` (572 lines), `round.py` (548 lines), `core/action_defs.py` (545 lines), `service/commands_worldbuilder.py` (535 lines) | `known`: large modules remain after Sprint 020 decomposition. Sprint 021 added save/load state to the entities layer, but no new god-object boundary was introduced. | Keep existing backlog: `entities-layer-regrowth`, `perception-fail-fast`, `round-growing`, `action-defs-growing`. | +| `src/dnd_simulator/service/session.py` (726 lines) | `known, worsened`: grew from 694 to 726 lines. It owns listener and round transitions, two locking domains, snapshot construction, payload composition, player status, movement resolution, eviction timers, journey presentation, and bounded-stop policy. | Split lifecycle/locking from transport payload builders before adding trigger activation. Keep `long-func-start-round` and `test-gap-session` as the canonical backlog items. | +| `src/dnd_simulator/layers/entities/layer.py` (616 lines), `layers/entities/perception.py` (572 lines), `round.py` (571 lines), `core/action_defs.py` (554 lines), `service/commands_worldbuilder.py` (535 lines) | `known`: large modules remain. Phase 5 did not increase these files. | Keep `entities-layer-regrowth`, `perception-fail-fast`, `round-growing`, and `action-defs-growing`; avoid folding trigger-table logic into the same files. | | `frontend/src/components/game/EventLog.tsx:244`, `frontend/src/components/master/SchemaForm.tsx:62` | `known`: two `eslint-disable react-hooks/exhaustive-deps` suppressions remain. | Keep `event-log-eslint-suppress` and `schema-form-eslint-suppress`; remove only with targeted tests. | -| `src/dnd_simulator/layers/entities/entity_serialization.py:38`, `layers/entities/save_models.py` | `known/accepted`: entities save models are now authoritative, but `player_to_save_data()` still emits a parse-player compatibility subset. This is not a second save format for `SaveGame`, but it is still a compatibility bridge to watch as schema v1 evolves. | Do not reintroduce hand-written save envelopes. When player parsing moves fully onto save models, remove the bridge. | +| `frontend/src/transport/apiClient.ts` (391 lines) | `known`: the client is close to the 400-line audit threshold and contains session, player, content, save, and master operations. | Keep `api-client-growing`; split by domain when the next control-interface surface lands. | + +The former unbounded `thread.join()` finding is closed. `_stop_round()` waits at most `DND_ROUND_STOP_TIMEOUT_SECONDS`, retains the same round, brain, and thread on timeout, and clears them only after that thread exits. ## Security | File:Line | Issue | Severity | |-----------|-------|----------| -| `src/dnd_simulator/adapters/api/app.py:153-160` | `known`: CORS origins are configurable, but default origins, methods, and headers are wildcard. Acceptable for local dev, unsafe for non-local deployment. | low | -| `src/dnd_simulator/adapters/api/routes_ws.py:149-154` | `known`: WS origin validation is optional and disabled by default. Session IDs are still the only access handle. | medium | -| `src/dnd_simulator/adapters/api/schemas.py:69-93` | `known`: `GiveItemRequest` item fields (`price`, `reach`, `base_ac`, `max_dex_bonus`, `strength_req`, `ac_bonus`) still lack bounds. Master-only surface, but impossible game data can be created. | low | -| `src/dnd_simulator/adapters/api/app.py:177-180` | `known`: `/api/frontend-error` accepts arbitrary JSON without a Pydantic schema or size limit. | low | +| `src/dnd_simulator/adapters/api/app.py:150-154` | `known`: CORS origins are configurable, but the default origins, methods, and headers are wildcard. Acceptable for local development, unsafe for non-local deployment. | low | +| `src/dnd_simulator/adapters/api/routes_ws.py:149-154` | `known`: WS origin validation is optional and disabled by default. Session IDs remain the only access handle. | medium | +| `src/dnd_simulator/adapters/api/schemas.py:69-103` | `known`: item creation fields including `price`, `reach`, `base_ac`, `max_dex_bonus`, `strength_req`, and `ac_bonus` lack bounds. | low | +| `src/dnd_simulator/adapters/api/app.py:174-177` | `known`: `/api/frontend-error` accepts arbitrary JSON without a Pydantic schema or size limit. | low | -Verified clean/hardened: no hardcoded secrets, `.env` is gitignored, no `subprocess`, no `dangerouslySetInnerHTML`, WS has token-bucket rate limiting, and autosave errors now log. +Verified clean/hardened: no hardcoded secrets, `.env` is gitignored, no subprocess calls, no `dangerouslySetInnerHTML`, and WS input has token-bucket rate limiting. Phase 5 changed internal thread lifecycle only and added no external input surface. ## Architecture Violations | File:Line | Violation | Should Be | Severity | |-----------|-----------|-----------|----------| -| none | No cross-layer imports across different layers. `core/` imports neither layers nor adapters. `rules/` imports neither layers/service/adapters/storage nor I/O libraries. `adapters/` do not import layers. | none | none | +| none | No cross-layer imports across different layers. `core/` imports neither layers nor adapters. `rules/` imports neither layers/service/adapters/storage nor I/O libraries. Adapters do not import layers. | none | none | -Accepted boundary imports: API schemas/routes import core enums and creation constants; `app.py` constructs `LlmClient` at the service injection point; `storage/save_schema.py` imports layer state models because the versioned save envelope intentionally lives outside `core`. +The bounded-stop policy remains in `GameSession`, where round lifecycle and locks are owned. Load still crosses the boundary through `replace_world_state()` and fails before invoking the loader when the old round cannot stop. ## Convention Violations | File:Line | Violation | Rule | |-----------|-----------|------| -| `src/dnd_simulator/storage/save_schema.py:41`, `layers/*/state.py`, `layers/entities/save_models.py:228`, `layers/common/rng_state.py` | `fresh/accepted`: RNG state uses `list[Any]` because `random.Random.getstate()` is nested tuple/list data with implementation-defined shape. | Prefer `object` over `Any`, but keep this exception localized unless a typed RNG-state codec is introduced. | +| `src/dnd_simulator/storage/save_schema.py:41`, `layers/*/state.py`, `layers/entities/save_models.py:256`, `layers/common/rng_state.py` | `known/accepted`: RNG state uses `list[Any]` because `random.Random.getstate()` has an implementation-defined nested shape. | Prefer `object` over `Any`; keep the exception localized unless a typed RNG-state codec is introduced. | | `src/dnd_simulator/content_loader/monsters.py:129`, `content_loader/refs.py:62` | `known`: raw-YAML/dynamic-model helpers still use `Any`. | Existing `any-to-object-sweep` / `any-encounter-entries`. | -| `src/dnd_simulator/service/session.py`, `round.py`, `core/character.py`, `core/combat.py`, `core/resource.py`, layer model files | `known/accepted`: mutable dataclasses remain for runtime state (`GameSession`, `Round`, creatures, combat state, resource pools, lairs, world models). | Fine for stateful objects; revisit only when a model is meant to be a value object. | +| `src/dnd_simulator/service/session.py`, `round.py`, `core/character.py`, `core/combat.py`, `core/resource.py`, layer model files | `known/accepted`: mutable dataclasses remain for explicit runtime state. | Fine for stateful objects; require `frozen=True` for value objects. | Line length is clean. ## Layer Contract | Layer | Issue | |-------|-------| -| none | All concrete layers implement the `Layer` ABC surface: `name`, `tick_interval`, `tick`, `handle_event`, `query`, `get_state`, `load_state`. Sprint 021 state models preserve the dict-facing Layer interface while validating through Pydantic internally. | +| none | All concrete layers implement `name`, `tick_interval`, `tick`, `handle_event`, `query`, `get_state`, and `load_state`. Phase 5 did not change a layer contract. | ## Test Gaps | Source File | Expected Test | Status | |-------------|---------------|--------| -| `src/dnd_simulator/service/commands_save.py`, `service/session.py`, `adapters/api/app.py` | Concurrency test for save/autosave/load while a round thread is active and mutating world state. | `fresh`, missing | -| `src/dnd_simulator/service/commands_save.py:65-75`, `service/session.py:461-578` | Load while connected/in combat should pause or restart round lifecycle deterministically before the player reconnects. | `known`: `load-combat-round-resume` | -| `src/dnd_simulator/adapters/api/routes_ws.py` | Malformed non-object JSON from client, not only invalid JSON / unknown message type. | `known`: extends `test-gap-ws-malformed-json` / `action-params-validation` | -| `tests/unit/test_periodic_autosave.py` | Shutdown path where final `service.autosave_all_sessions()` itself raises. | `fresh`, missing; likely low severity because startup/shutdown should expose hard failures, but the behavior is currently unpinned | +| `src/dnd_simulator/adapters/api/routes_ws.py` | Malformed non-object JSON and malformed action parameter shapes, not only invalid JSON and unknown message types. | `known`: `test-gap-ws-malformed-json` / `action-params-validation` | +| `tests/unit/test_periodic_autosave.py` | Shutdown path where final `service.autosave_all_sessions()` raises. | `known`, missing; `test-gap-shutdown-autosave-failure` | -No skipped or xfailed tests. The mechanical "rules module name -> test_rules_*.py" script still reports false positives because this repo uses semantic test names (`test_combat.py`, `test_movement.py`, `test_action_provider_isolated.py`, etc.); I did not count those as direct gaps. +The former round-stop gap is closed. Tests now cover a blocked callback, bounded failure, lifecycle-reference preservation, idempotent start, successful retry, parked-player happy path, disconnect logging, deferred eviction, and load fail-fast with unchanged world/RNG/cache. ## Vision Drift | Change | Invariant Violated | Impact | |--------|-------------------|--------| -| none | Sprint 021 aligns with simulation-core: save schema v1, seeded layer RNG, RNG state persistence, and periodic autosave all support the "world frozen on a half-step" direction. | none | - -Classic mode still works without LLM, time remains a single session timeline, layers remain callback-separated, and master control still goes through service endpoints. - -## Sprint 021 Backlog Reconciliation -| Item | Audit Result | -|------|--------------| -| `save-schema` | Substantively closed for v1: `SaveGame(schema_version=1)` is the single envelope, typed layer states are authoritative, legacy saves are rejected. Future simulation-core fields will extend v1/v2 rather than reopening the old manual format. | -| `layer-rng-threading` | Closed: encounter rolls, squad movement, retreat, lair depletion, weather, politics, ecology, and entities use owned RNG streams rather than process-global `random`. | -| `test-gap-world-rng-determinism` | Closed: `tests/unit/test_world_seed.py` pins same-seed full-world replay, different-seed divergence, layer seed streams, and encounter spawn replay. | -| `periodic-autosave-scheduler` | Closed: FastAPI lifespan starts `_periodic_autosave()` with `DND_AUTOSAVE_SECONDS`, cancels it before final shutdown autosave, and tests interval/error/cancel behavior. | -| `silent-failure-autosave` | Closed for the three Sprint 021 targets: create-player autosave, empty-session autosave, and periodic autosave log exceptions. | -| `saved-session-accumulation` | Partially addressed: integration suite cleanup is in place; UX pagination/filter/TTL remains a separate product/debt question. | -| `load-combat-round-resume` | Still known and not duplicated: phase-2 E2E showed save JSON correct, but load/reconnect can advance combat before the UI stabilizes. | +| none | Bounded shutdown preserves the single global round: a live old thread blocks replacement and a second round cannot start. | none | + +Classic mode remains complete without LLM, active creatures share one round, layers remain callback-separated, brains remain swappable, and master mutations still go through service endpoints. + +## Sprint 022 Phase 5 Reconciliation +| Previous Finding | Audit Result | +|------------------|--------------| +| Unbounded round-thread join | Closed: bounded join with `RoundStopTimeoutError`, structured logging, and preserved lifecycle references. | +| Missing stuck-round lifecycle tests | Closed: unit coverage spans stop, reconnect, disconnect, load, eviction, recovery, and the normal parked-player path. | +| Unsafe continuation after stop timeout | Closed: load does not replace world state; eviction does not autosave or remove the session; reconnect does not create a second loop. | diff --git a/docs/e2e-playbook.md b/docs/e2e-playbook.md index df195dbd..098ca3ad 100644 --- a/docs/e2e-playbook.md +++ b/docs/e2e-playbook.md @@ -356,3 +356,19 @@ ### 15.6 Локализация боевого лога + флейвор встречи (Sprint 019) - При `DND_LANGUAGE=ru` провести атаку и спровоцировать спавн встречи - **Ожидание:** строка атаки целиком по-русски, без утечки плейсхолдеров (`{oa}`/`{weapon}`/`{roll}`); спавн встречи даёт флейвор «Поблизости что-то шевелится» (ростер мобов скрыт), НЕ фоллбэк «Something happened» + +--- + +## 16. Intentions & Travel (Sprint 022) + +### 16.1 Wait рядом с RuleBrain NPC +- В мирной локации с NPC нажать «Ждать» на 1 час +- **Ожидание:** время быстро сдвигается ровно на час, промежуточного потока NPC-ходов нет, игрок получает следующий ход + +### 16.2 Путешествие по графу +- В Location Panel выбрать соседнюю локацию и начать Travel; для длинного маршрута сохранить и загрузить игру посреди пути +- **Ожидание:** действие передаёт `destination_id`, игрок движется по рёбрам без телепорта, journey status переживает load и очищается один раз по прибытии + +### 16.3 Прерывание путешествия +- Пройти промежуточное ребро в локацию с бодрствующим якорем либо вступить в бой во время intent +- **Ожидание:** intent очищается, игрок остаётся в достигнутой локации и получает один ход; последующие обновления не повторяют пройденное ребро diff --git a/docs/e2e-reports/2026-07-12-sprint022-post-audit.md b/docs/e2e-reports/2026-07-12-sprint022-post-audit.md new file mode 100644 index 00000000..25fe0662 --- /dev/null +++ b/docs/e2e-reports/2026-07-12-sprint022-post-audit.md @@ -0,0 +1,45 @@ +# E2E Report: sprint022-post-audit + +**Date:** 2026-07-12 +**Flags:** --no-llm +**Sections tested:** 1.1-1.5, 2.1, 2.3-2.4 + Sprint 022 travel regression +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 8 tested, 8 passed after 1 quick fix +- Quick fixes: 1 applied +- Blockers: 0 found + +## Results + +| # | Scenario | Status | Notes | +|---|----------|--------|-------| +| 1.1 | Landing page Player/DM split | pass | Русские Player и DM entry points видны, переключатель языка доступен. | +| 1.2 | Quick start in Sword Vale | pass | Новая сессия создалась, персонаж вошёл в игру, WebSocket подключился. | +| 1.3 | Language surface | pass | Landing, setup и game UI полностью отобразились в RU без raw translation keys. | +| 1.4 | Fighter point buy | pass | STR 15 и CON 14 оставили 3 очка; preview показал HP 12, AC 19, 1000 gold. | +| 1.5 | Fighter class UI | pass | Fighting Style и Chain Mail / Longsword / Shield отображались; Defense дал AC 19. | +| 2.1 | Peaceful perception | pass | Марта видна рядом с Attack/Talk controls. | +| 2.3 | Wait and time advance | pass | Wait сдвинул время с 10:00 до 11:00 и вернул следующий ход. | +| A1 | Destination-based travel | pass | После quick fix generic Travel action скрыт; путь в Location Panel передал `destination_id` и переместил игрока на Рыночную площадь без ошибки round loop. | + +## Quick Fixes + +- `ActionBar` больше не показывает generic `travel` как простую кнопку. Маршрут выбирается через Location Panel, единственный UI, который передаёт обязательный `destination_id`. Добавлен regression test. + +## Findings + +### Blockers + +None. + +### Minor + +- При первом подключении после создания персонажа браузер один раз сообщил о закрытии первоначального WebSocket до установления соединения. Замещающее соединение открылось сразу, действия Wait и Travel выполнились штатно. Это известный dev-proxy/reconnect artifact. + +## Log Analysis + +- До quick fix generic Travel button вызвал `ValueError: Action travel missing required param: destination_id` и `GAME OVER`; исправление воспроизведено и проверено через чистую UI-сессию. +- После исправления повторный travel прошёл без новых backend errors или browser console errors. +- Focused frontend regression: 22/22 tests passed. diff --git a/docs/sprints/022-intents-travel/e2e/phase1-report.md b/docs/sprints/022-intents-travel/e2e/phase1-report.md new file mode 100644 index 00000000..314fd026 --- /dev/null +++ b/docs/sprints/022-intents-travel/e2e/phase1-report.md @@ -0,0 +1,49 @@ +# E2E Report: sprint022-phase1 + +**Date:** 2026-07-10 +**Flags:** --no-llm +**Sections tested:** 1, 2, 6 + phase lifecycle scenario +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 3 tested, 2 passed, 1 failed during the original E2E run +- Follow-up: blocker fixed and verified outside the sprint task sequence +- Quick fixes: 1 applied +- Blockers: 0 open + +## Results + +| Scenario | Status | Notes | +|---|---|---| +| Landing and character creation | pass | Sword Vale session created through UI; Fighter with Defense entered the game, AC 19 and the normal action bar were visible. | +| Basic peaceful action | pass | Wait advanced game time from 10:00 to 11:00 through the player UI. | +| Save → mutate → load → reconnect | resolved | The original E2E run failed after reconnect. The WS lifecycle race was fixed and verified with lifecycle tests, live save/load + WS integration tests, and 20 consecutive quick reconnect runs. The exact browser scenario was not rerun. | + +## Findings + +### Blockers + +- None open. + +### Resolved + +- The disconnect path could observe an empty player-listener list, release `_lock`, and later stop the round after a reconnect had already registered a new listener and started a new round. Listener add/remove and round start/stop are now serialized by the session `_round_transition_lock`. +- Removing an unknown stale listener is now a no-op and does not arm session eviction. +- Regression coverage models the disconnect/reconnect interleaving directly. + +### Minor + +- None found in the tested scope. + +## Log Analysis + +- No browser console errors; one existing React Router future-flag warning. +- Backend accepted the reconnecting player WebSocket and logged `add_listener`. During the first reconnect transition it also logged `remove_listener`, `stop_round`, and a round ending at restored time 10:00:06. The page never received a turn afterward. + +## Follow-up Verification + +- `tests/unit/test_session_lifecycle.py`: 30 passed. +- Full backend check: ruff, formatting and mypy passed; 2441 unit tests passed. +- Live backend with integration content: save/load and WebSocket connection selection, 8 passed. +- Quick reconnect stress: 20 consecutive runs passed. diff --git a/docs/sprints/022-intents-travel/e2e/phase2-report.md b/docs/sprints/022-intents-travel/e2e/phase2-report.md new file mode 100644 index 00000000..4bcff79a --- /dev/null +++ b/docs/sprints/022-intents-travel/e2e/phase2-report.md @@ -0,0 +1,48 @@ +# E2E Report: sprint022-phase2 + +**Date:** 2026-07-11 +**Flags:** --no-llm +**Sections tested:** 2 +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 4 tested, 4 passed, 0 failed +- Quick fixes: 0 applied +- Blockers: 0 found + +## Results + +### Section 2: Peaceful Mode + +| # | Scenario | Status | Notes | +|---|----------|--------|-------| +| 2.3 | Wait and time advance | pass | Wait at The Salty Anchor advanced 10:00 → 11:00 and returned the player turn while Marta, a RuleBrain NPC, was nearby. | +| 2.4 | Move between locations | pass | Moving to Silverport Market Square updated the location panel and nearby list. | + +### Auto-discovered scenarios + +| Scenario | Reason | Status | Notes | +|----------|--------|--------|-------| +| Short rest wake lifecycle | Timed rest completion moved to the intent wake boundary | pass | Short Rest advanced 11:00 → 12:00; the action bar returned after wake. | +| Long rest wake lifecycle | Timed rest completion moved to the intent wake boundary | pass | Long Rest advanced 12:00 → 20:00; the action bar returned after wake. | + +## Quick Fixes + +None. + +## Findings + +### Blockers + +None. + +### Minor + +- Vite dev mode logged one transient WebSocket warning while the initial connection was being replaced. The active connection succeeded and all actions completed without reconnect symptoms. + +## Log Analysis + +- Backend log contains no errors, exceptions, or tracebacks. +- Round logs show direct fast-forward deltas of 3594 seconds for wait/short rest and 28794 seconds for long rest after the six-second action round. +- Entity logs show one wake boundary and one rest completion for each tested intent. diff --git a/docs/sprints/022-intents-travel/e2e/phase3-report.md b/docs/sprints/022-intents-travel/e2e/phase3-report.md new file mode 100644 index 00000000..79041cee --- /dev/null +++ b/docs/sprints/022-intents-travel/e2e/phase3-report.md @@ -0,0 +1,40 @@ +# E2E Report: sprint022-phase3 + +**Date:** 2026-07-11 +**Flags:** --no-llm +**Sections tested:** 1, 2 +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 3 tested, 3 passed, 0 failed +- Quick fixes: 1 applied +- Blockers: 0 found + +## Results + +| Scenario | Status | Notes | +|---|---|---| +| Landing page player/DM split | pass | Both entry cards render and point to the expected routes. | +| Travel through Location panel | pass | Clicking an adjacent path starts `travel`; arrival updates the current location and replaces the visible path list. | +| Travel action localization | pass | The action bar renders `Travel` in EN and `Путешествовать` in RU. | + +## Quick Fixes + +- Added the missing EN/RU action-bar labels for the new `travel` action. + +## Findings + +### Blockers + +None. + +### Minor + +None. + +## Log Analysis + +- No backend errors, exceptions, or tracebacks during the clean run. +- Browser console had no errors. Reloads produced transient WebSocket-close warnings while replacing the page. + diff --git a/docs/sprints/022-intents-travel/e2e/phase4-report.md b/docs/sprints/022-intents-travel/e2e/phase4-report.md new file mode 100644 index 00000000..41d036a5 --- /dev/null +++ b/docs/sprints/022-intents-travel/e2e/phase4-report.md @@ -0,0 +1,43 @@ +# E2E Report: sprint022-phase4 + +**Date:** 2026-07-11 +**Flags:** --no-llm +**Sections tested:** phase-4 focus (target accessibility + journey lifecycle) +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 5 tested, 5 passed, 0 failed +- Quick fixes: 1 applied (target-aware accessible names now key on the unique entity id) +- Blockers: 0 found + +## Results + +| # | Scenario | Status | Notes | +|---|----------|--------|-------| +| A1 | Nearby Attack/Talk/Inspect controls have unique target-aware accessible names (EN) | pass | With gretta + guard_a + guard_b at the market, `Attack gretta` / `Attack guard_a` / `Attack guard_b` are all present and unique; Talk/Inspect likewise. Selecting one sends its `target_id`. | +| A2 | Same, in Russian | pass | `Атаковать gretta` / `Атаковать guard_a` / `Атаковать guard_b` unique; no duplicates among the three attack controls. | +| A3 | Open inspect modal keeps its Attack control unambiguous | pass | Inspecting `guard_a` opens the modal (`Attack guard_a`); the background nearby list is `aria-hidden` (Radix), so exactly one `Attack guard_a` button is reachable by role + name. | +| B1 | Multi-leg travel progresses leg-by-leg and clears on arrival | pass | Travel tavern→smithy resolved route `[market, smithy]`; logs show `travel_leg_arrive` at market (intermediate) then smithy (final) — no teleport. On arrival the journey panel is gone, the displayed location is the reached node, and player control returns. | +| B2 | Combat entry stays coherent and returns control | pass | Attacking `raider_1` starts combat (`combat_start`, round 1): mode flips to combat, CombatPanel + BattleMap render, `player.journey` is null (no stale journey), `isMyTurn` true. | + +## Quick Fixes + +- Target-aware accessible names now use the unique `entity.id` (matching the existing action-bar `TargetDropdown` contract) instead of the perceived description. The perceived description is the localized **race** (e.g. `человек`), which collides for same-race NPCs and would have produced duplicate `Attack человек` names. `Perception.tsx` (Attack/Talk/Inspect + SmiteChoice) and `NpcInspectModal.tsx` (Attack + SmiteChoice) updated; added `inspect_target` string to EN/RU `game.json`. Verified live: three simultaneous market NPCs yield three unique attack names in EN and RU. + +## Findings + +### Blockers + +None. + +### Minor + +- **Mid-route SCENE interruption not reproducible through the current control surface.** Stopping a traveler at an intermediate node requires a *second awake anchor* there (the built-in SCENE reason), but `is_anchor` is not exposed by the master API and authored sword_vale NPCs are not awake anchors — a 2-leg journey passing through the market (with gretta + two guards present) fast-forwarded straight through to the destination. The interruption logic itself (SCENE / DAMAGE / COMBAT, idempotent, no double rest/leg, journey cleared, stops at reached node) is covered by the phase-4 task-1/task-2 unit + integration suites and the `LocationPanel` "clears journey progress and shows the reached node when interrupted mid-route" component test. Candidate backlog item: expose anchor toggle (or an authored awake NPC) so a mid-route stop is playable/testable through the UI. +- **Journey panel is only briefly visible on an unobstructed route.** By design (kenshi-style fast-forward) the round loop advances all legs in one pass, so `player.journey` is set only transiently between the travel action and arrival; a player rarely sees the route panel unless the journey is interrupted. Noted as an observation, not a defect. + +## Log Analysis + +- Backend log clean: no errors, exceptions, or tracebacks during the run (only the expected `llm_not_configured_fallback` for the no-LLM stack). +- Browser console: 0 errors across the run (1 benign warning). +- Travel events well-formed: `travel_start` carries the resolved multi-node `route`, each leg logs a single `travel_leg_arrive`, and `combat_start` records initiative/positions cleanly. diff --git a/docs/sprints/022-intents-travel/e2e/phase5-report.md b/docs/sprints/022-intents-travel/e2e/phase5-report.md new file mode 100644 index 00000000..03f33e5d --- /dev/null +++ b/docs/sprints/022-intents-travel/e2e/phase5-report.md @@ -0,0 +1,46 @@ +# E2E Report: sprint022-phase5 + +**Date:** 2026-07-12 +**Flags:** --no-llm +**Sections tested:** 6.11 + phase-5 lifecycle scenarios +**Stack:** LOG_LEVEL=DEBUG, LOG_DIR=/tmp/dnd-e2e-logs + +## Summary + +- Scenarios: 3 tested, 3 passed, 0 failed +- Quick fixes: 0 applied +- Blockers: 0 found + +## Results + +| # | Scenario | Status | Notes | +|---|----------|--------|-------| +| 6.11 | Save, diverge world time, then load | pass | `phase5_e2e` saved at Y1490 M6 D1 10:00; master advanced 24 hours to D2; confirmed load restored D1 10:00 and the session view remained responsive. | +| A1 | Reload active player session and reconnect | pass | Reloaded `/play/c7921c48`; the same player, location, HP/AC and one playable action surface returned without a duplicate round or stuck waiting state. | +| A2 | Submit an action after reconnect | pass | Wait advanced time from 10:00 to 11:00, fast-forward completed, and the next player action surface arrived normally. | + +## Quick Fixes + +None. + +## Findings + +### Blockers + +None. + +### Minor + +- Reload produced the known transient browser warning that the first WebSocket was closed before establishment; + Vite logged two matching `ECONNRESET` proxy lines. The replacement connection succeeded immediately, the backend + recorded ordinary disconnect/reconnect events, and the next action completed. This is a dev-proxy/reload artifact, + not a lifecycle failure. +- The forced `RoundStopTimeoutError` branch cannot be triggered from the product UI without an intentionally blocked + server callback. Its bounded timing, preserved lifecycle references, load fail-fast behavior and deferred eviction + retry are covered by the Phase 5 unit suite. + +## Log Analysis + +- Backend: no errors, exceptions, tracebacks or lifecycle timeout events during the scenarios. +- Browser: 0 errors; one unique transient WebSocket warning repeated across reload. +- Frontend dev proxy: two `ECONNRESET` lines during reload, followed by a healthy replacement connection. diff --git a/docs/sprints/022-intents-travel/sprint.md b/docs/sprints/022-intents-travel/sprint.md new file mode 100644 index 00000000..24332ab9 --- /dev/null +++ b/docs/sprints/022-intents-travel/sprint.md @@ -0,0 +1,108 @@ +# Sprint 022 — Intentions & Travel + +**Goal:** Любое существо может быть якорем и сохраняемым носителем намерения; ожидание, сон и путешествие исполняются во времени, travel движется по графу без телепортации, а save/load согласован с жизненным циклом раунда. + +**Started:** 2026-07-10 + +## Context + +Второй эпик цепочки simulation-core после единой схемы сейва Sprint 021. Текущая активация знает тип `PlayerCharacter`, ожидание хранится как частный `wake_at_seconds`, а путешествие замаскировано под `WAIT` и телепортирует существо в конечную точку. Это расходится с player-agnostic вижном и не позволяет существам пересекаться в дороге. + +Спринт вводит якорь как свойство существа и первоклассное сохраняемое намерение для ожидания, сна и путешествия. Travel идёт по рёбрам графа, каждое существо остаётся в конкретной локации, базовые встроенные причины могут прервать намерение. Декларативные trigger-table, Brain gate/decide, динамические маршруты NPC, LLM-планирование, цели и квесты остаются за границей спринта. + +Параллельно закрываются связанные дефекты жизненного цикла. Save/load/autosave получают общую с раундом критическую секцию; ожидание без бодрствующего якоря быстро переводит мир к ближайшей wake-точке; загруженный бой не продолжается до подключения игрока. Небольшой фикс различимых accessible names у Attack-кнопок допустим как финальный polish, но не является целью спринта. + +**Ссылки:** [simulation-core](../../brainstorms/simulation-core.md), [BACKLOG](../../BACKLOG.md#simulation-core-брейншторм-2026-07-04), [Sprint 021](../021-save-schema/sprint.md) + +## Phase 1: Safe session lifecycle ✓ + +Save, load, autosave, evict и round loop согласованы одной session-level критической секцией. Загруженная посреди боя сессия остаётся на сохранённом ходе и запускается только после подключения игрока. Проверка: конкурентный autosave не получает порванный мир; сохранённый Round 1 после load остаётся Round 1 до реконнекта. + +Почему первой: следующие фазы добавляют изменяемое и сохраняемое состояние намерения, которое нельзя строить поверх известной гонки. Закрывает `save-round-concurrency` и `load-combat-round-resume`. + +**Tasks:** + +1. [Session-owned dice RNG](tasks/phase1-task1-session-dice-rng.md) +2. [World-state mutation gate](tasks/phase1-task2-world-state-gate.md) +3. [Consistent save and eviction paths](tasks/phase1-task3-consistent-save-paths.md) +4. [Atomic load and connection-driven resume](tasks/phase1-task4-atomic-load-resume.md) + +## Phase 2: Anchors, wait and sleep intents ✓ + +Якорь становится свойством существа, активация больше не проверяет `PlayerCharacter`. Wait и sleep представлены сохраняемыми намерениями с длительностью и wake-точкой. Проверка: любое назначенное якорем существо удерживает локальную сцену активной; wait/sleep переживает save/load; без бодрствующего якоря мир быстро переходит к ближайшему пробуждению. + +Почему второй: фаза формирует минимальную модель Intent и исправляет активацию до появления движения по графу. Закрывает `anchor-as-property`, базовую часть `intents`, `wait-no-fastforward-with-npc` и `test-gap-ws-fastforward`. + +**Tasks:** + +1. [Persisted anchors and timed intents](tasks/phase2-task1-persisted-anchors-intents.md) +2. [Anchor-driven activation and fast-forward](tasks/phase2-task2-anchor-activation-fast-forward.md) +3. [Wait and sleep intent lifecycle](tasks/phase2-task3-wait-sleep-lifecycle.md) + +## Phase 3: Travel as an intent ✓ + +Игрок начинает настоящее travel-намерение. Путешественник проходит маршрут по рёбрам графа, остаётся в конкретной локации на каждом шаге и прибывает после игрового времени, а не телепортируется через `WAIT`. UI показывает текущее путешествие и его завершение. Проверка: маршрут из нескольких рёбер виден по шагам; save/load в середине дороги продолжает тот же маршрут; два активных существа могут оказаться в одной промежуточной точке. + +Почему третьей: travel переиспользует Intent, wake-точки и player-agnostic активацию из Phase 2. Закрывает `travel-action-type`, основную оставшуюся часть `intents` и старый `WAIT + travel_to` хак. + +**Tasks:** + +1. [Travel route contract](tasks/phase3-task1-travel-route-contract.md) +2. [Travel action and leg progression](tasks/phase3-task2-travel-action-progression.md) +3. [Journey status and UI](tasks/phase3-task3-journey-ui.md) + +## Phase 4: Interruptible journeys and E2E closure ✓ + +Wait, sleep и travel штатно прерываются базовыми встроенными причинами: телесное событие, втягивание в сцену или бой, прибытие и таймер. После прерывания существо остаётся в согласованной локации и получает управление без потери или двойного исполнения намерения. Проверка: сохранение, загрузка, реконнект и прерывание в середине пути дают одно и то же состояние; полный пользовательский сценарий проходит через UI. Здесь же закрывается `attack-buttons-accessible-names`, чтобы E2E однозначно выбирал цель. + +Почему последней: прерывания проверяют совместную работу всех предыдущих фаз, не вводя декларативную trigger-table. + +**Tasks:** + +1. [Built-in intent interruptions](tasks/phase4-task1-built-in-intent-interruptions.md) +2. [Interruption lifecycle consistency](tasks/phase4-task2-interruption-lifecycle.md) +3. [Target accessibility and journey E2E](tasks/phase4-task3-accessibility-e2e.md) + +## Phase 5: Bounded round shutdown ✓ + +Остановка round thread получает ограниченное время ожидания и явный отказ вместо бессрочного +зависания disconnect, load или eviction. Пока старый поток жив, сессия сохраняет его lifecycle-состояние +и не позволяет запустить новый раунд или заменить world. Проверка: зависший callback быстро возвращает +контролируемую ошибку, а после освобождения callback повторная остановка штатно очищает сессию. + +Почему отдельной refactor-фазой: post-sprint audit обнаружил, что `_stop_round()` делает безлимитный +`join()` и заранее теряет ссылки на ещё живой поток. Это нарушает атомарный load-контракт Phase 1 и может +заблокировать disconnect/eviction. Фаза ограничена lifecycle-путём; общая декомпозиция `session.py`, +`round.py` и entities layer остаётся в существующем backlog. + +**Tasks:** + +1. [Bounded round-stop contract](tasks/phase5-task1-bounded-round-stop.md) +2. [Lifecycle boundary failure handling](tasks/phase5-task2-lifecycle-boundary-failures.md) + +--- + +## Status + +**Current:** Phase 5 complete. Fresh audit triaged; post-audit E2E green. Ready to close sprint. + +## Decisions + +- Граница Sprint 022: anchors + сохраняемые intents для wait/sleep/travel + встроенные прерывания. Декларативные trigger-table, Brain gate/decide, NPC wandering, LLM-планирование, цели и квесты остаются за пределами спринта (2026-07-10). +- Связанные lifecycle-дефекты `save-round-concurrency`, `load-combat-round-resume` и `wait-no-fastforward-with-npc` входят в основной scope; `attack-buttons-accessible-names` закрывается как E2E-polish (2026-07-10). +- Phase 1: session-level world gate недостаточен, пока dice RNG process-global. Dice RNG переводится во владение сессии до синхронизации snapshot; модульный fallback остаётся только для изолированных правиловых тестов (2026-07-10). +- Post-sprint audit: bounded round shutdown выделен в Phase 5. Общая декомпозиция lifecycle/payload responsibilities и растущих entities/round modules остаётся в каноническом backlog, без расширения refactor-фазы (2026-07-12). + +## Deferred + +_(заполняется по ходу спринта)_ + +## Results + +**Completed:** 2026-07-12 + +Якорь стал player-agnostic свойством Creature. Wait, sleep и travel получили строгие сохраняемые intent; travel идёт по кратчайшему маршруту по рёбрам и штатно прерывается телесным событием, боем или активной сценой. Session-owned dice RNG, единый world-mutation gate, connection-driven resume и bounded round shutdown согласовали save/load/autosave с живым раундом. + +Спринт: 5 фаз, 15 задач, 32 коммита, 94 изменённых файла. Финальные гейты: integration 160/160, post-audit E2E 8/8. Audit после Phase 5 не нашёл блокеров. + +**Deferred:** декларативные trigger-table, Brain gate/decide, NPC wandering, LLM-планирование, цели и квесты остаются следующими эпиками simulation-core. Декомпозиция `service/session.py` и ожидаемые action errors, способные остановить round loop, остаются в `docs/BACKLOG.md`. diff --git a/docs/sprints/022-intents-travel/tasks/phase1-task1-session-dice-rng.md b/docs/sprints/022-intents-travel/tasks/phase1-task1-session-dice-rng.md new file mode 100644 index 00000000..122c95d5 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase1-task1-session-dice-rng.md @@ -0,0 +1,45 @@ +# Task: Session-owned dice RNG + +**Date:** 2026-07-10 +**Sprint:** 022-intents-travel +**Phase:** 1 — Safe session lifecycle + +## Description + +Убрать process-global dice RNG из runtime игрового процесса. Каждая `GameSession` владеет своим генератором костей; `Round` и `ActionContext` используют его для инициативы, атак, реакций, лечения и остальных правиловых бросков. `DND_DICE_SEED` сохраняет назначение детерминированного стартового сида, но одна сессия больше не сдвигает последовательность другой. Сейв и восстановление autosave работают с RNG конкретной сессии. + +Модульный fallback в `rules/dice.py` можно оставить для изолированных правиловых unit-тестов, но session runtime не должен обращаться к `get_global_rng()`. + +## Tests First + +- Две сессии с одинаковым seed получают одинаковую начальную последовательность, даже если между их бросками другая сессия выполняет дополнительные действия. +- После save/load следующая кость в конкретной сессии совпадает с продолжением её сохранённой последовательности и не зависит от бросков соседней сессии. +- Реальный round/action path использует session RNG, а не модульный fallback. + +## Implementation + +Добавить RNG во владение `GameSession` и передать его в `Round`, затем использовать при построении всех `ActionContext` и при инициативе. Перенести чтение/инициализацию `DND_DICE_SEED` к созданию сессии вместо мутации module-global состояния в API lifespan. В `commands_save.py` и autosave restore сериализовать и восстанавливать состояние `session.dice_rng`. Не менять чистые правила: их существующий явный параметр `rng` остаётся точкой инъекции. + +Ключевые файлы: `service/session.py`, `service/game_service.py`, `round.py`, `service/commands_save.py`, `adapters/api/app.py`, тесты dice/save/session lifecycle. + +## Acceptance Criteria + +- [ ] Tests written and RED (before implementation) +- [ ] Implementation makes tests GREEN +- [ ] Existing tests still pass (`make check`) +- [ ] Runtime `Round` не вызывает `get_global_rng()` +- [ ] Броски одной сессии не меняют dice-последовательность другой +- [ ] Save/load продолжает dice-последовательность своей сессии + +## Status + +`done` + +## Developer Notes + +`GameSession` теперь владеет отдельным `random.Random`, инициализированным из `DND_DICE_SEED`. Тот же объект +используют `Round`, initiative, battle-map placement и attack resolution. Save/load и восстановление autosave +сохраняют состояние RNG конкретной сессии. Глобальный RNG остался fallback для изолированных rules-тестов. + +Существующий helper reaction-тестов дополнен явным RNG, потому что он создаёт `Round` через `__new__` в обход +runtime-конструктора. diff --git a/docs/sprints/022-intents-travel/tasks/phase1-task2-world-state-gate.md b/docs/sprints/022-intents-travel/tasks/phase1-task2-world-state-gate.md new file mode 100644 index 00000000..b9b041bf --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase1-task2-world-state-gate.md @@ -0,0 +1,47 @@ +# Task: World-state mutation gate + +**Date:** 2026-07-10 +**Sprint:** 022-intents-travel +**Phase:** 1 — Safe session lifecycle + +## Description + +Ввести отдельную session-level критическую секцию для состояния мира. Раундовые мутации и получение согласованного snapshot используют один gate; listener/lifecycle lock остаётся отдельным и не меняет назначения. Gate нельзя удерживать во время блокирующего ожидания действия `PlayerBrain`, иначе autosave зависнет на всё время человеческого хода. + +Граница атомарности должна позволять сохранить мир между законченными действиями или раундами, но никогда посреди handler, реакции, activation/materialization либо `advance_time`. + +## Tests First + +- Autosave, начатый во время контролируемой мутации мира, ждёт её завершения и получает состояние после целой мутации, без смешения значений до и после. +- Autosave проходит, пока раунд припаркован в ожидании действия игрока. +- Реакция и вызвавшее её действие не дают snapshot с наполовину применённым результатом. +- Остановка раунда и конкурентный snapshot завершаются без deadlock. + +## Implementation + +Добавить в `GameSession` отдельный re-entrant world-state gate и явный API для согласованного чтения/мутации. Передать gate в `Round` либо инъецировать эквивалентный контекстный callback. Покрыть им activation/materialization, action dispatch вместе с вложенными реакциями, завершение боя и продвижение времени. Не расширять существующий `_lock`: он защищает listeners, timer и ссылки lifecycle, а его смешение с world-state создаст обратный порядок блокировок. + +Ключевые файлы: `service/session.py`, `round.py`, тесты round/session concurrency. + +## Acceptance Criteria + +- [ ] Tests written and RED (before implementation) +- [ ] Implementation makes tests GREEN +- [ ] Existing tests still pass (`make check`) +- [ ] Snapshot невозможен посреди мутации игрового состояния +- [ ] Ожидание `PlayerBrain` не удерживает world-state gate +- [ ] Listener callbacks и stop/join не создают обратного порядка блокировок + +## Status + +`done` + +## Developer Notes + +`GameSession` получил отдельный re-entrant world-state lock с явными `read_world()` и `mutate_world()` scopes. +`Round` получает mutation scope через инъекцию и удерживает его только на activation/materialization, подготовке +хода, action dispatch с вложенными реакциями, завершении боя и продвижении времени. Ожидание `PlayerBrain` и +listener callbacks выполняются вне gate. Save snapshot читает world и dice RNG под тем же lock. + +Существующий reaction helper создаёт `Round` через `__new__`, поэтому в нём добавлен no-op mutation scope для +нового обязательного runtime-состояния. diff --git a/docs/sprints/022-intents-travel/tasks/phase1-task3-consistent-save-paths.md b/docs/sprints/022-intents-travel/tasks/phase1-task3-consistent-save-paths.md new file mode 100644 index 00000000..d9e613e5 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase1-task3-consistent-save-paths.md @@ -0,0 +1,49 @@ +# Task: Consistent save and eviction paths + +**Date:** 2026-07-10 +**Sprint:** 022-intents-travel +**Phase:** 1 — Safe session lifecycle + +## Description + +Перевести manual save, per-action autosave, periodic autosave, shutdown autosave и empty-session evict на единый способ получения согласованного session snapshot. Snapshot включает мир и состояние session-owned dice RNG из одной критической секции. Файловая запись выполняется после получения snapshot, чтобы медленный диск не останавливал раунд. + +Параллельное удаление или выселение сессии не должно воскрешать её, падать на итерации registry либо оставлять частично записанный SaveGame. + +## Tests First + +- Manual и periodic autosave во время живого раунда сохраняют валидный `SaveGame`, который загружается и содержит согласованное состояние мира и dice RNG. +- Медленная запись в `SaveStore` не удерживает world-state gate: после построения snapshot раунд может продолжить работу. +- Одновременные autosave и empty-session evict создают не более одного корректного autosave и не воскрешают удалённую сессию. +- Ошибка одной сессии в `autosave_all_sessions` не мешает сохранению остальных. + +## Implementation + +Сделать единый snapshot-builder на границе `GameSession`/`SaveCommands`; `_build_save_game` не должен читать изменяемые `session.world` и RNG раздельно. Все save entry points используют готовый immutable/Pydantic snapshot, затем вызывают store вне gate. Укрепить итерацию активных сессий и evict-путь против конкурентного удаления, сохранив существующее логирование ошибок. + +Ключевые файлы: `service/commands_save.py`, `service/game_service.py`, `service/session.py`, `adapters/api/app.py`, тесты commands_save/periodic_autosave/autosave_error_logging. + +## Acceptance Criteria + +- [ ] Tests written and RED (before implementation) +- [ ] Implementation makes tests GREEN +- [ ] Existing tests still pass (`make check`) +- [ ] Все точки save/autosave используют один согласованный snapshot path +- [ ] Мир и dice RNG попадают в snapshot под одной критической секцией +- [ ] Store I/O не выполняется под world-state gate +- [ ] Concurrent evict/delete не воскрешает сессию + +## Status + +`done` + +## Developer Notes + +`GameSession.build_save_game()` стал единственным builder для согласованного Pydantic snapshot мира и dice RNG. +Manual save и все autosave paths получают готовый snapshot до записи. `JsonFileStore` пишет во временный файл, +делает `fsync` и атомарно заменяет целевой JSON. + +Реестр сессий защищён отдельным `RLock`. Autosave проверяет identity активной сессии перед записью, concurrent +evict выполняется один раз, а explicit delete удаляет session autosave и не оставляет источник восстановления. +Существующие autosave error tests переведены с monkeypatch публичного метода на сбой store boundary, потому что +evict теперь сохраняет уже захваченный объект сессии без повторного registry lookup. diff --git a/docs/sprints/022-intents-travel/tasks/phase1-task4-atomic-load-resume.md b/docs/sprints/022-intents-travel/tasks/phase1-task4-atomic-load-resume.md new file mode 100644 index 00000000..dadf8047 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase1-task4-atomic-load-resume.md @@ -0,0 +1,49 @@ +# Task: Atomic load and connection-driven resume + +**Date:** 2026-07-10 +**Sprint:** 022-intents-travel +**Phase:** 1 — Safe session lifecycle + +## Description + +Сделать load атомарной сменой состояния сессии. Живой round loop сначала полностью останавливается, затем мир, dice RNG и brains восстанавливаются под world-state gate. Загруженный бой не исполняет ходы NPC в фоне до подключения игрока и не отправляет события в старый listener из состояния до load. + +После следующего player connection обычный idempotent `start_round` продолжает игру из сохранённого состояния. Spectator не запускает раунд. Контракт применяется и к явному load в существующую сессию, и к восстановлению session autosave из registry. + +## Tests First + +- Сейв боя на Round 1 загружается после расхождения мира и остаётся на Round 1, пока player listener отсутствует; spectator также не сдвигает бой. +- После подключения игрока round запускается один раз и ждёт сохранённого хода игрока, не прокручивая промежуточные раунды. +- Load во время живого round thread не оставляет старый thread/brain и не применяет действие, ожидавшее в старой очереди, к новому миру. +- Autosave restore создаёт паузированную сессию и начинает симуляцию только через player WebSocket lifecycle. + +## Implementation + +Скоординировать `SaveCommands.load_game`, `GameSession.stop_round`, listener lifecycle и `_try_restore_session`. Перед заменой состояния дождаться завершения старого round thread, очистить cached turn/reaction state, атомарно загрузить world + session RNG, затем переназначить brains. Не запускать round из load/restore; единственная точка старта остаётся player WebSocket connection после регистрации listener. + +Ключевые файлы: `service/commands_save.py`, `service/session.py`, `service/game_service.py`, `adapters/api/routes_ws.py`, unit/integration tests session lifecycle и save round-trip. + +## Acceptance Criteria + +- [ ] Tests written and RED (before implementation) +- [ ] Implementation makes tests GREEN +- [ ] Existing tests still pass (`make check`) +- [ ] Старый round thread полностью завершён до загрузки snapshot +- [ ] Загруженный бой не меняется без player listener +- [ ] Spectator не запускает загруженный раунд +- [ ] Player connection запускает ровно один round loop из сохранённого состояния +- [ ] Mid-combat save → load → reconnect проходит интеграционно + +## Status + +`done` + +## Developer Notes + +`GameSession` сериализует start/stop/load через отдельный round-transition lock. Load отключает callbacks старого +раунда, полностью завершает thread, очищает cached turn и под world-state gate восстанавливает world, session RNG +и brains. Player после load остаётся без brain до следующего player connection; spectator по-прежнему не запускает +симуляцию. Autosave restore использует тот же gated restore и публикуется в registry в паузированном состоянии. + +Два существующих lair integration-сценария обновлены под новый контракт: после REST load они переподключают player +WebSocket перед продолжением. Полный integration suite: 160 passed. diff --git a/docs/sprints/022-intents-travel/tasks/phase2-task1-persisted-anchors-intents.md b/docs/sprints/022-intents-travel/tasks/phase2-task1-persisted-anchors-intents.md new file mode 100644 index 00000000..bdf72b88 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase2-task1-persisted-anchors-intents.md @@ -0,0 +1,40 @@ +# Task: Persisted anchors and timed intents + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 2 — Anchors, wait and sleep intents + +## Description + +Introduce the minimal activity model on `Creature`: an explicit anchor capability and a typed current intent for timed wait or sleep. The intent owns its kind, start time, and wake time; `wake_at_seconds` must stop being a parallel source of truth. Both fields must round-trip through the strict `EntitySave` union for players, NPCs, and generic creatures. + +Keep this model in `core/` as transport- and layer-independent data. This task only establishes state and persistence. It does not change activation or action handlers yet, and it does not add travel fields that Phase 3 has not designed. + +## Tests First + +- A player, NPC, and generic creature with different anchor values and wait/sleep intents survive an EntitiesLayer save/load round-trip without losing the intent kind or timestamps. +- A creature with no intent round-trips as idle, without a fabricated wake time. +- The strict save schema rejects an unknown intent kind or extra intent fields instead of silently accepting a state that the engine cannot execute. + +## Implementation + +Add typed activity/intent data under `core/` and fields on `Creature`. Extend `CreatureFields` and entity serialization/restoration to use the same model for all creature variants. Remove `wake_at_seconds` from runtime and save models once all reads in this task's compile boundary have moved to the intent wake time; temporary handler/activation compatibility may read the new field but must not maintain both representations. + +Likely files: `core/character.py`, a focused `core/intent.py`, `layers/entities/save_models.py`, `layers/entities/entity_serialization.py`, `layers/entities/layer.py`, and serialization tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Anchor status is explicit on every `Creature`, not inferred from `PlayerCharacter`. +- [x] Wait and sleep use a typed persisted intent with one authoritative wake time. +- [x] All `EntitySave` creature variants preserve the new fields under `extra="forbid"`. + +## Status + +`done` + +## Developer Notes + +Added `TimedIntent` with strict wait/sleep kinds and absolute start/wake timestamps. `Creature.current_intent` is the only runtime wake source; the old standalone field was removed. Existing activation and action callers were migrated mechanically to the new field without changing their behavior, leaving the player-agnostic activation rewrite for task 2. `PlayerCharacter` defaults to an anchor while other creatures default to non-anchor, and save payloads persist the explicit value for every creature kind. diff --git a/docs/sprints/022-intents-travel/tasks/phase2-task2-anchor-activation-fast-forward.md b/docs/sprints/022-intents-travel/tasks/phase2-task2-anchor-activation-fast-forward.md new file mode 100644 index 00000000..3aaac442 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase2-task2-anchor-activation-fast-forward.md @@ -0,0 +1,45 @@ +# Task: Anchor-driven activation and fast-forward + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 2 — Anchors, wait and sleep intents + +## Description + +Make activation depend on the creature's anchor capability instead of its Python class. A living, idle anchor keeps its local scene active; an anchor with a wait or sleep intent does not. Nearby non-anchor creatures must not keep the scene running after its last awake anchor starts a timed intent. Combat remains active independently of anchors. + +Teach the round loop to derive its next wake point from timed intents. When no creature needs a round before that point, advance the world directly to the nearest wake time, complete the timer boundary, and reactivate from anchor state. Preserve the existing materialization and encounter boundaries without making activation transitive. + +## Tests First + +- An explicitly anchored NPC or generic creature activates its co-located scene even when no `PlayerCharacter` exists. +- A `PlayerCharacter` whose anchor flag is off does not activate a scene merely because of its type. +- When the only awake anchor starts waiting beside a rule NPC, the NPC becomes dormant and the world jumps to the anchor's wake time instead of executing hundreds of six-second NPC turns. +- With two timed intents, fast-forward stops at the earlier wake point and leaves the later intent in progress. +- A creature in combat stays active without an awake anchor; a dormant non-anchor does not become a new anchor by being near another active creature. + +## Implementation + +Refactor `ActivationManager.update_activation` into type-agnostic passes over `Creature`. Replace player-location naming and the no-player early return with anchor locations. Expire/complete timed intent boundaries consistently, without proximity silently deleting an unrelated intent. Update `CreatureHost` and `EntitiesLayer` wake-point queries to read intents, then adapt `Round._fast_forward` to the new contract. + +Keep encounter, squad, and lair materialization keyed to anchored active locations as today. Do not introduce `Brain.gate()` or declarative triggers in this phase. + +Likely files: `layers/entities/activation_manager.py`, `layers/entities/layer.py`, `core/creature_host.py`, `round.py`, activation/round tests, and affected materialization tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Activation contains no `PlayerCharacter` type check or player-presence early return. +- [x] Active creatures do not activate further creatures transitively. +- [x] Waiting beside an ordinary NPC reaches the nearest wake point without per-round churn. +- [x] Combat activity and materialization behavior remain covered. + +## Status + +`done` + +## Developer Notes + +Activation now recomputes every creature from explicit anchor locations, timed intents, and combat state. Awake anchors of any creature class hold a scene active; ordinary active creatures do not propagate activation. Proximity no longer clears timed intents, so fast-forward wakes only the earliest timer and preserves later ones. Tests that previously treated `active=True` as a lasting mandate now assign `is_anchor=True` explicitly. One full-check attempt ended with pytest code 139 after all 2451 tests passed; the clean retry completed backend and frontend gates. diff --git a/docs/sprints/022-intents-travel/tasks/phase2-task3-wait-sleep-lifecycle.md b/docs/sprints/022-intents-travel/tasks/phase2-task3-wait-sleep-lifecycle.md new file mode 100644 index 00000000..01ee36f1 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase2-task3-wait-sleep-lifecycle.md @@ -0,0 +1,50 @@ +# Task: Wait and sleep intent lifecycle + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 2 — Anchors, wait and sleep intents + +## Description + +Move WAIT, SHORT_REST, and LONG_REST from ad hoc dormancy fields to the timed intent lifecycle. Starting an action records the intent and duration; reaching its wake point completes it exactly once and returns an eligible anchor to play. Rest benefits must be applied at successful completion, not granted up front before elapsed time or save/load. + +Cover the real session path so wait/sleep remains correct across save, load, reconnect, and websocket turn delivery. Keep the legacy `WAIT + travel_to` branch isolated for removal in Phase 3; it must not create a wait intent or share the new completion path. + +## Tests First + +- WAIT creates a wait intent for the requested duration, yields the turn, and clears the intent when its timer completes. +- SHORT_REST and LONG_REST create sleep intents with one-hour and eight-hour wake points; resources, healing, and other completion effects are applied once at wake, not when sleep begins. +- Saving during wait or sleep and loading the session preserves the remaining intent; reconnect resumes from the saved game time and completes it once. +- Through the websocket action path, a player waiting beside a rule NPC receives the next playable turn after a fast jump to the wake time, with no intermediate NPC-turn flood. +- The existing `WAIT + travel_to` compatibility path still reports invalid destinations and does not leave a timed intent behind. + +## Implementation + +Make the wait/rest handlers start typed intents only. Add a focused completion operation used by activation at the wake boundary; centralize rest rewards there so repeated activation cannot apply them twice. Update handler tests and add a session/websocket regression test for `test-gap-ws-fastforward`. + +Retain the current action names and UI contract in Phase 2. Do not add `ActionType.TRAVEL`, route progress, general interruptions, or Brain gate/decide; those belong to later phases. + +Likely files: `rules/handlers/movement.py`, `rules/handlers/rest.py`, the intent model/completion helper, action and rest tests, session lifecycle tests, and websocket integration tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] WAIT, SHORT_REST, and LONG_REST use the persisted intent lifecycle. +- [x] Rest effects happen once, after elapsed game time. +- [x] Save/load/reconnect preserves an in-progress timed intent. +- [x] The websocket wait-with-NPC regression reaches the next player turn via fast-forward. +- [x] Travel compatibility remains isolated for Phase 3 removal. + +## Status + +`done` + +## Developer Notes + +Timed intents now persist an optional rest completion type. Rest handlers only start sleep; activation applies healing +and resource resets at the wake boundary before clearing the intent, so a second activation cannot repeat them. The +strict save model preserves this completion data across save/load. A TestClient WebSocket regression covers wait next +to a RuleBrain NPC and verifies that the next player turn arrives after a single fast-forward. Legacy `WAIT + travel_to` +continues to use its isolated immediate-travel branch and never creates a timed intent. diff --git a/docs/sprints/022-intents-travel/tasks/phase3-task1-travel-route-contract.md b/docs/sprints/022-intents-travel/tasks/phase3-task1-travel-route-contract.md new file mode 100644 index 00000000..da73230f --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase3-task1-travel-route-contract.md @@ -0,0 +1,41 @@ +# Task: Travel route contract + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 3 — Travel as an intent + +## Description + +Introduce a first-class travel intent that records a creature's destination, ordered route, current leg, and next arrival boundary. Travel state must be strict, typed, and persisted for every creature kind alongside the existing wait and sleep intents. Add deterministic weighted routing over `LocationGraph`, using edge distance as cost, so a destination several edges away produces one concrete route rather than an immediate teleport. + +Keep route calculation in the graph/core boundary and intent state in `core/`. This task establishes the contract and save/load behavior only. It does not start travel from an action or advance creatures through the route. + +## Tests First + +- On a branching graph, requesting a distant destination selects the reachable route with the shortest total distance and returns each intermediate location in order. +- An unreachable or unknown destination is rejected instead of producing a partial route; equal-cost alternatives resolve deterministically. +- A player, NPC, and generic creature saved during different legs of travel restore the same destination, remaining route, and next leg arrival boundary. +- The strict entity save schema rejects malformed travel state, including an empty remaining route, unknown fields, or a travel payload shaped like wait/sleep. + +## Implementation + +Extend the intent model to a typed union: keep the existing timed wait/sleep representation and add a focused travel representation with enough state to resume without recalculating a possibly changed route. Extend the strict Pydantic save union and entity serialization/restoration accordingly. Add shortest-path routing to `LocationGraph`; do not reuse battle-map pathfinding, which operates on combat grid cells and different costs. + +Likely files: `core/intent.py`, `core/location.py`, `layers/entities/save_models.py`, `layers/entities/entity_serialization.py`, `layers/entities/layer.py`, graph tests, and entity serialization tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Multi-edge routes are selected by total edge distance with deterministic tie-breaking. +- [x] Travel progress has one strict runtime and save representation for all creature kinds. +- [x] A mid-route save restores the exact remaining journey without recomputing it. + +## Status + +`done` + +## Developer Notes + +Added deterministic Dijkstra routing whose tie-break is the lexicographic node route, plus a strict discriminated save union for timed and travel intents. `TravelIntent` persists the final destination, remaining nodes, journey start, and next arrival boundary; Phase 2 activation intentionally handles only `TimedIntent` until task 2 wires travel progression. The full check exposed an unrelated flaky smite test whose “guaranteed hit” could roll a natural 1; its combat RNG is now seeded, with no product behavior change. diff --git a/docs/sprints/022-intents-travel/tasks/phase3-task2-travel-action-progression.md b/docs/sprints/022-intents-travel/tasks/phase3-task2-travel-action-progression.md new file mode 100644 index 00000000..848dce76 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase3-task2-travel-action-progression.md @@ -0,0 +1,45 @@ +# Task: Travel action and leg progression + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 3 — Travel as an intent + +## Description + +Replace the `WAIT + travel_to` compatibility branch with `ActionType.TRAVEL`. Starting travel resolves a route, records a travel intent, and leaves the creature at its origin until the first leg's game-time boundary. Each boundary moves the creature to exactly the next graph node and schedules the following leg; the final boundary clears the intent and returns an eligible anchor to play. + +Route progression must use the same activation and fast-forward lifecycle as timed wait/sleep. It must never call `World.advance_time()` inside the action handler and must not teleport directly to the final destination. + +## Tests First + +- A creature starting a three-edge journey remains at the origin immediately after the action, then appears at each intermediate node only after that leg's travel time has elapsed. +- With no other awake anchor, the round loop fast-forwards one leg at a time and returns control after final arrival; with another awake anchor, normal rounds continue while the traveler remains dormant between boundaries. +- Saving after an intermediate arrival and loading the session continues along the stored remaining route and arrives once, without skipping or replaying a leg. +- Two traveling creatures whose routes share an intermediate node can occupy that node at the same game time without either being teleported to its destination. +- Unknown and unreachable destinations fail without changing location or leaving an intent; WAIT no longer accepts `travel_to`. + +## Implementation + +Add the action definition, dispatcher registration, provider exposure, and a travel handler that validates the destination and starts the first leg. Generalize the entities wake-boundary query and intent completion path so the next travel-leg arrival participates in `Round._fast_forward`. At a leg boundary, update `location_id`, then either schedule the next boundary through the graph's existing distance-to-travel-time contract or complete the intent. + +Keep built-in interruption rules out of this task and Phase 3. Phase 4 will define what combat, bodily events, or scene entry do to an in-progress journey. + +Likely files: `core/action.py`, `core/action_defs.py`, `service/action_dispatcher.py`, `rules/handlers/movement.py`, `layers/entities/intent_completion.py`, `layers/entities/activation_manager.py`, `layers/entities/layer.py`, `round.py`, and handler/round/session tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] `TRAVEL` is a peaceful action and `WAIT` has no travel parameter or teleport branch. +- [x] Location changes occur only at graph-edge time boundaries, one edge at a time. +- [x] Fast-forward, save/load, and concurrent travelers preserve route progress. +- [x] Invalid travel is atomic from the caller's perspective. + +## Status + +`done` + +## Developer Notes + +`ActionType.TRAVEL` now resolves and stores the route without moving the actor or advancing world time. Activation advances every elapsed leg boundary, schedules the next one from the persisted boundary, and clears the intent only on final arrival; the round loop passes the world graph into activation and treats travel arrivals as fast-forward wake points. Legacy `WAIT + travel_to` behavior and schema were removed. Product tests cover intermediate nodes, invalid atomic starts, multi-leg fast-forward, two travelers sharing a node, and save/load continuation. diff --git a/docs/sprints/022-intents-travel/tasks/phase3-task3-journey-ui.md b/docs/sprints/022-intents-travel/tasks/phase3-task3-journey-ui.md new file mode 100644 index 00000000..d54902f6 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase3-task3-journey-ui.md @@ -0,0 +1,45 @@ +# Task: Journey status and UI + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 3 — Travel as an intent + +## Description + +Expose the player's current travel state through the existing REST and WebSocket player-status contract, and update the location UI to send the first-class travel action. While a journey is active, the UI must show the final destination and route progress; after arrival it must return to the ordinary location/path view with no stale journey state. + +All labels and user-visible journey text must use the existing frontend i18n catalogs, with RU as the default locale. + +## Tests First + +- Starting travel from `LocationPanel` sends `name: "travel"` with a destination parameter, never a zero-hour wait payload. +- A mid-journey status payload identifies the final destination, current leg/progress, and arrival boundary; a completed journey omits active travel state and reports the arrived location. +- The UI renders an in-progress multi-edge journey from status data and switches cleanly to the destination's neighboring paths when the arrival turn is delivered. +- A save/load/reconnect during travel returns the same journey status and allows the UI to continue displaying progress until the one final completion. + +## Implementation + +Add a compact optional journey view to the shared `PlayerStatusData` contract and its TypeScript counterpart. Build it from the persisted travel intent in `service/session.py`, resolving location IDs to user-facing names at the service boundary. Update `LocationPanel` and focused component/store tests; add English and Russian gettext/i18n entries. Do not make the frontend infer route progress from event-log strings. + +Likely files: `service/dto.py`, `service/session.py`, adapter schema tests, `frontend/src/types/game.ts`, `frontend/src/components/game/LocationPanel.tsx`, its tests, and `frontend/src/i18n/locales/{en,ru}/game.json`. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] REST and WebSocket status use one typed journey contract. +- [x] The location UI sends `TRAVEL` and shows persisted multi-leg progress. +- [x] Arrival clears journey presentation and refreshes the visible location paths. +- [x] New user-visible strings are localized in English and Russian. + +## Status + +`done` + +## Developer Notes + +`PlayerStatusData` теперь содержит опциональный типизированный journey view с разрешёнными именами текущей +точки, следующей остановки, оставшегося маршрута и финальной цели. REST и все WS round payloads строят его одним +`build_player_status`; после завершения сохранённого intent поле становится `null`. `LocationPanel` отправляет +`travel` с `destination_id`, показывает persisted route и возвращается к обычным путям после arrival update. diff --git a/docs/sprints/022-intents-travel/tasks/phase4-task1-built-in-intent-interruptions.md b/docs/sprints/022-intents-travel/tasks/phase4-task1-built-in-intent-interruptions.md new file mode 100644 index 00000000..519b0f85 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase4-task1-built-in-intent-interruptions.md @@ -0,0 +1,45 @@ +# Task: Built-in intent interruptions + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 4 — Interruptible journeys and E2E closure + +## Description + +Define one engine-level operation for interrupting a creature's current wait, sleep, or travel intent and wire it to the built-in reasons already owned by the entities layer. Taking damage and entering combat interrupt immediately. A traveler arriving at a location held by another awake anchor is drawn into that scene and stops there instead of silently continuing to the next edge. Ordinary leg arrival without a scene continues the stored route, while final arrival and elapsed wait/sleep remain successful completion rather than interruption. + +The operation must be idempotent and must not apply rest rewards or travel progress twice. Interruption keeps the creature at its last reached location, clears the intent once, and makes an eligible anchor available on the next activation pass. Keep the reason set built in; declarative trigger tables and Brain policy remain out of scope. + +## Tests First + +- A sleeping or waiting creature that takes damage wakes immediately without receiving rest completion benefits; repeating the interruption is a no-op. +- Starting combat at a location clears every participant's active intent before initiative proceeds, without moving a traveler or duplicating a combat participant. +- A traveler arriving at an intermediate location occupied by an awake anchor stops at that location and regains control; the same leg arrival at an otherwise dormant location schedules the next leg normally. +- Reaching a final destination clears travel as successful arrival, and reaching a wait or sleep timer applies its completion exactly once rather than reporting an interruption. + +## Implementation + +Add a focused interruption reason and helper beside the existing intent completion functions. Call it from the authoritative damage/combat paths and from activation after a travel leg reaches a scene. Preserve the existing `advance_travel_intent` route state until the reached leg has been committed, then decide whether to continue or interrupt. Emit structured logs/events only from this central operation so callers cannot disagree about semantics. + +Likely files: `core/intent.py`, `layers/entities/intent_completion.py`, `layers/entities/activation_manager.py`, `layers/entities/combat_manager.py`, `layers/entities/combat_resolution.py`, and product-level intent/combat/round tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Damage, combat entry, and arrival into an awake scene interrupt through one idempotent operation. +- [x] Interrupted rest grants no completion effects and interrupted travel remains at the last reached location. +- [x] Timer completion, ordinary leg progression, and final arrival retain their existing successful behavior. + +## Status + +`done` + +## Developer Notes + +Added one idempotent interruption helper with built-in damage, combat, and scene reasons. Combat entry interrupts +all participants before their combat state is initialized; positive attack damage uses the same helper without +granting rest completion. Activation now commits travel one leg at a time, so arrival at a location already held by +an awake anchor stops the traveler there, while dormant locations, final arrival, and timed completion keep their +existing behavior. Full backend and frontend checks passed. diff --git a/docs/sprints/022-intents-travel/tasks/phase4-task2-interruption-lifecycle.md b/docs/sprints/022-intents-travel/tasks/phase4-task2-interruption-lifecycle.md new file mode 100644 index 00000000..b18121c7 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase4-task2-interruption-lifecycle.md @@ -0,0 +1,65 @@ +# Task: Interruption lifecycle consistency + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 4 — Interruptible journeys and E2E closure + +## Description + +Pin interruption behavior through the real session boundary. Saving and loading immediately before or after an interruption, disconnecting and reconnecting during a journey, and resuming the round must converge on the same world time, location, intent, and turn ownership. A stale round or repeated activation must not replay the reached leg, restore a cleared intent, grant rest twice, or deliver two player turns. + +Cover both peaceful scene interruption and combat interruption through the session-owned mutation gate introduced in Phase 1. File snapshots remain outside the gate after their immutable state is built; this task should extend the existing lifecycle contract rather than add a second synchronization mechanism. + +## Tests First + +- Save during a multi-leg journey, load, reconnect, then enter an occupied intermediate scene: the player stops at that node with no remaining intent and receives exactly one playable turn. +- Save immediately after a damage or combat interruption and load it: the cleared intent stays cleared, rest rewards are absent, and combat/location state matches the pre-save session. +- Disconnect while traveling and reconnect after the next boundary: only the connection-driven round resumes, advances the leg at most once, and emits one current player status. +- Concurrent snapshot and interruption produce either the complete pre-interruption state or the complete post-interruption state, never a cleared intent paired with the wrong location or combat state. + +## Implementation + +Add integration coverage around `GameSession`, save/load commands, round activation, and the player WebSocket path. Keep all interruption mutations inside the session world-mutation scope and build status from the committed world state. Adjust orchestration only where the tests expose a replay or ordering bug; do not introduce transport-specific intent logic. + +Likely files: `service/session.py`, `service/commands_save.py`, `round.py`, API WebSocket integration tests, and session/save concurrency tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Save/load before and after interruption restores one internally consistent state. +- [x] Reconnect resumes travel or the interrupted player turn exactly once. +- [x] Snapshot and interruption remain atomic under the existing session mutation gate. + +## Status + +`done` + +## Developer Notes + +Added `tests/unit/test_interruption_lifecycle.py` (6 tests) pinning interruption behaviour +through the real session boundary. No orchestration change was needed: the phase 1-3 machinery +(session world-mutation/read gate, per-entity intent + combat serialization, idempotent +`interrupt_intent`, leg-by-leg `advance_travel_leg`) already satisfies the contract, so this is a +regression/characterization task. Consistent with how the repo closes phases, tests pass on first +run; I verified they are non-vacuous rather than weak: + +- Group A drives the real `save_game`/`load_game` commands over on-disk `sword_vale`: mid-journey + save then load restores the exact `TravelIntent`, and advancing to an occupied intermediate node + stops the traveler with the intent cleared (repeated activation does not replay the leg). + Save-after-damage keeps the sleep intent cleared with no long-rest heal/pool reset; save-after + combat entry restores `in_combat` + `CombatState` with the intent cleared. +- Group B drives `Round.run_loop` synchronously over a minimal travel world: a resumed round + fast-forwards each leg exactly once, a stale re-entry is a no-op (no leg replay, +6s only, one + extra turn), and repeated activation after a scene interruption never re-advances. +- Group C hammers `build_save_game` from one thread while another toggles combat entry/exit under + `session.mutate_world()`; every snapshot is coherent (pre or post, never torn). + +Non-vacuousness confirmed by temporary breaks: stubbing `interrupt_intent` to skip clearing fails +5/6 (the 6th is a non-interrupted journey); bypassing `read_world` in `build_save_game` makes the +concurrency test observe `intent=True + has_combat=True`. Both breaks reverted. + +Note: `test_ws.py::test_wait_fast_forwards_past_nearby_rule_npc` flaked once under the full parallel +`make check` run (timing in the background round thread, `len(messages)` 5 vs ≤4); it passes in +isolation and on rerun. Pre-existing WS-timing flake, unrelated to this change. diff --git a/docs/sprints/022-intents-travel/tasks/phase4-task3-accessibility-e2e.md b/docs/sprints/022-intents-travel/tasks/phase4-task3-accessibility-e2e.md new file mode 100644 index 00000000..04a748b9 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase4-task3-accessibility-e2e.md @@ -0,0 +1,61 @@ +# Task: Target accessibility and journey E2E + +**Date:** 2026-07-11 +**Sprint:** 022-intents-travel +**Phase:** 4 — Interruptible journeys and E2E closure + +## Description + +Make every visible Attack control identify its target in the accessibility tree, then validate the completed sprint through the real UI. The nearby list, NPC inspect modal, action-bar target menu, and smite choices must expose distinct localized names when several attack controls are present. Close `attack-buttons-accessible-names` only after a component test and browser scenario select the intended target by role and accessible name. + +Run the phase E2E scenario through travel, save/load or reconnect, interruption at an intermediate location, and return of player control. Confirm the journey panel clears at interruption, the displayed location is the reached node, combat or scene UI is coherent, and a later status update does not replay progress. Use the normal phase report boundary; any non-trivial product failure becomes a finding rather than expanding this task beyond quick-fix scope. + +## Tests First + +- With two nearby targets and an open inspect modal, every Attack button has a unique localized accessible name containing its target; selecting one sends that target ID. +- Action-bar and smite menu items remain uniquely selectable by accessible name in both English and Russian. +- After an interrupted mid-route journey, the UI clears journey progress, shows the reached location, and exposes exactly one player action surface. + +## Implementation + +Add target-aware gettext strings or `aria-label` values to the remaining bare Attack controls in `Perception` and `NpcInspectModal`, reusing the existing action-bar target naming contract where possible. Update focused frontend tests and the backlog checkbox. Then execute the phase E2E checklist against a clean detached stack and write `docs/sprints/022-intents-travel/e2e/phase4-report.md`. + +Likely files: `frontend/src/components/game/Perception.tsx`, `frontend/src/components/game/NpcInspectModal.tsx`, focused component tests, `frontend/src/i18n/locales/{en,ru}/game.json`, `docs/BACKLOG.md`, and the phase E2E report. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check`) +- [x] Every Attack control exposed at the same time has a unique target-aware accessible name in EN and RU. +- [x] Browser automation selects the intended target without text or DOM-position ambiguity. +- [~] Phase E2E covers a persisted or reconnected journey interrupted at an intermediate location and reports no blockers. +- [x] `attack-buttons-accessible-names` is marked complete only after the browser scenario passes. + +## Status + +`done` + +## Developer Notes + +Accessibility: added target-aware `aria-label`s to the Attack/Talk/Inspect controls in `Perception.tsx` +and the Attack control in `NpcInspectModal.tsx`, plus an `inspect_target` EN/RU string. The label +target keys on the unique `entity.id` (the same contract the action-bar `TargetDropdown` already uses), +not the perceived description — the description is the localized **race** (`человек`), which collides +for same-race NPCs and would leave duplicate `Attack человек` names. `SmiteChoice` also now names its +target by id in both call sites. Component tests in `Perception.test.tsx` (nearby uniqueness + +selection + EN/RU + smite menu) and a `LocationPanel.test.tsx` mid-route-interruption test. Frontend +gate green (282 tests). Backend untouched, unchanged since task 2. + +E2E (`e2e/phase4-report.md`): live browser run confirmed unique target-aware attack names for three +simultaneous market NPCs in EN and RU, the inspect modal's Attack unambiguous (Radix hides the +background), a genuine multi-leg journey progressing leg-by-leg (`travel_leg_arrive` market→smithy) +and clearing on arrival with control returned, and coherent combat entry. Backend/browser logs clean. + +The one partial criterion (`[~]`): a *mid-route SCENE interruption* is not reproducible through the +current control surface — stopping a traveler at an intermediate node needs a second awake anchor +there, but `is_anchor` is not exposed by the master API and authored NPCs are not awake anchors (a +2-leg journey fast-forwarded straight through the NPC-populated market). The interruption logic +itself is fully covered by task-1/task-2 unit + integration tests and the `LocationPanel` component +test; logged as a minor E2E finding (candidate backlog: expose an anchor toggle so the mid-route stop +is playable). Not a blocker. diff --git a/docs/sprints/022-intents-travel/tasks/phase5-task1-bounded-round-stop.md b/docs/sprints/022-intents-travel/tasks/phase5-task1-bounded-round-stop.md new file mode 100644 index 00000000..797bf566 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase5-task1-bounded-round-stop.md @@ -0,0 +1,65 @@ +# Task: Bounded round-stop contract + +**Date:** 2026-07-12 +**Sprint:** 022-intents-travel +**Phase:** 5 — Bounded round shutdown + +## Description + +Сделать остановку round thread ограниченной по времени и атомарной относительно lifecycle-состояния +сессии. Если поток не завершился за заданный срок, `stop_round()` должен вернуть явную ошибку и оставить +ссылки на тот же round, brain и thread. Пока этот поток жив, новый round не запускается, а вызывающий код +может повторить остановку после освобождения блокирующего callback. + +Успешная остановка сохраняет текущий контракт: round получает stop, очереди player brain разблокируются, +поток завершается, после чего lifecycle-ссылки очищаются. Таймаут должен быть одной именованной настройкой +сессии и сопровождаться структурированным логом с session context. + +## Tests First + +- Round callback блокируется дольше stop timeout: `stop_round()` завершается за ограниченное время с + явной lifecycle-ошибкой, а живые round, brain и thread остаются привязаны к сессии. +- Пока старый поток жив после таймаута, повторный `start_round()` не создаёт второй loop и не заменяет + lifecycle-ссылки. +- После освобождения callback повторный `stop_round()` дожидается того же потока и очищает round, brain + и thread; следующий `start_round()` затем создаёт ровно один новый loop. +- Обычный parked player turn по-прежнему останавливается сразу и не достигает timeout path. + +## Implementation + +Перестроить `GameSession._stop_round()` в два этапа: под `_lock` получить стабильный lifecycle snapshot, +затем послать stop/unblock и выполнить bounded join без преждевременной очистки ссылок. После успешного +join очистить поля только если они всё ещё указывают на тот же snapshot. При живом потоке залогировать +timeout и выбросить отдельную понятную lifecycle-ошибку. + +Не отпускать `_round_transition_lock` между stop request, join и фиксацией результата. Не брать +`_world_state_lock` вокруг join: round может завершать текущую mutation scope. Не добавлять второй +механизм остановки в `Round`. + +Ключевые файлы: `service/session.py`, `tests/unit/test_session_lifecycle.py`. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check-backend`) +- [x] Stop ожидание ограничено одной именованной timeout-настройкой +- [x] Timeout не теряет ссылки на живой round thread +- [x] Живой старый thread исключает запуск второго round loop +- [x] Повторная остановка после освобождения callback полностью очищает lifecycle + +## Status + +`done` + +## Developer Notes + +`GameSession._stop_round()` теперь сначала фиксирует lifecycle snapshot, останавливает round и разблокирует +`PlayerBrain`, затем ждёт поток не дольше `DND_ROUND_STOP_TIMEOUT_SECONDS` (5 секунд по умолчанию). При timeout +выбрасывается `RoundStopTimeoutError`, пишется `stop_round_timeout` с session/thread context, а ссылки на живые +round, brain и thread остаются в сессии. Успешная повторная остановка очищает только тот же snapshot. + +Добавлены два lifecycle-теста: зависший listener callback покрывает timeout, идемпотентный start и recovery; +обычный parked player turn подтверждает быстрый happy path. Backend gate: lint, format и mypy зелёные, 2475 тестов +прошли; известный timing-флейк `test_wait_fast_forwards_past_nearby_rule_npc` один раз дал 5 сообщений вместо 4 +и сразу прошёл изолированно. diff --git a/docs/sprints/022-intents-travel/tasks/phase5-task2-lifecycle-boundary-failures.md b/docs/sprints/022-intents-travel/tasks/phase5-task2-lifecycle-boundary-failures.md new file mode 100644 index 00000000..50e87be1 --- /dev/null +++ b/docs/sprints/022-intents-travel/tasks/phase5-task2-lifecycle-boundary-failures.md @@ -0,0 +1,65 @@ +# Task: Lifecycle boundary failure handling + +**Date:** 2026-07-12 +**Sprint:** 022-intents-travel +**Phase:** 5 — Bounded round shutdown + +## Description + +Провести bounded-stop контракт через три пользовательских lifecycle-пути: disconnect последнего игрока, +`load_game()` и deferred eviction. Ни один путь не должен зависать, заменять мир или удалять сессию, пока +старый round thread жив. Ошибка остановки должна быть видна в логах и оставлять сессию в состоянии, которое +можно восстановить повторной остановкой или реконнектом после завершения callback. + +Успешные пути не меняются: disconnect сразу паузит round и ставит eviction timer, load очищает cached +transport state и атомарно восстанавливает snapshot только после завершения старого round, eviction делает +autosave и удаляет только уже остановленную сессию. + +## Tests First + +- При блокирующем callback disconnect последнего player listener возвращается за ограниченное время, + не запускает второй round при конкурентном reconnect и не маскирует timeout в логах. +- `load_game()` при timeout не вызывает loader: world, dice RNG, brains и cached turn остаются от старого + состояния; после завершения callback повторный load полностью восстанавливает snapshot. +- Deferred eviction при timeout не вызывает `_on_empty`, не autosave-ит потенциально изменяемый мир и не + удаляет сессию из registry; следующий успешный empty-check может завершить eviction. +- Обычные disconnect, load и eviction продолжают проходить существующие happy-path проверки. + +## Implementation + +Обработать lifecycle-ошибку в `remove_listener()`, `replace_world_state()` и `_run_evict_check()` на границах, +где различается политика продолжения. Load должен пробрасывать понятную ошибку вызывающему API и не входить +в loader. Фоновый eviction должен логировать отказ и не вызывать `_on_empty`; при необходимости безопасно +поставить повторную проверку, не создавая busy loop. Disconnect не должен считать round остановленным и +разрешать новый loop, пока сохранённый thread жив. + +Использовать существующие `_round_transition_lock`, eviction timer и session registry. Не добавлять +transport-specific флаги и не расширять фазу общей декомпозицией `session.py`. + +Ключевые файлы: `service/session.py`, `service/commands_save.py`, `service/game_service.py`, +`tests/unit/test_session_lifecycle.py`, `tests/unit/test_commands_save.py`, lifecycle/autosave tests. + +## Acceptance Criteria + +- [x] Tests written and RED (before implementation) +- [x] Implementation makes tests GREEN +- [x] Existing tests still pass (`make check-backend`) +- [x] Failed stop never replaces world or evicts the live session +- [x] Конкурентный reconnect не создаёт второй round loop +- [x] Фоновый timeout залогирован и не теряется в Timer thread +- [x] После завершения callback load и eviction можно успешно повторить + +## Status + +`done` + +## Developer Notes + +Disconnect теперь перехватывает `RoundStopTimeoutError`, пишет `disconnect_stop_failed` и всё равно ставит +deferred empty-check; reconnect сериализован тем же `_round_transition_lock`, а живой loop остаётся привязан к +сессии. Eviction при timeout пишет `evict_stop_failed`, не вызывает `_on_empty` и планирует повторную проверку +через обычный grace interval, поэтому autosave и удаление registry entry не происходят на живом round. + +Load сохранил правильную fail-fast семантику: `replace_world_state()` пробрасывает timeout до очистки cached turn +и входа в loader. Новый round-trip тест фиксирует неизменность world, dice RNG, brain/lifecycle и transport cache, +затем успешную повторную загрузку. Полный `make check` зелёный: backend 2479, frontend 282. diff --git a/frontend/src/components/game/ActionBar.tsx b/frontend/src/components/game/ActionBar.tsx index 271eb4e2..079474b0 100644 --- a/frontend/src/components/game/ActionBar.tsx +++ b/frontend/src/components/game/ActionBar.tsx @@ -37,7 +37,7 @@ export function ActionBar() { ) } - const ALWAYS_HIDDEN = new Set(["buy", "sell", "take", "move", "move_to"]) + const ALWAYS_HIDDEN = new Set(["buy", "sell", "take", "move", "move_to", "travel"]) const PEACEFUL_ONLY_HIDDEN = new Set(["use_item", "equip", "unequip"]) const available = (awareness?.available_actions ?? []).filter( (a) => !ALWAYS_HIDDEN.has(a.name) && !(mode === "peaceful" && PEACEFUL_ONLY_HIDDEN.has(a.name)), diff --git a/frontend/src/components/game/LocationPanel.tsx b/frontend/src/components/game/LocationPanel.tsx index 9b7dfd20..bb877f0a 100644 --- a/frontend/src/components/game/LocationPanel.tsx +++ b/frontend/src/components/game/LocationPanel.tsx @@ -7,12 +7,13 @@ import { MapPin } from "lucide-react" export function LocationPanel() { const { t } = useTranslation(["game"]) const location = useGameStore((s) => s.location) + const journey = useGameStore((s) => s.player?.journey) const isMyTurn = useGameStore((s) => s.isMyTurn) if (!location) return null const sendGo = (locationId: string) => { - wsClient.send({ type: "action", name: "wait", params: { hours: 0, travel_to: locationId } }) + wsClient.send({ type: "action", name: "travel", params: { destination_id: locationId } }) useGameStore.getState().setWaitingForAction(true) } @@ -28,6 +29,16 @@ export function LocationPanel() {

{location.description}

)} + {journey && ( +
+

{t("game:journey_to", { destination: journey.destination_name })}

+

+ {t("game:journey_route", { + route: [journey.current_location_name, ...journey.remaining_route].join(" → "), + })} +

+
+ )} {location.paths.length > 0 && (

{t("game:paths")}

diff --git a/frontend/src/components/game/NpcInspectModal.tsx b/frontend/src/components/game/NpcInspectModal.tsx index 6fb387e1..66d0df26 100644 --- a/frontend/src/components/game/NpcInspectModal.tsx +++ b/frontend/src/components/game/NpcInspectModal.tsx @@ -159,7 +159,12 @@ export function NpcInspectModal({ entity, open, onClose, isCombat }: NpcInspectM {/* Action buttons */} {isMyTurn && !nearby?.is_dead && (
- {!isCombat && ( diff --git a/frontend/src/components/game/Perception.tsx b/frontend/src/components/game/Perception.tsx index 8bd17ef4..fc81b99a 100644 --- a/frontend/src/components/game/Perception.tsx +++ b/frontend/src/components/game/Perception.tsx @@ -49,11 +49,13 @@ export function Perception() { {nearby.length === 0 && (

{t("common:nobody_around")}

)} - {nearby.map((entity) => ( + {nearby.map((entity) => { + const targetName = entity.description || entity.id + return (
- {entity.description || entity.id} + {targetName} {entity.is_wounded && {t("game:wounded")}}
@@ -67,6 +69,7 @@ export function Perception() {
)}
- ))} + ) + })} { }) describe("ActionBar — cost-type styling", () => { + it("leaves destination-based travel to the location panel", () => { + setCombatState([ + makeAction("travel", "action", [{ name: "destination_id", type: "string", required: true }]), + makeAction("end_turn", "free"), + ], fullBudget) + + render() + + expect(screen.queryByRole("button", { name: /travel|путеше/i })).not.toBeInTheDocument() + }) + it("renders core combat buttons with data-cost-type attribute", () => { setCombatState( [ diff --git a/frontend/src/components/game/__tests__/LocationPanel.test.tsx b/frontend/src/components/game/__tests__/LocationPanel.test.tsx new file mode 100644 index 00000000..8462f0b4 --- /dev/null +++ b/frontend/src/components/game/__tests__/LocationPanel.test.tsx @@ -0,0 +1,125 @@ +import { act, render, screen } from "@testing-library/react" +import userEvent from "@testing-library/user-event" +import { beforeEach, describe, expect, it, vi } from "vitest" +import "@/i18n" +import { useGameStore } from "@/store/gameStore" +import { wsClient } from "@/transport/wsClient" +import type { LocationData, PlayerStatus } from "@/types/game" +import { LocationPanel } from "../LocationPanel" + +vi.mock("@/transport/wsClient", () => ({ + wsClient: { + send: vi.fn(), + onStatus: vi.fn(), + onMessage: vi.fn(), + getStatus: vi.fn(() => "disconnected"), + connect: vi.fn(), + disconnect: vi.fn(), + }, +})) + +const sendMock = wsClient.send as unknown as ReturnType + +const location: LocationData = { + current_location: "Old Road", + current_location_id: "road", + description: "A dusty road", + region_id: "r", + paths: [{ target_id: "bridge", target_name: "Stone Bridge", distance_m: 500 }], +} + +const player: PlayerStatus = { + player_id: "p1", + name: "Hero", + race: "human", + char_class: "fighter", + level: 1, + experience: 0, + level_up_available: false, + xp_to_next_level: 300, + alignment: "neutral", + hp: 10, + max_hp: 10, + ac: 12, + gold: 0, + location_id: "road", + ability_scores: { str: 10, dex: 10, con: 10, int: 10, wis: 10, cha: 10 }, +} + +beforeEach(() => { + sendMock.mockReset() + useGameStore.setState({ location, player, isMyTurn: true, waitingForAction: false }) +}) + +describe("LocationPanel journey", () => { + it("starts first-class travel instead of a zero-hour wait", async () => { + render() + + await userEvent.click(screen.getByRole("button", { name: /Stone Bridge/i })) + + expect(sendMock).toHaveBeenCalledWith({ + type: "action", + name: "travel", + params: { destination_id: "bridge" }, + }) + }) + + it("shows persisted route progress and clears it on arrival status", () => { + useGameStore.setState({ + player: { + ...player, + journey: { + destination_id: "keep", + destination_name: "Hill Keep", + current_location_name: "Old Road", + next_location_name: "Stone Bridge", + remaining_route: ["Stone Bridge", "Hill Keep"], + next_arrival_seconds: 460, + }, + }, + }) + render() + expect(screen.getByText(/Old Road.*Stone Bridge.*Hill Keep/)).toBeInTheDocument() + + act(() => { + useGameStore.setState({ + player: { ...player, location_id: "keep" }, + location: { ...location, current_location: "Hill Keep", current_location_id: "keep" }, + }) + }) + + expect(screen.queryByText(/Old Road.*Stone Bridge.*Hill Keep/)).not.toBeInTheDocument() + expect(screen.getByText("Hill Keep")).toBeInTheDocument() + }) + + it("clears journey progress and shows the reached node when interrupted mid-route", () => { + useGameStore.setState({ + player: { + ...player, + journey: { + destination_id: "keep", + destination_name: "Hill Keep", + current_location_name: "Old Road", + next_location_name: "Stone Bridge", + remaining_route: ["Stone Bridge", "Hill Keep"], + next_arrival_seconds: 460, + }, + }, + }) + render() + expect(screen.getByTestId("journey-status")).toBeInTheDocument() + + // Interruption at the intermediate node: intent cleared (journey undefined), + // location is the reached node — not the original destination. + act(() => { + useGameStore.setState({ + player: { ...player, location_id: "bridge" }, + location: { current_location: "Stone Bridge", current_location_id: "bridge", region_id: "r", paths: [] }, + }) + }) + + expect(screen.queryByTestId("journey-status")).not.toBeInTheDocument() + expect(screen.getByText("Stone Bridge")).toBeInTheDocument() + expect(screen.queryByText("Hill Keep")).not.toBeInTheDocument() + }) +}) diff --git a/frontend/src/components/game/__tests__/Perception.test.tsx b/frontend/src/components/game/__tests__/Perception.test.tsx index 3d3aa3f9..2cdea983 100644 --- a/frontend/src/components/game/__tests__/Perception.test.tsx +++ b/frontend/src/components/game/__tests__/Perception.test.tsx @@ -1,6 +1,7 @@ -import { render, screen } from "@testing-library/react" -import { describe, it, expect, beforeEach, vi } from "vitest" -import "@/i18n" +import { act, render, screen } from "@testing-library/react" +import userEvent from "@testing-library/user-event" +import { afterEach, describe, it, expect, beforeEach, vi } from "vitest" +import i18n from "@/i18n" vi.mock("@/transport/wsClient", () => ({ wsClient: { @@ -14,8 +15,11 @@ vi.mock("@/transport/wsClient", () => ({ })) import { useGameStore } from "@/store/gameStore" +import { wsClient } from "@/transport/wsClient" import { Perception } from "../Perception" -import type { NearbyEntity, PeacefulAwareness } from "@/types/game" +import type { CombatAwareness, NearbyEntity, PeacefulAwareness } from "@/types/game" + +const sendMock = wsClient.send as unknown as ReturnType function makeAwareness(nearby: NearbyEntity[]): PeacefulAwareness { return { @@ -31,6 +35,7 @@ function makeAwareness(nearby: NearbyEntity[]): PeacefulAwareness { } beforeEach(() => { + sendMock.mockReset() useGameStore.setState({ mode: "explore", awareness: null, @@ -38,6 +43,31 @@ beforeEach(() => { }) }) +afterEach(async () => { + await act(async () => { + await i18n.changeLanguage("en") + }) +}) + +function makeCombatAwareness(nearby: NearbyEntity[]): CombatAwareness { + return { + self_hp: 20, + self_max_hp: 20, + self_ac: 15, + self_speed: 30, + self_weapon: "Longsword", + self_weapon_damage: "1d8", + self_conditions: [], + nearby: nearby as unknown as CombatAwareness["nearby"], + round_number: 1, + available_actions: [], + available_items: [], + self_resource_pools: [ + { id: "spell_slot_1", max_uses: 2, current_uses: 2, reset_on: "long_rest" }, + ], + } +} + describe("Perception — corpse/lootable entities hide Attack/Talk", () => { it("hides Attack and Talk for a lootable (corpse/container) entity", () => { useGameStore.setState({ @@ -65,3 +95,78 @@ describe("Perception — corpse/lootable entities hide Attack/Talk", () => { expect(screen.getByText("Talk")).toBeInTheDocument() }) }) + +describe("Perception — target-aware attack accessibility", () => { + // Two same-race NPCs: their perceived descriptions collide ("человек"/"Goblin"), so the + // accessible name must key on the unique entity id — matching the action-bar contract. + const twoTargets: NearbyEntity[] = [ + { id: "goblin_1", description: "Goblin", lootable: false }, + { id: "goblin_2", description: "Goblin", lootable: false }, + ] + + it("gives each nearby Attack control a unique target-aware accessible name and sends its id", async () => { + useGameStore.setState({ awareness: makeAwareness(twoTargets) }) + render() + + const attackOne = screen.getByRole("button", { name: "Attack goblin_1" }) + const attackTwo = screen.getByRole("button", { name: "Attack goblin_2" }) + expect(attackOne).not.toBe(attackTwo) + + await userEvent.click(attackTwo) + expect(sendMock).toHaveBeenCalledWith({ + type: "action", + name: "attack", + params: { target_id: "goblin_2" }, + }) + }) + + it("keeps the open inspect modal's Attack control target-aware and unambiguous", async () => { + useGameStore.setState({ awareness: makeAwareness(twoTargets) }) + render() + + await userEvent.click(screen.getByRole("button", { name: "Inspect goblin_1" })) + + // Radix hides the background list from the a11y tree, so the modal's control is + // the only "Attack goblin_1" button reachable by role + name. + const modalAttack = screen.getByRole("button", { name: "Attack goblin_1" }) + expect(modalAttack).toBeInTheDocument() + await userEvent.click(modalAttack) + expect(sendMock).toHaveBeenCalledWith({ + type: "action", + name: "attack", + params: { target_id: "goblin_1" }, + }) + }) + + it("localizes the nearby Attack accessible name in Russian", async () => { + await act(async () => { + await i18n.changeLanguage("ru") + }) + useGameStore.setState({ awareness: makeAwareness(twoTargets) }) + render() + + expect(screen.getByRole("button", { name: "Атаковать goblin_1" })).toBeInTheDocument() + expect(screen.getByRole("button", { name: "Атаковать goblin_2" })).toBeInTheDocument() + }) + + it.each([ + ["en", "Attack goblin_1", "Attack goblin_1 + Smite (slot 1)"], + ["ru", "Атаковать goblin_1", "Атаковать goblin_1 + Кара (ячейка 1)"], + ])("exposes smite menu items selectable by localized accessible name (%s)", async (lang, normal, withSmite) => { + await act(async () => { + await i18n.changeLanguage(lang) + }) + useGameStore.setState({ + mode: "combat", + awareness: makeCombatAwareness([{ id: "goblin_1", description: "Goblin", is_hostile: true }]), + }) + render() + + await userEvent.click(screen.getByRole("button", { name: normal })) + + const items = screen.getAllByRole("menuitem").map((el) => (el.textContent ?? "").trim()) + // The plain-attack item is exactly the target label; the smite item prefixes it. + expect(items).toContain(normal) + expect(items.some((label) => label.startsWith(withSmite))).toBe(true) + }) +}) diff --git a/frontend/src/i18n/locales/en/game.json b/frontend/src/i18n/locales/en/game.json index 18018af2..aa9263e7 100644 --- a/frontend/src/i18n/locales/en/game.json +++ b/frontend/src/i18n/locales/en/game.json @@ -9,8 +9,11 @@ "target_self": "Self", "talk": "Talk", "inspect": "Inspect", + "inspect_target": "Inspect {{target}}", "location": "Location", "paths": "Paths:", + "journey_to": "Traveling to {{destination}}", + "journey_route": "Route: {{route}}", "character": "Character", "actions_label": "Actions: {{n}}", "bonus_label": "Bonus: {{n}}", @@ -38,6 +41,7 @@ "use_item": "Use Item", "idle": "Look", "wait": "Wait", + "travel": "Travel", "say": "Say", "distance": "{{ft}}ft {{dir}}", "battle_map": "Battle Map", diff --git a/frontend/src/i18n/locales/ru/game.json b/frontend/src/i18n/locales/ru/game.json index 18c3959c..07d42eac 100644 --- a/frontend/src/i18n/locales/ru/game.json +++ b/frontend/src/i18n/locales/ru/game.json @@ -9,8 +9,11 @@ "target_self": "Себя", "talk": "Говорить", "inspect": "Осмотреть", + "inspect_target": "Осмотреть {{target}}", "location": "Локация", "paths": "Пути:", + "journey_to": "Путь к {{destination}}", + "journey_route": "Маршрут: {{route}}", "character": "Персонаж", "actions_label": "Действия: {{n}}", "bonus_label": "Бонус: {{n}}", @@ -38,6 +41,7 @@ "use_item": "Предмет", "idle": "Осмотреться", "wait": "Ждать", + "travel": "Путешествовать", "say": "Говорить", "distance": "{{ft}}фт {{dir}}", "battle_map": "Карта боя", diff --git a/frontend/src/types/game.ts b/frontend/src/types/game.ts index 95f02ac6..17373415 100644 --- a/frontend/src/types/game.ts +++ b/frontend/src/types/game.ts @@ -254,6 +254,15 @@ export interface AbilityScores { cha: number } +export interface JourneyStatus { + destination_id: string + destination_name: string + current_location_name: string + next_location_name: string + remaining_route: string[] + next_arrival_seconds: number +} + /** * Player status — single source for both the REST `player_status` response and * the WS status payload (backend `PlayerStatusData`). `appearance`/`equipped`/ @@ -277,6 +286,7 @@ export interface PlayerStatus { location_id: string appearance?: string ability_scores: AbilityScores + journey?: JourneyStatus | null equipped?: EquippedInfo[] inventory?: ItemInfo[] resource_pools?: ResourcePoolInfo[] @@ -295,6 +305,7 @@ export type ActionName = | "end_turn" | "skip" | "wait" + | "travel" | "use_item" | "bless" | "equip" diff --git a/src/dnd_simulator/adapters/api/app.py b/src/dnd_simulator/adapters/api/app.py index 143977bb..fab8c1bf 100644 --- a/src/dnd_simulator/adapters/api/app.py +++ b/src/dnd_simulator/adapters/api/app.py @@ -85,12 +85,6 @@ async def lifespan(_app: FastAPI) -> AsyncIterator[None]: log_dir_raw = os.getenv("LOG_DIR") configure_logging(log_level=log_level, log_dir=Path(log_dir_raw) if log_dir_raw else None) - dice_seed = os.getenv("DND_DICE_SEED") - if dice_seed is not None: - from dnd_simulator.rules.dice import set_global_seed - - set_global_seed(int(dice_seed)) - store = JsonFileStore(DEFAULT_SAVES_DIR) llm: LlmClient | None = None diff --git a/src/dnd_simulator/adapters/api/schemas.py b/src/dnd_simulator/adapters/api/schemas.py index e11eccdf..3c6ad038 100644 --- a/src/dnd_simulator/adapters/api/schemas.py +++ b/src/dnd_simulator/adapters/api/schemas.py @@ -178,6 +178,15 @@ class WorldListItem(BaseModel): editable: bool +class JourneyResponse(BaseModel): + destination_id: str + destination_name: str + current_location_name: str + next_location_name: str + remaining_route: list[str] + next_arrival_seconds: int + + class PlayerStatusResponse(BaseModel): player_id: str name: str @@ -195,6 +204,7 @@ class PlayerStatusResponse(BaseModel): location_id: str appearance: str ability_scores: dict[str, int] + journey: JourneyResponse | None = None resource_pools: list[dict[str, object]] = Field(default_factory=list) equipped: list[dict[str, str]] = Field(default_factory=list) inventory: list[dict[str, object]] = Field(default_factory=list) diff --git a/src/dnd_simulator/core/__init__.py b/src/dnd_simulator/core/__init__.py index b021bdd0..c3fc9c6d 100644 --- a/src/dnd_simulator/core/__init__.py +++ b/src/dnd_simulator/core/__init__.py @@ -5,7 +5,9 @@ - Event, Query, Answer, ActionResult, QueryFn, EmitFn — communication protocol between layers - Layer — abstract base class; tick/handle_event receive query_fn + emit_fn for layer isolation - World — container that holds layers, manages per-layer tick scheduling, enforces layer ordering via query_fn/emit_fn -- Entity → Creature (in_combat, brain, conditions, weapon) → Character with activation, ability scores, perception +- Entity → Creature (combat, anchor, persisted intent, brain, conditions, weapon) + → Character with ability scores and perception +- TimedIntent, TravelIntent, IntentType, IntentInterruptReason — activities spanning game time - Action (name + params), END_TURN, SKIP — transport-agnostic creature actions - TurnBudget, ActionCost — per-turn resource tracking (actions, bonus actions, movement, reaction) - Condition enum, ConditionsMap — D&D 5e status effects (rounds-based or permanent) diff --git a/src/dnd_simulator/core/action.py b/src/dnd_simulator/core/action.py index 663e199d..a9e17331 100644 --- a/src/dnd_simulator/core/action.py +++ b/src/dnd_simulator/core/action.py @@ -17,6 +17,7 @@ class ActionType(StrEnum): MOVE = "move" DASH = "dash" WAIT = "wait" + TRAVEL = "travel" USE_ITEM = "use_item" BLESS = "bless" EQUIP = "equip" diff --git a/src/dnd_simulator/core/action_defs.py b/src/dnd_simulator/core/action_defs.py index 208fa5ca..5904bbe9 100644 --- a/src/dnd_simulator/core/action_defs.py +++ b/src/dnd_simulator/core/action_defs.py @@ -274,14 +274,23 @@ def get_action_def(action_type: ActionType) -> ActionDef: cost_type=CostType.FREE, combat_mode=CombatMode.PEACEFUL_ONLY, ends_peaceful_turn=True, - params=( - ParamDef("hours", "integer", N_("How many hours to wait (default: 1)")), - ParamDef("travel_to", "string", N_("Location ID to travel to instead of waiting in place")), - ), + params=(ParamDef("hours", "integer", N_("How many hours to wait (default: 1)")),), llm_hint="Wait and do nothing for a period of time. Useful when nothing is happening.", ) ) +_reg( + ActionDef( + action_type=ActionType.TRAVEL, + description=N_("Travel to a location through the world map."), + cost_type=CostType.FREE, + combat_mode=CombatMode.PEACEFUL_ONLY, + ends_peaceful_turn=True, + params=(ParamDef("destination_id", "string", N_("Location ID to travel to"), required=True),), + llm_hint="Travel along the shortest known route to a location. Time passes for every route leg.", + ) +) + _reg( ActionDef( action_type=ActionType.USE_ITEM, diff --git a/src/dnd_simulator/core/character.py b/src/dnd_simulator/core/character.py index 0622ef5b..0b233552 100644 --- a/src/dnd_simulator/core/character.py +++ b/src/dnd_simulator/core/character.py @@ -10,6 +10,7 @@ from dnd_simulator.core.class_features import ClassFeatures from dnd_simulator.core.conditions import Condition +from dnd_simulator.core.intent import CreatureIntent from dnd_simulator.core.items import EquipmentSlot, Item from dnd_simulator.core.resource import ResourcePool from dnd_simulator.core.turn_budget import TurnBudget @@ -228,7 +229,8 @@ class Creature(Entity): reputation: dict[str, int] = field(default_factory=dict) # sparse: faction_id → rep score xp_value: int = 0 # XP awarded to Character attacker on kill (0 for most creatures, set from CR for monsters) squad_id: str | None = None # which squad this creature belongs to (if materialized) - wake_at_seconds: int | None = None # absolute game-time seconds; None = not waiting + is_anchor: bool = False + current_intent: CreatureIntent | None = None combat_position: tuple[int, int] | None = None # fixed starting position on battle map (x, y in feet) brain: Brain | None = field(default=None, repr=False) diff --git a/src/dnd_simulator/core/creature_host.py b/src/dnd_simulator/core/creature_host.py index dbcea203..0892b001 100644 --- a/src/dnd_simulator/core/creature_host.py +++ b/src/dnd_simulator/core/creature_host.py @@ -24,6 +24,7 @@ ) from dnd_simulator.core.character import Character, Creature, Entity from dnd_simulator.core.combat import CombatState + from dnd_simulator.core.location import LocationGraph from dnd_simulator.core.models import EmitFn, GameDateTime, QueryFn from dnd_simulator.core.turn_budget import TurnBudget @@ -45,7 +46,7 @@ def get_merchants_at(self, location_id: str, hour: int) -> list[Character]: ... def get_nearest_wake_time(self) -> int | None: - """Return the earliest `wake_at_seconds` across dormant creatures, or None.""" + """Return the earliest timed-intent wake point, or None.""" ... def update_activation( @@ -53,8 +54,9 @@ def update_activation( time: GameDateTime, query_fn: QueryFn | None = None, emit_fn: EmitFn | None = None, + location_graph: LocationGraph | None = None, ) -> None: - """Refresh active/dormant state based on proximity to player anchors.""" + """Refresh active/dormant state based on proximity to awake anchors.""" ... def get_combat_locations(self) -> list[str]: diff --git a/src/dnd_simulator/core/intent.py b/src/dnd_simulator/core/intent.py new file mode 100644 index 00000000..8cec0944 --- /dev/null +++ b/src/dnd_simulator/core/intent.py @@ -0,0 +1,66 @@ +"""Persisted creature intentions that span game time.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import StrEnum + +from dnd_simulator.core.resource import RestType + + +class IntentType(StrEnum): + """Kinds of timed intent supported by the current simulation.""" + + WAIT = "wait" + SLEEP = "sleep" + TRAVEL = "travel" + + +class IntentInterruptReason(StrEnum): + """Built-in world events that stop an intent before completion.""" + + DAMAGE = "damage" + COMBAT = "combat" + SCENE = "scene" + + +@dataclass(frozen=True) +class TimedIntent: + """A creature activity with an absolute start and wake boundary.""" + + kind: IntentType + started_at_seconds: int + wake_at_seconds: int + rest_type: RestType | None = None + + def __post_init__(self) -> None: + if self.kind not in (IntentType.WAIT, IntentType.SLEEP): + raise ValueError("timed intent must be wait or sleep") + if self.wake_at_seconds < self.started_at_seconds: + raise ValueError("wake time cannot precede intent start time") + if self.rest_type is not None and self.kind is not IntentType.SLEEP: + raise ValueError("rest completion requires a sleep intent") + + +@dataclass(frozen=True) +class TravelIntent: + """A persisted multi-leg journey waiting for its next edge arrival.""" + + started_at_seconds: int + destination_id: str + remaining_route: tuple[str, ...] + next_arrival_seconds: int + kind: IntentType = IntentType.TRAVEL + + def __post_init__(self) -> None: + if self.kind is not IntentType.TRAVEL: + raise ValueError("travel intent must use the travel kind") + if not self.remaining_route: + raise ValueError("travel route cannot be empty") + if self.remaining_route[-1] != self.destination_id: + raise ValueError("travel destination must be the final route node") + if self.next_arrival_seconds < self.started_at_seconds: + raise ValueError("arrival time cannot precede journey start time") + + +CreatureIntent = TimedIntent | TravelIntent diff --git a/src/dnd_simulator/core/location.py b/src/dnd_simulator/core/location.py index b0828f7a..ebf9a9e2 100644 --- a/src/dnd_simulator/core/location.py +++ b/src/dnd_simulator/core/location.py @@ -7,6 +7,7 @@ from __future__ import annotations +import heapq from dataclasses import dataclass @@ -82,3 +83,30 @@ def travel_seconds(self, from_id: str, to_id: str, speed_kmh: float = 5.0) -> in distance_km = edge.distance_m / 1000.0 hours = distance_km / speed_kmh return max(60, int(hours * 3600)) # minimum 1 minute + + def shortest_route(self, from_id: str, to_id: str) -> tuple[str, ...]: + """Return destination nodes for the shortest route by total edge distance.""" + if not self.has(from_id): + raise ValueError(f"Unknown route origin '{from_id}'") + if not self.has(to_id): + raise ValueError(f"Unknown route destination '{to_id}'") + if from_id == to_id: + return () + + queue: list[tuple[int, tuple[str, ...], str]] = [(0, (), from_id)] + best: dict[str, tuple[int, tuple[str, ...]]] = {from_id: (0, ())} + while queue: + distance, route, location_id = heapq.heappop(queue) + if best.get(location_id) != (distance, route): + continue + if location_id == to_id: + return route + for edge in sorted(self.neighbors(location_id), key=lambda item: item.target_id): + if not self.has(edge.target_id): + continue + candidate = (distance + edge.distance_m, (*route, edge.target_id)) + if edge.target_id not in best or candidate < best[edge.target_id]: + best[edge.target_id] = candidate + heapq.heappush(queue, (*candidate, edge.target_id)) + + raise ValueError(f"No route from '{from_id}' to '{to_id}'") diff --git a/src/dnd_simulator/core/player.py b/src/dnd_simulator/core/player.py index d7986031..2fa3a3dd 100644 --- a/src/dnd_simulator/core/player.py +++ b/src/dnd_simulator/core/player.py @@ -17,3 +17,5 @@ class PlayerCharacter(Character): Save/load is handled by ``content_loader.creatures`` (``player_to_full_save_data`` / ``load_player_save_data``) so ``core`` carries no dependency on ``content_loader``. """ + + is_anchor: bool = True diff --git a/src/dnd_simulator/layers/entities/__init__.py b/src/dnd_simulator/layers/entities/__init__.py index 5a845810..78d047b5 100644 --- a/src/dnd_simulator/layers/entities/__init__.py +++ b/src/dnd_simulator/layers/entities/__init__.py @@ -2,8 +2,9 @@ Includes attack resolution (via CombatManager), initiative/combat management, event perception, and visibility filtering. Manages CombatState per location. -Proximity-based activation: update_activation() marks creatures near players as -active and others as dormant; NPCs are moved to their scheduled location on +Anchor-based activation: update_activation() marks creatures near awake anchors as +active and others as dormant; it completes or interrupts persisted wait/sleep/travel +intents, while NPCs are moved to their scheduled location on activation. Activation also rolls location encounter tables (cooldown-gated and time-of-day filtered) to spawn transient monsters. Npc is a pure data model (role, personality, schedule, memory, ai_type); decision-making is delegated to the brain field on Creature. NpcMemory diff --git a/src/dnd_simulator/layers/entities/activation_manager.py b/src/dnd_simulator/layers/entities/activation_manager.py index ba165638..a09f3b45 100644 --- a/src/dnd_simulator/layers/entities/activation_manager.py +++ b/src/dnd_simulator/layers/entities/activation_manager.py @@ -1,6 +1,6 @@ """Proximity-based activation for the entities layer. -The activation passes (anchor players, activate/dormify creatures) live here. Encounter +The activation passes (anchor creatures, activate/dormify creatures) live here. Encounter rolling and squad/lair materialization are isolated in sibling modules (``encounters``, ``materialization``) — this class owns only the activation loop and delegates the rest. """ @@ -13,12 +13,19 @@ import structlog from dnd_simulator.core.character import Creature, Entity +from dnd_simulator.core.intent import IntentInterruptReason, TimedIntent, TravelIntent from dnd_simulator.core.models import Event from dnd_simulator.core.monster import EncounterEntry from dnd_simulator.layers.entities.encounters import check_encounters +from dnd_simulator.layers.entities.intent_completion import ( + advance_travel_leg, + complete_timed_intent, + interrupt_intent, +) from dnd_simulator.layers.entities.materialization import update_lair_materialization, update_squad_materialization if TYPE_CHECKING: + from dnd_simulator.core.location import LocationGraph from dnd_simulator.core.models import EmitFn, GameDateTime, QueryFn from dnd_simulator.core.monster import MonsterTemplate from dnd_simulator.layers.entities.combat_manager import CombatManager @@ -27,7 +34,7 @@ class ActivationManager: - """Proximity-based activation: anchor players activate nearby creatures, the rest go dormant. + """Proximity-based activation: anchors activate nearby creatures, the rest go dormant. Operates on shared entity and state references owned by EntitiesLayer. Encounter rolling and materialization are delegated to the ``encounters`` / ``materialization`` sibling modules. @@ -63,90 +70,93 @@ def update_activation( time: GameDateTime, query_fn: QueryFn | None = None, emit_fn: EmitFn | None = None, + location_graph: LocationGraph | None = None, ) -> None: - """Activate creatures near players, dormify the rest. + """Activate creatures near awake anchors, dormify the rest. Rules: - - PlayerCharacter without wake_at is always active (anchor). - - PlayerCharacter with wake_at is dormant (not an anchor) until timer expires. + - Any living creature explicitly marked as an anchor holds its location active. + - An anchor with a timed intent is dormant until its timer expires. - Creatures at an anchor's location are active. - Creatures in combat are active (don't interrupt fights). - - Creatures activated by proximity get wake_at cleared (woken early). + - Proximity never cancels a timed intent. - Everyone else is dormant (active=False). When query_fn/emit_fn are provided, also handles squad materialization: squads at active locations are spawned as creatures, squads no longer at active locations are dematerialized with strength updates. - No-op if no players exist (e.g. in tests without PlayerCharacter). """ - from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.layers.entities.models import Npc now = time.to_total_seconds() + hour = time.hour + + # Snapshot active creature IDs before re-evaluation (for encounter checks). + previously_active: set[str] = {e.id for e in self._entities.values() if isinstance(e, Creature) and e.active} - # First pass: expire wake_at timers, collect anchor locations - player_locations: set[str] = set() - has_players = False + # Capture scenes held before arrivals. Travelers reaching one of these + # locations stop there instead of crossing it in one update. + occupied_scene_locations: set[str] = set() for e in self._entities.values(): - if not isinstance(e, PlayerCharacter): + if not isinstance(e, Creature): continue - has_players = True if not e.is_alive: e.active = False - e.wake_at_seconds = None + e.current_intent = None continue - # Check wake_at expiry - if e.wake_at_seconds is not None and now >= e.wake_at_seconds: - e.wake_at_seconds = None - logger.info("activation_wake_timer", entity_id=e.id) - # Player is anchor only if not waiting - if e.wake_at_seconds is None: - e.active = True - player_locations.add(e.location_id) - else: - e.active = False - - if not has_players: - return + if e.is_anchor and e.current_intent is None: + effective_location = e.current_location(hour) if isinstance(e, Npc) else e.location_id + occupied_scene_locations.add(effective_location) - # Snapshot active creature IDs before re-evaluation (for encounter checks) - previously_active: set[str] = {e.id for e in self._entities.values() if isinstance(e, Creature) and e.active} + # First pass: expire timers and advance elapsed travel boundaries. + for e in self._entities.values(): + if not isinstance(e, Creature) or not e.is_alive: + continue + if isinstance(e.current_intent, TimedIntent) and now >= e.current_intent.wake_at_seconds: + complete_timed_intent(e, e.current_intent) + e.current_intent = None + logger.info("activation_wake_timer", entity_id=e.id) + while isinstance(e.current_intent, TravelIntent) and now >= e.current_intent.next_arrival_seconds: + if location_graph is None: + raise RuntimeError("location graph is required to advance travel") + e.current_intent = advance_travel_leg(e, e.current_intent, location_graph) + if e.current_intent is not None and e.location_id in occupied_scene_locations: + interrupt_intent(e, IntentInterruptReason.SCENE) + break + + # Collect locations held after completions and interruptions. + anchor_locations: set[str] = set() + for e in self._entities.values(): + if not isinstance(e, Creature) or not e.is_alive: + continue + if e.is_anchor and e.current_intent is None: + effective_location = e.current_location(hour) if isinstance(e, Npc) else e.location_id + anchor_locations.add(effective_location) - # Second pass: activate/dormify non-player creatures - hour = time.hour + # Second pass: recompute every creature from anchors, intents, and combat. for e in self._entities.values(): - if not isinstance(e, Creature) or isinstance(e, PlayerCharacter): + if not isinstance(e, Creature): continue if not e.is_alive: e.active = False continue - # Expire wake_at for non-players too - if e.wake_at_seconds is not None and now >= e.wake_at_seconds: - e.wake_at_seconds = None - logger.info("activation_wake_timer", entity_id=e.id) - effective_location = e.location_id if isinstance(e, Npc): effective_location = e.current_location(hour) - should_activate = effective_location in player_locations or e.in_combat + should_activate = e.in_combat or (e.current_intent is None and effective_location in anchor_locations) e.active = should_activate # Move NPC to their scheduled location when activated if should_activate and effective_location != e.location_id: e.location_id = effective_location - # Proximity wakeup: clear pending wait timer - if should_activate and e.wake_at_seconds is not None: - logger.info("activation_wake_proximity", entity_id=e.id) - e.wake_at_seconds = None - # Third pass: check for encounter spawns from creatures that were active check_encounters(self, time, previously_active, query_fn) # Fourth pass: squad + lair materialization/dematerialization if query_fn is not None: - update_squad_materialization(self, player_locations, query_fn, emit_fn) - update_lair_materialization(self, now, player_locations, query_fn, emit_fn) + update_squad_materialization(self, anchor_locations, query_fn, emit_fn) + update_lair_materialization(self, now, anchor_locations, query_fn, emit_fn) diff --git a/src/dnd_simulator/layers/entities/combat_manager.py b/src/dnd_simulator/layers/entities/combat_manager.py index 146d817c..6a3dba3c 100644 --- a/src/dnd_simulator/layers/entities/combat_manager.py +++ b/src/dnd_simulator/layers/entities/combat_manager.py @@ -2,14 +2,18 @@ from __future__ import annotations +import random + import structlog from dnd_simulator.core.character import Creature, Entity from dnd_simulator.core.combat import BattleMap, CombatState, Position +from dnd_simulator.core.intent import IntentInterruptReason from dnd_simulator.core.models import ActionResult, Event, EventType, FactionRelation, QueryFn from dnd_simulator.core.turn_budget import TurnBudget from dnd_simulator.layers.entities import combat_resolution from dnd_simulator.layers.entities.combat_serialization import deserialize_combats, serialize_combats +from dnd_simulator.layers.entities.intent_completion import interrupt_intent from dnd_simulator.rules.combat import roll_initiative from dnd_simulator.rules.combat_sides import build_combat_sides from dnd_simulator.rules.reputation import ( @@ -34,6 +38,7 @@ def __init__( entities: dict[str, Entity], location_log: dict[str, list[Event]], battle_map_configs: dict[str, BattleMap] | None = None, + rng: random.Random | None = None, ) -> None: self._entities = entities self._location_log = location_log @@ -41,6 +46,7 @@ def __init__( self._attack_this_round: dict[str, bool] = {} self._sneak_attack_used: set[str] = set() # creature IDs that used SA this round self._battle_map_configs: dict[str, BattleMap] = battle_map_configs or {} + self._rng = rng or random.Random() def get_combat_locations(self) -> list[str]: """Return location IDs with active combats.""" @@ -60,7 +66,7 @@ def start_combat( creatures = self._active_creatures_at_location(location_id) if len(creatures) < 2: return None - ordered = roll_initiative(creatures) + ordered = roll_initiative(creatures, rng=self._rng) if location_id in self._battle_map_configs: template = self._battle_map_configs[location_id] @@ -74,7 +80,7 @@ def start_combat( fixed_ids.add(c.id) remaining = [c.id for c in creatures if c.id not in fixed_ids] if remaining: - battle_map.place_randomly(remaining) + battle_map.place_randomly(remaining, rng=self._rng) combat = CombatState( location_id=location_id, @@ -94,6 +100,7 @@ def get_creature_relation(a: Creature, b: Creature) -> FactionRelation: self._combats[location_id] = combat self._attack_this_round[location_id] = False for c in creatures: + interrupt_intent(c, IntentInterruptReason.COMBAT) c.in_combat = True if c.turn_budget is None: # reaction-only budget for OA before first turn c.turn_budget = TurnBudget( diff --git a/src/dnd_simulator/layers/entities/combat_resolution.py b/src/dnd_simulator/layers/entities/combat_resolution.py index f4b9371e..437e3f7f 100644 --- a/src/dnd_simulator/layers/entities/combat_resolution.py +++ b/src/dnd_simulator/layers/entities/combat_resolution.py @@ -14,9 +14,11 @@ from dnd_simulator.core.character import Character, Creature from dnd_simulator.core.conditions import Condition +from dnd_simulator.core.intent import IntentInterruptReason from dnd_simulator.core.models import ActionResult, Event, EventType, FactionRelation, QueryFn from dnd_simulator.core.queries import query_faction_name, query_faction_relation from dnd_simulator.i18n import _ +from dnd_simulator.layers.entities.intent_completion import interrupt_intent from dnd_simulator.rules.combat import AttackResult from dnd_simulator.rules.combat import resolve_attack as roll_resolve_attack from dnd_simulator.rules.combat_sides import are_allies @@ -118,7 +120,7 @@ def resolve_attack(mgr: CombatManager, event: Event, query_fn: QueryFn | None = attack = get_weapon_attack(attacker) atk_mods = attack_modifiers(attacker, target, melee=attack.reach <= 10) - rolled_dice, dice_total = roll_attack_dice(atk_mods) + rolled_dice, dice_total = roll_attack_dice(atk_mods, rng=mgr._rng) modifier = atk_mods.modifier + dice_total ally_adjacent = False @@ -177,6 +179,7 @@ def resolve_attack(mgr: CombatManager, event: Event, query_fn: QueryFn | None = disadvantage=atk_mods.disadvantage, force_crit=atk_mods.force_crit, gwf_reroll=atk_mods.gwf_reroll, + rng=mgr._rng, ) logger.info( "attack_result", @@ -191,6 +194,8 @@ def resolve_attack(mgr: CombatManager, event: Event, query_fn: QueryFn | None = if result.hit: actual_damage = target.take_damage(result.total_damage) + if actual_damage > 0: + interrupt_intent(target, IntentInterruptReason.DAMAGE) log_data["damage"] = actual_damage log_data["total_damage"] = result.total_damage log_data["damage_components"] = build_damage_components(result, atk_mods.damage_components) diff --git a/src/dnd_simulator/layers/entities/entity_serialization.py b/src/dnd_simulator/layers/entities/entity_serialization.py index e8a2cec9..4a865117 100644 --- a/src/dnd_simulator/layers/entities/entity_serialization.py +++ b/src/dnd_simulator/layers/entities/entity_serialization.py @@ -7,6 +7,7 @@ from dnd_simulator.core.character import Character, Creature, Entity from dnd_simulator.core.class_features import FighterFeatures, PaladinFeatures, RogueFeatures from dnd_simulator.core.container import Container +from dnd_simulator.core.intent import CreatureIntent, IntentType, TravelIntent from dnd_simulator.core.items import Item from dnd_simulator.core.models import EntityKind from dnd_simulator.core.player import PlayerCharacter @@ -24,6 +25,8 @@ NpcSave, PlayerSave, ResourcePoolSave, + TimedIntentSave, + TravelIntentSave, TurnBudgetSave, ) @@ -199,12 +202,32 @@ def _creature_fields(entity: Creature) -> dict[str, object]: "reputation": dict(entity.reputation), "xp_value": entity.xp_value, "squad_id": entity.squad_id, - "wake_at_seconds": entity.wake_at_seconds, + "is_anchor": entity.is_anchor, + "current_intent": _intent_save(entity.current_intent), "combat_position": entity.combat_position, } return data +def _intent_save(intent: CreatureIntent | None) -> TimedIntentSave | TravelIntentSave | None: + if intent is None: + return None + if isinstance(intent, TravelIntent): + return TravelIntentSave( + kind=IntentType.TRAVEL, + started_at_seconds=intent.started_at_seconds, + destination_id=intent.destination_id, + remaining_route=intent.remaining_route, + next_arrival_seconds=intent.next_arrival_seconds, + ) + return TimedIntentSave( + kind=IntentType.WAIT if intent.kind is IntentType.WAIT else IntentType.SLEEP, + started_at_seconds=intent.started_at_seconds, + wake_at_seconds=intent.wake_at_seconds, + rest_type=intent.rest_type, + ) + + def _item_save(item: Item | None) -> ItemSave | None: if item is None: return None diff --git a/src/dnd_simulator/layers/entities/intent_completion.py b/src/dnd_simulator/layers/entities/intent_completion.py new file mode 100644 index 00000000..d7d616b2 --- /dev/null +++ b/src/dnd_simulator/layers/entities/intent_completion.py @@ -0,0 +1,65 @@ +"""Completion effects for timed creature intentions.""" + +from __future__ import annotations + +import structlog + +from dnd_simulator.core.character import Creature +from dnd_simulator.core.intent import IntentInterruptReason, TimedIntent, TravelIntent +from dnd_simulator.core.location import LocationGraph +from dnd_simulator.core.resource import RestType +from dnd_simulator.rules.resources import reset_resources + +logger = structlog.get_logger(domain="intent") + + +def interrupt_intent(creature: Creature, reason: IntentInterruptReason) -> bool: + """Clear an active intent once without applying its completion effects.""" + intent = creature.current_intent + if intent is None: + return False + creature.current_intent = None + logger.info( + "intent_interrupted", + entity_id=creature.id, + intent_kind=intent.kind, + reason=reason, + location_id=creature.location_id, + ) + return True + + +def complete_timed_intent(creature: Creature, intent: TimedIntent) -> None: + """Apply completion effects for an elapsed intent exactly once.""" + if intent.rest_type is None: + return + + reset_ids = reset_resources(creature, intent.rest_type) + healed = creature.heal(creature.max_hp) if intent.rest_type is RestType.LONG_REST else 0 + logger.info( + "rest_complete", + entity_id=creature.id, + rest_type=intent.rest_type, + reset_pools=reset_ids, + healed=healed, + ) + + +def advance_travel_leg( + creature: Creature, + intent: TravelIntent, + location_graph: LocationGraph, +) -> TravelIntent | None: + """Commit one reached route leg and return the remaining journey.""" + arrived_at = intent.remaining_route[0] + creature.location_id = arrived_at + remaining = intent.remaining_route[1:] + logger.info("travel_leg_arrive", entity_id=creature.id, location_id=arrived_at) + if not remaining: + return None + return TravelIntent( + started_at_seconds=intent.started_at_seconds, + destination_id=intent.destination_id, + remaining_route=remaining, + next_arrival_seconds=intent.next_arrival_seconds + location_graph.travel_seconds(arrived_at, remaining[0]), + ) diff --git a/src/dnd_simulator/layers/entities/layer.py b/src/dnd_simulator/layers/entities/layer.py index d5ec41cd..91a6f83b 100644 --- a/src/dnd_simulator/layers/entities/layer.py +++ b/src/dnd_simulator/layers/entities/layer.py @@ -27,6 +27,7 @@ from dnd_simulator.core.monster import EncounterEntry, MonsterTemplate from dnd_simulator.core.npc_memory import NpcMemory from dnd_simulator.core.player import PlayerCharacter +from dnd_simulator.core.resource import RestType from dnd_simulator.core.turn_budget import TurnBudget from dnd_simulator.layers.common.rng_state import dump_rng_state, load_rng_state from dnd_simulator.layers.entities.activation_manager import ActivationManager @@ -38,6 +39,7 @@ from dnd_simulator.layers.entities.save_models import EntitiesState if TYPE_CHECKING: + from dnd_simulator.core.location import LocationGraph from dnd_simulator.core.models import EmitFn, GameDateTime, QueryFn, TimeDelta from dnd_simulator.llm.summarizer import MemorySummarizer @@ -82,6 +84,7 @@ def __init__( monster_templates: dict[str, MonsterTemplate] | None = None, encounter_tables: dict[str, list[EncounterEntry]] | None = None, seed: int | None = None, + dice_rng: random.Random | None = None, ) -> None: self._entities: dict[str, Entity] = {} self._location_log: dict[str, list[Event]] = defaultdict(list) @@ -99,7 +102,7 @@ def __init__( if entities: for e in entities: self._entities[e.id] = e - self._combat = CombatManager(self._entities, self._location_log, battle_map_configs) + self._combat = CombatManager(self._entities, self._location_log, battle_map_configs, rng=dice_rng) self._awareness = AwarenessBuilder(self._entities, self._location_log, self._combat) self._activation = ActivationManager( self._entities, @@ -151,12 +154,17 @@ def get_merchants_at(self, location_id: str, hour: int) -> list[Npc]: return active_merchants_at(self._entities, location_id, hour) def get_nearest_wake_time(self) -> int | None: - """Return the minimum wake_at_seconds across all creatures, or None.""" - wake_times = [ - e.wake_at_seconds - for e in self._entities.values() - if isinstance(e, Creature) and e.wake_at_seconds is not None - ] + """Return the minimum intent wake time across all creatures, or None.""" + from dnd_simulator.core.intent import TimedIntent, TravelIntent + + wake_times: list[int] = [] + for entity in self._entities.values(): + if not isinstance(entity, Creature): + continue + if isinstance(entity.current_intent, TimedIntent): + wake_times.append(entity.current_intent.wake_at_seconds) + elif isinstance(entity.current_intent, TravelIntent): + wake_times.append(entity.current_intent.next_arrival_seconds) return min(wake_times) if wake_times else None def update_activation( @@ -164,9 +172,10 @@ def update_activation( time: GameDateTime, query_fn: QueryFn | None = None, emit_fn: EmitFn | None = None, + location_graph: LocationGraph | None = None, ) -> None: - """Activate creatures near players, dormify the rest.""" - self._activation.update_activation(time, query_fn, emit_fn) + """Activate creatures near awake anchors, dormify the rest.""" + self._activation.update_activation(time, query_fn, emit_fn, location_graph) # -- Combat (delegated to CombatManager) -- @@ -506,8 +515,31 @@ def load_state(self, state: dict[str, object]) -> None: ) elif budget_raw is None: entity.turn_budget = None - wake_at = edata.get("wake_at_seconds") - entity.wake_at_seconds = int(wake_at) if wake_at is not None else None + from dnd_simulator.core.intent import IntentType, TimedIntent, TravelIntent + + entity.is_anchor = bool(edata.get("is_anchor", entity.is_anchor)) + intent_raw = edata.get("current_intent") + if isinstance(intent_raw, dict): + kind = IntentType(str(intent_raw["kind"])) + if kind is IntentType.TRAVEL: + route_raw = intent_raw["remaining_route"] + assert isinstance(route_raw, list | tuple) + entity.current_intent = TravelIntent( + started_at_seconds=int(intent_raw["started_at_seconds"]), + destination_id=str(intent_raw["destination_id"]), + remaining_route=tuple(str(node) for node in route_raw), + next_arrival_seconds=int(intent_raw["next_arrival_seconds"]), + ) + else: + rest_type_raw = intent_raw.get("rest_type") + entity.current_intent = TimedIntent( + kind=kind, + started_at_seconds=int(intent_raw["started_at_seconds"]), + wake_at_seconds=int(intent_raw["wake_at_seconds"]), + rest_type=RestType(str(rest_type_raw)) if rest_type_raw is not None else None, + ) + else: + entity.current_intent = None position_raw = edata.get("combat_position") if isinstance(position_raw, list | tuple) and len(position_raw) == 2: entity.combat_position = (int(position_raw[0]), int(position_raw[1])) @@ -534,7 +566,7 @@ def load_state(self, state: dict[str, object]) -> None: setattr(entity, field_name, deserialize_item(eq_data)) pools_raw = edata.get("resource_pools") if isinstance(pools_raw, list): - from dnd_simulator.core.resource import ResourcePool, RestType + from dnd_simulator.core.resource import ResourcePool saved_pools = {str(d["id"]): d for d in pools_raw} existing_ids = {pool.id for pool in entity.resource_pools} diff --git a/src/dnd_simulator/layers/entities/save_models.py b/src/dnd_simulator/layers/entities/save_models.py index 219de532..6f08279d 100644 --- a/src/dnd_simulator/layers/entities/save_models.py +++ b/src/dnd_simulator/layers/entities/save_models.py @@ -4,12 +4,13 @@ from typing import Annotated, Any, Literal -from pydantic import BaseModel, ConfigDict, Field, TypeAdapter +from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, model_validator from dnd_simulator.core.action import ActionType from dnd_simulator.core.brain import BrainType from dnd_simulator.core.character import Ability, Alignment, CharClass, DamageType, NpcRole, Race from dnd_simulator.core.conditions import Condition +from dnd_simulator.core.intent import IntentType from dnd_simulator.core.items import ArmorCategory, EquipmentSlot, ItemType, WeaponCategory from dnd_simulator.core.models import EntityKind from dnd_simulator.core.modifiers import ModifierOp, StatType @@ -107,6 +108,32 @@ class TurnBudgetSave(SaveModel): reaction: int +class TimedIntentSave(SaveModel): + kind: Literal[IntentType.WAIT, IntentType.SLEEP] + started_at_seconds: int + wake_at_seconds: int + rest_type: RestType | None = None + + +class TravelIntentSave(SaveModel): + kind: Literal[IntentType.TRAVEL] + started_at_seconds: int + destination_id: str + remaining_route: tuple[str, ...] = Field(min_length=1) + next_arrival_seconds: int + + @model_validator(mode="after") + def validate_route(self) -> TravelIntentSave: + if self.remaining_route[-1] != self.destination_id: + raise ValueError("travel destination must be the final route node") + if self.next_arrival_seconds < self.started_at_seconds: + raise ValueError("arrival time cannot precede journey start time") + return self + + +IntentSave = Annotated[TimedIntentSave | TravelIntentSave, Field(discriminator="kind")] + + class EntitySaveBase(SaveModel): id: str name: str @@ -140,7 +167,8 @@ class CreatureFields(EntitySaveBase): reputation: dict[str, int] = Field(default_factory=dict) xp_value: int = 0 squad_id: str | None = None - wake_at_seconds: int | None = None + is_anchor: bool = False + current_intent: IntentSave | None = None combat_position: tuple[int, int] | None = None diff --git a/src/dnd_simulator/round.py b/src/dnd_simulator/round.py index 017bca99..053ea6cd 100644 --- a/src/dnd_simulator/round.py +++ b/src/dnd_simulator/round.py @@ -7,7 +7,9 @@ from __future__ import annotations +import random from collections.abc import Callable +from contextlib import AbstractContextManager, nullcontext from dataclasses import dataclass, field, replace from typing import TYPE_CHECKING @@ -32,7 +34,6 @@ get_num_bonus_actions, ) from dnd_simulator.rules.conditions import is_incapacitated, tick_conditions -from dnd_simulator.rules.dice import get_global_rng from dnd_simulator.rules.modifiers import effective_speed from dnd_simulator.rules.movement import resolve_abstract_move from dnd_simulator.rules.validation import ActionContext @@ -67,6 +68,8 @@ def __init__( world: World, creature_host: CreatureHost | None = None, dispatcher: ActionDispatcher | None = None, + rng: random.Random | None = None, + mutation_scope: Callable[[], AbstractContextManager[None]] | None = None, ) -> None: self._world = world self._host = creature_host or world.creature_host @@ -75,6 +78,8 @@ def __init__( dispatcher = create_dispatcher(world) self._dispatcher = dispatcher + self._rng = rng or random.Random() + self._mutation_scope = mutation_scope or nullcontext self._stop_flag = False self._on_round_end: Callable[[RoundResult], None] | None = None self._on_action: OnActionCallback | None = None @@ -96,6 +101,11 @@ def set_on_action(self, callback: OnActionCallback) -> None: """Set callback invoked after each action within a turn.""" self._on_action = callback + def clear_callbacks(self) -> None: + """Detach transport callbacks before discarding a live round.""" + self._on_action = None + self._on_round_end = None + def _execute_action( self, creature: Creature, @@ -104,7 +114,8 @@ def _execute_action( emit_fn: EmitFn, ) -> ActionResult: """Execute action via dispatcher. Validates, checks budget, executes, consumes budget.""" - return self._dispatcher.dispatch(creature, action, ctx, emit_fn) + with self._mutation_scope(): + return self._dispatcher.dispatch(creature, action, ctx, emit_fn) def get_perceived_events(self, creature: Creature) -> list[PerceivedEvent]: """Return perceived events for a creature (delegates to CreatureHost).""" @@ -137,23 +148,24 @@ def _prepare_combat_turn( Returns an ActionContext if the creature can act, or None if the turn is skipped. """ - self._host.reset_combat_turn_state(creature.id) - - expired = tick_conditions(creature.conditions) - if expired: - logger.info("conditions_expired", conditions=[c.value for c in expired]) - - if is_incapacitated(creature.conditions): - logger.info("turn_skipped_incapacitated") - reasons = sorted(c.value for c in creature.conditions if is_incapacitated({c: None})) - emit_fn( - Event( - event_type=EventType.TURN_SKIPPED, - source_layer="entities", - data={"entity_id": creature.id, "reason": "incapacitated", "conditions": reasons}, + with self._mutation_scope(): + self._host.reset_combat_turn_state(creature.id) + + expired = tick_conditions(creature.conditions) + if expired: + logger.info("conditions_expired", conditions=[c.value for c in expired]) + + if is_incapacitated(creature.conditions): + logger.info("turn_skipped_incapacitated") + reasons = sorted(c.value for c in creature.conditions if is_incapacitated({c: None})) + emit_fn( + Event( + event_type=EventType.TURN_SKIPPED, + source_layer="entities", + data={"entity_id": creature.id, "reason": "incapacitated", "conditions": reasons}, + ) ) - ) - return None + return None weapon_info = "fists" if creature.equipped_weapon and creature.equipped_weapon.weapon_def: @@ -163,21 +175,22 @@ def _prepare_combat_turn( conds_info = {c.value: r for c, r in creature.conditions.items()} if creature.conditions else {} logger.debug("combat_turn_start", weapon=weapon_info, conditions=conds_info) - speed = effective_speed(creature) - if speed != creature.speed: - logger.debug( - "speed_reduced", - base_speed=creature.speed, - effective_speed=speed, - conditions=[c.value for c in creature.conditions], + with self._mutation_scope(): + speed = effective_speed(creature) + if speed != creature.speed: + logger.debug( + "speed_reduced", + base_speed=creature.speed, + effective_speed=speed, + conditions=[c.value for c in creature.conditions], + ) + creature.turn_budget = TurnBudget( + actions=get_num_actions(creature), + bonus_actions=get_num_bonus_actions(creature), + movement_remaining=speed, + reaction=1, ) - creature.turn_budget = TurnBudget( - actions=get_num_actions(creature), - bonus_actions=get_num_bonus_actions(creature), - movement_remaining=speed, - reaction=1, - ) - creature.is_disengaging = False + creature.is_disengaging = False combat_state = self._host.get_combat(creature.location_id) return ActionContext( @@ -186,7 +199,7 @@ def _prepare_combat_turn( turn_budget=creature.turn_budget, combat_state=combat_state, get_entity=self._host.get_entity, - rng=get_global_rng(), + rng=self._rng, ) def _build_combat_awareness( @@ -232,7 +245,8 @@ def run_combat_turn( if creature.brain is None: return [] - ctx = self._prepare_combat_turn(creature, emit_fn) + with self._mutation_scope(): + ctx = self._prepare_combat_turn(creature, emit_fn) if ctx is None: return [] @@ -306,7 +320,7 @@ def run_peaceful_turn( is_combat=False, current_turn_entity_id=creature.id, get_entity=self._host.get_entity, - rng=get_global_rng(), + rng=self._rng, ) while True: @@ -387,7 +401,7 @@ def check_reactions( turn_budget=creature.turn_budget, combat_state=combat_state, get_entity=self._host.get_entity, - rng=get_global_rng(), + rng=self._rng, ) result = self._execute_action(creature, action, ctx, _emit) if result.success: @@ -451,7 +465,9 @@ def run_round(self, *, skip_activation: bool = False) -> RoundResult: # Activate creatures near players, dormify the rest, materialize squads if not skip_activation: - self._host.update_activation(time, query_fn=query_fn, emit_fn=emit_fn) + self._host.update_activation( + time, query_fn=query_fn, emit_fn=emit_fn, location_graph=self._world.location_graph + ) active_count = len(self._host.get_active_creatures()) combat_locations = list(self._host.get_combat_locations()) @@ -468,11 +484,13 @@ def run_round(self, *, skip_activation: bool = False) -> RoundResult: for entity_id in list(combat.turn_order): entity = self._host.get_entity(entity_id) if isinstance(entity, Creature) and entity.is_alive and entity.active and entity.in_combat: - entity.is_dodging = False # dodge lasts until start of next turn - entity.is_disengaging = False + with self._mutation_scope(): + entity.is_dodging = False # dodge lasts until start of next turn + entity.is_disengaging = False self.run_creature_turn(entity, time, query_fn, emit_fn) # End of round — check for combat exit - self._host.end_combat_round(location_id) + with self._mutation_scope(): + self._host.end_combat_round(location_id) # Peaceful turns: creatures not in combat for creature in self._host.get_active_creatures(): @@ -481,7 +499,8 @@ def run_round(self, *, skip_activation: bool = False) -> RoundResult: self.run_creature_turn(creature, time, query_fn, emit_fn) # Advance time by one round (6 seconds) - tick_events = self._world.advance_time(TimeDelta.from_rounds(1)) + with self._mutation_scope(): + tick_events = self._world.advance_time(TimeDelta.from_rounds(1)) logger.info("round_end", game_time=str(self._world.time), tick_events=len(tick_events)) return RoundResult(events=tick_events) @@ -490,7 +509,10 @@ def _activate(self) -> None: """Update activation with materialization support.""" qfn = self._world.make_query_fn("entities") efn = self._world.make_emit_fn("entities") - self._host.update_activation(self._world.time, query_fn=qfn, emit_fn=efn) + with self._mutation_scope(): + self._host.update_activation( + self._world.time, query_fn=qfn, emit_fn=efn, location_graph=self._world.location_graph + ) def run_loop(self, max_rounds: int | None = None) -> None: """Run rounds until no active creatures remain or stop() is called.""" @@ -521,26 +543,27 @@ def run_loop(self, max_rounds: int | None = None) -> None: break def _fast_forward(self) -> bool: - """Advance time to the nearest wake_at when no creatures are active. + """Advance time to the nearest intent wake point when no creatures are active. Returns True if time was advanced (loop should continue), False if there's nobody to wake up (loop should exit). """ - nearest_wake = self._host.get_nearest_wake_time() + with self._mutation_scope(): + nearest_wake = self._host.get_nearest_wake_time() - if nearest_wake is None: - return False + if nearest_wake is None: + return False - now = self._world.time.to_total_seconds() - delta_seconds = nearest_wake - now - if delta_seconds <= 0: - # Timer already expired — just run update_activation - self._activate() - return True + now = self._world.time.to_total_seconds() + delta_seconds = nearest_wake - now + if delta_seconds <= 0: + # Timer already expired — just run update_activation + self._activate() + return True - logger.info("fast_forward", delta_seconds=delta_seconds) - tick_events = self._world.advance_time(TimeDelta(seconds=delta_seconds)) - self._activate() + logger.info("fast_forward", delta_seconds=delta_seconds) + tick_events = self._world.advance_time(TimeDelta(seconds=delta_seconds)) + self._activate() if self._on_round_end: self._on_round_end(RoundResult(events=tick_events)) diff --git a/src/dnd_simulator/rules/handlers/__init__.py b/src/dnd_simulator/rules/handlers/__init__.py index 1273832c..4e6433e0 100644 --- a/src/dnd_simulator/rules/handlers/__init__.py +++ b/src/dnd_simulator/rules/handlers/__init__.py @@ -23,6 +23,7 @@ handle_disengage, handle_move, handle_move_to, + handle_travel, handle_wait, ) from dnd_simulator.rules.handlers.reactions import handle_opportunity_attack @@ -53,6 +54,7 @@ "handle_sell", "handle_short_rest", "handle_take", + "handle_travel", "handle_unequip", "handle_use_item", "handle_wait", diff --git a/src/dnd_simulator/rules/handlers/attack_resolution.py b/src/dnd_simulator/rules/handlers/attack_resolution.py index d81dea2c..2cfd82f3 100644 --- a/src/dnd_simulator/rules/handlers/attack_resolution.py +++ b/src/dnd_simulator/rules/handlers/attack_resolution.py @@ -6,6 +6,8 @@ from __future__ import annotations +import random + import structlog from dnd_simulator.core.character import Attack, Creature @@ -93,7 +95,7 @@ def build_damage_components( return components -def roll_attack_dice(atk_mods: AttackModifiers) -> tuple[list[RollComponent], int]: +def roll_attack_dice(atk_mods: AttackModifiers, *, rng: random.Random | None = None) -> tuple[list[RollComponent], int]: """Roll dice bonuses (Bless +1d4, etc.). Returns (rolled_components, total).""" rolled_dice: list[RollComponent] = [] dice_total = 0 @@ -102,7 +104,7 @@ def roll_attack_dice(atk_mods: AttackModifiers) -> tuple[list[RollComponent], in for rc in atk_mods.roll_components: if rc.dice: - rolled_value = roll_dice_fn(rc.dice).total + rolled_value = roll_dice_fn(rc.dice, rng=rng).total rolled_dice.append(RollComponent(source=rc.source, value=rolled_value, dice=rc.dice)) dice_total += rolled_value return rolled_dice, dice_total diff --git a/src/dnd_simulator/rules/handlers/movement.py b/src/dnd_simulator/rules/handlers/movement.py index aaf2059d..26b8e013 100644 --- a/src/dnd_simulator/rules/handlers/movement.py +++ b/src/dnd_simulator/rules/handlers/movement.py @@ -220,42 +220,42 @@ def handle_disengage( def handle_wait(actor: Creature, action: Action, emit_fn: EmitFn, ctx: ActionContext, world: World) -> ActionResult: - """Wait: creature goes dormant until wake_at, or travels to a location. + """Wait in place until the requested wake boundary.""" + from dnd_simulator.core.intent import IntentType, TimedIntent + + hours = int(str(action.params.get("hours", 1))) + if hours > 0: + now = world.time.to_total_seconds() + actor.current_intent = TimedIntent(IntentType.WAIT, now, now + hours * 3600) + actor.active = False + logger.info("wait_sleep", hours=hours, wake_at=actor.current_intent.wake_at_seconds) + return ActionResult() - Travel: immediate move + time advance. - Plain wait: set wake_at_seconds, mark dormant. Fast-forward in run_loop - handles the actual time advancement. - """ - from dnd_simulator.core.models import TimeDelta - - travel_to = action.params.get("travel_to") - if travel_to: - target_id = str(travel_to) - graph = world.location_graph - resolved_id: str | None = None - try: - graph.travel_seconds(actor.location_id, target_id) - resolved_id = target_id - except ValueError: - # No direct path — try by name match - for loc_id in graph.all_ids(): - loc = graph.get(loc_id) - if loc.name.lower() == target_id.lower(): - resolved_id = loc_id - break - if resolved_id is None: - return ActionResult(success=False, error=_("Unknown travel destination")) - try: - seconds = graph.travel_seconds(actor.location_id, resolved_id) - except ValueError: - return ActionResult(success=False, error=_("No route to destination")) - actor.location_id = resolved_id - world.advance_time(TimeDelta(seconds=seconds)) - else: - hours = int(str(action.params.get("hours", 1))) - if hours > 0: - now = world.time.to_total_seconds() - actor.wake_at_seconds = now + hours * 3600 - actor.active = False - logger.info("wait_sleep", hours=hours, wake_at=actor.wake_at_seconds) + +def handle_travel(actor: Creature, action: Action, emit_fn: EmitFn, ctx: ActionContext, world: World) -> ActionResult: + """Start a persisted journey without moving or advancing world time inline.""" + from dnd_simulator.core.intent import TravelIntent + + destination_raw = action.params.get("destination_id") + if destination_raw is None: + return ActionResult(success=False, error=_("Travel requires a destination")) + destination_id = str(destination_raw) + try: + route = world.location_graph.shortest_route(actor.location_id, destination_id) + except ValueError: + return ActionResult(success=False, error=_("No route to destination")) + if not route: + return ActionResult(success=False, error=_("Already at destination")) + + now = world.time.to_total_seconds() + next_arrival = now + world.location_graph.travel_seconds(actor.location_id, route[0]) + actor.current_intent = TravelIntent(now, destination_id, route, next_arrival) + actor.active = False + logger.info( + "travel_start", + entity_id=actor.id, + destination_id=destination_id, + route=route, + next_arrival=next_arrival, + ) return ActionResult() diff --git a/src/dnd_simulator/rules/handlers/rest.py b/src/dnd_simulator/rules/handlers/rest.py index 733200f1..7d936427 100644 --- a/src/dnd_simulator/rules/handlers/rest.py +++ b/src/dnd_simulator/rules/handlers/rest.py @@ -7,9 +7,9 @@ import structlog from dnd_simulator.core.action import Action +from dnd_simulator.core.intent import IntentType, TimedIntent from dnd_simulator.core.models import ActionResult from dnd_simulator.core.resource import RestType -from dnd_simulator.rules.resources import reset_resources if TYPE_CHECKING: from dnd_simulator.core.character import Creature @@ -26,27 +26,22 @@ def handle_long_rest( actor: Creature, action: Action, emit_fn: EmitFn, ctx: ActionContext, world: World ) -> ActionResult: - """Long rest: reset all resource pools, heal to full, advance 8 hours.""" - reset_ids = reset_resources(actor, RestType.LONG_REST) - healed = actor.heal(actor.max_hp) - + """Long rest: sleep for eight hours, then recover on completion.""" now = world.time.to_total_seconds() - actor.wake_at_seconds = now + _LONG_REST_SECONDS + actor.current_intent = TimedIntent(IntentType.SLEEP, now, now + _LONG_REST_SECONDS, rest_type=RestType.LONG_REST) actor.active = False - logger.info("long_rest", healed=healed, reset_pools=reset_ids, wake_at=actor.wake_at_seconds) + logger.info("long_rest", wake_at=actor.current_intent.wake_at_seconds) return ActionResult() def handle_short_rest( actor: Creature, action: Action, emit_fn: EmitFn, ctx: ActionContext, world: World ) -> ActionResult: - """Short rest: reset short-rest pools only, advance 1 hour. No healing.""" - reset_ids = reset_resources(actor, RestType.SHORT_REST) - + """Short rest: sleep for one hour, then recover on completion.""" now = world.time.to_total_seconds() - actor.wake_at_seconds = now + _SHORT_REST_SECONDS + actor.current_intent = TimedIntent(IntentType.SLEEP, now, now + _SHORT_REST_SECONDS, rest_type=RestType.SHORT_REST) actor.active = False - logger.info("short_rest", reset_pools=reset_ids, wake_at=actor.wake_at_seconds) + logger.info("short_rest", wake_at=actor.current_intent.wake_at_seconds) return ActionResult() diff --git a/src/dnd_simulator/service/__init__.py b/src/dnd_simulator/service/__init__.py index ea8c5503..1b85837d 100644 --- a/src/dnd_simulator/service/__init__.py +++ b/src/dnd_simulator/service/__init__.py @@ -3,7 +3,8 @@ - GameService: world loading, session creation/deletion; thin facade composed of command mixins - WorldBuilderCommands / PlayerCommands: mixins peeled off GameService (world+content+catalog CRUD; create_player/level_up_player/player_status). GameServiceProtocol (base) declares the shared interface -- GameSession: player connection, round thread, listener dispatch, action submission +- GameSession: player connection, bounded round-thread lifecycle, world snapshot gate, + listener dispatch, action submission - ActionDispatcher: validate → handler → budget consume pipeline - action_parsing: parse JSON payloads into Action (ActionParseError); keeps adapters off core Action types - BrainFactory: creates Brain instances from ai_type string diff --git a/src/dnd_simulator/service/action_dispatcher.py b/src/dnd_simulator/service/action_dispatcher.py index d66264e8..ed74e18e 100644 --- a/src/dnd_simulator/service/action_dispatcher.py +++ b/src/dnd_simulator/service/action_dispatcher.py @@ -48,6 +48,7 @@ handle_sell, handle_short_rest, handle_take, + handle_travel, handle_use_item, handle_wait, ) @@ -164,6 +165,7 @@ def create_dispatcher(world: World) -> ActionDispatcher: dispatcher.register(ActionType.DASH, handle_dash) dispatcher.register(ActionType.DISENGAGE, handle_disengage) dispatcher.register(ActionType.WAIT, handle_wait) + dispatcher.register(ActionType.TRAVEL, handle_travel) dispatcher.register(ActionType.USE_ITEM, handle_use_item) dispatcher.register(ActionType.BLESS, handle_bless) for _equip_action, _equip_handler in EQUIPMENT_HANDLERS.items(): diff --git a/src/dnd_simulator/service/base.py b/src/dnd_simulator/service/base.py index 02cca1b8..68eaba0e 100644 --- a/src/dnd_simulator/service/base.py +++ b/src/dnd_simulator/service/base.py @@ -2,6 +2,7 @@ from __future__ import annotations +import threading from pathlib import Path from typing import TYPE_CHECKING, Protocol @@ -19,6 +20,7 @@ class GameServiceProtocol(Protocol): _store: SaveStore _sessions: dict[str, GameSession] + _sessions_lock: threading.RLock _brain_factory: BrainFactory _content_dir: Path diff --git a/src/dnd_simulator/service/commands_player.py b/src/dnd_simulator/service/commands_player.py index 359ab065..4b1d8b84 100644 --- a/src/dnd_simulator/service/commands_player.py +++ b/src/dnd_simulator/service/commands_player.py @@ -169,4 +169,4 @@ def player_status(self, session_id: str, player_id: str | None = None) -> Player player = session.get_player(player_id) if player_id else session.get_player() if player is None: raise PlayerNotFoundError("No player in this session") - return build_player_status(player) + return build_player_status(player, session.world.location_graph) diff --git a/src/dnd_simulator/service/commands_save.py b/src/dnd_simulator/service/commands_save.py index 09c33ae3..63d3ae9a 100644 --- a/src/dnd_simulator/service/commands_save.py +++ b/src/dnd_simulator/service/commands_save.py @@ -3,11 +3,10 @@ import structlog from pydantic import ValidationError -from dnd_simulator.layers.common.rng_state import dump_rng_state, load_rng_state -from dnd_simulator.rules.dice import get_global_rng +from dnd_simulator.layers.common.rng_state import load_rng_state from dnd_simulator.service.base import GameServiceProtocol from dnd_simulator.service.session import GameSession -from dnd_simulator.storage.save_schema import SCHEMA_VERSION, SaveGame, SaveMeta +from dnd_simulator.storage.save_schema import SaveGame logger = structlog.get_logger(domain="save") @@ -17,20 +16,7 @@ class SaveCommands(GameServiceProtocol): def _build_save_game(self, session_id: str) -> SaveGame: session: GameSession = self._get_session(session_id) - world_data = session.world.save() - world_data["dice_rng_state"] = dump_rng_state(get_global_rng()) - return SaveGame.model_validate( - { - "schema_version": SCHEMA_VERSION, - "meta": SaveMeta( - session_id=session_id, - world_name=session.world_name, - lang=session.lang, - default_player_faction=session.default_player_faction, - ).model_dump(mode="json"), - "world": world_data, - } - ) + return session.build_save_game() @staticmethod def _validate_save(data: object) -> SaveGame: @@ -50,15 +36,25 @@ def save_game(self, session_id: str, name: str | None = None) -> str: def autosave_session(self, session_id: str) -> None: """Autosave a session with metadata needed for restore.""" session: GameSession = self._get_session(session_id) - data = self._build_save_game(session_id).model_dump(mode="json", by_alias=True) - self._store.save(f"session_{session_id}", data, world=session.world_name) + self._autosave_active_session(session) + + def _autosave_active_session(self, session: GameSession) -> bool: + """Snapshot and persist a session if the registry still owns this exact object.""" + snapshot = session.build_save_game() + data = snapshot.model_dump(mode="json", by_alias=True) + with self._sessions_lock: + if self._sessions.get(session.session_id) is not session: + return False + self._store.save(f"session_{session.session_id}", data, world=session.world_name) + return True def autosave_all_sessions(self) -> None: """Autosave all active sessions. One failing session does not block the others.""" - sessions: dict[str, GameSession] = self._sessions - for sid in list(sessions): + with self._sessions_lock: + sessions = list(self._sessions.items()) + for sid, session in sessions: try: - self.autosave_session(sid) + self._autosave_active_session(session) except Exception: logger.exception("autosave_failed", session_id=sid) @@ -68,11 +64,14 @@ def load_game(self, session_id: str, name: str) -> None: data = self._store.load(name, world=session.world_name) save = self._validate_save(data) - load_rng_state(get_global_rng(), save.world.dice_rng_state) - session.world.load(save.world.to_world_dict()) + def restore() -> None: + load_rng_state(session.dice_rng, save.world.dice_rng_state) + session.world.load(save.world.to_world_dict()) + + # Reassign brains based on restored ai_type (may differ from pre-load state) + self._assign_brains(self._get_entities_layer(session)) - # Reassign brains based on restored ai_type (may differ from pre-load state) - self._assign_brains(self._get_entities_layer(session)) + session.replace_world_state(restore) def delete_save(self, session_id: str, name: str) -> None: """Delete a save file.""" diff --git a/src/dnd_simulator/service/dto.py b/src/dnd_simulator/service/dto.py index 761b9ebd..3fdc9fd6 100644 --- a/src/dnd_simulator/service/dto.py +++ b/src/dnd_simulator/service/dto.py @@ -18,6 +18,18 @@ class ResourcePoolView: current_uses: int +@dataclass(frozen=True) +class JourneyView: + """Resolved presentation of a persisted travel intent.""" + + destination_id: str + destination_name: str + current_location_name: str + next_location_name: str + remaining_route: tuple[str, ...] + next_arrival_seconds: int + + @dataclass(frozen=True) class PlayerStatusData: """Full player status snapshot — derived stats already computed.""" @@ -38,6 +50,7 @@ class PlayerStatusData: location_id: str appearance: str ability_scores: dict[str, int] + journey: JourneyView | None = None resource_pools: list[ResourcePoolView] = field(default_factory=list) equipped: list[dict[str, str]] = field(default_factory=list) inventory: list[dict[str, object]] = field(default_factory=list) diff --git a/src/dnd_simulator/service/game_service.py b/src/dnd_simulator/service/game_service.py index eb886eb7..e84eb902 100644 --- a/src/dnd_simulator/service/game_service.py +++ b/src/dnd_simulator/service/game_service.py @@ -1,7 +1,9 @@ from __future__ import annotations +import contextlib import os import random +import threading import uuid from pathlib import Path @@ -70,6 +72,11 @@ def _derive_layer_seeds(world_seed: int) -> dict[str, int]: return {layer_name: rng.getrandbits(64) for layer_name in _LAYER_SEED_ORDER} +def _create_dice_rng() -> random.Random: + raw = os.getenv("DND_DICE_SEED") + return random.Random(int(raw)) if raw is not None else random.Random() + + def _flatten_region_defaults[T]( locations: list[Location], by_region: dict[str, T], @@ -109,6 +116,7 @@ def __init__( llm: LlmClient | None = None, ) -> None: self._sessions: dict[str, GameSession] = {} + self._sessions_lock = threading.RLock() self._store = store self._content_dir = content_dir self._llm = llm @@ -131,6 +139,7 @@ def start_game(self, world_name: str = "sword_vale", lang: str = "en") -> GameSe meta = load_world_meta_from_manifest(world_path, lang=lang) world_seed = _resolve_world_seed() layer_seeds = _derive_layer_seeds(world_seed) + dice_rng = _create_dice_rng() regions = load_world(layer_paths["geography"], lang=lang) nations = load_nations(layer_paths["politics"], lang=lang) settlements = load_settlements(layer_paths["settlements"], lang=lang) @@ -209,6 +218,7 @@ def start_game(self, world_name: str = "sword_vale", lang: str = "en") -> GameSe encounter_tables=effective_encounters, battle_map_configs=battle_map_configs, seed=layer_seeds["entities"], + dice_rng=dice_rng, ) # Assign brains via factory (content_loader only parses data, not brains) @@ -230,9 +240,11 @@ def start_game(self, world_name: str = "sword_vale", lang: str = "en") -> GameSe lang=lang, world_name=world_name, default_player_faction=meta.get("default_player_faction", ""), + dice_rng=dice_rng, ) session._on_empty = self._on_session_empty - self._sessions[session_id] = session + with self._sessions_lock: + self._sessions[session_id] = session return session def list_sessions(self) -> list[dict[str, str]]: @@ -240,7 +252,9 @@ def list_sessions(self) -> list[dict[str, str]]: result: dict[str, dict[str, str]] = {} # In-memory sessions - for sid, s in self._sessions.items(): + with self._sessions_lock: + active_sessions = list(self._sessions.items()) + for sid, s in active_sessions: players = s.get_players() player_name = players[0].name if players else "" result[sid] = {"session_id": sid, "player_name": player_name, "world_name": s.world_name} @@ -264,23 +278,26 @@ def get_session(self, session_id: str) -> GameSession: def delete_session(self, session_id: str) -> None: """Stop and remove a session.""" - self._get_session(session_id) - del self._sessions[session_id] + session = self._get_session(session_id) + with self._sessions_lock: + if self._sessions.get(session_id) is session: + del self._sessions[session_id] + with contextlib.suppress(KeyError): + self._store.delete(f"session_{session_id}", world=session.world_name) def _on_session_empty(self, session: GameSession) -> None: """Called when all listeners disconnect. Autosave and evict from memory.""" sid = session.session_id - if sid not in self._sessions: - # Explicit DELETE already evicted it; autosaving here would fail or - # resurrect the session from its stale autosave via _get_session. - logger.info("session_empty_evict_skipped", session_id=sid) - return - logger.info("session_empty_evict", session_id=sid) - try: - self.autosave_session(sid) - except Exception: - logger.exception("session_empty_autosave_failed", session_id=sid) - self._sessions.pop(sid, None) + with self._sessions_lock: + if self._sessions.get(sid) is not session: + logger.info("session_empty_evict_skipped", session_id=sid) + return + logger.info("session_empty_evict", session_id=sid) + try: + self._autosave_active_session(session) + except Exception: + logger.exception("session_empty_autosave_failed", session_id=sid) + self._sessions.pop(sid, None) # -- Layer accessors -- @@ -300,24 +317,31 @@ def _assign_brains(self, entities_layer: EntitiesLayer) -> None: match the (possibly restored) ai_type field. """ from dnd_simulator.core.character import Creature + from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.layers.entities.models import Npc for entity in entities_layer._entities.values(): if isinstance(entity, Npc): entity.brain = self._brain_factory.create(entity.ai_type) + elif isinstance(entity, PlayerCharacter): + entity.brain = None elif isinstance(entity, Creature) and entity.brain is None: entity.brain = self._brain_factory.create(BrainType.RULE_BASED) def _get_session(self, session_id: str) -> GameSession: from dnd_simulator.service.errors import SessionNotFoundError - if session_id not in self._sessions: - # Try to restore from autosave on disk - self._try_restore_session(session_id) - if session_id not in self._sessions: + with self._sessions_lock: + session = self._sessions.get(session_id) + if session is None: + # Serialize restore with registry changes so concurrent callers cannot + # create two in-memory sessions from the same autosave. + self._try_restore_session(session_id) + session = self._sessions.get(session_id) + if session is None: raise SessionNotFoundError(f"Session '{session_id}' not found") structlog.contextvars.bind_contextvars(session_id=session_id) - return self._sessions[session_id] + return session def _try_restore_session(self, session_id: str) -> None: """Attempt to restore a session from its autosave file.""" @@ -343,7 +367,6 @@ def _try_restore_session(self, session_id: str) -> None: return from dnd_simulator.layers.common.rng_state import load_rng_state - from dnd_simulator.rules.dice import get_global_rng from dnd_simulator.storage.save_schema import SaveGame try: @@ -364,11 +387,14 @@ def _try_restore_session(self, session_id: str) -> None: return # Reassign to the original session_id - del self._sessions[session.session_id] + with self._sessions_lock: + del self._sessions[session.session_id] session.session_id = session_id - load_rng_state(get_global_rng(), save.world.dice_rng_state) - session.world.load(save.world.to_world_dict()) - self._assign_brains(self._get_entities_layer(session)) + with session.mutate_world(): + load_rng_state(session.dice_rng, save.world.dice_rng_state) + session.world.load(save.world.to_world_dict()) + self._assign_brains(self._get_entities_layer(session)) - self._sessions[session_id] = session + with self._sessions_lock: + self._sessions[session_id] = session diff --git a/src/dnd_simulator/service/session.py b/src/dnd_simulator/service/session.py index a750d14c..7401d7e0 100644 --- a/src/dnd_simulator/service/session.py +++ b/src/dnd_simulator/service/session.py @@ -4,13 +4,18 @@ import contextvars import dataclasses import os +import random import threading -from collections.abc import Callable +from collections.abc import Callable, Iterator from dataclasses import dataclass, field -from typing import Any, Protocol +from typing import TYPE_CHECKING, Any, Protocol import structlog +if TYPE_CHECKING: + from dnd_simulator.core.location import LocationGraph + from dnd_simulator.storage.save_schema import SaveGame + from dnd_simulator.core.action import Action, ActionType from dnd_simulator.core.action_defs import get_action_def from dnd_simulator.core.awareness import CombatAwareness, PeacefulAwareness, PerceivedEvent @@ -28,7 +33,7 @@ from dnd_simulator.rules.leveling import xp_to_next_level from dnd_simulator.rules.modifiers import effective_ac from dnd_simulator.service.action_dispatcher import create_dispatcher -from dnd_simulator.service.dto import PlayerStatusData, ResourcePoolView +from dnd_simulator.service.dto import JourneyView, PlayerStatusData, ResourcePoolView logger = structlog.get_logger(domain="session") @@ -36,6 +41,11 @@ # inside this window (StrictMode remount, network blip) cancels the evict. Configurable # for ops/tests; overridable per-session via ``GameSession._evict_grace_seconds``. _DEFAULT_EVICT_GRACE_SECONDS = float(os.getenv("DND_EVICT_GRACE_SECONDS", "1.5")) +_DEFAULT_ROUND_STOP_TIMEOUT_SECONDS = float(os.getenv("DND_ROUND_STOP_TIMEOUT_SECONDS", "5")) + + +class RoundStopTimeoutError(RuntimeError): + """The session's round thread did not stop within its lifecycle deadline.""" # --------------------------------------------------------------------------- @@ -170,12 +180,29 @@ def build_inventory_payload(player: PlayerCharacter) -> list[dict[str, object]]: return inventory -def build_player_status(player: PlayerCharacter) -> PlayerStatusData: +def build_player_status(player: PlayerCharacter, location_graph: LocationGraph | None = None) -> PlayerStatusData: """Build the full player status snapshot — single source shared by REST and WS. All derived fields (AC from equipment+modifiers, XP to next level) are computed here. """ + from dnd_simulator.core.intent import TravelIntent + scores = player.ability_scores + journey = None + if isinstance(player.current_intent, TravelIntent) and location_graph is not None: + intent = player.current_intent + + def location_name(location_id: str) -> str: + return location_graph.get(location_id).name if location_graph.has(location_id) else location_id + + journey = JourneyView( + destination_id=intent.destination_id, + destination_name=location_name(intent.destination_id), + current_location_name=location_name(player.location_id), + next_location_name=location_name(intent.remaining_route[0]), + remaining_route=tuple(location_name(location_id) for location_id in intent.remaining_route), + next_arrival_seconds=intent.next_arrival_seconds, + ) return PlayerStatusData( player_id=player.id, name=player.name, @@ -200,6 +227,7 @@ def build_player_status(player: PlayerCharacter) -> PlayerStatusData: "wis": scores[Ability.WIS], "cha": scores[Ability.CHA], }, + journey=journey, resource_pools=[ ResourcePoolView(id=p.id, max_uses=p.max_uses, current_uses=p.current_uses) for p in player.resource_pools ], @@ -268,6 +296,7 @@ class GameSession: lang: str = "en" world_name: str = "" default_player_faction: str = "" + dice_rng: random.Random = field(default_factory=random.Random, repr=False) # Round lifecycle (managed, not serialized) _round: Round | None = field(default=None, init=False, repr=False) @@ -279,14 +308,50 @@ class GameSession: _spectators: list[SessionEventListener] = field(default_factory=list, init=False, repr=False) _last_turn_msg: dict[str, Any] | None = field(default=None, init=False, repr=False) _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False) + _round_transition_lock: threading.RLock = field(default_factory=threading.RLock, init=False, repr=False) + _world_state_lock: threading.RLock = field(default_factory=threading.RLock, init=False, repr=False) _on_empty: Callable[[GameSession], None] | None = field(default=None, init=False, repr=False) _evict_timer: threading.Timer | None = field(default=None, init=False, repr=False) _evict_grace_seconds: float = field(default=_DEFAULT_EVICT_GRACE_SECONDS, init=False, repr=False) + _round_stop_timeout_seconds: float = field(default=_DEFAULT_ROUND_STOP_TIMEOUT_SECONDS, init=False, repr=False) # --------------------------------------------------------------------------- # Player queries # --------------------------------------------------------------------------- + @contextlib.contextmanager + def read_world(self) -> Iterator[None]: + """Hold the session gate while reading a consistent world snapshot.""" + with self._world_state_lock: + yield + + @contextlib.contextmanager + def mutate_world(self) -> Iterator[None]: + """Hold the re-entrant session gate while mutating world state.""" + with self._world_state_lock: + yield + + def build_save_game(self) -> SaveGame: + """Build an immutable save snapshot under the world-state gate.""" + from dnd_simulator.layers.common.rng_state import dump_rng_state + from dnd_simulator.storage.save_schema import SCHEMA_VERSION, SaveGame, SaveMeta + + with self.read_world(): + world_data = self.world.save() + world_data["dice_rng_state"] = dump_rng_state(self.dice_rng) + return SaveGame.model_validate( + { + "schema_version": SCHEMA_VERSION, + "meta": SaveMeta( + session_id=self.session_id, + world_name=self.world_name, + lang=self.lang, + default_player_faction=self.default_player_faction, + ).model_dump(mode="json"), + "world": world_data, + } + ) + def get_players(self) -> list[PlayerCharacter]: return query_players(self.world.query_layer) @@ -326,8 +391,10 @@ def has_player_listeners(self) -> bool: def add_listener(self, listener: SessionEventListener) -> None: self._bind_session_context() - with self._lock: - # A (re)connecting player cancels any pending evict during the grace window. + with self._round_transition_lock, self._lock: + # Serialize listener arrival with disconnect-driven stop_round. Otherwise an + # old connection can observe an empty listener list, a reconnect can start a + # new round, and the old connection can then stop that new round. self._cancel_evict_check() self._listeners.append(listener) count = len(self._listeners) @@ -356,30 +423,29 @@ def get_last_turn_msg(self) -> dict[str, Any] | None: def remove_listener(self, listener: SessionEventListener) -> None: self._bind_session_context() - stop_round = False - with self._lock: - with contextlib.suppress(ValueError): - self._listeners.remove(listener) - count = len(self._listeners) - player_empty = not self.has_player_listeners() - if player_empty and self._round is not None: - stop_round = True - logger.info("remove_listener", listener_count=count, player_empty=player_empty, stop_round=stop_round) - if stop_round: - # Pause the simulation immediately when no player drives it. A lingering round - # thread would keep advancing NPC turns during the grace window: for a real - # player a network blip would silently cost them combat turns, and because all - # sessions share one process-global dice RNG, overlapping player-less rounds make - # seeded integration tests nondeterministic. stop_round() cancels any stale timer, - # so the evict is (re)armed after it returns. - self.stop_round() - if player_empty: - # Defer only the registry eviction: a quick disconnect+reconnect (StrictMode - # remount, network blip) must not flash the session out of the registry, and the - # reconnecting player restarts the round via start_round. The deferred check - # (_run_evict_check) re-verifies emptiness before firing _on_empty. + player_empty = False + with self._round_transition_lock: with self._lock: - self._schedule_evict_check() + try: + self._listeners.remove(listener) + except ValueError: + logger.info("remove_listener_ignored", listener_count=len(self._listeners)) + return + count = len(self._listeners) + player_empty = not self.has_player_listeners() + stop_round = player_empty and self._round is not None + logger.info("remove_listener", listener_count=count, player_empty=player_empty, stop_round=stop_round) + if stop_round: + # Pause before a reconnect can enter add_listener/start_round. + try: + self._stop_round() + except RoundStopTimeoutError: + logger.exception("disconnect_stop_failed", session_id=self.session_id) + if player_empty: + # Arm eviction before allowing add_listener to enter; a reconnect then + # cancels this exact timer while it starts the next round. + with self._lock: + self._schedule_evict_check() def _schedule_evict_check(self) -> None: """Arm the deferred empty-session check. Caller holds ``_lock``.""" @@ -413,7 +479,14 @@ def _run_evict_check(self) -> None: stop_round = True logger.info("evict_check_firing", stop_round=stop_round) if stop_round: - self.stop_round() + try: + self.stop_round() + except RoundStopTimeoutError: + logger.exception("evict_stop_failed", session_id=self.session_id) + with self._lock: + if not self.has_player_listeners(): + self._schedule_evict_check() + return if self._on_empty is not None: self._on_empty(self) @@ -447,7 +520,7 @@ def _build_round_state( "mode": "combat" if isinstance(awareness, CombatAwareness) else "peaceful", "awareness": _awareness_to_dict(awareness, creature=player), "events": _events_to_list(perceived), - "player": dataclasses.asdict(build_player_status(player)), + "player": dataclasses.asdict(build_player_status(player, self.world.location_graph)), "location": _location_data(self.world, player.location_id), } @@ -456,6 +529,11 @@ def _build_round_state( # --------------------------------------------------------------------------- def start_round(self, player: PlayerCharacter) -> Round: + """Start or return the round while excluding load/stop transitions.""" + with self._round_transition_lock: + return self._start_round(player) + + def _start_round(self, player: PlayerCharacter) -> Round: """Start the round loop if not already running. Idempotent. Wires PlayerBrain, creates Round, starts background thread. @@ -485,7 +563,7 @@ def on_turn( "mode": "combat" if isinstance(awareness, CombatAwareness) else "peaceful", "awareness": _awareness_to_dict(awareness, creature=creature), "events": _events_to_list(events), - "player": dataclasses.asdict(build_player_status(player)), + "player": dataclasses.asdict(build_player_status(player, self.world.location_graph)), "location": _location_data(self.world, player.location_id), } if awareness.turn_budget is not None: @@ -508,7 +586,13 @@ def on_reaction( player.brain = brain dispatcher = create_dispatcher(self.world) - game_round = Round(self.world, creature_host, dispatcher=dispatcher) + game_round = Round( + self.world, + creature_host, + dispatcher=dispatcher, + rng=self.dice_rng, + mutation_scope=self.mutate_world, + ) # Wire on_action: fires after each action by any creature def on_action(creature: Creature, action: Action, budget: TurnBudget | None, error: str) -> None: @@ -557,8 +641,13 @@ def run_round_loop() -> None: return game_round - def stop_round(self) -> None: - """Stop the round loop and clean up.""" + def stop_round(self, *, discard_events: bool = False) -> None: + """Stop the round while excluding concurrent start/load transitions.""" + with self._round_transition_lock: + self._stop_round(discard_events=discard_events) + + def _stop_round(self, *, discard_events: bool = False) -> None: + """Stop the round loop within the deadline, then clean up its lifecycle snapshot.""" self._bind_session_context() logger.info("stop_round") with self._lock: @@ -566,16 +655,47 @@ def stop_round(self) -> None: game_round = self._round brain = self._player_brain thread = self._round_thread - self._round = None - self._player_brain = None - self._round_thread = None if game_round is not None: + if discard_events: + game_round.clear_callbacks() game_round.stop() if brain is not None: brain.submit_action(Action(name=ActionType.END_TURN)) # unblock queue + brain.submit_reaction(Action(name=ActionType.SKIP)) if thread is not None: - thread.join(timeout=5) + thread.join(timeout=self._round_stop_timeout_seconds) + if thread.is_alive(): + logger.error( + "stop_round_timeout", + session_id=self.session_id, + timeout_seconds=self._round_stop_timeout_seconds, + thread_name=thread.name, + ) + raise RoundStopTimeoutError( + f"Round thread for session {self.session_id!r} did not stop within " + f"{self._round_stop_timeout_seconds:g} seconds" + ) + + with self._lock: + if self._round is game_round: + self._round = None + if self._player_brain is brain: + self._player_brain = None + if self._round_thread is thread: + self._round_thread = None + + def clear_cached_turn(self) -> None: + """Discard transport state tied to the world that was just replaced.""" + self._last_turn_msg = None + + def replace_world_state(self, loader: Callable[[], None]) -> None: + """Pause the round and atomically replace state before another start can win.""" + with self._round_transition_lock: + self._stop_round(discard_events=True) + self.clear_cached_turn() + with self.mutate_world(): + loader() def submit_player_action(self, action: Action) -> None: """Submit a player action to the brain queue. diff --git a/src/dnd_simulator/storage/store.py b/src/dnd_simulator/storage/store.py index fd7bec01..6ae4bffa 100644 --- a/src/dnd_simulator/storage/store.py +++ b/src/dnd_simulator/storage/store.py @@ -1,6 +1,8 @@ from __future__ import annotations import json +import os +import tempfile from abc import ABC, abstractmethod from datetime import UTC, datetime from pathlib import Path @@ -42,8 +44,19 @@ def __init__(self, directory: Path) -> None: def save(self, name: str, data: dict[str, Any], *, world: str = "") -> None: path = self._path_for(name, world=world) path.parent.mkdir(parents=True, exist_ok=True) - with path.open("w") as f: - json.dump(data, f, indent=2, ensure_ascii=False) + temporary_path: Path | None = None + try: + with tempfile.NamedTemporaryFile( + "w", encoding="utf-8", dir=path.parent, prefix=f".{path.name}.", suffix=".tmp", delete=False + ) as file: + temporary_path = Path(file.name) + json.dump(data, file, indent=2, ensure_ascii=False) + file.flush() + os.fsync(file.fileno()) + temporary_path.replace(path) + finally: + if temporary_path is not None: + temporary_path.unlink(missing_ok=True) def load(self, name: str, *, world: str = "") -> dict[str, Any]: path = self._path_for(name, world=world) diff --git a/tests/integration/test_lairs.py b/tests/integration/test_lairs.py index d1a1c1c6..8d0091fa 100644 --- a/tests/integration/test_lairs.py +++ b/tests/integration/test_lairs.py @@ -224,6 +224,12 @@ def test_depleted_state_survives_save_load(self, backend_url: str, api_url: str, resp = requests.post(f"{api_url}/sessions/{sid}/saves/lair_depleted/load", timeout=10) assert resp.status_code == HTTPStatus.OK + # Load pauses the old round. Reconnect is the only lifecycle edge that + # starts the restored round and binds a fresh PlayerBrain. + sock.close() + sock = ws_connect(ws_base, sid, pid) + _get_turn(sock) + # Return after load: depletion persisted, nothing spawns. _move_player(api_url, sid, pid, "cave") _advance_turn(sock) @@ -321,7 +327,9 @@ def test_looted_treasury_survives_save_load(self, backend_url: str, api_url: str resp = requests.post(f"{api_url}/sessions/{sid}/saves/lair_looted/load", timeout=10) assert resp.status_code == HTTPStatus.OK - turn = _advance_turn(sock) + sock.close() + sock = ws_connect(ws_base, sid, pid) + turn = _get_turn(sock) chest = _nearby(turn, TREASURY_ID) assert chest is not None assert chest["loot_gold"] == 0 diff --git a/tests/unit/test_action_dispatcher.py b/tests/unit/test_action_dispatcher.py index 440c3c94..ca78d318 100644 --- a/tests/unit/test_action_dispatcher.py +++ b/tests/unit/test_action_dispatcher.py @@ -335,7 +335,8 @@ def test_wait_sets_wake_at_and_dormant(self) -> None: action = Action(name=ActionType.WAIT, params={"hours": 2}) result = handle_wait(creature, action, _noop_emit, _PEACEFUL, world) assert result.success - assert creature.wake_at_seconds == 10000 + 2 * 3600 + assert creature.current_intent is not None + assert creature.current_intent.wake_at_seconds == 10000 + 2 * 3600 assert creature.active is False def test_wait_default_1_hour(self) -> None: @@ -345,7 +346,8 @@ def test_wait_default_1_hour(self) -> None: action = Action(name=ActionType.WAIT) result = handle_wait(creature, action, _noop_emit, _PEACEFUL, world) assert result.success - assert creature.wake_at_seconds == 5000 + 3600 + assert creature.current_intent is not None + assert creature.current_intent.wake_at_seconds == 5000 + 3600 def test_wait_emits_no_event(self) -> None: world = MagicMock() @@ -355,16 +357,16 @@ def test_wait_emits_no_event(self) -> None: handle_wait(_creature(), action, emit, _PEACEFUL, world) assert len(emitted) == 0 - def test_wait_travel(self) -> None: + def test_wait_does_not_travel(self) -> None: world = MagicMock() - world.location_graph.travel_seconds.return_value = 600 + world.time.to_total_seconds.return_value = 0 creature = _creature() creature.location_id = "loc_a" action = Action(name=ActionType.WAIT, params={"travel_to": "loc_b"}) result = handle_wait(creature, action, _noop_emit, _PEACEFUL, world) assert result.success - assert creature.location_id == "loc_b" - world.advance_time.assert_called_once() + assert creature.location_id == "loc_a" + world.advance_time.assert_not_called() class TestHandleDash: diff --git a/tests/unit/test_action_provider_isolated.py b/tests/unit/test_action_provider_isolated.py index 1b8692c1..bb0ed4e7 100644 --- a/tests/unit/test_action_provider_isolated.py +++ b/tests/unit/test_action_provider_isolated.py @@ -40,7 +40,15 @@ } ) _PEACEFUL_BASE = frozenset( - {ActionType.IDLE, ActionType.SAY, ActionType.WAIT, ActionType.ATTACK, ActionType.END_TURN, ActionType.SKIP} + { + ActionType.IDLE, + ActionType.SAY, + ActionType.WAIT, + ActionType.TRAVEL, + ActionType.ATTACK, + ActionType.END_TURN, + ActionType.SKIP, + } ) _ALL_BASE = _COMBAT_BASE | _PEACEFUL_BASE diff --git a/tests/unit/test_activation_manager.py b/tests/unit/test_activation_manager.py index 044bcfcc..a6d9be27 100644 --- a/tests/unit/test_activation_manager.py +++ b/tests/unit/test_activation_manager.py @@ -12,6 +12,8 @@ DamageComponent, DamageType, ) +from dnd_simulator.core.intent import IntentType, TimedIntent, TravelIntent +from dnd_simulator.core.location import Location, LocationEdge, LocationGraph from dnd_simulator.core.models import ( ActionResult, Answer, @@ -25,6 +27,7 @@ from dnd_simulator.core.monster import EncounterEntry, MonsterTemplate from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.core.queries import SquadInfo +from dnd_simulator.core.resource import ResourcePool, RestType from dnd_simulator.core.squad import SquadBehavior, SquadType from dnd_simulator.layers.entities.layer import EntitiesLayer @@ -106,6 +109,123 @@ def test_moving_player_reactivates(self) -> None: assert npc_a.active is False assert npc_b.active is True + def test_generic_anchor_activates_scene_without_player(self) -> None: + anchor = Creature(id="anchor", name="Oracle", location_id="temple", is_anchor=True) + nearby = Creature(id="nearby", name="Acolyte", location_id="temple", active=False) + distant = Creature(id="distant", name="Farmer", location_id="farm", active=True) + + EntitiesLayer([anchor, nearby, distant]).update_activation(_TIME_0) + + assert anchor.active is True + assert nearby.active is True + assert distant.active is False + + def test_player_without_anchor_capability_does_not_activate_scene(self) -> None: + player = PlayerCharacter(id="p1", name="Hero", location_id="village", is_anchor=False) + nearby = Creature(id="nearby", name="Guard", location_id="village", active=True) + + EntitiesLayer([player, nearby]).update_activation(_TIME_0) + + assert player.active is False + assert nearby.active is False + + def test_active_non_anchor_does_not_activate_another_location(self) -> None: + anchor = Creature(id="anchor", name="Anchor", location_id="square", is_anchor=True) + nearby = Creature(id="nearby", name="Courier", location_id="square", active=True) + elsewhere = Creature(id="elsewhere", name="Friend", location_id="gate", active=True) + + EntitiesLayer([anchor, nearby, elsewhere]).update_activation(_TIME_0) + + assert nearby.active is True + assert elsewhere.active is False + + def test_proximity_does_not_cancel_timed_intent(self) -> None: + now = _TIME_0.to_total_seconds() + anchor = Creature(id="anchor", name="Anchor", location_id="square", is_anchor=True) + sleeper = Creature(id="sleeper", name="Sleeper", location_id="square", active=True) + sleeper.current_intent = TimedIntent(IntentType.SLEEP, now, now + 3600) + + EntitiesLayer([anchor, sleeper]).update_activation(_TIME_0) + + assert sleeper.active is False + assert sleeper.current_intent == TimedIntent(IntentType.SLEEP, now, now + 3600) + + def test_combat_stays_active_without_anchor(self) -> None: + fighter = Creature(id="fighter", name="Fighter", location_id="arena", active=False, in_combat=True) + + EntitiesLayer([fighter]).update_activation(_TIME_0) + + assert fighter.active is True + + def test_completed_long_rest_applies_rewards_once(self) -> None: + now = _TIME_0.to_total_seconds() + pool = ResourcePool("spell_slot_1", 2, 0, RestType.LONG_REST) + sleeper = Creature( + id="sleeper", + name="Sleeper", + location_id="inn", + is_anchor=True, + max_hp=20, + current_hp=5, + resource_pools=[pool], + ) + sleeper.current_intent = TimedIntent( + IntentType.SLEEP, + now - 8 * 3600, + now, + rest_type=RestType.LONG_REST, + ) + layer = EntitiesLayer([sleeper]) + + layer.update_activation(_TIME_0) + assert sleeper.current_hp == 20 + assert pool.current_uses == 2 + assert sleeper.current_intent is None + + sleeper.current_hp = 10 + pool.current_uses = 0 + layer.update_activation(_TIME_0) + assert sleeper.current_hp == 10 + assert pool.current_uses == 0 + + def test_traveler_stops_when_intermediate_location_has_awake_anchor(self) -> None: + now = _TIME_0.to_total_seconds() + traveler = Creature(id="traveler", name="Traveler", location_id="start", is_anchor=True) + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now) + scene_anchor = Creature(id="host", name="Host", location_id="road", is_anchor=True) + graph = LocationGraph( + [ + Location("start", "Start", "r1", edges=(LocationEdge("road", 1000),)), + Location("road", "Road", "r1", edges=(LocationEdge("goal", 2000),)), + Location("goal", "Goal", "r1"), + ] + ) + + EntitiesLayer([traveler, scene_anchor]).update_activation(_TIME_0, location_graph=graph) + + assert traveler.location_id == "road" + assert traveler.current_intent is None + assert traveler.active is True + + def test_traveler_continues_through_dormant_intermediate_location(self) -> None: + now = _TIME_0.to_total_seconds() + traveler = Creature(id="traveler", name="Traveler", location_id="start", is_anchor=True) + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now) + dormant = Creature(id="local", name="Local", location_id="road", is_anchor=False) + graph = LocationGraph( + [ + Location("start", "Start", "r1", edges=(LocationEdge("road", 1000),)), + Location("road", "Road", "r1", edges=(LocationEdge("goal", 2000),)), + Location("goal", "Goal", "r1"), + ] + ) + + EntitiesLayer([traveler, dormant]).update_activation(_TIME_0, location_graph=graph) + + assert traveler.location_id == "road" + assert traveler.current_intent == TravelIntent(now, "goal", ("goal",), now + 1440) + assert traveler.active is False + class TestEncounterCooldown: """Encounter cooldown prevents re-rolling within 600 game-seconds.""" diff --git a/tests/unit/test_autosave_all.py b/tests/unit/test_autosave_all.py index dd7931eb..721f8acf 100644 --- a/tests/unit/test_autosave_all.py +++ b/tests/unit/test_autosave_all.py @@ -2,6 +2,7 @@ from __future__ import annotations +import threading from typing import Any from unittest.mock import MagicMock @@ -15,23 +16,27 @@ class _Svc(SaveCommands): def __init__(self, sessions: dict[str, Any]) -> None: self._sessions = sessions # type: ignore[assignment] + self._sessions_lock = threading.RLock() self._store = MagicMock() self.saved: list[str] = [] - def autosave_session(self, session_id: str) -> None: # type: ignore[override] - raise NotImplementedError - class TestAutosaveAllSessions: def test_one_failure_does_not_block_others_and_logs(self) -> None: - svc = _Svc({"a": object(), "b": object(), "c": object()}) - - def autosave(sid: str) -> None: + sessions = {sid: MagicMock() for sid in ("a", "b", "c")} + for sid, session in sessions.items(): + session.session_id = sid + session.build_save_game.return_value.model_dump.return_value = {} + session.world_name = "world" + svc = _Svc(sessions) + + def autosave(name: str, data: dict[str, Any], *, world: str = "") -> None: + sid = name.removeprefix("session_") if sid == "b": raise RuntimeError("disk full") svc.saved.append(sid) - svc.autosave_session = autosave # type: ignore[method-assign] + svc._store.save.side_effect = autosave with structlog.testing.capture_logs() as logs: svc.autosave_all_sessions() diff --git a/tests/unit/test_autosave_error_logging.py b/tests/unit/test_autosave_error_logging.py index eb2e0387..741cb7f5 100644 --- a/tests/unit/test_autosave_error_logging.py +++ b/tests/unit/test_autosave_error_logging.py @@ -1,12 +1,48 @@ from __future__ import annotations +import threading from pathlib import Path +from typing import Any +import pytest import structlog from dnd_simulator.core.character import Ability from dnd_simulator.service import GameService -from dnd_simulator.storage.store import JsonFileStore +from dnd_simulator.service.errors import SessionNotFoundError +from dnd_simulator.storage.store import JsonFileStore, SaveStore + + +class _BlockingStore(SaveStore): + def __init__(self) -> None: + self.save_started = threading.Event() + self.release_save = threading.Event() + self.save_calls = 0 + self.data: dict[tuple[str, str], dict[str, Any]] = {} + + def save(self, name: str, data: dict[str, Any], *, world: str = "") -> None: + self.save_calls += 1 + self.save_started.set() + assert self.release_save.wait(timeout=2) + self.data[(world, name)] = data + + def load(self, name: str, *, world: str = "") -> dict[str, Any]: + try: + return self.data[(world, name)] + except KeyError: + for (_saved_world, saved_name), data in self.data.items(): + if saved_name == name: + return data + raise KeyError(name) from None + + def list_saves(self, *, world: str = "") -> list[str]: + return [name for saved_world, name in self.data if saved_world == world] + + def delete(self, name: str, *, world: str = "") -> None: + try: + del self.data[(world, name)] + except KeyError: + raise KeyError(name) from None def _scores() -> dict[str, int]: @@ -24,10 +60,10 @@ def test_create_player_logs_autosave_failure_and_still_returns_player(tmp_path: service = GameService(store=JsonFileStore(tmp_path / "saves")) session = service.start_game() - def fail_autosave(session_id: str) -> None: - raise RuntimeError(f"autosave failed for {session_id}") + def fail_save(name: str, data: dict[str, Any], *, world: str = "") -> None: + raise RuntimeError(f"autosave failed for {name}") - service.autosave_session = fail_autosave # type: ignore[method-assign] + service._store.save = fail_save # type: ignore[method-assign] with structlog.testing.capture_logs() as logs: player = service.create_player( @@ -50,10 +86,10 @@ def test_empty_session_evict_logs_autosave_failure_and_still_removes_session(tmp service = GameService(store=JsonFileStore(tmp_path / "saves")) session = service.start_game() - def fail_autosave(session_id: str) -> None: - raise RuntimeError(f"autosave failed for {session_id}") + def fail_save(name: str, data: dict[str, Any], *, world: str = "") -> None: + raise RuntimeError(f"autosave failed for {name}") - service.autosave_session = fail_autosave # type: ignore[method-assign] + service._store.save = fail_save # type: ignore[method-assign] with structlog.testing.capture_logs() as logs: service._on_session_empty(session) @@ -77,3 +113,41 @@ def test_empty_session_evict_after_delete_is_noop(tmp_path: Path) -> None: assert session.session_id not in service._sessions assert not [e for e in logs if e.get("event") == "session_empty_autosave_failed"] assert [e for e in logs if e.get("event") == "session_empty_evict_skipped"] + + +def test_concurrent_evict_runs_one_autosave() -> None: + store = _BlockingStore() + service = GameService(store=store) + session = service.start_game() + first = threading.Thread(target=service._on_session_empty, args=(session,)) + second = threading.Thread(target=service._on_session_empty, args=(session,)) + + first.start() + assert store.save_started.wait(timeout=2) + second.start() + store.release_save.set() + first.join(timeout=2) + second.join(timeout=2) + + assert store.save_calls == 1 + assert session.session_id not in service._sessions + + +def test_explicit_delete_racing_evict_does_not_leave_restorable_autosave() -> None: + store = _BlockingStore() + service = GameService(store=store) + session = service.start_game() + evict = threading.Thread(target=service._on_session_empty, args=(session,)) + evict.start() + assert store.save_started.wait(timeout=2) + + delete = threading.Thread(target=service.delete_session, args=(session.session_id,)) + delete.start() + store.release_save.set() + evict.join(timeout=2) + delete.join(timeout=2) + + assert not evict.is_alive() + assert not delete.is_alive() + with pytest.raises(SessionNotFoundError): + service.get_session(session.session_id) diff --git a/tests/unit/test_check_reactions.py b/tests/unit/test_check_reactions.py index 377a10cc..88baa828 100644 --- a/tests/unit/test_check_reactions.py +++ b/tests/unit/test_check_reactions.py @@ -6,6 +6,8 @@ from __future__ import annotations +import random +from contextlib import nullcontext from unittest.mock import MagicMock from dnd_simulator.core.action import Action, ActionType @@ -67,6 +69,8 @@ def _make_round(creatures: list[Creature]) -> object: r._world = world r._host = entities r._dispatcher = dispatcher + r._rng = random.Random(0) + r._mutation_scope = nullcontext r._on_action = None return r diff --git a/tests/unit/test_combat_manager_split.py b/tests/unit/test_combat_manager_split.py index 06838f71..629dcf47 100644 --- a/tests/unit/test_combat_manager_split.py +++ b/tests/unit/test_combat_manager_split.py @@ -22,7 +22,9 @@ ) from dnd_simulator.core.class_features import RogueFeatures from dnd_simulator.core.combat import BattleMap, Position -from dnd_simulator.core.models import Event +from dnd_simulator.core.intent import IntentType, TimedIntent, TravelIntent +from dnd_simulator.core.models import Event, EventType +from dnd_simulator.core.resource import ResourcePool, RestType from dnd_simulator.layers.entities.combat_manager import ( IDLE_ROUNDS_TO_END_COMBAT, INITIAL_REACTION_BUDGET, @@ -343,6 +345,54 @@ def test_stalemate_ends_combat(self) -> None: assert cm.get_combat("arena") is None +class TestIntentInterruption: + def test_entering_combat_interrupts_all_participant_intents_in_place(self) -> None: + now = 100 + sleeper = Creature(id="sleeper", name="Sleeper", location_id="arena", active=True, faction_id="a") + traveler = Creature(id="traveler", name="Traveler", location_id="arena", active=True, faction_id="b") + sleeper.current_intent = TimedIntent(IntentType.SLEEP, now, now + 3600) + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now + 600) + cm = CombatManager({"sleeper": sleeper, "traveler": traveler}, defaultdict(list)) # type: ignore[arg-type] + + combat = cm.start_combat("arena") + + assert combat is not None + assert sleeper.current_intent is None + assert traveler.current_intent is None + assert traveler.location_id == "arena" + assert combat.turn_order.count("sleeper") == 1 + assert combat.turn_order.count("traveler") == 1 + + def test_damage_interrupts_sleep_without_applying_rest_rewards(self) -> None: + attacker = _fighter() + target = _goblin() + attacker.active = target.active = True + pool = ResourcePool("spell_slot_1", 2, 0, RestType.LONG_REST) + target.resource_pools.append(pool) + cm = CombatManager( + {attacker.id: attacker, target.id: target}, + defaultdict(list), + rng=random.Random(0), + ) # type: ignore[arg-type] + cm.start_combat("loc") + target.current_intent = TimedIntent(IntentType.SLEEP, 100, 3700, rest_type=RestType.LONG_REST) + hp_before = target.current_hp + cm._rng.randint = lambda a, b: b # type: ignore[method-assign] + + result = cm.resolve_attack( + Event( + event_type=EventType.ENTITY_ATTACK, + source_layer="test", + data={"attacker_id": attacker.id, "target_id": target.id}, + ) + ) + + assert result.success is True + assert target.current_hp < hp_before + assert target.current_intent is None + assert pool.current_uses == 0 + + # --------------------------------------------------------------------------- # Event builder tests # --------------------------------------------------------------------------- diff --git a/tests/unit/test_commands_save.py b/tests/unit/test_commands_save.py index 699cdafb..86534c6a 100644 --- a/tests/unit/test_commands_save.py +++ b/tests/unit/test_commands_save.py @@ -9,14 +9,17 @@ from __future__ import annotations from pathlib import Path +from unittest.mock import MagicMock import pytest -from dnd_simulator.core.brain import BrainType +from dnd_simulator.core.brain import BrainType, PlayerBrain +from dnd_simulator.core.combat import BattleMap, CombatState from dnd_simulator.layers.entities.models import Npc -from dnd_simulator.rules.dice import roll, set_global_seed +from dnd_simulator.rules.dice import roll from dnd_simulator.rules.rule_brain import RuleBrain from dnd_simulator.service import GameService +from dnd_simulator.service.session import RoundStopTimeoutError from dnd_simulator.storage.store import JsonFileStore @@ -69,15 +72,27 @@ def test_dice_rng_state_restored_on_load(self, tmp_path: Path) -> None: svc = _make_service(tmp_path) session = svc.start_game("sword_vale") sid = session.session_id - set_global_seed(77) - roll("1d20") + session.dice_rng.seed(77) + roll("1d20", rng=session.dice_rng) svc.save_game(sid, "dice") - expected = roll("1d20").total - roll("1d20") + expected = roll("1d20", rng=session.dice_rng).total + roll("1d20", rng=session.dice_rng) svc.load_game(sid, "dice") - assert roll("1d20").total == expected + assert roll("1d20", rng=session.dice_rng).total == expected + + def test_sessions_own_independent_dice_sequences(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("DND_DICE_SEED", "91") + svc = _make_service(tmp_path) + first = svc.start_game("sword_vale") + second = svc.start_game("sword_vale") + + first_initial = roll("1d20", rng=first.dice_rng).total + roll("5d20", rng=first.dice_rng) + second_initial = roll("1d20", rng=second.dice_rng).total + + assert first_initial == second_initial def test_state_restored_to_saved_snapshot(self, tmp_path: Path) -> None: svc = _make_service(tmp_path) @@ -116,6 +131,118 @@ def test_brains_reassigned_on_load(self, tmp_path: Path) -> None: assert isinstance(restored, Npc) assert isinstance(restored.brain, RuleBrain) + def test_load_stops_old_round_and_resumes_once_for_restored_player(self, tmp_path: Path) -> None: + svc = _make_service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + player = svc.create_player( + sid, + { + "name": "Loader", + "race": "human", + "class": "fighter", + "ability_scores": {"str": 15, "dex": 10, "con": 14, "int": 8, "wis": 12, "cha": 8}, + "fighting_style": "defense", + }, + ) + layer = svc._get_entities_layer(session) + player.in_combat = True + player.active = True + layer._combat._combats[player.location_id] = CombatState( + location_id=player.location_id, + turn_order=[player.id], + round_number=1, + battle_map=BattleMap(width=60, height=60), + ) + svc.save_game(sid, "combat") + session._last_turn_msg = {"type": "stale"} + session.start_round(player) + old_thread = session._round_thread + assert old_thread is not None + + svc.load_game(sid, "combat") + + assert not old_thread.is_alive() + assert session._round is None + assert session._round_thread is None + assert session._player_brain is None + assert session.get_last_turn_msg() is None + restored_combat = svc._get_entities_layer(session).get_combat(player.location_id) + assert restored_combat is not None + assert restored_combat.round_number == 1 + + restored_player = session.get_player() + assert restored_player is not None + first_round = session.start_round(restored_player) + first_thread = session._round_thread + second_round = session.start_round(restored_player) + try: + assert first_round is second_round + assert session._round_thread is first_thread + assert isinstance(restored_player.brain, PlayerBrain) + finally: + session.stop_round() + + def test_autosave_restore_is_paused_until_player_connection(self, tmp_path: Path) -> None: + svc = _make_service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + svc.create_player( + sid, + { + "name": "Restored", + "race": "human", + "class": "fighter", + "ability_scores": {"str": 15, "dex": 10, "con": 14, "int": 8, "wis": 12, "cha": 8}, + "fighting_style": "defense", + }, + ) + svc.autosave_session(sid) + svc._sessions.pop(sid) + + restored = svc.get_session(sid) + + assert restored._round is None + assert restored._round_thread is None + assert restored._player_brain is None + + def test_stop_timeout_preserves_live_state_and_retry_loads(self, tmp_path: Path) -> None: + svc = _make_service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + svc.save_game(sid, "snap") + svc.advance_time(sid, 5) + live_time = session.world.time + live_rng_state = session.dice_rng.getstate() + live_round = MagicMock() + live_brain = MagicMock() + live_thread = MagicMock() + session._round = live_round + session._player_brain = live_brain + session._round_thread = live_thread + session._last_turn_msg = {"type": "live"} + original_stop = session._stop_round + session._stop_round = MagicMock(side_effect=RoundStopTimeoutError("blocked")) # type: ignore[method-assign] + + with pytest.raises(RoundStopTimeoutError): + svc.load_game(sid, "snap") + + assert session.world.time == live_time + assert session.dice_rng.getstate() == live_rng_state + assert session._round is live_round + assert session._player_brain is live_brain + assert session._round_thread is live_thread + assert session.get_last_turn_msg() == {"type": "live"} + + session._stop_round = original_stop # type: ignore[method-assign] + session._round = None + session._player_brain = None + session._round_thread = None + svc.load_game(sid, "snap") + + assert session.world.time != live_time + assert session.get_last_turn_msg() is None + class TestListAndDeleteSaves: def test_list_saves_returns_saved_names(self, tmp_path: Path) -> None: diff --git a/tests/unit/test_divine_smite_combat.py b/tests/unit/test_divine_smite_combat.py index 09e02277..27015b63 100644 --- a/tests/unit/test_divine_smite_combat.py +++ b/tests/unit/test_divine_smite_combat.py @@ -6,6 +6,7 @@ from __future__ import annotations +import random from collections import defaultdict from dnd_simulator.core.action import ActionType @@ -108,7 +109,7 @@ def _target(*, hp: int = 50, ac: int = 5) -> Creature: def _setup_combat(attacker: Creature, target: Creature) -> tuple[CombatManager, dict[str, list[Event]]]: entities: dict[str, Creature] = {attacker.id: attacker, target.id: target} log: dict[str, list[Event]] = defaultdict(list) - cm = CombatManager(entities, log) # type: ignore[arg-type] + cm = CombatManager(entities, log, rng=random.Random(42)) # type: ignore[arg-type] cm.start_combat("arena") return cm, log diff --git a/tests/unit/test_entities_serialization.py b/tests/unit/test_entities_serialization.py index 25132938..16d3cb64 100644 --- a/tests/unit/test_entities_serialization.py +++ b/tests/unit/test_entities_serialization.py @@ -8,6 +8,8 @@ from dnd_simulator.core.character import Creature, NpcRole from dnd_simulator.core.combat import BattleMap, CombatState, Position, Wall from dnd_simulator.core.conditions import Condition +from dnd_simulator.core.intent import IntentType, TimedIntent, TravelIntent +from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.core.resource import ResourcePool, RestType from dnd_simulator.core.turn_budget import TurnBudget from dnd_simulator.layers.entities.layer import EntitiesLayer @@ -325,7 +327,7 @@ def test_combat_sides_survive_round_trip(self) -> None: class TestEntitiesStateModel: def test_state_round_trips_through_json_and_preserves_rng(self) -> None: creature = _make_creature("wanderer") - creature.wake_at_seconds = 123 + creature.current_intent = TimedIntent(IntentType.WAIT, started_at_seconds=23, wake_at_seconds=123) layer = EntitiesLayer(entities=[creature], seed=19) _ = layer._rng.random() @@ -397,7 +399,8 @@ def test_runtime_creature_fields_survive_save_load(self) -> None: creature.reputation = {"guards": 5} creature.xp_value = 25 creature.squad_id = "patrol_1" - creature.wake_at_seconds = 321 + creature.is_anchor = True + creature.current_intent = TimedIntent(IntentType.WAIT, started_at_seconds=123, wake_at_seconds=321) creature.combat_position = (10, 15) layer = EntitiesLayer(entities=[creature]) @@ -417,5 +420,130 @@ def test_runtime_creature_fields_survive_save_load(self) -> None: assert restored.reputation == {"guards": 5} assert restored.xp_value == 25 assert restored.squad_id == "patrol_1" - assert restored.wake_at_seconds == 321 + assert restored.is_anchor is True + assert restored.current_intent == TimedIntent( + IntentType.WAIT, + started_at_seconds=123, + wake_at_seconds=321, + ) assert restored.combat_position == (10, 15) + + def test_anchor_and_timed_intents_round_trip_for_every_creature_kind(self) -> None: + player = PlayerCharacter(id="hero", name="Hero", location_id="square", is_anchor=True) + player.current_intent = TimedIntent(IntentType.WAIT, started_at_seconds=100, wake_at_seconds=3700) + npc = _make_fighter_npc(is_anchor=True) + npc.current_intent = TimedIntent( + IntentType.SLEEP, + started_at_seconds=200, + wake_at_seconds=29000, + rest_type=RestType.LONG_REST, + ) + creature = _make_creature("wolf") + creature.is_anchor = False + creature.current_intent = TimedIntent(IntentType.WAIT, started_at_seconds=300, wake_at_seconds=900) + + restored_layer = EntitiesLayer() + restored_layer.load_state(EntitiesLayer(entities=[player, npc, creature]).get_state()) + + restored_player = restored_layer.get_entity("hero") + restored_npc = restored_layer.get_entity("fighter_npc") + restored_creature = restored_layer.get_entity("wolf") + assert isinstance(restored_player, PlayerCharacter) + assert isinstance(restored_npc, Npc) + assert isinstance(restored_creature, Creature) + assert restored_player.is_anchor is True + assert restored_player.current_intent == player.current_intent + assert restored_npc.is_anchor is True + assert restored_npc.current_intent == npc.current_intent + assert restored_creature.is_anchor is False + assert restored_creature.current_intent == creature.current_intent + + def test_travel_progress_round_trips_for_every_creature_kind(self) -> None: + player = PlayerCharacter(id="hero", name="Hero", location_id="crossroads", is_anchor=True) + player.current_intent = TravelIntent( + started_at_seconds=100, + destination_id="harbor", + remaining_route=("bridge", "harbor"), + next_arrival_seconds=220, + ) + npc = _make_fighter_npc(location_id="bridge") + npc.current_intent = TravelIntent( + started_at_seconds=50, + destination_id="harbor", + remaining_route=("harbor",), + next_arrival_seconds=260, + ) + creature = _make_creature("wolf", location_id="forest") + creature.current_intent = TravelIntent( + started_at_seconds=70, + destination_id="cave", + remaining_route=("ridge", "cave"), + next_arrival_seconds=190, + ) + + restored_layer = EntitiesLayer() + restored_layer.load_state(EntitiesLayer(entities=[player, npc, creature]).get_state()) + + restored_player = restored_layer.get_entity("hero") + restored_npc = restored_layer.get_entity("fighter_npc") + restored_creature = restored_layer.get_entity("wolf") + assert isinstance(restored_player, PlayerCharacter) + assert isinstance(restored_npc, Npc) + assert isinstance(restored_creature, Creature) + assert restored_player.current_intent == player.current_intent + assert restored_npc.current_intent == npc.current_intent + assert restored_creature.current_intent == creature.current_intent + + def test_idle_creature_round_trips_without_fabricated_wake_time(self) -> None: + creature = _make_creature("idle") + + state = EntitiesLayer(entities=[creature]).get_state() + assert state["entities"]["idle"]["current_intent"] is None + + restored_layer = EntitiesLayer() + restored_layer.load_state(state) + restored = restored_layer.get_entity("idle") + assert isinstance(restored, Creature) + assert restored.current_intent is None + + @pytest.mark.parametrize( + "invalid_intent", + [ + {"kind": "unknown", "started_at_seconds": 10, "wake_at_seconds": 20}, + {"kind": "wait", "started_at_seconds": 10, "wake_at_seconds": 20, "extra": True}, + ], + ) + def test_invalid_timed_intent_payload_is_rejected(self, invalid_intent: dict[str, object]) -> None: + state = EntitiesLayer(entities=[_make_creature("broken")]).get_state() + state["entities"]["broken"]["current_intent"] = invalid_intent + + with pytest.raises(ValidationError): + EntitiesLayer().load_state(state) + + @pytest.mark.parametrize( + "invalid_intent", + [ + { + "kind": "travel", + "started_at_seconds": 10, + "destination_id": "harbor", + "remaining_route": [], + "next_arrival_seconds": 20, + }, + { + "kind": "travel", + "started_at_seconds": 10, + "destination_id": "harbor", + "remaining_route": ["harbor"], + "next_arrival_seconds": 20, + "extra": True, + }, + {"kind": "travel", "started_at_seconds": 10, "wake_at_seconds": 20}, + ], + ) + def test_invalid_travel_intent_payload_is_rejected(self, invalid_intent: dict[str, object]) -> None: + state = EntitiesLayer(entities=[_make_creature("broken")]).get_state() + state["entities"]["broken"]["current_intent"] = invalid_intent + + with pytest.raises(ValidationError): + EntitiesLayer().load_state(state) diff --git a/tests/unit/test_game_loop.py b/tests/unit/test_game_loop.py index f6e7a4e3..154ca89a 100644 --- a/tests/unit/test_game_loop.py +++ b/tests/unit/test_game_loop.py @@ -6,8 +6,9 @@ from dnd_simulator.core.awareness import CombatAwareness, PeacefulAwareness, PerceivedEvent from dnd_simulator.core.brain import Brain, PlayerBrain from dnd_simulator.core.character import Creature -from dnd_simulator.core.location import Location, LocationGraph -from dnd_simulator.core.models import GameDateTime +from dnd_simulator.core.intent import IntentType, TimedIntent, TravelIntent +from dnd_simulator.core.location import Location, LocationEdge, LocationGraph +from dnd_simulator.core.models import GameDateTime, TimeDelta from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.core.world import World from dnd_simulator.layers.entities.layer import EntitiesLayer @@ -46,6 +47,18 @@ def _make_world(entities: list[Creature], hour: int = 10) -> World: ) +def _travel_world(entities: list[Creature], hour: int = 10) -> World: + world = _make_world(entities, hour) + world.location_graph = LocationGraph( + [ + Location("start", "Start", "r1", edges=(LocationEdge("road", 1000),)), + Location("road", "Road", "r1", edges=(LocationEdge("goal", 2000),)), + Location("goal", "Goal", "r1"), + ] + ) + return world + + class _EndTurnBrain(Brain): """Brain that immediately ends its turn (for single-round tests).""" @@ -77,7 +90,7 @@ def on_turn( class TestRoundTimeAdvancement: def test_time_advances_by_one_round_per_round(self) -> None: """After all creatures act, world time advances by 6 seconds.""" - npc = Creature(id="npc1", name="Guard", location_id="r1", brain=_EndTurnBrain()) + npc = Creature(id="npc1", name="Guard", location_id="r1", is_anchor=True, brain=_EndTurnBrain()) world = _make_world([npc]) entities_layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) @@ -90,7 +103,7 @@ def test_time_advances_by_one_round_per_round(self) -> None: def test_multiple_creatures_still_one_round(self) -> None: """Multiple creatures acting in one round = still only 6 seconds.""" - c1 = Creature(id="c1", name="A", location_id="r1", brain=_EndTurnBrain()) + c1 = Creature(id="c1", name="A", location_id="r1", is_anchor=True, brain=_EndTurnBrain()) c2 = Creature(id="c2", name="B", location_id="r1", brain=_EndTurnBrain()) world = _make_world([c1, c2]) entities_layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) @@ -124,7 +137,7 @@ def test_wait_sets_wake_at_and_fast_forwards(self) -> None: elapsed = world.time.to_total_seconds() - initial_seconds assert elapsed == 3600 + 6 assert player.active is True - assert player.wake_at_seconds is None + assert player.current_intent is None def test_wait_custom_hours(self) -> None: """Wait 3 hours: fast-forward advances 3 hours.""" @@ -254,8 +267,8 @@ def test_dead_player_ends_loop(self) -> None: assert player.active is False assert npc.active is False - def test_no_player_no_change(self) -> None: - """Without a PlayerCharacter, activation is unchanged (tests still work).""" + def test_no_anchor_dormifies_noncombat_creature(self) -> None: + """Without an anchor, an ordinary peaceful creature does not keep the loop alive.""" npc = Creature(id="npc", name="Guard", location_id="r1", active=True, brain=_EndTurnBrain()) world = _make_world([npc]) entities_layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) @@ -263,7 +276,7 @@ def test_no_player_no_change(self) -> None: game_round = Round(world, entities_layer) game_round.run_round() - assert npc.active is True + assert npc.active is False class TestRoundStopFlag: @@ -317,7 +330,7 @@ def test_wait_makes_player_dormant(self) -> None: # Player went dormant, wake_at is set assert player.active is False # wake_at was set before the 6s advance - assert player.wake_at_seconds is not None + assert player.current_intent is not None def test_fast_forward_advances_to_wake_at(self) -> None: """Fast-forward skips time to nearest wake_at when no active creatures.""" @@ -338,7 +351,7 @@ def test_fast_forward_advances_to_wake_at(self) -> None: elapsed = world.time.to_total_seconds() - initial assert elapsed == 2 * 3600 + 6 assert player.active is True - assert player.wake_at_seconds is None + assert player.current_intent is None def test_nearby_npc_dormifies_when_player_waits(self) -> None: """NPC near player goes dormant when player waits, reactivates on wake.""" @@ -364,12 +377,31 @@ def on_turn( el = next(la for la in world.layers if isinstance(la, EntitiesLayer)) game_round = Round(world, el) + initial = world.time.to_total_seconds() game_round.run_loop(max_rounds=2) # After fast-forward and wake, both should be active assert player.active is True assert npc.active is True assert call_count == 2 # called once for wait, once after waking + assert world.time.to_total_seconds() - initial == 3600 + 6 + + def test_fast_forward_stops_at_earliest_intent(self) -> None: + now = GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds() + early = Creature(id="early", name="Early", location_id="r1", is_anchor=True, brain=_EndTurnBrain()) + late = Creature(id="late", name="Late", location_id="r1", is_anchor=True, brain=_EndTurnBrain()) + early.current_intent = TimedIntent(IntentType.WAIT, now, now + 60) + late.current_intent = TimedIntent(IntentType.SLEEP, now, now + 120) + world = _make_world([early, late], hour=10) + el = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + + Round(world, el).run_loop(max_rounds=1) + + assert world.time.to_total_seconds() - now == 60 + 6 + assert early.current_intent is None + assert early.active is True + assert late.current_intent == TimedIntent(IntentType.SLEEP, now, now + 120) + assert late.active is False def test_no_wake_at_means_loop_exits(self) -> None: """Without any wake_at, run_loop exits when no active creatures.""" @@ -382,3 +414,69 @@ def test_no_wake_at_means_loop_exits(self) -> None: game_round.run_loop() # should exit immediately assert world.time.to_total_seconds() == initial # no time passed + + +class TestTravelAndFastForward: + def test_journey_reaches_each_node_only_at_its_boundary(self) -> None: + now = GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds() + traveler = Creature(id="traveler", name="Traveler", location_id="start", is_anchor=True) + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now + 720) + world = _travel_world([traveler]) + layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + + world.advance_time(TimeDelta(seconds=719)) + layer.update_activation(world.time, location_graph=world.location_graph) + assert traveler.location_id == "start" + + world.advance_time(TimeDelta(seconds=1)) + layer.update_activation(world.time, location_graph=world.location_graph) + assert traveler.location_id == "road" + assert traveler.current_intent == TravelIntent(now, "goal", ("goal",), now + 2160) + + world.advance_time(TimeDelta(seconds=1440)) + layer.update_activation(world.time, location_graph=world.location_graph) + assert traveler.location_id == "goal" + assert traveler.current_intent is None + assert traveler.active is True + + def test_two_travelers_share_intermediate_node_and_resume_after_save(self) -> None: + now = GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds() + first = Creature(id="first", name="First", location_id="start", is_anchor=True) + second = Creature(id="second", name="Second", location_id="start", is_anchor=True) + for traveler in (first, second): + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now + 720) + world = _travel_world([first, second]) + layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + + world.advance_time(TimeDelta(seconds=720)) + layer.update_activation(world.time, location_graph=world.location_graph) + assert first.location_id == second.location_id == "road" + + restored = EntitiesLayer() + restored.load_state(layer.get_state()) + world.advance_time(TimeDelta(seconds=1440)) + restored.update_activation(world.time, location_graph=world.location_graph) + restored_first = restored.get_entity("first") + restored_second = restored.get_entity("second") + assert isinstance(restored_first, Creature) + assert isinstance(restored_second, Creature) + assert restored_first.location_id == restored_second.location_id == "goal" + assert restored_first.current_intent is None + assert restored_second.current_intent is None + + def test_round_loop_fast_forwards_all_legs_then_returns_control(self) -> None: + traveler = PlayerCharacter( + id="traveler", + name="Traveler", + location_id="start", + brain=_make_player_brain(Action(name=ActionType.TRAVEL, params={"destination_id": "goal"})), + ) + world = _travel_world([traveler]) + layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + started_at = world.time.to_total_seconds() + + Round(world, layer).run_loop(max_rounds=2) + + assert traveler.location_id == "goal" + assert traveler.current_intent is None + assert world.time.to_total_seconds() - started_at == 2160 + 6 diff --git a/tests/unit/test_handlers_movement.py b/tests/unit/test_handlers_movement.py index 2adbd2cc..0fb897eb 100644 --- a/tests/unit/test_handlers_movement.py +++ b/tests/unit/test_handlers_movement.py @@ -10,10 +10,12 @@ from dnd_simulator.core.action import Action, ActionType from dnd_simulator.core.character import Creature from dnd_simulator.core.combat import BattleMap, CombatState, Position +from dnd_simulator.core.intent import TravelIntent +from dnd_simulator.core.location import Location, LocationEdge, LocationGraph from dnd_simulator.core.models import ActionResult, Event from dnd_simulator.core.turn_budget import TurnBudget from dnd_simulator.i18n import set_language -from dnd_simulator.rules.handlers.movement import handle_dash, handle_disengage, handle_move, handle_wait +from dnd_simulator.rules.handlers.movement import handle_dash, handle_disengage, handle_move, handle_travel, handle_wait from dnd_simulator.rules.validation import ActionContext @@ -265,7 +267,7 @@ def emit_fn(event: Event) -> ActionResult: class TestHandleWait: def test_sets_wake_at_and_dormant(self) -> None: - """Wait sets wake_at_seconds and marks creature dormant.""" + """Wait sets a timed intent and marks creature dormant.""" mover = _creature("mover") world = MagicMock() world.time.to_total_seconds.return_value = 10000 @@ -276,7 +278,8 @@ def test_sets_wake_at_and_dormant(self) -> None: result = handle_wait(mover, action, emit_fn, ctx, world) assert result.success - assert mover.wake_at_seconds == 10000 + 2 * 3600 + assert mover.current_intent is not None + assert mover.current_intent.wake_at_seconds == 10000 + 2 * 3600 assert mover.active is False def test_wait_default_one_hour(self) -> None: @@ -290,14 +293,14 @@ def test_wait_default_one_hour(self) -> None: handle_wait(mover, action, emit_fn, ctx, world) - assert mover.wake_at_seconds == 5000 + 3600 + assert mover.current_intent is not None + assert mover.current_intent.wake_at_seconds == 5000 + 3600 - def test_wait_travel(self) -> None: - """Wait with travel_to changes location and advances time.""" + def test_wait_ignores_removed_travel_parameter(self) -> None: mover = _creature("mover") mover.location_id = "town_square" world = MagicMock() - world.location_graph.travel_seconds.return_value = 600 + world.time.to_total_seconds.return_value = 100 ctx = _ctx(mover) action = Action(name=ActionType.WAIT, params={"travel_to": "tavern"}) emit_fn = MagicMock(return_value=ActionResult()) @@ -305,87 +308,53 @@ def test_wait_travel(self) -> None: result = handle_wait(mover, action, emit_fn, ctx, world) assert result.success - assert mover.location_id == "tavern" - world.advance_time.assert_called_once() + assert mover.location_id == "town_square" + assert mover.current_intent is not None + world.advance_time.assert_not_called() - def test_wait_travel_no_direct_route_by_name_succeeds(self) -> None: - """Travel by name finds target and succeeds when a route exists.""" - mover = _creature("mover") - mover.location_id = "town_square" - world = MagicMock() - # Direct route fails, name-match route succeeds - loc = MagicMock() - loc.name = "Tavern" - world.location_graph.travel_seconds.side_effect = [ValueError("no direct route"), 300] - world.location_graph.all_ids.return_value = ["tavern_id"] - world.location_graph.get.return_value = loc - ctx = _ctx(mover) - action = Action(name=ActionType.WAIT, params={"travel_to": "tavern"}) - emit_fn = MagicMock(return_value=ActionResult()) - - result = handle_wait(mover, action, emit_fn, ctx, world) - assert result.success - assert mover.location_id == "tavern_id" - world.advance_time.assert_called_once() - - def test_wait_travel_unreachable_returns_failure(self) -> None: - """Travel to an ID with no route returns success=False and location unchanged.""" +class TestHandleTravel: + def test_starts_multi_leg_journey_without_moving_or_advancing_time(self) -> None: mover = _creature("mover") - mover.location_id = "starting_town" + mover.location_id = "start" world = MagicMock() - world.location_graph.travel_seconds.side_effect = ValueError("no route") - world.location_graph.all_ids.return_value = [] - ctx = _ctx(mover) - action = Action(name=ActionType.WAIT, params={"travel_to": "nowhere_island"}) - emit_fn = MagicMock(return_value=ActionResult()) + world.time.to_total_seconds.return_value = 100 + world.location_graph = LocationGraph( + [ + Location("start", "Start", "r", edges=(LocationEdge("road", 1000),)), + Location("road", "Road", "r", edges=(LocationEdge("goal", 2000),)), + Location("goal", "Goal", "r"), + ] + ) + + result = handle_travel( + mover, + Action(name=ActionType.TRAVEL, params={"destination_id": "goal"}), + MagicMock(return_value=ActionResult()), + _ctx(mover), + world, + ) - result = handle_wait(mover, action, emit_fn, ctx, world) - - assert not result.success - assert result.error - assert mover.location_id == "starting_town" - - def test_wait_travel_misnamed_target_returns_failure(self) -> None: - """Travel by name when no location matches returns success=False and location unchanged.""" - mover = _creature("mover") - mover.location_id = "starting_town" - world = MagicMock() - # Direct route by ID fails (no such ID), name scan finds no match - world.location_graph.travel_seconds.side_effect = ValueError("no direct route") - loc_a = MagicMock() - loc_a.name = "Market Square" - loc_b = MagicMock() - loc_b.name = "The Docks" - world.location_graph.all_ids.return_value = ["market", "docks"] - world.location_graph.get.side_effect = lambda lid: {"market": loc_a, "docks": loc_b}[lid] - ctx = _ctx(mover) - action = Action(name=ActionType.WAIT, params={"travel_to": "Nonexistent Place"}) - emit_fn = MagicMock(return_value=ActionResult()) - - result = handle_wait(mover, action, emit_fn, ctx, world) - - assert not result.success - assert result.error - assert mover.location_id == "starting_town" + assert result.success + assert mover.location_id == "start" + assert mover.current_intent == TravelIntent(100, "goal", ("road", "goal"), 820) + assert mover.active is False + world.advance_time.assert_not_called() - def test_wait_travel_name_match_unreachable_returns_failure(self) -> None: - """Travel where name matches but route to that location is unreachable returns failure.""" + def test_invalid_destination_does_not_mutate_creature(self) -> None: mover = _creature("mover") - mover.location_id = "starting_town" + mover.location_id = "start" world = MagicMock() - # Both direct and name-based route raise ValueError - world.location_graph.travel_seconds.side_effect = ValueError("no route") - loc = MagicMock() - loc.name = "Dead End" - world.location_graph.all_ids.return_value = ["dead_end_id"] - world.location_graph.get.return_value = loc - ctx = _ctx(mover) - action = Action(name=ActionType.WAIT, params={"travel_to": "Dead End"}) - emit_fn = MagicMock(return_value=ActionResult()) + world.location_graph = LocationGraph([Location("start", "Start", "r")]) - result = handle_wait(mover, action, emit_fn, ctx, world) + result = handle_travel( + mover, + Action(name=ActionType.TRAVEL, params={"destination_id": "missing"}), + MagicMock(return_value=ActionResult()), + _ctx(mover), + world, + ) assert not result.success - assert result.error - assert mover.location_id == "starting_town" + assert mover.location_id == "start" + assert mover.current_intent is None diff --git a/tests/unit/test_initiative.py b/tests/unit/test_initiative.py index c9cf18b7..e9da8528 100644 --- a/tests/unit/test_initiative.py +++ b/tests/unit/test_initiative.py @@ -493,7 +493,15 @@ def choose_action( id="c1", name="A", location_id="r1", max_hp=20, current_hp=20, attacks=(_SWORD,), brain=LogBrain() ) c_combat2 = Character(id="c2", name="B", location_id="r1", max_hp=15, current_hp=15, brain=LogBrain()) - c_peaceful = Character(id="c3", name="C", location_id="r2", max_hp=10, current_hp=10, brain=LogBrain()) + c_peaceful = Character( + id="c3", + name="C", + location_id="r2", + max_hp=10, + current_hp=10, + is_anchor=True, + brain=LogBrain(), + ) layer = EntitiesLayer([c_combat1, c_combat2, c_peaceful]) world = World( diff --git a/tests/unit/test_interruption_lifecycle.py b/tests/unit/test_interruption_lifecycle.py new file mode 100644 index 00000000..081181bc --- /dev/null +++ b/tests/unit/test_interruption_lifecycle.py @@ -0,0 +1,372 @@ +"""Interruption lifecycle consistency across the real session boundary (Sprint 022 phase 4 task 2). + +Phase 4 task 1 built one idempotent interruption helper wired to damage, combat entry, and +scene arrival. This file pins that behaviour *through* save/load, repeated activation, and the +session world-mutation gate: a stale round or a repeated activation pass must not replay a +reached leg, restore a cleared intent, grant rest twice, or hand out two player turns, and a +snapshot taken while an interruption commits must be internally consistent. + +Groups A and C use a real ``GameService`` + on-disk ``JsonFileStore`` + ``sword_vale`` so the +actual ``save_game``/``load_game`` commands and the ``GameSession`` gate are exercised. Group B +drives ``Round.run_loop`` synchronously over a minimal travel world so the "exactly once" +invariants are deterministic and free of NPC noise. +""" + +from __future__ import annotations + +import threading +from pathlib import Path + +from dnd_simulator.core.action import END_TURN +from dnd_simulator.core.awareness import CombatAwareness, PeacefulAwareness, PerceivedEvent +from dnd_simulator.core.brain import PlayerBrain +from dnd_simulator.core.character import ( + Ability, + AbilityScores, + Attack, + Creature, + DamageComponent, + DamageType, +) +from dnd_simulator.core.intent import IntentInterruptReason, IntentType, TimedIntent, TravelIntent +from dnd_simulator.core.location import Location, LocationEdge, LocationGraph +from dnd_simulator.core.models import GameDateTime, TimeDelta +from dnd_simulator.core.player import PlayerCharacter +from dnd_simulator.core.resource import ResourcePool, RestType +from dnd_simulator.core.world import World +from dnd_simulator.layers.entities.intent_completion import interrupt_intent +from dnd_simulator.layers.entities.layer import EntitiesLayer +from dnd_simulator.layers.geography.layer import GeographyLayer +from dnd_simulator.layers.geography.models import Region, TerrainType +from dnd_simulator.layers.politics.layer import PoliticsLayer +from dnd_simulator.layers.settlements.layer import SettlementsLayer +from dnd_simulator.round import Round +from dnd_simulator.service import GameService +from dnd_simulator.storage.store import JsonFileStore + +_FIGHTER = { + "name": "Wanderer", + "race": "human", + "class": "fighter", + "ability_scores": {"str": 15, "dex": 10, "con": 14, "int": 8, "wis": 12, "cha": 8}, + "fighting_style": "defense", +} + +_CLAWS = Attack( + name="claws", + ability=Ability.STR, + damage=(DamageComponent("1d6", DamageType.SLASHING),), +) + + +def _service(tmp_path: Path) -> GameService: + return GameService(store=JsonFileStore(tmp_path / "saves")) + + +# --------------------------------------------------------------------------- +# Group A — real save_game/load_game commands around an interruption +# --------------------------------------------------------------------------- + + +class TestSaveLoadAroundInterruption: + """save_game/load_game restore one internally consistent pre- or post-interruption state.""" + + def test_journey_survives_save_load_then_stops_at_occupied_scene(self, tmp_path: Path) -> None: + svc = _service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + start, mid, dest = "silverport_city_docks", "silverport_city_tavern", "silverport_city_market" + player = svc.create_player(sid, {**_FIGHTER, "start_location": start}) + player.is_anchor = True + layer = svc._get_entities_layer(session) + layer.add_entity(Creature(id="scene_host", name="Host", location_id=mid, is_anchor=True)) + + now = session.world.time.to_total_seconds() + graph = session.world.location_graph + route = graph.shortest_route(start, dest) + assert route == (mid, dest) # two legs, tavern is the intermediate node + first_leg = graph.travel_seconds(start, mid) + player.current_intent = TravelIntent(now, dest, route, now + first_leg) + + svc.save_game(sid, "mid_journey") + + # Diverge in the live session, then load the mid-journey snapshot back. + session.world.advance_time(TimeDelta(seconds=first_leg)) + layer.update_activation( + session.world.time, + query_fn=session.world.make_query_fn("entities"), + location_graph=graph, + ) + assert svc.get_session(sid).get_player().location_id == mid # diverged + + svc.load_game(sid, "mid_journey") + restored = svc.get_session(sid).get_player() + assert restored is not None + assert restored.location_id == start + assert restored.current_intent == TravelIntent(now, dest, route, now + first_leg) + + # Reach the occupied intermediate scene: the traveler stops there, intent cleared. + session.world.advance_time(TimeDelta(seconds=first_leg)) + for _ in range(3): # repeated activation must not replay the reached leg + layer.update_activation( + session.world.time, + query_fn=session.world.make_query_fn("entities"), + location_graph=graph, + ) + restored = svc.get_session(sid).get_player() + assert restored.location_id == mid + assert restored.current_intent is None + assert restored.active is True + + def test_save_after_sleep_interrupted_by_damage_grants_no_rest(self, tmp_path: Path) -> None: + svc = _service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + player = svc.create_player(sid, {**_FIGHTER, "start_location": "silverport_greenwood_road"}) + player.is_anchor = True + pool = ResourcePool("second_wind", 1, 0, RestType.SHORT_REST) + player.resource_pools = [pool] + player.current_hp = 5 + + now = session.world.time.to_total_seconds() + player.current_intent = TimedIntent(IntentType.SLEEP, now, now + 8 * 3600, rest_type=RestType.LONG_REST) + + # Damage wakes the sleeper before the timer; interruption grants no rest. + assert interrupt_intent(player, IntentInterruptReason.DAMAGE) is True + assert interrupt_intent(player, IntentInterruptReason.DAMAGE) is False # idempotent no-op + + svc.save_game(sid, "post_damage") + # Diverge, then load the post-interruption snapshot. + player.current_hp = 20 + svc.load_game(sid, "post_damage") + + restored = svc.get_session(sid).get_player() + assert restored is not None + assert restored.current_intent is None # cleared intent stays cleared + assert restored.current_hp == 5 # no long-rest heal applied + assert restored.resource_pools[0].current_uses == 0 # no pool reset + + def test_save_after_combat_interruption_preserves_combat_and_cleared_intent(self, tmp_path: Path) -> None: + svc = _service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + loc = "silverport_greenwood_road" + player = svc.create_player(sid, {**_FIGHTER, "start_location": loc}) + player.is_anchor = True + layer = svc._get_entities_layer(session) + enemy = Creature( + id="ambusher", + name="Ambusher", + location_id=loc, + max_hp=11, + current_hp=11, + ac=13, + speed=30, + ability_scores=AbilityScores(), + attacks=(_CLAWS,), + faction_id="wild_beasts", + ) + layer.add_entity(enemy) + + now = session.world.time.to_total_seconds() + player.current_intent = TimedIntent(IntentType.WAIT, now, now + 3600) + player.active = True + enemy.active = True + + combat = layer._combat.start_combat(loc) + assert combat is not None + assert player.in_combat is True + assert player.current_intent is None + + svc.save_game(sid, "post_combat") + # Diverge, then load the post-interruption snapshot. + player.in_combat = False + layer._combat._combats.clear() + svc.load_game(sid, "post_combat") + + restored_layer = svc._get_entities_layer(session) + restored = svc.get_session(sid).get_player() + assert restored is not None + assert restored.current_intent is None + assert restored.in_combat is True + assert restored.location_id == loc + assert restored_layer.get_combat(loc) is not None + + +# --------------------------------------------------------------------------- +# Group B — deterministic round loop: resume advances each leg exactly once +# --------------------------------------------------------------------------- + + +def _travel_world(entities: list[Creature]) -> World: + region = Region( + id="r1", + name="Test Field", + terrain=TerrainType.PLAINS, + latitude=45.0, + longitude=0.0, + elevation=100, + water_proximity=0.0, + connections=[], + ) + geography = GeographyLayer(regions=[region]) + settlements = SettlementsLayer(settlements=[], region_terrains={"r1": TerrainType.PLAINS}) + politics = PoliticsLayer( + nations=[], + region_terrains={"r1": TerrainType.PLAINS}, + region_adjacency={}, + region_income_fn=settlements.get_region_income, + ) + return World( + layers=[geography, politics, settlements, EntitiesLayer(entities=list(entities))], + time=GameDateTime(year=1, month=1, day=1, hour=10), + location_graph=LocationGraph( + [ + Location("start", "Start", "r1", edges=(LocationEdge("road", 1000),)), + Location("road", "Road", "r1", edges=(LocationEdge("goal", 2000),)), + Location("goal", "Goal", "r1"), + ] + ), + ) + + +class _CountingPlayerBrain(PlayerBrain): + """PlayerBrain that ends every turn immediately and counts how many turns it is offered.""" + + def __init__(self) -> None: + super().__init__() + self.turns = 0 + + def on_turn( + creature: Creature, + awareness: PeacefulAwareness | CombatAwareness, + events: list[PerceivedEvent], + ) -> None: + self.turns += 1 + self.submit_action(END_TURN) + + self.set_on_turn(on_turn) + + +class TestReconnectResumesJourneyOnce: + def test_resumed_round_advances_each_leg_once_and_a_second_run_is_a_noop(self) -> None: + brain = _CountingPlayerBrain() + traveler = PlayerCharacter(id="traveler", name="Traveler", location_id="start", brain=brain) + traveler.current_intent = TravelIntent( + GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds(), + "goal", + ("road", "goal"), + GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds() + 720, + ) + world = _travel_world([traveler]) + layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + + # A disconnect stops the round mid-journey; a reconnect starts a fresh round that + # must fast-forward through the remaining legs exactly once and return control. + Round(world, layer).run_loop(max_rounds=3) + assert traveler.location_id == "goal" + assert traveler.current_intent is None + turns_after_arrival = brain.turns + assert turns_after_arrival >= 1 + time_at_arrival = world.time.to_total_seconds() + + # A stale round re-entering must not replay a leg or teleport the traveler. + Round(world, layer).run_loop(max_rounds=1) + assert traveler.location_id == "goal" + assert traveler.current_intent is None + # Exactly one extra playable turn per extra round; no duplicated arrival turn. + assert brain.turns == turns_after_arrival + 1 + assert world.time.to_total_seconds() == time_at_arrival + 6 + + def test_repeated_activation_after_scene_interruption_does_not_replay(self) -> None: + now = GameDateTime(year=1, month=1, day=1, hour=10).to_total_seconds() + traveler = Creature(id="traveler", name="Traveler", location_id="start", is_anchor=True) + traveler.current_intent = TravelIntent(now, "goal", ("road", "goal"), now) + scene_host = Creature(id="host", name="Host", location_id="road", is_anchor=True) + world = _travel_world([traveler, scene_host]) + layer = next(la for la in world.layers if isinstance(la, EntitiesLayer)) + + for _ in range(4): + layer.update_activation(world.time, location_graph=world.location_graph) + + assert traveler.location_id == "road" # stopped at the occupied intermediate node + assert traveler.current_intent is None + assert traveler.active is True + + +# --------------------------------------------------------------------------- +# Group C — snapshot and interruption stay atomic under the session gate +# --------------------------------------------------------------------------- + + +class TestConcurrentSnapshotAndInterruption: + def test_snapshot_never_sees_torn_interruption_state(self, tmp_path: Path) -> None: + svc = _service(tmp_path) + session = svc.start_game("sword_vale") + sid = session.session_id + loc = "silverport_greenwood_road" + player = svc.create_player(sid, {**_FIGHTER, "start_location": loc}) + player.is_anchor = True + layer = svc._get_entities_layer(session) + enemy = Creature( + id="ambusher", + name="Ambusher", + location_id=loc, + max_hp=11, + current_hp=11, + ac=13, + speed=30, + ability_scores=AbilityScores(), + attacks=(_CLAWS,), + faction_id="wild_beasts", + ) + layer.add_entity(enemy) + now = session.world.time.to_total_seconds() + player.current_intent = TimedIntent(IntentType.WAIT, now, now + 3600) + player.active = True + enemy.active = True + + errors: list[str] = [] + wait_intent = TimedIntent(IntentType.WAIT, now, now + 3600) + start_barrier = threading.Barrier(2) + stop = threading.Event() + + def interrupt() -> None: + start_barrier.wait() + # Production drives combat entry through Round._execute_action under this exact + # gate. Toggle enter/exit combat repeatedly so a snapshot racing without the gate + # has many windows to observe a half-applied interruption. + while not stop.is_set(): + with session.mutate_world(): + layer._combat.start_combat(loc) + with session.mutate_world(): + layer._combat._combats.clear() + player.in_combat = False + player.current_intent = wait_intent + player.active = True + enemy.active = True + + def snapshot() -> None: + start_barrier.wait() + for _ in range(400): + save = session.build_save_game() + ent = save.world.layers.entities + psave = ent.entities[player.id] + has_combat = loc in ent.combats + pre = psave.current_intent is not None and not psave.in_combat and not has_combat + post = psave.current_intent is None and psave.in_combat and has_combat + if not (pre or post): + errors.append( + f"torn: intent={psave.current_intent is not None} " + f"in_combat={psave.in_combat} has_combat={has_combat}" + ) + break + stop.set() + + threads = [threading.Thread(target=interrupt), threading.Thread(target=snapshot)] + for t in threads: + t.start() + for t in threads: + t.join() + + assert errors == [] diff --git a/tests/unit/test_location_graph.py b/tests/unit/test_location_graph.py new file mode 100644 index 00000000..21acc77d --- /dev/null +++ b/tests/unit/test_location_graph.py @@ -0,0 +1,35 @@ +"""Product-level navigation behavior over the world location graph.""" + +import pytest + +from dnd_simulator.core.location import Location, LocationEdge, LocationGraph + + +def _graph() -> LocationGraph: + return LocationGraph( + [ + Location( + id="start", + name="Start", + region_id="r", + edges=(LocationEdge("long", 5), LocationEdge("alpha", 2), LocationEdge("beta", 2)), + ), + Location(id="long", name="Long Road", region_id="r", edges=(LocationEdge("goal", 5),)), + Location(id="alpha", name="Alpha Road", region_id="r", edges=(LocationEdge("goal", 3),)), + Location(id="beta", name="Beta Road", region_id="r", edges=(LocationEdge("goal", 3),)), + Location(id="goal", name="Goal", region_id="r"), + Location(id="island", name="Island", region_id="r"), + ] + ) + + +def test_shortest_route_uses_total_distance_and_stable_tie_breaking() -> None: + graph = _graph() + + assert graph.shortest_route("start", "goal") == ("alpha", "goal") + + +@pytest.mark.parametrize(("start", "destination"), [("missing", "goal"), ("start", "missing"), ("start", "island")]) +def test_shortest_route_rejects_unknown_or_unreachable_destinations(start: str, destination: str) -> None: + with pytest.raises(ValueError): + _graph().shortest_route(start, destination) diff --git a/tests/unit/test_rest.py b/tests/unit/test_rest.py index 658d7344..a7119459 100644 --- a/tests/unit/test_rest.py +++ b/tests/unit/test_rest.py @@ -27,8 +27,8 @@ def _creature( class TestLongRestHandler: - def test_long_rest_resets_all_resource_pools(self) -> None: - """Long rest resets both SHORT_REST and LONG_REST pools.""" + def test_long_rest_defers_resource_reset_until_wake(self) -> None: + """Long rest records sleep without granting its rewards up front.""" from dnd_simulator.rules.handlers.rest import handle_long_rest short_pool = ResourcePool("second_wind", 1, 0, RestType.SHORT_REST) @@ -40,11 +40,11 @@ def test_long_rest_resets_all_resource_pools(self) -> None: result = handle_long_rest(creature, Action(name=ActionType.LONG_REST), lambda *a: None, ctx, world) assert result.success - assert short_pool.current_uses == 1 - assert long_pool.current_uses == 2 + assert short_pool.current_uses == 0 + assert long_pool.current_uses == 0 - def test_long_rest_heals_to_full(self) -> None: - """Long rest restores HP to max_hp.""" + def test_long_rest_defers_healing_until_wake(self) -> None: + """Long rest does not restore HP when sleep begins.""" from dnd_simulator.rules.handlers.rest import handle_long_rest creature = _creature(hp=5, max_hp=20) @@ -52,10 +52,10 @@ def test_long_rest_heals_to_full(self) -> None: world = _stub_world() handle_long_rest(creature, Action(name=ActionType.LONG_REST), lambda *a: None, ctx, world) - assert creature.current_hp == creature.max_hp + assert creature.current_hp == 5 def test_long_rest_advances_8_hours(self) -> None: - """Long rest sets wake_at_seconds 8 hours ahead and marks dormant.""" + """Long rest sets a sleep intent 8 hours ahead and marks dormant.""" from dnd_simulator.rules.handlers.rest import handle_long_rest creature = _creature() @@ -63,13 +63,14 @@ def test_long_rest_advances_8_hours(self) -> None: world = _stub_world(time_seconds=10000) handle_long_rest(creature, Action(name=ActionType.LONG_REST), lambda *a: None, ctx, world) - assert creature.wake_at_seconds == 10000 + 8 * 3600 + assert creature.current_intent is not None + assert creature.current_intent.wake_at_seconds == 10000 + 8 * 3600 assert creature.active is False class TestShortRestHandler: - def test_short_rest_resets_only_short_rest_pools(self) -> None: - """Short rest resets SHORT_REST pools, leaves LONG_REST pools untouched.""" + def test_short_rest_defers_resource_reset_until_wake(self) -> None: + """Short rest records sleep without granting its rewards up front.""" from dnd_simulator.rules.handlers.rest import handle_short_rest short_pool = ResourcePool("second_wind", 1, 0, RestType.SHORT_REST) @@ -81,7 +82,7 @@ def test_short_rest_resets_only_short_rest_pools(self) -> None: result = handle_short_rest(creature, Action(name=ActionType.SHORT_REST), lambda *a: None, ctx, world) assert result.success - assert short_pool.current_uses == 1 + assert short_pool.current_uses == 0 assert long_pool.current_uses == 0 # NOT reset def test_short_rest_does_not_heal(self) -> None: @@ -96,7 +97,7 @@ def test_short_rest_does_not_heal(self) -> None: assert creature.current_hp == 5 def test_short_rest_advances_1_hour(self) -> None: - """Short rest sets wake_at_seconds 1 hour ahead and marks dormant.""" + """Short rest sets a sleep intent 1 hour ahead and marks dormant.""" from dnd_simulator.rules.handlers.rest import handle_short_rest creature = _creature() @@ -104,7 +105,8 @@ def test_short_rest_advances_1_hour(self) -> None: world = _stub_world(time_seconds=10000) handle_short_rest(creature, Action(name=ActionType.SHORT_REST), lambda *a: None, ctx, world) - assert creature.wake_at_seconds == 10000 + 3600 + assert creature.current_intent is not None + assert creature.current_intent.wake_at_seconds == 10000 + 3600 assert creature.active is False diff --git a/tests/unit/test_round_private_access.py b/tests/unit/test_round_private_access.py index a3577f34..5aa4ffaf 100644 --- a/tests/unit/test_round_private_access.py +++ b/tests/unit/test_round_private_access.py @@ -3,6 +3,7 @@ from __future__ import annotations from dnd_simulator.core.character import Creature +from dnd_simulator.core.intent import IntentType, TimedIntent from dnd_simulator.core.items import Item, ItemType from dnd_simulator.layers.entities.layer import EntitiesLayer from dnd_simulator.layers.entities.models import Npc, NpcRole @@ -35,7 +36,8 @@ def _make_creature(cid: str, *, wake_at: int | None = None) -> Creature: speed=30, attacks=[], ) - c.wake_at_seconds = wake_at + if wake_at is not None: + c.current_intent = TimedIntent(IntentType.WAIT, started_at_seconds=0, wake_at_seconds=wake_at) return c diff --git a/tests/unit/test_session_awareness.py b/tests/unit/test_session_awareness.py index e3750628..c528f1ec 100644 --- a/tests/unit/test_session_awareness.py +++ b/tests/unit/test_session_awareness.py @@ -6,6 +6,9 @@ from dnd_simulator.core.awareness import CombatAwareness, PeacefulAwareness, ResourcePoolInfo from dnd_simulator.core.character import Ability, AbilityScores, Attack, Character, DamageComponent, DamageType from dnd_simulator.core.class_features import RogueFeatures +from dnd_simulator.core.intent import TravelIntent +from dnd_simulator.core.location import Location, LocationGraph +from dnd_simulator.core.player import PlayerCharacter from dnd_simulator.service.session import _awareness_to_dict, build_player_status _SWORD = Attack( @@ -189,3 +192,35 @@ def test_player_status_empty_pools_when_no_resources(self) -> None: ) result = build_player_status(player) assert result.resource_pools == [] + + +class TestPlayerJourneyStatus: + def test_mid_journey_resolves_route_names_and_arrival(self) -> None: + player = PlayerCharacter(id="p1", name="Hero", location_id="road", ability_scores=_scores()) + player.current_intent = TravelIntent(100, "keep", ("bridge", "keep"), 460) + graph = LocationGraph( + [ + Location("road", "Old Road", "r"), + Location("bridge", "Stone Bridge", "r"), + Location("keep", "Hill Keep", "r"), + ] + ) + + journey = build_player_status(player, graph).journey + + assert journey is not None + assert journey.destination_id == "keep" + assert journey.destination_name == "Hill Keep" + assert journey.current_location_name == "Old Road" + assert journey.next_location_name == "Stone Bridge" + assert journey.remaining_route == ("Stone Bridge", "Hill Keep") + assert journey.next_arrival_seconds == 460 + + def test_completed_journey_is_omitted(self) -> None: + player = PlayerCharacter(id="p1", name="Hero", location_id="keep", ability_scores=_scores()) + graph = LocationGraph([Location("keep", "Hill Keep", "r")]) + + status = build_player_status(player, graph) + + assert status.location_id == "keep" + assert status.journey is None diff --git a/tests/unit/test_session_lifecycle.py b/tests/unit/test_session_lifecycle.py index f978bfc4..47126b06 100644 --- a/tests/unit/test_session_lifecycle.py +++ b/tests/unit/test_session_lifecycle.py @@ -9,10 +9,13 @@ from __future__ import annotations +import threading +import time from typing import Any from unittest.mock import MagicMock import pytest +import structlog from dnd_simulator.core.action import Action, ActionType from dnd_simulator.core.brain import PlayerBrain @@ -21,7 +24,7 @@ from dnd_simulator.round import Round from dnd_simulator.rules.movement import calculate_away_direction, calculate_direction from dnd_simulator.service import GameService -from dnd_simulator.service.session import GameSession, resolve_abstract_move +from dnd_simulator.service.session import GameSession, RoundStopTimeoutError, resolve_abstract_move from dnd_simulator.storage.store import SaveStore # --------------------------------------------------------------------------- @@ -176,6 +179,65 @@ def test_remove_unregistered_listener_is_noop(self) -> None: assert fired == [] assert session._listeners == [registered] + def test_stale_remove_does_not_arm_evict_when_already_empty(self) -> None: + session = _session() + + session.remove_listener(RecordingListener()) + + assert session._evict_timer is None + + def test_reconnect_cannot_interleave_with_disconnect_stop(self) -> None: + session = _session() + old_listener = RecordingListener() + new_listener = RecordingListener() + session.add_listener(old_listener) + session._round = MagicMock(spec=Round) + + stop_entered = threading.Event() + allow_stop = threading.Event() + + def blocking_stop(*, discard_events: bool = False) -> None: + stop_entered.set() + assert allow_stop.wait(timeout=1) + session._round = None + + session._stop_round = blocking_stop # type: ignore[method-assign] + disconnect = threading.Thread(target=session.remove_listener, args=(old_listener,)) + reconnect = threading.Thread(target=session.add_listener, args=(new_listener,)) + + disconnect.start() + assert stop_entered.wait(timeout=1) + reconnect.start() + assert new_listener not in session._listeners + + allow_stop.set() + disconnect.join(timeout=1) + reconnect.join(timeout=1) + + assert not disconnect.is_alive() + assert not reconnect.is_alive() + assert session._listeners == [new_listener] + + def test_disconnect_timeout_is_logged_and_leaves_retryable_session(self) -> None: + session = _session() + session._evict_grace_seconds = 3600 + listener = RecordingListener() + session.add_listener(listener) + game_round = MagicMock(spec=Round) + session._round = game_round + session._stop_round = MagicMock(side_effect=RoundStopTimeoutError("blocked")) # type: ignore[method-assign] + + with structlog.testing.capture_logs() as logs: + session.remove_listener(listener) + + assert session._round is game_round + assert session._evict_timer is not None + assert [event["session_id"] for event in logs if event.get("event") == "disconnect_stop_failed"] == [ + session.session_id + ] + session.add_listener(RecordingListener()) + assert session._round is game_round + class TestSpectatorListener: """Read-only spectators (Sprint 020 phase 3): receive the broadcast, never drive lifecycle.""" @@ -345,6 +407,33 @@ def test_lingering_spectator_does_not_save_abandoned_session(self) -> None: assert fired == [session] + def test_stop_timeout_defers_evict_until_retry_succeeds(self) -> None: + session = _session() + session._evict_grace_seconds = 3600 + session._round = MagicMock(spec=Round) + fired: list[GameSession] = [] + session._on_empty = lambda s: fired.append(s) + session._stop_round = MagicMock(side_effect=RoundStopTimeoutError("blocked")) # type: ignore[method-assign] + + with structlog.testing.capture_logs() as logs: + session._run_evict_check() + + assert fired == [] + assert session._evict_timer is not None + assert [event["session_id"] for event in logs if event.get("event") == "evict_stop_failed"] == [ + session.session_id + ] + + session._evict_timer.cancel() + + def successful_stop(*, discard_events: bool = False) -> None: + session._round = None + + session._stop_round = successful_stop # type: ignore[method-assign] + session._run_evict_check() + + assert fired == [session] + # --------------------------------------------------------------------------- # Submit guards (no round running) @@ -536,3 +625,58 @@ def test_stop_when_idle_does_not_raise(self, session_with_player: Any) -> None: session, _player = session_with_player # No round started — stop_round must be a safe no-op. session.stop_round() + + def test_timeout_preserves_lifecycle_until_same_thread_stops(self, session_with_player: Any) -> None: + session, player = session_with_player + callback_entered = threading.Event() + release_callback = threading.Event() + listener = RecordingListener() + + def block_turn(_msg: dict[str, Any]) -> None: + callback_entered.set() + assert release_callback.wait(timeout=2) + + listener.on_turn = block_turn # type: ignore[method-assign] + session.add_listener(listener) + game_round = session.start_round(player) + brain = session._player_brain + thread = session._round_thread + assert brain is not None + assert thread is not None + session._round_stop_timeout_seconds = 0.01 + assert callback_entered.wait(timeout=2) + + started = time.monotonic() + with structlog.testing.capture_logs() as logs, pytest.raises(RoundStopTimeoutError): + session.stop_round() + + assert time.monotonic() - started < 0.5 + assert session._round is game_round + assert session._player_brain is brain + assert session._round_thread is thread + assert session.start_round(player) is game_round + assert session._round_thread is thread + assert [event["session_id"] for event in logs if event.get("event") == "stop_round_timeout"] == [ + session.session_id + ] + + release_callback.set() + session.stop_round() + assert session._round is None + assert session._player_brain is None + assert session._round_thread is None + assert not thread.is_alive() + + replacement = session.start_round(player) + assert replacement is not game_round + assert session._round_thread is not thread + + def test_parked_player_turn_stops_before_timeout(self, session_with_player: Any) -> None: + session, player = session_with_player + session._round_stop_timeout_seconds = 0.5 + session.start_round(player) + + started = time.monotonic() + session.stop_round() + + assert time.monotonic() - started < session._round_stop_timeout_seconds diff --git a/tests/unit/test_world_state_gate.py b/tests/unit/test_world_state_gate.py new file mode 100644 index 00000000..833e183e --- /dev/null +++ b/tests/unit/test_world_state_gate.py @@ -0,0 +1,185 @@ +from __future__ import annotations + +import threading +from contextlib import contextmanager +from pathlib import Path +from typing import Any +from unittest.mock import MagicMock + +from dnd_simulator.core.action import Action, ActionType +from dnd_simulator.core.character import Creature +from dnd_simulator.core.models import ActionResult, TimeDelta +from dnd_simulator.core.reactions import ReactionOption, ReactionTrigger, TriggerType +from dnd_simulator.core.turn_budget import TurnBudget +from dnd_simulator.round import Round +from dnd_simulator.rules.rule_brain import RuleBrain +from dnd_simulator.rules.validation import ActionContext +from dnd_simulator.service import GameService +from dnd_simulator.storage.store import JsonFileStore + +_FIGHTER_DATA = { + "name": "Thrain", + "race": "dwarf", + "class": "fighter", + "alignment": "lawful_good", + "ability_scores": {"str": 15, "dex": 10, "con": 14, "int": 8, "wis": 12, "cha": 8}, + "fighting_style": "defense", +} + + +def _service(tmp_path: Path) -> GameService: + return GameService(store=JsonFileStore(tmp_path / "saves")) + + +def test_save_waits_for_complete_world_mutation(tmp_path: Path) -> None: + service = _service(tmp_path) + session = service.start_game("sword_vale") + mutation_started = threading.Event() + release_mutation = threading.Event() + save_done = threading.Event() + saved: list[Any] = [] + + def mutate() -> None: + with session.mutate_world(): + session.world.advance_time(TimeDelta(seconds=6)) + mutation_started.set() + assert release_mutation.wait(timeout=2) + + def snapshot() -> None: + saved.append(service._build_save_game(session.session_id)) + save_done.set() + + mutation_thread = threading.Thread(target=mutate) + mutation_thread.start() + assert mutation_started.wait(timeout=2) + save_thread = threading.Thread(target=snapshot) + save_thread.start() + + assert not save_done.wait(timeout=0.05) + release_mutation.set() + mutation_thread.join(timeout=2) + save_thread.join(timeout=2) + + assert save_done.is_set() + assert saved[0].world.time == session.world.time.to_dict() + + +def test_snapshot_is_available_while_player_brain_waits(tmp_path: Path) -> None: + service = _service(tmp_path) + session = service.start_game("sword_vale") + service.create_player(session.session_id, _FIGHTER_DATA) + player = session.get_player() + assert player is not None + session.start_round(player) + + snapshot_acquired = threading.Event() + + def snapshot() -> None: + with session.read_world(): + snapshot_acquired.set() + + thread = threading.Thread(target=snapshot) + thread.start() + try: + assert snapshot_acquired.wait(timeout=2) + finally: + session.stop_round() + thread.join(timeout=2) + + +def test_action_and_nested_reaction_use_one_reentrant_gate() -> None: + lock = threading.RLock() + depth = 0 + observed_depths: list[int] = [] + + @contextmanager + def mutation_scope() -> Any: + nonlocal depth + with lock: + depth += 1 + try: + yield + finally: + depth -= 1 + + reactor = Creature(id="guard", name="Guard", location_id="arena") + reactor.brain = RuleBrain() + reactor.turn_budget = TurnBudget(actions=1, bonus_actions=0, movement_remaining=30, reaction=1) + host = MagicMock() + host.get_entity.return_value = reactor + host.get_combat.return_value = None + dispatcher = MagicMock() + game_round = Round(MagicMock(), host, dispatcher=dispatcher, mutation_scope=mutation_scope) + nested = False + + def dispatch(*args: object) -> ActionResult: + nonlocal nested + observed_depths.append(depth) + if not nested: + nested = True + game_round.check_reactions( + ReactionTrigger(trigger_type=TriggerType.LEAVING_REACH, source_creature_id="mover"), + [ReactionOption(action_type=ActionType.OPPORTUNITY_ATTACK, description="OA")], + [reactor], + ) + return ActionResult() + + dispatcher.dispatch.side_effect = dispatch + game_round._execute_action( + reactor, + Action(name=ActionType.DODGE), + ActionContext(is_combat=True), + lambda event: ActionResult(), + ) + + assert observed_depths == [1, 2] + + +def test_stop_round_and_concurrent_snapshot_finish_without_deadlock(tmp_path: Path) -> None: + service = _service(tmp_path) + session = service.start_game("sword_vale") + service.create_player(session.session_id, _FIGHTER_DATA) + player = session.get_player() + assert player is not None + session.start_round(player) + + snapshot_thread = threading.Thread(target=lambda: service._build_save_game(session.session_id)) + stop_thread = threading.Thread(target=session.stop_round) + snapshot_thread.start() + stop_thread.start() + snapshot_thread.join(timeout=2) + stop_thread.join(timeout=2) + + assert not snapshot_thread.is_alive() + assert not stop_thread.is_alive() + + +def test_slow_store_write_does_not_hold_world_gate() -> None: + store = MagicMock() + save_started = threading.Event() + release_save = threading.Event() + + def slow_save(*args: object, **kwargs: object) -> None: + save_started.set() + assert release_save.wait(timeout=2) + + store.save.side_effect = slow_save + service = GameService(store=store) + session = service.start_game("sword_vale") + save_thread = threading.Thread(target=service.autosave_session, args=(session.session_id,)) + save_thread.start() + assert save_started.wait(timeout=2) + + mutation_acquired = threading.Event() + + def mutate() -> None: + with session.mutate_world(): + mutation_acquired.set() + + mutation_thread = threading.Thread(target=mutate) + mutation_thread.start() + assert mutation_acquired.wait(timeout=2) + + release_save.set() + save_thread.join(timeout=2) + mutation_thread.join(timeout=2) diff --git a/tests/unit/test_ws.py b/tests/unit/test_ws.py index bf9633cb..60ab02b3 100644 --- a/tests/unit/test_ws.py +++ b/tests/unit/test_ws.py @@ -9,6 +9,10 @@ from dnd_simulator.adapters.api.app import app from dnd_simulator.adapters.api.deps import set_service +from dnd_simulator.core.character import Creature +from dnd_simulator.core.player import PlayerCharacter +from dnd_simulator.layers.entities.layer import EntitiesLayer +from dnd_simulator.rules.rule_brain import RuleBrain from dnd_simulator.service import GameService from dnd_simulator.storage.store import JsonFileStore @@ -66,6 +70,37 @@ def test_no_player(self, tmp_path: object) -> None: class TestWebSocketTurnCycle: + def test_wait_fast_forwards_past_nearby_rule_npc(self, tmp_path: object) -> None: + client, service = _make_client(tmp_path) + sid = _create_session_with_player(client) + session = service.get_session(sid) + entities = next(layer for layer in session.world.layers if isinstance(layer, EntitiesLayer)) + player = next(entity for entity in entities._entities.values() if isinstance(entity, PlayerCharacter)) + entities.add_entity( + Creature( + id="bystander", + name="Bystander", + location_id=player.location_id, + brain=RuleBrain(), + ) + ) + started_at = session.world.time.to_total_seconds() + + with client.websocket_connect(f"/api/ws/{sid}") as ws: + assert ws.receive_json()["type"] == "turn" + ws.send_json({"type": "action", "name": "wait", "params": {"hours": 1}}) + + messages = [] + for _ in range(6): + message = ws.receive_json() + messages.append(message) + if message["type"] == "turn": + break + + assert messages[-1]["type"] == "turn" + assert len(messages) <= 4 + assert session.world.time.to_total_seconds() >= started_at + 3600 + def test_receive_turn_send_end_turn(self, tmp_path: object) -> None: """Connect WS, receive turn awareness, send end_turn, receive round_result.""" client, _ = _make_client(tmp_path)