GameLattice.Narrative 0.1.7

Game Lattice

An engine-agnostic, data-driven RPG framework: C# provides the engine, JSON provides the soul.

The C# core is a fixed interpreter over a closed vocabulary of effect, condition, and task primitives. Every gameplay noun — items, spells, quests, NPC brains, weather, economies — is a JSON def that hot-loads into a running session without recompiling. The data formats are designed to be authorable by LLMs as well as humans: paste docs/llm-guide.md into a model's context and it can write working content.

Why it's interesting

• Content never touches C#. A new spell, a blueprint NPC variant, or a two-step quest is JSON that hot-loads and runs. Adding a new primitive is a deliberate, small C# event.
• Five AI tiers, one vocabulary. NPC brains scale from two-state FSMs through Half-Life-style schedules and reactive behavior trees up to GOAP and HTN planners — all sharing the same task/condition verbs, so content can move an NPC between tiers without rewriting it. The dungeon demo reproduces the F.E.A.R. flanking result with three GOAP soldiers.
• Engine-agnostic by construction. The libraries target netstandard2.1 (Unity 2021.2+, Godot 4 .NET, any modern .NET host) and never reference an engine; hosts implement five small interfaces (clock/log, content source, navigation, animation, physics queries).
• Deterministic and testable. Everything above the hosting seams runs under a seeded RNG — the three demo scenes play out headless in CI as simulation tests against golden transcripts.
• Built for modding. Blueprint inheritance with array patches ($append/$remove), content packs that overlay base content, generated JSON schemas for every def kind, and a validation CLI with link-pass and AI-reachability warnings.
• Visual authoring, no drift. Lattice Studio (a standalone visual editor that runs in your browser) manages the whole JSON corpus with schema-driven forms, cross-ref pickers, node-graph canvases, and a live engine-equivalent hot-reload mirror — all derived in-process from the same def model, so the editor can never disagree with the runtime. See below.

What's in the box

Install

Every merge to main cuts a GitHub release automatically — see docs/releasing.md.

Quick start

Working from the repo requires the .NET 10 SDK (the shipped libraries themselves target netstandard2.1):

dotnet test                                   # build + run all tests (incl. the demo scenes)
dotnet run --project samples/Lattice.Demo     # interactive host shell (kitchen-sink scene)
dotnet run --project samples/Lattice.Demo -- --scene tavern    # or: dungeon | quest
dotnet run --project src/Lattice.Tooling -- validate content

Hosting the framework

Modules attach onto a GameSession in dependency order, then content loads once:

var session   = GameSession.Create(services, LatticeWorld.AddDefTypes(LatticeAi.CreateDefTypes()));
var rpg       = LatticeRpg.Attach(session);
var narrative = LatticeNarrative.Attach(session, rpg);
var ai        = LatticeAi.Attach(session, rpg, narrative);
var world     = LatticeWorld.Attach(session, rpg);   // composition is additive
session.LoadContent();
session.Boot("lifecycle_tavern");                     // a lifecycle def is a bootable scene

services is a HostServices built from five interfaces; standalone implementations (seeded RNG host, directory content source with hot reload, grid A*, stub animation, permissive physics) ship in the box, so the framework runs headless with zero engine code.

Authoring content

Defs are plain JSON — this is the shipped healing potion; effects compose, no item class exists:

{ "id": "item_healing_potion", "type": "item", "name": "Healing Potion",
  "tags": ["consumable"], "basePrice": 12, "consumeOnUse": true,
  "useActions": [ { "type": "Heal", "formula": "10" },
                  { "type": "RemoveStatus", "status": "status_poison" } ] }

Formulas are strings evaluated against the live world ("Str * 2 + 4", "2d6 + 4", "CAN_SEE_ENEMY * 50"); cross-references are ids checked by a link pass at load. Start with docs/llm-guide.md, then keep docs/manifest.md (every registered def and primitive) beside you.

Lattice Studio — the visual content editor

Hand-editing JSON and LLM authoring both scale poorly to hundreds of defs. Lattice Studio is a local, visual editor that makes managing the corpus a breeze for humans while staying truthful to the data model — it never becomes a second source of truth. It reads and writes content/**/*.json in place with clean, minimal diffs (so it composes with hand edits, LLM authoring, and git PRs), and it derives all of its game knowledge — schemas, the def catalog, and validation — in-process from the same Lattice.Tooling that backs the lattice CLI. The editor adds presentation, never meaning, so it can't drift from the runtime.

