BodyAndBrain.Engine 0.5.0

BodyAndBrain.Engine

A deterministic, CQRS-backed rules engine for the Body and Brain (BaB) role-playing system, built for CRPG creators. Send it commands and queries; it creates characters, generates NPCs and monsters, resolves attacks and spells, ticks status effects, and persists everything, returning a structured YAML result for every action.

• Target framework: .NET 10 (net10.0)
• Persistence: LiteDB (embedded, single file)
• Dispatch: SharpNinja.FeatureFlags.Cqrs.IDispatcher
• Data: an embedded YAML catalog transcribed from the BaB manual and the BodyAndBrain.xlsm workbook
• Configuration: Magic numbers (base hits, level caps, etc.) loaded from Data/magic-numbers.yaml via IConfiguration
• Determinism: Per-action rollOverride + optional RandomSeed on BodyAndBrainEngineOptions for full run reproducibility

What it is, and is not

It is a .NET library that owns the rules: character creation, generation, combat math, spell resolution, status effects, and a replayable action log. Every randomized operation accepts a roll override, so identical inputs always produce identical results (ideal for tests, replays, and server-authoritative netcode).

It is not a game loop, renderer, turn scheduler, AI, or network layer. It does not decide whose turn it is or draw anything. You own the game; the engine owns the rules. Where the canonical sources leave a mechanic underspecified (summoning, mind control, teleport, revival), the engine does not invent rules: it returns a success flagged requiresAdjudication: true with a stable reason code, handing the decision to your game or a human game master.

Quick start

Register the engine and drive it through the typed client or the dispatcher:

using BodyAndBrain.Engine;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddBodyAndBrainEngine(o => o.StorePath = "mygame.db");
using var provider = services.BuildServiceProvider();

var engine = provider.GetRequiredService<IBodyAndBrainEngine>();

var hero  = await engine.CreatePlayerCharacterAsync("Mira", "Human", "Fighter", "Soldier");
var ogre  = await engine.GenerateMonsterAsync("ogre-fighter", level: 5, name: "Cave Ogre");

var result = await engine.ExecuteActionAsync(
    "physical-attack-1h-edge", hero.Id, ogre.Id,
    parameters: new Dictionary<string, string> { ["armor"] = "soft-leather" });

Console.WriteLine(result.Document);            // full YAML action result
Console.WriteLine(result.RequiresAdjudication); // false for a resolved attack

See docs/manual/getting-started.md for the full walkthrough.

Documentation

The complete creator manual lives in docs/manual/:

Shipped content

Building and testing

From the repository root:

dotnet build BodyAndBrain.Engine.slnx
dotnet test  BodyAndBrain.Engine.slnx

dotnet test BodyAndBrain.Engine.slnx is the required validation gate. The suite exercises every race/profession combination, every monster, every weapon, and every catalog action through the dispatcher.

Repository layout

src/BodyAndBrain.Engine/          The engine library
  Data/bodyandbrain.game.yaml     Embedded canonical game catalog
tests/BodyAndBrain.Engine.Tests/  Dispatch-level requirement coverage
docs/manual/                      Creator manual (start here)
docs/Project/wiki/                Functional, technical, and testing requirements
BodyAndBrain.Engine.slnx          Solution

Canonical sources and fidelity

The engine implements only what the BaB manual and BodyAndBrain.xlsm workbook specify unambiguously. Where the workbook supplies a number and the manual supplies intent, the manual's labels and effects win on conflict. Mechanics the sources leave open are surfaced as adjudication rather than guessed. See the manual's note on adjudication.

Authors

Gateway Programming School; SharpNinja.