CultMath/docs/design.md

Design

CultMath exists to make renderer math readable in every place it needs to live: Rust hot kernels, C# host code, and HLSL shader code.

Rules

• Keep type names HLSL-shaped: float2, float3, float4, and math.
• Keep Rust as the owner of native hot-path kernels and parity fixtures.
• Keep C#, shader, and scripting surfaces as runtime wrappers, not competing math authorities.
• Keep shaders/CultMath.hlsl as the canonical shader mirror for shared intrinsics. Project-local shader helpers should move here once more than one organ needs them or once CPU/GPU parity matters.
• Implement public shader semantics directly; do not copy Unity.Mathematics.
• Prefer small immutable value types.
• Prefer component-wise overloads over clever generic machinery until the API earns that complexity.
• Keep the surface boring and exact. Noise primitives are allowed when they are source-grounded, shader-shaped, and shared by more than one project. Matrices, quaternions, and packing helpers still need an owner before they enter.
• Planetary geometry is a scale-aware field query, not a renderer asset. CPU simulation is the reference consumer; pages, patches, and maps are derived lowerings carrying field identity and unresolved error.
• Application base fields and gameplay meaning enter through narrow inputs. CultMath does not own biomes, resources, traversability, render materials, or committed game consequences.

Non-Goals

• Compiling C# to shaders.
• Generating HLSL from Rust or Rust from HLSL.
• Replacing System.Numerics for general .NET work.
• Recreating every Unity.Mathematics type because a spreadsheet somewhere says “coverage.” That way lies decorative obesity.