It's a single-process standalone .NET web app (ASP.NET minimal API + a React/TypeScript SPA) that runs locally and opens in your default browser — deliberately not an in-Unity/in-Godot tool, because building inside one engine would pick a side, against the framework's engine-agnostic thesis.

What it does

• Master browser — one virtualized table across every def kind, with search, kind/tag facets, a blueprint tree, and live validation badges. This is what makes "hundreds" manageable.
• Schema-driven forms — each def gets an editor generated from its schema, with searchable cross-reference pickers (go-to-def, dangling-ref warnings), union/primitive builders fed by the catalog's documented arg signatures, blueprint inherited/overridden field display, and field hints pulled from the def types' own doc comments.
• Node-graph canvases (React Flow) — visual graphs for behavioral kinds: editable dialogue trees and FSM brains (connect, rewire, add/delete), read-only behavior trees and HTN hierarchies, and a whole-domain GOAP action graph (the F.E.A.R.-style goal/action link view).
• New defs & clone — create a def routed to the right file (majority-file-per-kind, overridable) or clone an existing one, all re-validated on save.
• Live engine mirror — a persistent hot-reload session shows exactly what a running Godot/Unity host would see: a top-bar live pill that pulses on reload and goes amber when a broken edit is rejected (old defs kept), recovering when you fix it.

Working with the graph editors. Select any def of a graph-capable kind — dialogue trees, behavior trees, FSM brains, HTN compound tasks, or GOAP actions/goals — and a ⊞ graph button appears in the editor header; click it for a full-screen canvas (pan, zoom, minimap), or append ?graph to the URL to open it automatically. Dialogue and FSM graphs are editable: drag a node's ● handle onto another node to link them, drag a link's end to rewire it, select a node or edge and press Delete to remove it, and use + node to add one — then Save (the def is re-validated, with any errors shown inline). Behavior-tree, HTN, and GOAP graphs are read-only visualizations (the GOAP view spans the whole action/goal domain, not a single def). Closing the canvas (✕) returns you to the form editor, which stays in sync.

Download (no tools needed) — Windows. Grab game-lattice-studio-win-x64-*.zip from the latest release, unzip, and double-click Lattice Studio.exe. It's a self-contained app (no .NET install required): a small console window opens and the editor opens in your default browser, preloaded with the demo content, so you land in a full, editable world; use Open folder… in the top bar to point it at your own content/. Keep the console window open while you work — closing it stops Studio. (Unsigned, so Windows SmartScreen may prompt — choose More info → Run anyway.)

Run from source (any OS — needs the .NET 10 SDK, plus Node to build the SPA):

# Build the SPA once (populates wwwroot), then launch (opens your browser):
cd src/Lattice.Studio/web && npm ci && npm run build && cd ../../..
dotnet run --project src/Lattice.Studio

# Or, for SPA hot-reload while developing the editor itself (two terminals):
dotnet run --project src/Lattice.Studio -- --no-open     # backend API on :5210
cd src/Lattice.Studio/web && npm run dev                 # Vite dev server, proxies /api → :5210

dotnet publish builds the SPA automatically; scripts/Build-Studio.ps1 packages the downloadable zip the release ships (self-contained .exe + bundled content).

Flags: --content <dir> (defaults to the last folder you opened, else the nearest content/ found walking up from the working directory), --port N (default 5210), --no-open (serve headless, without opening a browser — for automation). See plan/08-content-editor.md for the full design.

The demo scenes

Three scenes ship as content (content/scenes.json) and double as CI simulation tests:

• The Tavern — a full game day: the innkeeper's routine flips with day phases, patrons run needs-driven activity loops, Charisma haggles bar prices, a look-away meta-sensor interrupts dialogue, and a patron comments when the rain rolls in.
• The Dungeon — three GOAP soldiers flank via exclusive attack-node reservation, rat-tier critters provably never invoke the planner, kills roll loot tables, a poison trap ticks, and an HTN boss falls back from ranged to melee.
• The Quest-Giver — quest_wolves end-to-end (accept → hunt → report → reward) across a mid-quest save/load.

The demo shell exposes the whole machine: agent, senses, bt, utility, needs, dump, trace, groups, bb, roles, path, time, events, quests, perf, hud.

Documentation

Repository layout

Status

All planned milestones (M0–M7) are complete and shipping as v0.1.x: the data backbone, RPG systems, narrative, the full five-tier AI suite, world simulation, modding/LLM integration, and the three demo scenes. The M8 authoring tool — Lattice Studio — is also complete (it's a local developer tool, not part of the shipped/packaged libraries). See the CHANGELOG for the detailed history and plan/00-overview.md for what's next.

License

Apache-2.0