Document shared planetary field runtime

This commit is contained in:
Meta Vens 2026-07-13 01:14:17 +01:00
commit 2ef556783e
2 changed files with 373 additions and 0 deletions

View file

@ -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

View file

@ -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.