docs: target r3 text, README status and entry points, Windows MinGW result

lodur-target.md becomes the r3 text: body on Ymir, layer type names and tick order,
one-physics-world restated with the game as owner, core tests build without Ymir.
README status drops 'layers 1-4 not coded'. first-slice.md records the MinGW Windows
build (DLL prefix workaround) instead of 'unrun'.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-11-19 20:49:12 +01:00
commit fc34388ef9
3 changed files with 112 additions and 111 deletions

View file

@ -4,16 +4,23 @@ 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 plus a first slice of layer 5.** The design is
[`docs/lodur-target.md`](docs/lodur-target.md); read it first. What runs today is a
PD-muscle active ragdoll on Ymir's Box3D SoA world: [`docs/first-slice.md`](docs/first-slice.md)
(measured and unmeasured). Layers 1-4 (perception, reflex, drive, behaviour) are not
coded.
**Status: layers 1-3 and a layer-4 stand-in run on a PD-muscle ragdoll on Ymir.** The
design is [`docs/lodur-target.md`](docs/lodur-target.md); read it first. `Lodur.Core`
holds perception, the withdrawal reflex, the drive state and a hold-against-reflex
stand-in, run per character by `Actor`; `Lodur.Body.Ymir` is the PD-muscle active ragdoll
on Ymir's Box3D SoA world ([`docs/first-slice.md`](docs/first-slice.md), measured and
unmeasured). Behaviour selection beyond the stand-in, impairment and the learned tracker
are not coded.
Entry points: `src/Lodur.Core/PdMuscle.cs` (engine-free PD law, strength per muscle),
`src/Lodur.Body.Ymir/HumanoidRagdoll.cs` (the ragdoll and `Drive`), `tests/Lodur.Tests`
(stand, fall, rest, same-seed-same-hash). Needs a sibling Ymir checkout at
`main` (the SoA joints merge, 2026-11-10, or later); `dotnet test tests/Lodur.Tests` builds its native library with cmake.
Entry points: `src/Lodur.Core/Actor.cs` (one character's nervous state, one tick per
physics step), `src/Lodur.Core/PdMuscle.cs` (engine-free PD law, strength per muscle),
`src/Lodur.Body.Ymir/HumanoidRagdoll.cs` (the ragdoll, `Drive` and `ReadRegions`),
`tests/Lodur.Core.Tests` (the layers and parity with the pain box; builds without Ymir),
`tests/Lodur.Tests` (stand, fall, rest, same-seed-same-hash, and the connected pain box:
`ConnectedPainBoxTests`). The map this was cut from is
[`docs/connect-rungs-map.md`](docs/connect-rungs-map.md). Needs a sibling Ymir checkout at
`main` (the SoA joints merge, 2026-11-10, or later); `dotnet test tests/Lodur.Tests` builds
its native library with cmake.
## The problem
@ -30,7 +37,7 @@ time. Lodur is that layer.
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
physics. v1 is a PD-tracking active ragdoll on Ymir; v2 adds a small learned
tracker for upright balance behind the same interface.
## First consumer

View file

@ -33,7 +33,7 @@ Ymir's structure-of-arrays world. Nothing above layer 5 exists yet.
## Not measured, or limits found
- Cross-platform bit-identity: unclaimed. Windows build and Unity consumption: unrun. One machine, Debug
- Cross-platform bit-identity: unclaimed. Windows (2026-11-19, no MSVC): builds and passes with MinGW gcc, `CMAKE_GENERATOR="Ninja Multi-Config" CC=gcc`; MinGW names the DLL `libymir_box3d.dll` where `Ymir.Box3D.csproj` expects `ymir_box3d.dll`, so copy it to the unprefixed name in `artifacts/box3d-native/production/Debug/bin/Debug` until Ymir emits that name. Test classes that build worlds must not run in parallel there (two live worlds crashed the host). Unity consumption: unrun. One machine, Debug
native build only; no Release run, no run in a second process.
- Explicit PD through torque lanes limits stiffness and damping: damping times the step must stay under the
inertia it acts on. Hips and spine went unstable at damping 15 and 20 and are set to 3 and 4; the gains

View file

