Playable AI Worgav App Spec

Date: 2026-06-01

Status: Draft 2

Primary goal: define a buildable web and mobile app that turns Worgav into a playable AI-assisted wargaming and role-playing game using the rulebook mechanics as the source of truth.

Primary sources:

• Project doc: docs/game-context.md
• Project doc: docs/transcripts/2026-05-25-jeff-talk-ideas.md
• Project doc: docs/transcripts/2026-06-01-jeff-meeting-ideas.md
• Website route: Worgav GM Handbook
• Project source: CODEX_sections.md
• Project source: WGV_dice/README.md

Executive Summary

The app is a playable Worgav campaign engine. Players control Guardian spirits bound to mortal hosts, operate through the Codex node lattice, form domains, command red shirts, create plans, scout encounters, and resolve conflict through NPDX mechanics. AI acts as the Game Master interface: it interprets freeform intent, proposes legal Codex actions, drafts plans, runs NPC dialogue, and narrates outcomes. The deterministic rules engine remains authoritative for dice, focus penalties, Battle Metric, skill checks, state changes, damage, morale, supply, and campaign persistence.

The first shippable version should be a responsive web app that behaves like a mobile app through PWA features. Native iOS/Android wrappers can come later after the game loop is proven.

Product Goals

1. Let a player create a Guardian, host, Champion, and starting domain.
2. Let a player type or speak natural-language intent and have the app map that intent to Codex actions.
3. Let the player review, edit, and confirm the mapped action before rules resolve it.
4. Use Worgav rulebook mechanics, especially NPDX, Battle Metric, Codex node focus, domain state, red shirts, plans, and scale.
5. Make planning playable: Specialists create plans, Leadership selects plans, Heroes execute plans, Scouts reveal information, Navigators position the group, and Guardians sustain the domain.
6. Support solo play with an AI Game Master first, then multiplayer and human GM modes.
7. Produce durable campaign logs that can be used for character growth, familiarity, debugging, replay, and future AI memory.

Non-Goals For The First Playable Version

• Full 3D graphics.
• Real-time action combat.
• Complete implementation of every rulebook table.
• Full planetary, fleet, or civilization-scale simulation.
• Native mobile apps before the responsive web/PWA loop works.
• AI-only story mode with no rule enforcement.
• Copying mechanics, tables, or protected text from other games.

Platforms

Version 1 Platform

Build as a responsive web app with PWA behavior:

• Desktop browser.
• Mobile browser.
• Installable mobile home-screen app.
• Touch-friendly controls.
• Local save fallback for single-player prototypes.

Later Platform Options

• Native wrapper through Capacitor or similar once the PWA is stable.
• Tablet-optimized GM screen.
• Offline campaign package export/import.
• Desktop app wrapper if local AI models or offline play become important.

Core Experience

The player should feel like they are commanding from two layers at once:

• Human layer: the host acts, speaks, fights, drives, hides, negotiates, suffers, and risks death.
• Guardian layer: the player sees domain structure, risk, plans, red shirts, symbols, supply, pressure, and probability.

The screen should therefore combine:

• A Game Master narrative feed.
• A command composer for freeform intent.
• A Codex/focus panel showing occupied nodes and penalties.
• A domain panel showing host, allies, red shirts, supplies, plans, and threats.
• A roll log showing mechanical truth behind narration.

Play Modes

Solo Guardian Mode

One player runs a Champion in a small starting domain. AI acts as Game Master, NPCs, opposing domains, and rules assistant.

This is the first target mode.

Party Mode

Two to seven players share one domain. Each player controls a Champion and takes Codex responsibilities. The AI or human GM coordinates scenes and validates actions.

Human Game Master Mode

A human GM controls scenario framing, NPC decisions, hidden information, and adjudication. AI assists with rule lookups, action mapping, roll execution, summaries, and NPC drafts.

Player-As-GM Simulation Mode

The player creates or selects competing domains, assigns goals, then watches AI agents run them under deterministic rules. This mode is useful for playtesting balance.

