Files
aevolution/docs/adr/0019-voxel-storage-and-meshing.md
T
dingoandClaude Opus 5 d5b4bd068e Initial commit: architecture docs and headless engineering proof
Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 15:44:41 -04:00

2.4 KiB

ADR-0019: Sparse voxel storage and deferred meshing

Status

Proposed. Sparse procedural base plus modifications is locked; actual layout, planet topology and mesher need experiments. No meshing dependency in M0.

Context

Deep/core modification, smooth surfaces and chemistry cannot use dense whole planet allocation or dozens of floats per voxel. Rendering cannot own inventories.

Decision

Recommend versioned sparse chunk interfaces, deterministic base, persisted edits and compaction. Separate geometry/material from optional channels; compare palette IDs, quantized fields, uniform values, sparse pages and coarser grids. Mesh caches key source/neighbor revisions, mesher version and LOD. M5 proves local storage; later identical fixtures compare Marching Cubes, Surface Nets and Dual Contouring.

Alternatives Considered

Dense planet and surface-only heightfields violate requirements. Uniform chunk fields provide a baseline but waste cold data; fully adaptive per-field trees complicate coupled updates. Sparse optional channels trade indexing for bounded resident work. Marching Cubes is a scalar triangulation baseline with ambiguity/ seam obligations. Surface Nets variants differ in smoothing/topology behavior. Dual Contouring uses Hermite data/QEFs with robustness and gradient obligations. Marching Cubes, Dual Contouring.

Benefits

Simulation remains graphics independent; untouched territory regenerates; all meshers share field views and fixtures. Chemistry survives visual redesign.

Costs

Retain generator versions, channel metadata/residuals, halos and compaction. Heavily modified territory still grows. Conservative mapping between grids costs.

Risks

Cracks/stale collision exploits, slow compressed updates, unbounded refinement, duplicated resources, and surface indexing that fails at the core. Paper access does not license arbitrary implementation code.

Consequences

Compare sphere, cavity, thin wall, tunnel, edits, chunk seams and mixed LOD. Measure generation/edit/remesh p50/p95/p99, peak/resident memory, snapshot size, topology/collision correctness and visible error. Test environmental conservation independently. Adoption records exact version, license, maintenance, portability, binary size and debugging complexity. A small volume proves no planet capacity.