Sidequest — onboarding prototype (slice v2)

A single-player, offline TUI idle-RPG prototype. You greet an NPC, receive a quest and an axe, then type one goal command — /craft 5 plank — and watch the hero resolve and execute the whole dependency tree on its own, narrating its reasoning as it goes (chop trees → haul logs → craft planks). This proves the "narrated autonomy" loop from DESIGN.md; see PROTOTYPE.md for the full slice spec.

Quick start

pnpm install
pnpm dev        # launch the playable TUI

Then play:

/talk mara          greet Mara — she offers the quest and hands you an axe
/craft 5 plank      set the goal; the hero auto-resolves it over real time
/say planks         deliver the 5 planks → 2 gold, the hearth is lit

Set SIDEQUEST_SEED=<int> to fix the RNG seed for a reproducible run.

Commands

| Command | Effect | |---|---| | /move <place> | Jump to town or forest (rejected while the hero is busy). | | /describe | List what's in the current location; flags NPCs calling for attention. | | /talk <npc> | Greet a nearby character (alias for /say hi). | | /say <text> | Speak — Mara's dialogue branches on keywords (hi, help, planks…). | | /craft <n> <item> | Goal command — resolve + auto-execute the dependency tree, narrated. | | /inv | Show your inventory. | | /plan | Show the current goal and progress. | | /stop | Abort the current goal immediately, keeping partial progress, no penalty. | | /help | List commands. |

Content is data, not code

The whole world is declared in content/*.json and interpreted by a generic engine — nothing about "planks" or "Mara" is hardcoded:

• items.json — items + display nouns.
• world.json — locations, entities (NPCs / stations / resources), starting state.
• productions.json — the dependency graph: each way to make an item (craft / gather) with its inputs, tool gates, and access gates.
• vendors.json — buy/sell tables (price per quantity). A vendor's sells entry is also a purchase node in the acquisition graph, so an item can be obtained by buying or making it.
• quests.json — quests as state machines (objective, grants, reward, world flags).
• dialogue.json — inspectable NPC conversation branches (keywords + guards + effects), so you can read how a quest's state changes from the data alone.
• tuning.json — the resolver's cost weights.

A host-side loader (src/content/) reads + validates the pack at startup (a typo like an undeclared item id fails loudly), then injects it into the engine. The cheapest-path resolver plans over the unified acquisition graph: e.g. a tree_log can be chopped (needs an axe) or bought; if there's no axe it buys logs, and if logs aren't for sale it will buy an axe then chop — all chosen by cost, from data. Edit a price in vendors.json and the game changes with no code change.

Architecture

Engine ⊥ view from day one — the same deterministic core ports to a future widget.

• src/protocol/ — the frozen data contract (domain types, ClientCommand, GameEvent). Pure data, no logic. Both the engine and the TUI import only from here.
• src/content/ — schema, validating loader, and derived lookups (Content) over the JSON pack. Host-side (the only code that does I/O).
• src/engine/ — headless, deterministic core. No DOM, no I/O, no Date.now() / Math.random(). Seeded mulberry32 RNG; all randomness flows through engine.rng.
  • rng.ts — the seedable RNG.
  • content.ts — locations, entities, recipes, durations, the quest, starting state (all tuning lives here).
  • engine.ts — new Engine({ seed }), .state, .snapshot(), .tick(dt) → GameEvent[], .apply(cmd) → GameEvent[].
  • dialogue.ts — Mara's Tibia-style keyword state machine + quest lifecycle.
  • resolver.ts — the narrated auto-cascade (the heart of the slice).
• src/tui/ — Ink (React-for-terminals) renderer. Owns the wall clock, calls engine.tick(dt) on a ~250ms interval, streams events into the action log, reads the input line, and dispatches commands via engine.apply — all in-process, no transport layer.

The action log is the engine's GameEvent stream; the view just replays it.

Tests

pnpm test        # vitest — engine, dialogue, resolver, and full e2e playthrough
pnpm typecheck   # tsc --noEmit

The engine is fully unit-tested headless and deterministic given a seed: the e2e suite drives apply + tick through the entire onboarding loop (greet → axe → craft → deliver → reward) as a regression guard, and asserts the "no axe" refusal and /stop partial-progress paths.