diff --git a/README.md b/README.md index b40a1b52..3833316e 100644 --- a/README.md +++ b/README.md @@ -262,6 +262,7 @@ Each subproject has a local README with package-specific detail: - [GameCult.Caching.NewtonsoftJson](src/GameCult.Caching.NewtonsoftJson/README.md) - [GameCult.Caching.MessagePack.Generator](src/GameCult.Caching.MessagePack.Generator/README.md) - [GameCult.Caching.MessagePack.Analyzers](src/GameCult.Caching.MessagePack.Analyzers/README.md) +- [GameCult.Geometry](src/GameCult.Geometry/README.md) - [GameCult.Networking](src/GameCult.Networking/README.md) - [GameCult.Mesh](src/GameCult.Mesh/README.md) - [Durable Node Quickstart](src/GameCult.Mesh/docs/durable-node-quickstart.md) diff --git a/src/GameCult.Geometry/README.md b/src/GameCult.Geometry/README.md index 8142f93a..57112b08 100644 --- a/src/GameCult.Geometry/README.md +++ b/src/GameCult.Geometry/README.md @@ -14,3 +14,51 @@ The package is deliberately substrate-shaped: the xeno boundary, but the live machine eats and emits typed CultCache documents. +## Runtime Path + +`vg-csg` emits domain documents, selected-cut manifests, and chunk artifacts as +MessagePack CultCache documents. A Unity runtime, local worker, or remote +geometry process should receive the same records through CultMesh/CultNet and +read them back as `CultGeometry*` types. + +```csharp +using GameCult.Caching; +using GameCult.Geometry; +using GameCult.Mesh; +using GameCult.Networking; + +var geometryDocuments = new CultNetDocumentRegistry(CultDocumentRegistry.Shared) + .Register(CultNetDocumentBinding.ForDocument()) + .Register(CultNetDocumentBinding.ForDocument()) + .Register(CultNetDocumentBinding.ForDocument()) + .Register(CultNetDocumentBinding.ForDocument()); + +using var node = await CultMesh.CreateNodeAsync("ragnarok-geometry.ccmp", new CultMeshNodeOptions +{ + DatabaseOptions = new CultNetDatabaseOptions + { + RuntimeId = "unity-runtime", + DocumentRegistry = geometryDocuments + } +}); + +using var chunks = node.Database + .Watch() + .Subscribe(change => ApplyChunk(change.Document)); +``` + +The record key is part of the contract. Rust and C# must compute the same key +for the same geometry record, so stable fingerprints use the Rust canonical +field order and invariant float text. If this drifts, the same chunk becomes two +different chunks depending on which runtime touched it first. That is not a +cache miss; that is split-brain geometry. + +## Documents + +- `CultGeometryDomainDocument`: one hierarchical domain tree, suitable for + Ragnarok/Fensalir-style feature DSL output. +- `CultGeometryBuildRequest`: one LOD/frustum/budget request for workers. +- `CultGeometrySelectedCutManifest`: the selected domain cut, deferred children, + fallback rows, and diagnostic contribution rows. +- `CultGeometryChunkArtifact`: render mesh, optional collider mesh, source + domain/claim identities, build counters, and transition clipping seed.