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.

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.

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. See the CHANGELOG for the detailed history and plan/00-overview.md for what's next.

License

Apache-2.0