TAS Neo

A text-based terminal adventure game inspired by the Fighting Fantasy gamebook series.

Running the Game

# Build a self-contained jar
mvn package -DskipTests

# Run with the default adventure
java -jar target/tas-neo-1.0-SNAPSHOT.jar

# Run a specific adventure (omit the .json extension)
java -jar target/tas-neo-1.0-SNAPSHOT.jar the-iron-road

Available adventures are in the adventures/ directory. The game reads from stdin and writes to stdout, so it requires an interactive terminal.

---

Documentation

Specifications

Document	Description
01 - Game Mechanics	Core rules: attributes, dice, luck tests, provisions
02 - Combat	Turn-based combat system
03 - Adventure Structure	Sections, choices, events, conditions, lifecycle hooks
04 - Terminal UI	Screen layout, input/output behaviour
05 - Scripting	Lua scripting system, lifecycle hook points, ScriptContext API
06 - Items	Item categories, inventory rules, item lifecycle hooks
07 - Party Members	Configurable companion entities: ships, companions, crews — fixed and dice-formula stats
08 - Adventure Authoring	Chapters, gates, briefs, and the adventure manifest
09 - Location Networks	Location graph, travel events, region-based navigation
10 - Session Logging	Session log format, event recording, replay
11 - Adventure Runner	Automated simulation: strategies, coverage, report format

Technical Design

Document	Description
01 - Architecture	Layer overview, package structure, key interfaces
02 - Domain Model	Player, Section, Event, Creature class designs
03 - Combat Engine	CombatEngine, LuckTest, SkillTest design
04 - Engine	Game loop, HookDispatcher, GameState
05 - Adventure Loader	JSON format, validation rules
06 - Testability	Test doubles, test strategy per layer
07 - Scripting Engine	LuaJ integration, HookDispatcher, ScriptContext, sandboxing
08 - Item Model	Item, Inventory, equip system, combat integration
09 - Party Member Model	PartyMember, StatDefinition, DiceFormula, defeat consequences
10 - Combat Systems	Pluggable CombatSystem interface, registry, PersonalCombatSystem, system composition
11 - Location Networks	Location graph, travel event types, region data model
12 - Session Logging	SessionLogger interface, log record types, replay strategy
13 - OO Design Guidelines	Refactoring decision framework: thresholds, patterns, TDD sequence

Adventure Analysis Tools

Tool	Purpose
AdventureReportGenerator	Structural summary: reachability, section types, chapter coverage
AdventureStateReport	State variable map: where each variable is set, read, checked, removed
AdventureItemReport	Item lifecycle: GAIN/LOSS/REQUIRED/FORBIDDEN per item
AdventureGateDigest	Gate contracts for all chapters in one view
AdventureSectionDigest	Compact per-chapter narrative digest
AdventureSectionInspector	Targeted queries: read sections, inbound refs, event/condition search, dead ends, state var focus, gate JSON
AdventureRunner	Batch simulation: N runs with configurable strategy, coverage report, unreached sections, never-selected choices
GamePlaybackRunner	Terminal UI verification: runs a planned section path through real TerminalOutput, writes captured output to file

Agent Workflow

Development pipeline

Spec → Design → Test → Code. See workflow/WORKFLOW.md for the full process.

Agent	Role	Definition
Spec	Writes and validates specs	workflow/agents/spec-agent.md
Design	Writes technical design	workflow/agents/design-agent.md
Test	Writes failing tests from design strategy tables	workflow/agents/test-agent.md
Code	Implements to make tests pass	workflow/agents/code-agent.md

Adventure authoring pipeline

See workflow/ADVENTURE-AUTHORING-PIPELINE.md for the full process.

Agent	Role	Definition
Adventure Architect	Designs chapter scaffold, manifest, gate contracts, and chapter briefs	workflow/agents/adventure-architect-agent.md
Adventure Reviewer	Reviews scaffold before authoring begins	workflow/agents/adventure-reviewer-agent.md
Adventure Author	Authors one chapter per invocation	workflow/agents/adventure-author-agent.md
Chapter Reviewer	Reviews each chapter immediately after authoring	workflow/agents/chapter-reviewer-agent.md
Consistency Check	Cross-chapter chain integrity after all chapters are approved	workflow/agents/consistency-check-agent.md

Tech Stack

• Java 21
• Maven
• JUnit 5 + AssertJ