From 409b56c5569953cde65875e6635e051cbaaf0cc5 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 27 Oct 2026 05:03:39 +0100 Subject: [PATCH] Lodur's target and README front door: what it is for, its five layers, invariants and first consumer Co-Authored-By: Claude Opus 5.5 --- README.md | 39 +++++++++++++++ docs/lodur-target.md | 117 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 README.md create mode 100644 docs/lodur-target.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..06ef5a0 --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# Lodur + +A physics character middleware for characters that **feel and react**: they +pull back from something hot, jump when poked, and, if they want their +objective badly enough, crawl toward it after losing a leg. + +**Status: design only. No code exists yet.** The design is +[`docs/lodur-target.md`](docs/lodur-target.md); read it first. + +## The problem + +Active-ragdoll middleware (NaturalMotion's Euphoria, RootMotion's PuppetMaster) +and learned physics controllers (DReCon, ProtoMotions) solve the body: physics, +pose tracking and, in the learned case, balance. None of them models the nervous +system. They have no senses that are not forces, no reflexes layered under +deliberate behaviour, and no character whose pain competes with its will over +time. Lodur is that layer. + +## Shape (planned) + +- **Core** (C#, no engine references): perception, reflexes, a drive state of + pain, shock, adrenaline and resolve that evolves every tick, and behaviour + selection that turns the drive into targets plus muscle strength. +- **Body** (per engine): follows those targets on the engine's own articulated + physics. v1 is a PD-tracking active ragdoll in Unity; v2 adds a small learned + tracker for upright balance behind the same interface. + +## First consumer + +[Bad Day Simulator](https://eureka.gamecult.org/forge/GameCult/BadDaySimulator), +a 3D physics sandbox. + +## Where it lives + +Canonical: `https://eureka.gamecult.org/forge/GameCult/Lodur`. GitHub +`GameCult/Lodur` is a push mirror. + +Prior-art research: +[`gamecult-ops/docs/research/euphoria-at-home-prior-art.md`](https://github.com/GameCult/gamecult-ops/blob/main/docs/research/euphoria-at-home-prior-art.md). diff --git a/docs/lodur-target.md b/docs/lodur-target.md new file mode 100644 index 0000000..7c66cf8 --- /dev/null +++ b/docs/lodur-target.md @@ -0,0 +1,117 @@ +# Lodur: target + +Campaign `lodur`. The operator's rulings live in the eureka-state mind under +root `motion-pipeline` (the workshop ran there); this document holds the +rationale and the design truths the campaign will produce. Where it and a +ruling disagree, the ruling wins and this file is stale. + +## What it is for + +A character that reacts to forces and stimuli, and compensates for injury, +the way a person would: it pulls back from something hot, jumps when poked, +and crawls toward its objective on one leg if it wants that objective badly +enough. (`motion-pipeline:ruling:euphoria-stimulus-and-impairment`.) + +The field has the physics and the balance. NaturalMotion's Euphoria shipped +active, physically simulated characters in GTA IV through Red Dead Redemption +2, and learned trackers (DReCon, ProtoMotions, MaskedMimic) follow arbitrary +motion while keeping their feet. What the field does not have, per the prior-art +pass, is the nervous system on top: senses that are not forces, reflexes layered +under deliberate behaviour with their own latencies, and a character whose will +competes with its pain. Euphoria's reactions are whole-body behaviours a game +starts; nothing in the record senses heat or a light touch, and nothing models +the twenty seconds in which a wounded character crawls, slows, and passes out. +That layer is Lodur. Evidence: `gamecult-ops/docs/research/euphoria-at-home-prior-art.md` +(sections 1-9 at `8320c18`, section 10 at `15d9a4e`). + +Named after the god in Voluspa who gives the first humans blood, warmth and +good colour (`motion-pipeline:ruling:euphoria-middleware-named-lodur`). + +## Layers + +Signal flows one way per tick; each layer has one owner. + +1. **Perception.** Contacts, impulses, temperature, proximity and named game + stimuli become typed stimuli on body regions. A poke that barely moves the + body is still a stimulus. +2. **Reflex.** Fast, local, involuntary responses to stimuli (withdrawal, + startle, bracing), each with a latency, overlaid on whatever the body is + doing. Physiology sets the scale: withdrawal roughly 60-150 ms, voluntary + reaction about 200 ms (figures `[M]` in the research doc; verify before + they become constants). +3. **Drive.** Per-character state that evolves every tick: pain accumulates + and decays, shock runs on a clock that blood loss speeds, adrenaline spikes + on threat and fades; resolve is a trait, and the objective pulls. Static + per-character values are this state with its dynamics frozen. + (`motion-pipeline:ruling:euphoria-drive-is-dynamic-state`.) +4. **Behaviour.** The drive selects and weights behaviours (writhe, crawl to + the objective, pass out, get up, the reflex overlay) that emit targets. +5. **Body.** Follows targets (poses, IK goals) with per-muscle strength on the + host engine's articulated physics. v1 is GameCult's own PD-tracking active + ragdoll and ships the ground behaviours; v2 is a small learned tracker + (DReCon scale: 340 us per character per frame measured, 60 us of it the + policy) for upright states, behind the same interface. + (`motion-pipeline:ruling:euphoria-body-layer-order`.) + +Layers 1-4 are the core: C# with no engine references, testable without an +engine. Layer 5 binds to the host: Unity `ArticulationBody` first; v2 inference +through the engine's runner (Unity Inference Engine, ONNX Runtime). +(`motion-pipeline:ruling:euphoria-first-consumer-sandbox-csharp-core`.) + +## Invariants + +- `core-engine-free`: the core assemblies reference no engine. A Unity type in + the core is a defect, not a convenience. +- `body-one-interface`: the body consumes only targets and per-muscle strength. + Drive, behaviour and reflex never set a joint, force or physics property + directly; swapping the PD ragdoll for a learned tracker changes no layer above. +- `one-physics-world`: the body simulates in the host's physics world. No + second world that the game's objects cannot touch. +- `reflex-below-voluntary`: a reflex acts on its own shorter latency and + overlays the running behaviour; it never waits for behaviour selection, and + behaviour selection never cancels a reflex already in flight. +- `drive-is-state`: what a hurt character does is decided by drive state + evolving over time, never by a per-wound lookup. +- `bounded-tick`: per-character work per tick is bounded and allocates nothing + in steady state. A middleware that hitches is unusable in a game. +- `content-is-cultcache`: persistent content (puppet and object definitions, + drive parameters, saved levels in Bad Day Simulator) is CultCache, per the + GameCult substrate doctrine. JSON is schema publication only. + +## First consumer + +Bad Day Simulator (`GameCult/BadDaySimulator`): a 3D sandbox in the spirit of +how People Playground plays, not its camera or UI. The player gets a level and +places puppets of various sorts and objects with set behaviours and +interactions. (`motion-pipeline:ruling:euphoria-sandbox-shape`, +`motion-pipeline:ruling:euphoria-sandbox-named-bad-day-simulator`.) It is a +separate repo so that Lodur's boundary has a real consumer from the first cut. + +## Not in scope + +- Adapting to arbitrary changes of body topology. The operator called it too + ambitious; impairment is handled through the drive and the behaviour set. +- A Rust port of the core, until a first consumer outside Unity exists. +- The StreamPixels overlay as a consumer before StreamPixels M1 ships. +- Depending on RootMotion PuppetMaster (paid, not redistributable, and no + balance control: research section 10.1). +- Hand-tuned balance controllers of the SIMBICON family as the upright path. + +## Open before the first cut is mapped + +The identity, lifecycle and authority table (one row per persistent kind) is +written before any cut; these feed it. + +- **Impairment states.** Self's proposal, not ruled: impairment as a closed set + of named body states (intact, missing a leg, missing an arm, both legs), with + mirror symmetry; crawling as the first locomotion after any leg loss; one-leg + hopping a stretch goal. +- **Rig.** Which humanoid the sandbox ships with, and its licence for a public + repo. The StreamPixels Little Heroes Mega Pack is a paid asset and cannot be + committed to a public repo. +- **Unity version** for Bad Day Simulator, and how Lodur's core is consumed + (UPM package from the Lodur repo, or a built assembly). +- **Training host for v2.** Raven trains only when the household's GPU allows + (`motion-pipeline:ruling:raven-gpu-defers-to-household`). +- **Trademark search** on "Bad Day Simulator" before anything public is + announced.