Hibernation Mode

When a player leaves, the domain persists. Conservative AI maintains assets, conceals holdings, responds defensively to attack, retreats when appropriate, and avoids aggressive expansion unless authorized.

MVP Scope

The first playable version should include:

• Campaign creation.
• Champion creation with Guardian, host, abilities, basic skills, faction, and starting domain.
• One starting domain with a host, small party, red shirts, supplies, and simple location.
• Text-based AI Game Master.
• Freeform command input.
• AI intent interpretation into Codex actions.
• Player confirmation before committing an action.
• Codex focus penalties from 1 to 7 active nodes.
• NPDX dice roller, starting with NPD10.
• Battle Metric calculation from ability and skill inputs.
• Plan creation and plan selection.
• Scout/recon encounter loop.
• Familiarity tracking for rolled actions, tools, people, places, units, and totems.
• One opposing domain or patrol.
• Turn log and campaign memory.
• Mobile responsive layout.

Core Game Loop

1. Scene Briefing: AI GM describes the current state from visible facts, known domain memory, and hidden GM state.
2. Player Intent: player types or speaks what they want to do.
3. Intent Parsing: AI extracts goals, targets, tone, risk, implied actions, and missing requirements.
4. Codex Mapping: AI proposes one or more Codex groups and node foci.
5. Rules Validation: deterministic engine checks whether actions are legal given domain state, focus limits, scale, resources, range, and permissions.
6. Player Review: UI shows proposed actions, focus penalty, expected checks, risks, and alternative options.
7. Commit: player confirms, edits, or cancels.
8. Resolution: engine rolls NPDX, applies Battle Metric, difficulty, focus penalty, and consequences.
9. Narration: AI GM narrates only the validated mechanical result.
10. State Update: campaign state, roll log, plans, domain resources, injuries, morale, and memory are updated.
11. Next Beat: GM presents new information, NPC reactions, or next decision point.

AI Responsibilities

AI should handle interpretation and expression, not final mechanical authority.

AI may:

• Interpret freeform player intent.
• Map intent to Codex groups and suggested actions.
• Ask clarifying questions when intent is impossible or dangerously ambiguous.
• Draft plans, treaties, glyph descriptions, orders, mission briefs, NPC dialogue, and scene narration.
• Summarize long campaign logs.
• Generate scenario content from approved rules and campaign context.
• Control NPCs and opposing domains through valid action proposals.

AI must not:

• Secretly alter dice results.
• Commit state changes without engine validation.
• Ignore focus penalties.
• Invent abilities, supplies, or domain assets that are not present.
• Resolve damage, morale, or death outside the rules engine.
• Treat narration as mechanical truth unless state has been updated.

Rule Engine Responsibilities

The rule engine is the source of truth for:

• NPDX rolls.
• Battle Metric.
• Focus penalties.
• Ability and skill checks.
• Difficulty and contested mode.
• Turn order and elapsed time.
• Domain ownership and supplies.
• Red shirt allocation and losses.
• Familiarity, object experience, and roll-ledger awards.
• Totem, belief, and momentum modifiers after those rules are finalized.
• Health, damage, shock, fatigue, morale, and recovery.
• Plan availability and prerequisites.
• Recon information levels.
• Valid action lists.
• Campaign state transitions.

The AI can propose; the engine disposes.

AI And Rules Pipeline

Every action should move through a structured pipeline:

1. IntentInput: raw text, speaker, scene id, domain id, active Champion id.
2. IntentInterpretation: extracted goals, targets, urgency, implied Codex groups, missing facts.
3. ActionProposal: concrete candidate actions with node costs, prerequisites, and risks.
4. ValidationResult: legal, illegal, needs choice, needs roll, or needs clarification.
5. ResolutionRequest: finalized action, roll parameters, involved actors, target state.
6. ResolutionResult: rolls, outcome symbols, state deltas, log entries.
7. NarrationRequest: validated result plus tone and visible facts.
8. NarrationOutput: player-facing story text, choices, and updated prompts.

