Ymir/README.md
2026-07-14 21:17:41 +01:00

102 lines
4.5 KiB
Markdown

# Ymir
Ymir is the GameCult Box3D wrapper and physics-daemon boundary for Aetheria and
future world-bearing projects. The name means **Not Invented Here**. We are
taking the hint.
Box3D owns physics algorithms. Ymir owns the service boundary that makes those
algorithms usable as durable, typed GameCult world truth. Unity, renderers, and
game products consume Ymir state and contact facts; they do not become physics
authorities.
## Ownership
- Box3D owns rigid-body integration, collision geometry, broadphase, solver
behavior, continuous collision, overlap and cast semantics, contact
lifecycle, force and torque lifetime, tolerances, and deterministic step
behavior for identical recorded inputs.
- Ymir currently owns the pinned Box3D version, stable GameCult entity ids,
native ABI isolation, public in-process retained sessions, explicit mutation
receipts, typed contact facts, snapshot lowering, deterministic result
ordering, versioned CultCache snapshots, and a diagnostic Eve publication.
- The Ymir daemon will own named session routing, durable command receipts,
checkpoint reconstruction, CultMesh command/fact publication, and process
supervision. Those are the daemon cutover contract, not a claim that the
current CLI already exposes them.
- Aetheria owns gameplay policy and supplies typed physical intent: bodies,
fields, tractor targets, forces, projectiles, filters, and the gameplay
consequences of Ymir contact facts.
- CultMath remains available for GameCult-side numeric projections and force
preparation. It is not a second collision or integration engine.
- Unity and Eve lowerers render world state and submit commands. They never
repair, override, or independently simulate authoritative physics.
Box3D opaque handles are process-local derived state. They are never durable
entity ids and never cross the public contract boundary.
## Current Cutover State
Box3D v0.1.0 is pinned at commit
`8441b4a06d6d09dcfb0b0f704df4d847d1437b92`. A Ymir-owned native shim and
parity suite already witness released Box3D behavior for:
- sphere overlap and shape casts
- tractor capsule membership and rounded caps
- numeric overlap and cast slop
- planar sphere-world stepping
- contact-begin facts
- restitution mixing
- transient torque lifetime
The production `Ymir.Box3D` boundary owns the native session ABI. The legacy
snapshot `YmirSimulator.Step` contract now creates an isolated Box3D session,
projects the result, and disposes it. It contains no managed integrator,
collision loop, or impulse solver.
That snapshot facade deliberately does not pretend to own long-lived world
identity. The public in-process `YmirSession` now exposes explicit body
mutations, force and torque commands, revisioned receipts, retained stepping,
and typed Begin/Hit/End facts. It never treats omission as removal. The daemon
still lacks a named session registry and CultMesh command lowering. Aetheria
will name one session per run and zone through that daemon contract; its old
process-wide simulator objects are not session identifiers. Retained-world
queries, checkpoint reconstruction, and non-Windows RID artifacts remain
cutover work.
See [the architecture map](docs/architecture.md) and
[the executable parity contract](docs/box3d-parity.md). The
[retained-session contract](docs/retained-session-contract.md) records the
current ownership cut and the public daemon boundary being built.
## Build And Test
Initialize the pinned dependency and run the solution:
```powershell
git submodule update --init --recursive
dotnet test Ymir.slnx
```
The parity project builds the native shim from source and requires CMake plus a
C17 compiler:
```powershell
dotnet test tests\Ymir.Box3D.Parity\Ymir.Box3D.Parity.csproj
```
Box3D is MIT licensed. Its license is retained in `extern/box3d`.
`GameCult.Ymir.Box3D` packages the managed boundary, Box3D license, and native
facade under `runtimes/<rid>/native`. A local Windows x64 package has loaded in
an isolated empty consumer without CMake or the submodule. A committed release
smoke is still required before that is a repeatable packaging guarantee. Linux
and macOS packages must be produced and smoked on their own release workers
before those RIDs are advertised.
## Cutover Rule
A Ymir cutover is complete only when all runtime stepping, collision queries,
and contact facts come from Box3D through an explicitly owned Ymir session.
Manual Unity callbacks and Aetheria geometry tests must be structurally unable
to decide the result. Snapshot compatibility calls may use isolated sessions;
they are not allowed to infer or share retained-world identity.