diff --git a/docs/README.md b/docs/README.md index c5a4c23..0b81054 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,9 @@ historical branch scar. - `stateless-planetary-erosion-rendering-plan.md`: authority map and staged implementation plan for spherical erosion, cube-sphere pages, LOD, intersection, differential shading, and verification. +- `cultmath-planetary-field-runtime-plan.md`: extraction and authority plan for + one CultMath planetary field shared by Aetheria daemon CPU simulation, + Fensalir and Unity 3D rendering, and Electron/Web map projections. - `../src/Saga/README.md`: studio-facing Saga middleware pitch and subproject overview for stochastic planetary flow. - `papers/fensalir-pipeline.tex`: living MiKTeX paper for the Fensalir diff --git a/docs/cultmath-planetary-field-runtime-plan.md b/docs/cultmath-planetary-field-runtime-plan.md new file mode 100644 index 0000000..3069415 --- /dev/null +++ b/docs/cultmath-planetary-field-runtime-plan.md @@ -0,0 +1,370 @@ +# CultMath Planetary Field Runtime Plan + +## Objective + +Make CultMath the canonical, renderer-independent planetary field runtime used +by Aetheria's daemon simulation, Unity's three-dimensional planet renderer, +Fensalir's D3D12 renderer, and Electron/Web strategic maps. + +The product is a deterministic, scale-aware spherical field that can be queried +on the CPU and lowered into several presentation substrates. Rendering is one +consumer. It is not the owner of planetary geometry. + +The intended end state is: + +> All deterministic planetary geometry, evidence, addressing, sampling, +> paging, projection, and refinement live in CultMath. Aetheria owns gameplay +> meaning and committed consequences. Renderers lower the same versioned field. + +## Current mechanism + +CultMath currently owns the matching C# and HLSL erosion operator, physical +frequency-band selection, spherical field primitives, and bounded radial +refinement. Fensalir and Zyphos currently own most of the surrounding planetary +machine: cube-sphere addressing, page contracts, residual generation, page +summaries, projected-error selection, residency transitions, page sampling, +patch construction, and renderer bindings. + +The completed Fensalir implementation proves the approach, but its ownership +boundary is too renderer-shaped for Aetheria. The reusable algorithms should +move into CultMath. D3D12 resource allocation and command recording should not. + +Aetheria's daemon is the authority for committed game state and simulation. +Unity objects, Electron canvases, local GPU pages, and projected map tiles are +derived state. Terrain queries that affect movement, visibility, construction, +resources, physics, or combat must be available to the daemon without booting a +renderer or depending on client cache residency. + +## Authority map + +### Owner + +CultMath owns the canonical planetary field function and the algorithms needed +to query or approximate it at a declared physical scale. + +Aetheria owns planet definitions, authored parameters, gameplay interpretation, +simulation policy, and every committed consequence of a terrain query. + +### Inputs + +The field runtime may read: + +- a stable planet identifier and field version; +- planet seed, radius, and declared coordinate frame; +- base-field and erosion parameters; +- a unit spherical direction or world-space query location; +- a physical sample footprint or requested wavelength range; +- an explicit accuracy/error budget; +- deterministic authored contributions supplied through a narrow Aetheria + policy boundary. + +### Outputs + +A point query returns a `PlanetarySurfaceSample` containing at least: + +- radius and radial displacement; +- planet-local and optional world-space surface position; +- tangent gradient, geometric normal, and slope; +- ridge, gully, drainage, and related field evidence; +- water-relative height when a sea datum is supplied; +- the resolved wavelength interval; +- a conservative unresolved-height bound; +- the planet and field versions used to produce the result. + +Batch, region, intersection, page, and projection queries compose this same +contract. They do not define separate terrain. + +### Derived state + +These are caches or projections, not owners: + +- cube-sphere pages, borders, child residuals, and summaries; +- quadtree residency and transition weights; +- Unity meshes, buffers, textures, and GameObjects; +- Fensalir D3D12 buffers and pipeline state; +- projected Electron/Web map tiles; +- shaded-relief, biome-color, political, or tactical map layers; +- local collision meshes and navigation grids. + +Eviction or regeneration may change latency or available fidelity. It must not +change the canonical answer at the same query scale. + +### Forbidden writers + +These paths must not decide planetary truth: + +- Unity scene lifetime, collision callbacks, or renderer-local noise; +- Electron-only projection or terrain generators; +- cube-face-local seeds or seam repair passes; +- D3D12- or ShaderLab-only erosion equations; +- cache residency, request order, or transition age; +- map palettes, labels, and visualization thresholds; +- renderer-specific gameplay compensators. + +### Shared paths + +Daemon point and batch queries, CPU and HLSL page baking, Unity and Fensalir +patch rendering, map-tile generation, reload, and LOD transitions identify and +evaluate the same field contract. + +### Cut line + +Move renderer-independent cube-sphere, page, residual, LOD, sampling, projection, +and patch algorithms out of Zyphos and Fensalir into CultMath. Delete the old +algorithm owners after each consumer delegates to CultMath. Do not preserve two +implementations behind adapters. + +Keep only resource allocation, descriptor layout, dispatch, camera/clip-space +conversion, render-pipeline integration, presentation materials, and user +interaction in renderer packages. + +## Invariants + +1. The same field version, direction, and physical footprint produce the same + terrain within the declared backend tolerance. +2. CPU simulation never depends on renderer availability or page residency. +3. Simulation queries explicitly declare physical footprint or wavelength + range. There is no ambiguous full-detail `HeightAt` authority. +4. The daemon alone commits gameplay consequences. Client evaluation is + prediction or presentation of daemon-published field truth. +5. Cube faces and map projections are coordinate charts, never terrain owners. +6. Parent and child pages share identical low-frequency terrain. Children add + only representable residual bands. +7. Page and tile eviction affects cost and fidelity availability, not identity. +8. A map pixel and a 3D point resolving to the same spherical direction and + footprint sample the same field. +9. Projection singularities and polar cutoffs are explicit contracts. +10. Integer hashing and field identity are exact across supported backends. + Floating-point results carry measured tolerances and error bounds. +11. Erosion evidence does not silently claim hydrology, climate, biome, + resource, or traversability authority. +12. CultMath core has no Unity, D3D12, Electron, or Aetheria dependency. + +## Canonical package shape + +```text +CultMath.Planetary +|-- Definition field definition, version, coordinate frame, query scale +|-- Field composition, erosion, differentials, conservative errors +|-- Topology cube faces, tile addresses, direction/UV, seam rules +|-- Query point, batch, ray, clearance, path, and region queries +|-- Pages layouts, generation, residuals, summaries, composition +|-- Residency projected-error selection, fallback, arrival, eviction +|-- Projection forward/inverse transforms and projected tile sampling +`-- Patch cube-sphere mesh, radial refinement, surface differentials +``` + +The HLSL surface mirrors these organs with small includes. Resource declarations +and executable compute/raster entry points remain adapter code so the common +functions work in Unity, Fensalir, and standalone parity probes. + +## CPU query contract + +The primary API is scale-aware: + +```csharp +PlanetarySurfaceSample SampleDirection( + in PlanetaryFieldDefinition planet, + float3 unitDirection, + in PlanetaryQueryScale scale); + +PlanetarySurfaceSample SamplePosition( + in PlanetaryFieldDefinition planet, + double3 planetLocalPosition, + in PlanetaryQueryScale scale); +``` + +`PlanetaryQueryScale` declares a footprint in metres or an explicit wavelength +range, plus an accepted unresolved-height bound. Named Aetheria policies such +as strategic, navigation, vehicle, or character scale belong to Aetheria and +lower to this physical contract before evaluation. + +Required CPU compositions are: + +- allocation-free point sampling and structure-of-arrays batches; +- bounded ray/surface intersection and segment clearance; +- great-circle and arbitrary path profiles; +- region min/max/slope queries with declared error; +- deterministic page baking identical to the GPU page contract; +- projection-tile sampling. + +World-space APIs use double precision for astronomical positions and reduce to +a stable planet-local frame before float field evaluation. Floating-origin +policy must not perturb the field. + +## Daemon integration + +The Aetheria daemon publishes typed planet definitions and field versions +through CultCache/CultMesh. Simulation systems query CultMath locally in the +daemon process. A result becomes game truth only when an Aetheria simulation +owner uses it in a committed operation or frame. + +The daemon may maintain CPU pages, spatial summaries, collision meshes, or +navigation grids. Every cache key includes complete field identity and query +scale. Cache misses evaluate the canonical field or report deferral; they never +substitute a different terrain function. + +The initial integration targets Aetheria's current C# daemon host. If authority +moves to Rust, the CultMath semantics and parity corpus specify the Rust port. +C# and HLSL remain first-class rather than becoming Unity artifacts. + +## Unity 3D lowering + +`CultMath.Unity` is a thin package outside core CultMath. It owns conversion to +Unity types, graphics buffers, shader entry points, page-atlas dispatch, +camera-relative patch submission, render-pipeline integration, and materials. + +It consumes CultMath HLSL for page generation, residual composition, sampling, +radial refinement, and differentials. Aetheria supplies the published planet +definition. Unity does not retain an independent planet generator. + +## Electron/Web 2D lowering + +A map follows one path: + +```text +pixel -> inverse projection -> unit sphere direction + -> scale-aware surface query -> evidence layer + -> client-owned palette, labels, and interaction +``` + +CultMath initially owns forward and inverse transforms for: + +- equirectangular; +- Web Mercator with an explicit polar cutoff; +- Equal Earth or Mollweide equal-area projection; +- orthographic globe view; +- azimuthal equidistant and equal-area local views; +- cube-face atlas; +- local tangent-plane maps. + +Two delivery modes share the same identity: + +1. The daemon or attached worker generates versioned projection tiles and + publishes typed descriptors plus binary assets through CultMesh/CDN. This is + the baseline for Electron and thin browser clients. +2. A future WebGPU lowering evaluates locally for unusual projections or highly + interactive inspection. + +The first mode provides one auditable CPU implementation without requiring a +JavaScript terrain port. WebGPU should be added only with a WGSL parity harness, +not as a hand-translated browser generator. + +A projection-tile key includes planet and field version, projection and +parameters, evidence layer, tile level/coordinates, dimensions and border, +wavelength/footprint policy, and sampling/encoding version. Tiles are derived +assets. Strategic objects, territories, visibility, orders, and simulation +facts remain typed Aetheria state layered over them. + +## Field definition and publication + +The portable field definition is a typed document, not renderer configuration. +It contains stable parameters, coordinate conventions, component identities, +and a content fingerprint. CultCache stores it; CultMesh publishes it. JSON is +only a schema, debug, or xenos-boundary projection. + +- CultMath emits geometry and field evidence. +- Aetheria decides biomes, resources, movement, settlement, and gameplay. +- Unity decides 3D material lowering. +- Electron decides map palettes, contours, labels, and overlays. + +## Execution roadmap + +### Phase 0: contract and parity corpus + +Define field identity, coordinates, query scale, sample, and error types. Record +canonical point, seam, corner, wavelength, and projection fixtures. Separate +exact integer/hash requirements from bounded floating-point parity. + +Exit: CPU, HLSL, page, and projection tests name the same field contract without +renderer-owned types. + +### Phase 1: topology extraction + +Move cube-face, tile-key, direction/UV, border, and seam algorithms to CultMath. +Replace Fensalir copies and test all edges and corners. + +Exit: Fensalir contains no private cube-sphere terrain topology. + +### Phase 2: authoritative CPU queries + +Add scale-aware point/batch queries, double-to-local reduction, differentials, +bounds, ray intersection, clearance, and path profiles. Integrate an Aetheria +daemon simulation smoke. + +Exit: the daemon makes a deterministic terrain decision without Unity or +Fensalir assemblies. + +### Phase 3: page machinery extraction + +Move page layouts, CPU baking, residual bands, summaries, sampling, and matching +HLSL into CultMath. Preserve Fensalir measurements and transition evidence. + +Exit: CPU and HLSL pages match direct queries within declared unresolved bounds; +Fensalir is only a resource/dispatch adapter. + +### Phase 4: residency and patch extraction + +Move projected-error selection, fallback, transition weights, patch topology, +and refinement composition. Keep camera projection and drawing in renderers. + +Exit: Unity and Fensalir consume the same page set and patch description for +equivalent camera/error inputs. + +### Phase 5: Unity adapter and Aetheria viewer + +Build `CultMath.Unity`, bind daemon-published definitions, render from orbit to +ground, and compare Unity readback and seams against the parity corpus. + +Exit: Aetheria views the daemon-defined planet without a second generator. + +### Phase 6: projections and map tiles + +Implement projection transforms, footprint calculation, antialiased tile +sampling, CultMesh/CDN publication, and Electron elevation, slope, shaded +relief, plus one Aetheria strategic overlay. + +Exit: Unity and Electron identify matching landmarks at shared directions; +changing projection changes only the chart. + +### Phase 7: optional WebGPU lowering + +Add WGSL only if interactive local evaluation earns its cost, then prove point, +seam, page, and projection parity. Daemon tiles remain production until then. + +### Phase 8: delete obsolete owners + +Remove superseded Zyphos/Fensalir algorithms and Aetheria's Unity-only celestial +terrain from authoritative paths. + +Exit: renderer code, cache state, or projection cannot change the planet. + +## Verification matrix + +| Claim | CPU daemon | Fensalir | Unity | Electron tiles | WebGPU later | +|---|---:|---:|---:|---:|---:| +| Field identity/hash | exact | exact | exact | exact metadata | exact | +| Point height/evidence | reference | bounded | bounded | sampled | bounded | +| Six-face edges/corners | required | required | required | projection-specific | required | +| Wavelength selection | reference | bounded | bounded | encoded in key | bounded | +| Page residual sum | reference | required | required | optional source | required | +| Projection round trip | reference | optional | optional | required | required | +| Cache-independent answer | required | required | required | required | required | + +Negative checks must prove that residency cannot change a direct query, +projection cannot change the spherical field, Unity settings cannot alter daemon +identity, stale tiles fail version checks, omitted wavelengths remain within +their bound, seams/poles remain single-valued, and reload/eviction cannot commit +gameplay state. + +## Initial deliverable + +1. Extract cube-sphere topology and scale-aware CPU point/batch queries. +2. Add an Aetheria daemon smoke for height, normal, slope, and error. +3. Add equirectangular and Equal Earth CPU projection sampling. +4. Produce one versioned elevation tile and one slope tile. +5. Match the same fixture directions against Fensalir's HLSL oracle. + +This proves the daemon and map architecture before moving the larger page and +patch machine. It produces useful Aetheria output without letting a quick tile +generator become a second planetary authority.