The narration step must receive the mechanical result. It should not reroll or reinterpret success.

Codex Action Model

Each action should map to one or more Codex groups.

An action can occupy multiple groups. Example:

Player input: “Send two red shirts to check the ridge while we hide the truck and prepare a crossfire.”

Mapped actions:

• Scout: check the ridge.
• Guardian: hide/protect the truck.
• Specialist: prepare crossfire plan.
• Leadership: approve ambush posture.
• Hero: hold fire until trigger.

If this creates too many foci, the player must choose what to drop or delegate.

Focus Penalty

The app must visibly show the current focus modifier:

The focus UI should make overload obvious. Players should be able to:

• Assign foci manually.
• Let AI suggest foci from text.
• Delegate foci to other Champions or red shirts when allowed.
• Drop a focus before committing.
• See why an overloaded action is risky.

Character Creation

The first playable character creator should support a Worgav-original life-path flow:

1. Choose or roll faction origin.
2. Create Guardian identity.
3. Create host identity.
4. Roll or assign six abilities: Charisma, Dexterity, Endurance, Intelligence, Luck, Power.
5. Select or roll early life background.
6. Choose one or more training paths: military, worker, college, criminal, merchant, occult, frontier, officer, synthetic/cyborg, or other rulebook-supported profession.
7. Gain skills and flaws from life events.
8. Roll or choose one peculiarity.
9. Define host awareness: unaware, suspicious, bargaining, resistant, or awakened.
10. Create starting domain, supplies, red shirts, and first mission hook.

Bad outcomes should create playable history rather than dead ends. Prison, injury, debt, exile, family loss, or failed training can produce skills, enemies, obligations, scars, and story leverage.

The first implementation should not expose every possible path. Start with a small V1 set: military, merchant, traveler/frontier, and possibly scientist. Treat these as career or education paths rather than hard classes.

Domain Model

A domain is a controlled set of people, places, and things. It should be represented explicitly in app state.

Required domain properties:

• Name.
• Faction.
• Scale.
• Current location.
• Controlled assets.
• Active Champions.
• Host bodies and backup-body status.
• Red shirts and henchmen.
• Supplies.
• Familiar objects, tools, people, units, and places.
• Plans.
• Symbols, totems, flags, and glyphs.
• Known contacts.
• Known threats.
• Recon map.
• Morale.
• Hibernation policy.

Domains can be contested. Contesting a domain may involve combat, infiltration, treaty, invitation, betrayal, symbol corruption, supply disruption, morale warfare, or direct attack on key Champions.

Red Shirt Model

Red shirts are not full player characters, but they are not meaningless counters either.

Required red shirt properties:

• Count.
• Type or role.
• Training level.
• Equipment quality.
• Morale.
• Attachment to domain or Champion.
• Familiarity with the domain, leader, unit, or repeated task.
• Current task.
• Casualty status.

Red shirts should:

• Absorb risk before Champions in many scale-appropriate situations.
• Perform delegated actions.
• Carry supplies.
• Gather basic information.
• Die, flee, freeze, rally, or become named NPCs based on events.

The app should allow a red shirt to be promoted into a named NPC or future host candidate when story events justify it.

Plans And Orders

Plans are structured game objects, not just text.

Required plan properties:

• Title.
• Author.
• Codex origin group, usually Specialist.
• Required resources.
• Required positions or foci.
• Trigger condition.
• Steps.
• Risk profile.
• Expected benefits.
• Expiration or context limit.
• Approval status.
• Execution status.

Plan states:

• Draft.
• Proposed.
• Approved.
• Armed.
• Executing.
• Completed.
• Failed.
• Lost.
• Obsolete.

If a planner is killed, captured, loses communication, defects, or leaves the domain, plans tied to that planner may become unavailable, harder to execute, or downgraded to a generic fallback.

Recon And Encounter Model

The app should model information quality separately from truth.

Recon levels:

1. Unknown.
2. Presence sensed.
3. Direction known.
4. Location bracketed.
5. Identity suspected.
6. Intent inferred.
7. Actionable certainty.

