Overview
Tavern is a Tabletop RPG Companion app — the highest combination richness app in the Aloysius Productions ecosystem, drawing from 7 source apps. It provides branching campaign management, RPG dice mechanics, oracle divination, AI-powered NPC dialogue, and synthesized sound effects in a unified React interface.
The app synthesizes mechanics from Quest-Forge (branching narrative, scene mood/weather, achievements), Dice (d4–d100 mechanics, notation parser), SoundBoard (ADSR synthesis presets), FortuneTeller (8-ball, tarot, rune divination), Poker (card/deck patterns), Eliza (persona-based conversational AI), and pseudogen (adventure engine interpolation).
Zone: staging/ — under evaluation for apps/ graduation.
Features
- CampaignManager — NarrativeEngine-powered branching campaigns with scene environments, journal, achievements, and party management. Sample campaign “Shadows of Thornhold” ships with 20 nodes and 4 endings.
- DiceRoller — d4–d100 support, notation parser (
2d6+3), advantage/disadvantage, critical detection. - Oracle — 8-ball divination, tarot (21 Major Arcana), 12 runes, coin flip.
- NpcDialogue — 6 NPC personalities mapped to Eliza Engine personas with stateful conversations.
- SoundEffects — 8 event-to-preset audio mappings for immersive gameplay. Declarative mapping keeps core logic testable in Node.js.
Tech Stack
| Layer | Technology | Version |
|---|---|---|
| Language | TypeScript | ^5.6.0 |
| Framework | React | ^19.0.0 |
| Build | Vite | ^7.3.1 |
| Test | Vitest | ^4.0.18 |
| Runtime | Node.js | >=18.0.0 |
Internal Dependencies
| Package | Purpose |
|---|---|
@ap/narrative-engine | Branching campaign story graphs |
@ap/eliza-engine | NPC dialogue with persona-based conversation |
@ap/audio | Synthesized sound effect presets |
Architecture
src/
├── modules/
│ ├── campaign/ CampaignManager — narrative campaigns + scene state
│ ├── dice/ DiceRoller — RPG dice mechanics + notation parser
│ ├── npc/ NpcDialogue — persona-based NPC conversations
│ └── oracle/ Oracle — divination modes (8-ball, tarot, runes)
├── lib/
│ └── SoundEffects Event-triggered audio presets
├── types/ Shared type definitions
└── index.ts Barrel exports
Dev server: port 3160
Key Decisions
ADR-001: Stateless NarrativeEngine Wrapper
CampaignManager maintains its own currentNodeId state rather than relying on NarrativeEngine internal state. The engine is reconstructed per-operation from the graph. NarrativeEngine is stateless by design — the campaign layer owns session position, making serialization straightforward.
ADR-002: Personality-to-Persona Mapping
6 NPC personality archetypes map to 6 Eliza personas: friendly→supportive, hostile→challenger, mysterious→philosopher, merchant→assistant, sage→tutor, trickster→stu. Leverages all 16 Eliza personas while providing RPG-meaningful labels. Extensible.
ADR-003: Deterministic RNG Injection
All random functions (dice, oracle, NPC selection) accept an optional rng: () => number parameter defaulting to Math.random. Enables deterministic testing without mocks. Seeded RNG (seed * 16807) % 2147483647 used in test suite.
ADR-004: Sound Mapping over Direct Audio
SoundEffects module provides a declarative mapping from game events to @ap/audio preset names. No direct AudioContext usage in the core library. The React UI layer consumes mappings and calls SoundGenerator at render time, keeping core testable in Node.js.
ADR-005: GAS for Project Management
Adopted GAS (Gloriously Awesome System) for project management. .planning/ handles “what to build and how”; .management/ handles compliance and documentation. Both coexist without conflict.
Current Status
v0.1 — Logic layer complete. All service modules implemented and tested (31 tests passing, 70%+ coverage). All three dependency packages (@ap/narrative-engine, @ap/eliza-engine, @ap/audio) extracted and tested. React UI built with 4 tab views (Dice, Oracle, Campaign, NPCs) and dark fantasy CSS theme. IndexedDB persistence wired. No strategic blockers.
Focus for next cycle: additional campaign content, visual polish, responsive testing, persistence integration with UI components.
| Metric | Status |
|---|---|
| CI/CD | Not yet deployed |
| Dependencies | Current |
| Documentation | Current |
| Test Coverage | 70%+ |
Source Lineage
| Source App | Contribution |
|---|---|
| Quest-Forge | Scene mood/weather, achievements, branching narrative |
| Dice | RPG dice mechanics, roll notation parsing |
| SoundBoard | ADSR synthesis presets for sound effects |
| FortuneTeller | Divination modes (8-ball, tarot) |
| Poker | Card/Deck model patterns |
| Eliza | Persona-based conversational AI |
| pseudogen | Adventure engine interpolation |