@ -1,123 +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
Campaign `lodur`. The operator's rulings live in Nibu's mind under roots `lodur` and `motion-pipeline` (the
workshop ran under `motion-pipeline`; some of those show as moved in Eureka's mind, and Nibu's copies are the
ones in force). This document holds the rationale and the design truths the campaign produces. 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`.)
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`).
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. 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`).
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.
Signal flows one way per tick, in this order; each layer has one owner. Layers 1-4 are `Lodur.Core`
(`netstandard2.1`, no references); layer 5 is a body binding.
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 responses to stimuli (withdrawal, startle,
bracing), each with a latency, overlaid on whatever the body is doing.
Their gain is set from above by the drive, the way descending pathways
modulate spinal reflexes: the Gom Jabbar case. 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`.)
1. **Perception** (`Perception`, `NerveParameters`, `BoxStimulus`). Contacts, impulses, temperature,
proximity and named game stimuli become typed signals on body regions. Input: one point per body region
(from the body binding, read-only) and the game's stimulus sources. Today one channel (noxious) and one
source kind: a box volume with an intensity the game writes each tick. Output per region: the stimulus, and
the afferent signal after threshold, sensitisation and conduction delay. A poke that barely moves the body
is still a stimulus.
2. **Reflex** (`WithdrawalReflex`, `WithdrawalParameters`). Fast, local responses to afferent signals
(withdrawal now; startle and bracing later), each with a latency, overlaid on whatever the body is doing.
Each reflex's gain is set ahead of time by the drive, the way descending pathways modulate spinal reflexes
(the Gom Jabbar case): a reflex reads the drive state of the previous tick, never waits for behaviour.
Output: the reflex command that leaks past suppression, the strain load of holding the rest down, and
flinch events. 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** (`DriveState`, `DriveParameters`). Per-character state that evolves every tick: pain from
afferent input, strain from suppressed reflexes, resolve drained by both and scaled by the objective's pull;
later shock on a clock that blood loss speeds and adrenaline that spikes on threat. Resolve reaching zero
breaks the will, which releases every suppression. 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 (hold against a reflex, withdraw, writhe, crawl to
the objective, pass out, get up) that emit targets and per-muscle strength into caller-owned arrays, and
nothing else. Today one stand-in: hold a pose against the withdrawal reflex, blended toward a withdraw pose
by the reflex leak, shaking with strain, and withdrawing once the will breaks.
5. **Body.** Follows targets with per-muscle strength in the game's physics world. v1 is GameCult's own
PD-tracking active ragdoll on **Ymir**, GameCult's boundary around a pinned Box3D, read and driven through
Ymir's structure-of-arrays world in place (`lodur:ruling:lodur-body-on-ymir`): `Lodur.Body.Ymir`. It owns
the puppet's shapes, joints and gains and reports body-region points upward to perception. v2 is a small
learned tracker for upright states (DReCon scale: 340 us per character per frame measured, 60 us of it the
policy) 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`.)
`Actor` runs layers 1-4 for one character in that order once per physics step, from caller-owned inputs into
caller-owned outputs, and reports its events (flinch, will broke, withdrew) as flags.
## 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-gain-from-drive`: a reflex fires on its own shorter latency and
overlays the running behaviour; it never waits for behaviour selection. Will
acts on reflexes ahead of time, not after: drive state (resolve, the pull of
the objective) sets each reflex's gain, so a resolved character can hold its
hand in the box. Suppression is never free: the stimulus still feeds pain,
and holding a reflex down shows as visible strain until resolve breaks.
Deliberate behaviour takes over a fired reflex only after its own, longer
latency. (`motion-pipeline:ruling:lodur-reflexes-suppressible-by-will`.)
- `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.
- `core-engine-free`: the core assemblies reference no engine and no physics. A Unity or Ymir type in the
core is a defect, not a convenience. The core's tests build without Ymir.
- `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 game creates and owns one physics world, Ymir's; Lodur adds its bodies to that
world and never creates one of its own. Game objects (a restraint, a box, a thrown chair) act on a puppet
through that world.
- `reflex-gain-from-drive`: a reflex fires on its own shorter latency and overlays the running behaviour; it
never waits for behaviour selection. Will acts on reflexes ahead of time, not after: drive state (resolve,
the pull of the objective) sets each reflex's gain, so a resolved character can hold its hand in the box.
Suppression is never free: the stimulus still feeds pain, and holding a reflex down shows as visible strain
until resolve breaks. Deliberate behaviour takes over a fired reflex only after its own, longer latency.
(`motion-pipeline:ruling:lodur-reflexes-suppressible-by-will`.)
- `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, and the same
inputs give the same outputs. 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.
Parameters that are only code defaults are not yet content.
## 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.
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`.) Its one physics world is Ymir's. It is a
separate repo so that Lodur's boundary has a real consumer from the first cut. Its first item is the pain box,
the Synaptic Induction Chamber (`lodur:ruling:bds-pain-box-item`,
`lodur:ruling:bds-pain-box-named-synaptic-induction-chamber`).
## 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.
- 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.
- 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).
- 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
## Open
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).
- **Impairment states.** Self's proposal, not ruled: 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.
- **How Bad Day Simulator consumes Lodur** (`lodur:question:bds-consumes-lodur`).
- **The pain measure** (`lodur:question:pain-sweep-measure`).
- **Ymir gaps Lodur needs next**: contact facts for pain from impacts, body removal, joint springs for stiff
ankles (`nibu-body:follow_up:ymir-soa-lodur-needs`).
- **Renderer and rig** for Bad Day Simulator: nothing draws the puppet yet.
- **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.
- **Trademark search** on "Bad Day Simulator" before anything public is announced.