Scout actions, sensor equipment, rumors, satellites, local contacts, spiritual perception, and enemy stealth should affect recon level. The AI GM can narrate uncertainty, but the state engine should store what is actually known by each domain.

Scale And Time

The first version should support only a few scales:

Larger scales can be represented in scenario summaries but should not be fully simulated in V1.

The app must store elapsed time because planning, travel, healing, supply, stealth, hibernation, and reinforcements depend on time.

Real And Imaginary Actions

The rulebook and transcript both require physical and spiritual/informational action.

The app should classify action effects:

• Real: physical movement, attack, repair, construction, transport, injury, supply use.
• Imaginary: fear, clue meaning, rumor, omen, morale, symbolic pressure, dream, charm, domain invitation, perceived risk.
• Mixed: flags, glyphs, totems, plans, rituals, speeches, deception, psychological warfare.

Imaginary actions should become concrete by modifying:

• Morale.
• Recon level.
• Focus cost.
• Difficulty.
• Plan availability.
• NPC choices.
• Domain permission.
• Risk of fumble.
• Hibernation behavior.

They should not bypass the rules engine.

Familiarity And Roll Ledger

Every meaningful roll should award familiarity to the thing used to take the action. That thing can be a weapon, tool, body part, vehicle, person, red-shirt unit, place, plan, symbol, glyph, or totem.

Required familiarity event fields:

• Actor.
• Action.
• Codex group or node.
• Real, imaginary, or mixed classification.
• Object/person/place/unit used.
• Target.
• Raw NPDX face sequence.
• Final snake score or roll value.
• Outcome symbol.
• Familiarity awarded.
• Domain and scale.
• Resulting state deltas.

Familiarity should be queryable in the UI. A player should be able to inspect why a sword, scout team, host hand, vehicle, or plan has become reliable or significant.

Totemic and magical effects should build on this ledger later. For V1, store the data even if the full familiarity bonus and momentum formulas are still draft rules.

NPDX Dice Requirements

V1 must implement NPD10. The engine should be designed for NPDX later.

Requirements:

• Face 1 is N.
• Face X is P.
• Faces 2 through X-1 are body results.
• N triggers decimal scaling.
• P triggers positive cascade.
• Body result stops chain.
• Rolls produce a snake score.
• Resolution produces an outcome symbol: M, H, h, -, or F.
• Every roll is stored with raw faces, snake score, final symbol, actor, action, difficulty, familiarity target, familiarity award, and state deltas.

The existing Python dice simulator and React dice console can inform implementation, but the game app should expose dice as a reusable rules package.

UI Specification

Mobile Layout

Mobile should use bottom navigation:

• Story: GM feed, player command composer, current choices.
• Codex: active foci, available actions, penalties, node groups.
• Domain: Champion, host, red shirts, supplies, plans, morale.
• Log: rolls, state changes, timeline, memories.

The command composer should remain reachable from the Story screen without hiding critical choices.

Desktop Layout

Desktop should use a three-panel layout:

• Left: domain and character state.
• Center: GM narrative and command composer.
• Right: Codex, actions, dice, and roll log.

Common UI Requirements

• Player can always inspect why an action is legal or illegal.
• Dice results are visible and auditable.
• AI-generated text is visually distinct from mechanical state.
• The app should never require reading a long rulebook page during play.
• The player should be able to play from typed commands alone.
• Touch targets must work on phones.
• Text should remain readable in long sessions.

Data Model Draft

Core entities:

• User
• Campaign
• Scene
• Domain
• Faction
• Guardian
• Host
• Champion
• RedShirt
• CodexGroup
• CodexFocus
• Ability
• Skill
• ObjectAsset
• FamiliarityRecord
• BeliefCommitment
• MomentumState
• Plan
• Order
• RuleOfEngagement
• Totem
• Glyph
• SupplyItem
• Transport
• Encounter
• ReconRecord
• ActionProposal
• ResolvedAction
• Roll
• StateDelta
• MemoryLog

Minimum V1 state should fit in a JSON document so solo campaigns can start local-first. Server persistence can later normalize the model into tables.

API And Service Draft

Initial services:

• rules.rollNPDX(input): returns raw roll, snake score, outcome symbol.
• rules.calculateBM(actor, skill, abilities): returns Battle Metric.
• rules.focusModifier(focusCount): returns node modifier.
• rules.calculateFamiliarityAward(roll, action, state): returns familiarity experience for the acted-through object/person/place/unit.
• rules.applyFamiliarity(event, state): returns updated familiarity records and related state deltas.
• rules.validateAction(action, state): returns legality and missing requirements.
• rules.resolveAction(action, state, roll): returns result and state delta.
• ai.interpretIntent(input, context): returns structured intent.
• ai.proposeActions(intent, state, codexCatalog): returns candidate actions.
• ai.narrateResult(result, visibleState): returns player-facing narration.
• memory.summarizeCampaignLog(log): returns compact memory.
• campaign.applyStateDelta(delta): persists state changes.

The AI services should use structured output and validation. Invalid AI output should be rejected and retried or converted into a clarification question.

Structured Action Example

{
  "intent": "Send two scouts ahead, keep the truck hidden, and prepare an ambush.",
  "actorChampionId": "champion_01",
  "proposedActions": [
    {
      "codexGroup": "Scout",
      "actionType": "recon",
      "target": "ridge road",
      "delegatedTo": "red_shirt_team_a",
      "requiresRoll": true
    },
    {
      "codexGroup": "Guardian",
      "actionType": "conceal_asset",
      "target": "truck",
      "requiresRoll": true
    },
    {
      "codexGroup": "Specialist",
      "actionType": "draft_plan",
      "target": "crossfire ambush",
      "requiresRoll": false
    },
    {
      "codexGroup": "Leadership",
      "actionType": "approve_plan",
      "target": "crossfire ambush",
      "requiresRoll": false
    }
  ]
}

Memory And Logs

Every meaningful event should produce two records:

• A player-readable campaign log entry.
• A structured mechanical event.

The campaign log gives continuity to the AI GM. The structured event gives auditability to the rules engine.

Memory tiers:

• Immediate scene memory: current scene, active threats, recent turns.
• Campaign summary: compact running summary for AI context.
• Mechanical ledger: full rolls and state changes.
• Lore notes: durable discoveries, factions, relationships, host/Guardian changes.

Multiplayer Requirements

Multiplayer can come after solo V1 but should influence the architecture now.

Requirements:

• Multiple Champions in one domain.
• Turn ownership and ready states.
• Shared GM narrative.
• Per-player private notes later.
• Human GM override later.
• Domain hibernation when players are absent.
• Conflict resolution when players issue incompatible commands.

For V1, design data structures with ownerUserId and visibility fields even if only one user exists.

Safety And Integrity Requirements

• AI cannot directly mutate campaign state.
• Rule outputs must be deterministic given state, action, and roll.
• All state changes must be logged.
• Hidden GM state must not leak into player prompts.
• User-provided text should be treated as untrusted input.
• Prompt injection in player/NPC text must not override system rules.
• The game should distinguish fictional conspiracy/horror content from real-world claims in generated text when necessary.
• Copyrighted third-party game mechanics or tables should not be copied into Worgav content.

Testing Requirements

Unit tests:

• NPDX roll mechanics.
• Familiarity ledger creation from rolls.
• Battle Metric calculation.
• Focus penalty table.
• Action validation.
• Plan state transitions.
• Recon level changes.
• Red shirt casualty allocation.
• Domain ownership changes.

Simulation tests:

• Run repeated encounters to identify broken probabilities.
• Compare overloaded focus actions against focused actions.
• Test prepared plan vs generic fallback.
• Test scout advantage before encounter.

End-to-end tests:

• Create campaign.
• Create Champion.
• Issue freeform command.
• Map to Codex actions.
• Confirm action.
• Resolve roll.
• Update state.
• Show narration and log.

Browser tests:

• Desktop layout.
• Mobile layout.
• Long text wrapping.
• Touch targets.
• Offline/local save behavior if implemented.

Milestones

Milestone 0: Rules And Content Inventory

• Catalog Codex actions.
• Extract ability and skill references.
• Decide V1 scale table.
• Define JSON schema for campaign state.
• Port or wrap NPDX dice logic.

Milestone 1: Local Rule Engine

• Implement NPD10.
• Implement Battle Metric.
• Implement focus penalties.
• Implement action validation and state deltas.
• Add tests.

Milestone 2: Character And Domain Creation

• Build Guardian/host/Champion creator.
• Build starting domain creator.
• Add red shirts, supplies, first mission hook.
• Add familiar objects, people, and units to the campaign ledger.
• Persist campaign locally.

Milestone 3: Codex Command Interface

• Build Codex panel.
• Build freeform command composer.
• Map simple typed intents to Codex proposals.
• Let player confirm or edit proposals.

Milestone 4: AI Game Master Loop

• Add AI intent interpretation.
• Add AI narration constrained by rule outputs.
• Add campaign memory summaries.
• Add hidden and visible scene state.

Milestone 5: First Playable Encounter

• Add scout/recon loop.
• Add one opposing patrol/domain.
• Add plans, ambush, retreat, attack, concealment, and morale.
• Complete one playable mission from start to result.

Milestone 6: PWA And Mobile Polish

• Add responsive mobile navigation.
• Add installable PWA shell.
• Add autosave and recovery.
• Run mobile browser verification.

Milestone 7: Multiplayer Foundation

• Add user ownership fields.
• Add shared campaign sessions.
• Add ready/commit flow.
• Add basic human GM controls.

V1 Acceptance Criteria

The app is playable when:

• A new player can create a Champion and starting domain without reading external docs.
• The player can type a freeform command and see the proposed Codex mapping.
• The player can see focus penalties before committing.
• The app resolves at least one meaningful NPD10 action.
• The app records familiarity for the object, person, place, unit, or totem used in that action.
• The app updates domain state after resolution.
• The AI narrates the result without contradicting the roll log.
• The player can create or use at least one plan.
• The player can scout and encounter an opposing force.
• Red shirts can be assigned, risked, and lost.
• The campaign can be saved and resumed.
• The interface works on desktop and phone.

Recommended Repo Direction

The existing repo has:

• website/: Astro handbook site.
• WGV_gm_dice_console/: React/Vite dice console.
• WGV_dice/: Python NPD10 simulator.

Recommended app path:

1. Keep website/ as the public handbook/reference site.
2. Create a new game app package, for example apps/game or worgav-game, rather than overloading the static handbook.
3. Extract reusable rules into a dedicated package, for example packages/rules.
4. Port the NPDX dice logic into the rules package with tests.
5. Reuse lessons from WGV_gm_dice_console, but treat it as a prototype rather than the final app.

If keeping repo structure flat is preferred, a new game/ folder is acceptable.

Key Product Risks

• The AI could make the game feel arbitrary unless mechanical authority is strict.
• The metaphysics can overwhelm the first-time player unless V1 starts at party scale.
• Character creation can become too large before the core loop is proven.
• Scale mechanics can delay play if the app tries to simulate armies too early.
• Hidden information and AI memory can leak if visibility is not modeled.
• Host replacement can make death meaningless unless cost and continuity loss are enforced.

Open Decisions

• Final app framework: Vite/React, Next.js, or another stack.
• Server persistence from day one vs local-first prototype.
• Exact AI provider abstraction.
• Final V1 character creation tables.
• Final V1 career path list: military, merchant, traveler/frontier, scientist, or other.
• Final V1 skill list.
• Final V1 scale-time table.
• Familiarity thresholds, bonuses, and momentum conversion.
• Exact host death and replacement flow.
• How much direct GM override is needed in V1.
• Whether AI voice input/output belongs in V1 or V2.
• Whether maps are text-only, grid-based, or abstract node graphs in V1.