EvaluatedApplications.HoloVoxel 1.5.2

HoloVoxel

Beta. The public API may change between versions while we improve it. Breaking changes always come with a new major version, and the release notes say what changed.

A holographic voxel/spatial engine for .NET, built on the Phasor VSA codec. The spatial sibling of HoloDb: where HoloDb stores tables holographically, HoloVoxel stores 3D space. Engine only — no rendering/graphics dependency, headless-verified; you supply the palette and the renderer.

No feature below is gated behind a tier or a license key — every type and method is available to every caller. No source or separate docs ship with the package; this file is the complete reference.

The idea

A chunk of the world is a single Phasor superposition — every voxel bound as position ⊗ content and summed — not an array of voxels. Reading a voxel is a correlation. Reading it with fewer components gives a cheaper, fuzzier result, so level-of-detail is the readout itself, not a downsample:

• Near = full component budget → the correlation collapses to a single crisp voxel.
• Far = a few components → the interference of everything that might be there blends into a soft, cheap blur.

"Crisp near, dreamy far" is continuous, with no discrete LOD meshes and no popping. The same dial is detail, compute, and (if you stream it) network bytes.

Table of contents

• Quick start
• Gotchas up front
• Block / Blocks — the palette
• IWorldSource — the terrain oracle interface
• WorldGen — the built-in procedural generator
• Ring — flat ↔ cylinder warp
• HoloWorld — the world / chunk cache
• Chunk — one chunk's hologram, decode paths
• Lod — distance budget + confidence-adaptive budget + spatial smoothing
• HoloModel / ModelVoxel / Creatures — entities
• Value types: Voxel, VoxelColor, SurfaceMesh
• Obsolete / removed API
• License

Quick start

dotnet add package EvaluatedApplications.HoloVoxel

using HoloVoxel.Core;

var world = new HoloWorld(seed: 2024);
foreach (var v in world.GetChunk(0, 0).DecodeField(step: 1, components: world.Comps))
    DrawCube(v.X, v.Y, v.Z, v.Size, v.R, v.G, v.B);   // crisp, full budget: 256 surface cells for a 16x16 chunk

// a distant chunk, decoded cheaply/fuzzily:
foreach (var v in world.GetChunk(40, 0).DecodeField(step: 8, components: 40)) DrawBlob(v);

Gotchas up front

• Coordinates. World/column coordinates (x, z) are integer world units; y is up. Chunk coordinates (cx, cz) are chunk indices, not world units — world column (cx*16 + lx, cz*16 + lz). A chunk's local index space (used by PosFace-keyed APIs like ModelVoxel) is bounded: lx,lz in [0, HoloWorld.ChunkSize) = [0,16), dy/y in [0, HoloWorld.MaxLayers) = [0,12). A HoloModel/Creatures voxel outside that box silently aliases another position's face — keep every voxel inside it.
• Chunk size is fixed. HoloWorld.ChunkSize (16 columns/side) and HoloWorld.ChunkDepth (4 buried layers per column on a full build) are const, not constructor parameters — every chunk in a HoloWorld is the same size.
• LOD semantics: near = crisp, far = fuzzy, and chunks only ever get FINER. Chunk.EnsureStep/ HoloWorld.GetChunkAt never coarsen an already-finer chunk — a finer hologram already contains every coarser grid position, so decoding at step >= BuildStep is always valid; decoding at step < BuildStep is not. Decode components/k is clamped to [8, storedWidth] everywhere — asking for fewer than 8 still reads 8.
• Truncated holograms are lossless up to their stored width. A chunk stores only as many components as it was last built/refined for (EnsureStep's comps); reading the first k ≤ that width is bit-identical to reading a full-width store. It never holds more detail than it was asked to.
• Chunk.Decode/Chunk.Accuracy require a full (step == 1) build — they read the per-cell ground truth kept only by a full build (headless verification / argmax use, not the renderer's job).
• Chunk.FieldConfidence is empty for any chunk whose per-cell truth wasn't kept — that includes every wall chunk AND any chunk whose first build was coarse (step > 1; coarse builds keep no per-cell truth, only the averaged hologram). For a genuine confidence signal, build/decode at step = 1 and vary components alone.
• Thread-safety. Call HoloWorld.Prewarm() once, single-threaded, before any concurrent chunk work — it fills the bounded position/block face caches up front; after that they're read-only, so parallel GetChunk/GetChunkAt/decode calls are lock-free and race-free. WorldGen.BuildMaze is the same shape: call once on the main thread (after setting XPeriod, before parallel decode) — it precomputes a read-only passage set. Skipping either under concurrent load races a dictionary/field.
• Memory scales with decoded detail, not world size. A chunk's hologram is 2 * storedWidth doubles regardless of how many voxels it represents — a far chunk decoded at components = 40 costs a fraction of a near chunk's storage, because that's literally all it was ever built with.
• The softmax sharpness (Beta = 11.0) that turns the interference blend crisp near / fuzzy far is an internal constant, not a public knob — it is not exposed for tuning.

Block / Blocks

The block palette. Block is a byte enum; Air is never stored (it's the absence of a voxel, not a material).

Block b = Block.Stone;
Console.WriteLine($"{b} = {(byte)b}, name={Blocks.Name[(int)b]}");       // Stone = 3, name=stone
Console.WriteLine(Blocks.Decodable.Length);                              // 8 (every Block except Air)
var (r, g, bl) = Blocks.Color[(int)Block.Grass];                         // 0.37, 0.69, 0.33

IWorldSource

The terrain oracle a Chunk pulls content through — a pure function of column/cell coordinates. WorldGen is the built-in implementation; implement this yourself (a tile map, a save file, an in-memory edit buffer) and hand it to HoloWorld's source constructor overload to drive the same cached, holographic-LOD engine from your own world data.

sealed class FlatWorldSource : IWorldSource
{
    public int Height(int x, int z) => 20;
    public Block SolidAt(int x, int y, int z, int height) => y == height ? Block.Grass : Block.Stone;
    public bool IsWall(int x, int z) => false;
    public int WallHeight(int x, int z) => 0;
}

var flatWorld = new HoloWorld(new FlatWorldSource(), seed: 1);
Console.WriteLine(flatWorld.GetChunk(0, 0).VoxelCount);   // 1024 (16x16 columns x ChunkDepth=4)

WorldGen

The built-in procedural generator (IWorldSource): wave-based continental/temperature fields select a Biome, drive Height/SolidAt, and an optional maze of wall structures crosses the land.

var gen = new WorldGen(seed: 7);
Console.WriteLine($"{gen.Seed} {WorldGen.SeaLevel}");          // 7 22
Console.WriteLine($"{gen.BiomeAt(0, 0)} {gen.Height(0, 0)}");  // e.g. Desert 49

gen.Arena = true;                               // flat, gentle sandbox terrain
Console.WriteLine(gen.Height(0, 0));             // e.g. 21

var race = new WorldGen(seed: 7) { RaceMode = true, NoWalls = true };  // rolling hills + mountain lobes, no maze
Console.WriteLine($"{race.Height(0, 0)} {race.IsWall(16, 0)}");        // e.g. 38 False

var ring = new WorldGen(seed: 7) { XPeriod = 2048 };   // x wraps seamlessly every 2048 world units
ring.BuildMaze(around: 64, zHalfCells: 8);             // call once, main thread, before any parallel decode
Console.WriteLine($"{WorldGen.MazeCell} {ring.IsWall(16, 0)} {ring.WallHeight(16, 0)}");  // 16 True e.g. 64

Ring

A pure render-space warp: bends flat world space onto the inside of a cylindrical ringworld. The holographic engine still stores/decodes flat chunks — only the final camera/vertex positions are bent, so streaming and chunk logic are unaffected.

var ring = new Ring(radius: 500);
var onRing = ring.ToRing(x: 100, y: 5, z: 0);          // flat -> 3D ring position
var backToFlat = ring.ToFlat(onRing.X, onRing.Y, onRing.Z);  // 3D ring position -> flat (x,z), e.g. (100, 0)

HoloWorld

The world: a cache of Chunks generated on demand, the shared codec, and the shared position/block face tables every chunk binds into.

var world = new HoloWorld(seed: 2024);               // built-in WorldGen, codec width (Dim) defaults to 16384
// var world2 = new HoloWorld(mySource, seed: 2024);  // or drive it from your own IWorldSource

Console.WriteLine($"{HoloWorld.ChunkSize} {HoloWorld.ChunkDepth} {HoloWorld.MaxLayers}");  // 16 4 12
Console.WriteLine($"{world.Comps} {world.Gen.Seed} {ReferenceEquals(world.Source, world.Gen)}"); // 8192 2024 True

world.Prewarm();                                      // fill shared caches BEFORE any parallel chunk work
var chunk = world.GetChunk(0, 0);                      // full-budget chunk at (0,0)
var coarse = world.GetChunkAt(cx: 0, cz: 0, step: 1, comps: world.Comps);  // create-coarse-or-refine
world.Invalidate(0, 0);                                // drop from cache (editable sources: terrain changed)

var (acc, bytes) = world.CapacityProbe(n: 200, palette: 8, budget: 1024, seed: 1);
Console.WriteLine($"{acc:F1}% {bytes}B");              // e.g. 90.0% 16384B

Chunk

One chunk's hologram, at whatever fidelity it was last built/refined to. Obtained from HoloWorld.GetChunk/ GetChunkAt — there is no public reason to new Chunk(...) directly (the constructor is public but HoloWorld is the intended entry point; it takes a HoloWorld instance as a required argument).

chunk.EnsureStep(step: 1, comps: world.Comps);   // refine to at least this fidelity (never coarsens)
Console.WriteLine($"{chunk.Cx} {chunk.Cz} {chunk.BuildStep} {chunk.IsWallCell} {chunk.VoxelCount}");

// colour field (softmax-blended material per cell — crisp near, interference-blurred far)
foreach (var v in chunk.DecodeField(step: 1, components: world.Comps)) { /* v.X,Y,Z,Size,R,G,B */ }

// triangulated surface mesh with analytic per-vertex normals + holographic colour
var mesh = chunk.DecodeMesh(step: 1, components: world.Comps);
Console.WriteLine($"{mesh.VertexCount} {mesh.TriangleCount}");   // e.g. 289 512

// split geometry from colour so a GPU/accelerator can supply the material blend itself
int[] faceIdx = chunk.MeshFaceIndices(step: 1);                  // dy==0 position-face index per mesh vertex
var colors = new float[faceIdx.Length * 3];                      // caller/GPU fills r,g,b per vertex...
var meshFromColors = chunk.DecodeMeshWithColors(step: 1, colors: colors);

// per-surface-cell softmax readout confidence (the adaptive-LOD ambiguity signal)
var confidence = chunk.FieldConfidence(components: world.Comps);  // List<(int X, int Z, float Confidence)>

// argmax decode + ground-truth accuracy — full (step==1) builds only, for headless verification
var decoded = chunk.Decode(components: world.Comps);               // List<Voxel>
double accFull = chunk.Accuracy(world.Comps);                      // e.g. 98.5
double acc48   = chunk.Accuracy(48);                                // e.g. 19.1 (fuzzier at a lower budget)

Lod

Pure functions for distance-based and confidence-adaptive component budgets, and spatial smoothing for far decode — no Chunk/HoloWorld access; scheduling policy (when/how often to apply them) is the caller's.

int comps = Lod.Components(distance: 200, maxComps: world.Comps);   // e.g. 160 — nearDist=28, exponent=2.0, min=24 by default
float h = Lod.SmoothHeight(world.Source, wx: 100, wz: 0, step: 8);  // footprint-averaged height (<=4x4=16 taps); step<=1 is the exact point sample

var confidence = chunk.FieldConfidence(world.Comps);
float avg = Lod.AverageConfidence(confidence, c => c.Confidence);   // works on Chunk's 3-tuple or HoloModel's 4-tuple via the selector; empty field -> 1

int adaptive = Lod.AdaptiveComponents(baseComps: comps, avgConfidence: avg, maxComps: world.Comps);
// unchanged at/above confidenceFloor (default 0.35); boosted toward maxComps below it; NEVER less than baseComps

HoloModel / ModelVoxel / Creatures

An entity (creature/prop) stored the same holographic way as a chunk: one small hologram, built once from an explicit voxel list and a named palette, decoded through the identical LOD/confidence math as terrain.

// ready-made examples
var (wraithVoxels, wraithPalette) = Creatures.Wraith();     // ~7x11x2 voxel humanoid, 3-material palette
var wraith = new HoloModel(world, wraithVoxels, wraithPalette);
Console.WriteLine($"({wraith.MinX},{wraith.MinY},{wraith.MinZ})..({wraith.MaxX},{wraith.MaxY},{wraith.MaxZ})");

var field = wraith.Decode(step: 1, components: world.Comps);         // List<VoxelColor>, local voxel coords
var conf  = wraith.FieldConfidence(components: world.Comps);          // List<(int X, int Y, int Z, float Confidence)>

var (crystalVoxels, crystalPalette) = Creatures.Crystal();            // single-material gem octahedron
var crystal = new HoloModel(world, crystalVoxels, crystalPalette);
Console.WriteLine(crystal.FieldConfidence(world.Comps)[0].Confidence); // 1 (single material = unambiguous by construction, not +Infinity)

// your own model, built directly from ModelVoxel + a palette
var voxels = new List<ModelVoxel> { new ModelVoxel(0, 0, 0, 0), new ModelVoxel(1, 0, 0, 0) };
var palette = new List<(string name, (float r, float g, float b) color)> { ("probe.mat", (1f, 0f, 0f)) };
var custom = new HoloModel(world, voxels, palette);

Value types: Voxel, VoxelColor, SurfaceMesh

// Voxel — Chunk.Decode's argmax result
// readonly record struct Voxel(int X, int Y, int Z, Block Block, float Confidence, int Size = 1)

// VoxelColor — DecodeField/HoloModel.Decode's blended-field render cell
// readonly record struct VoxelColor(int X, int Y, int Z, int Size, float R, float G, float B)

// SurfaceMesh — DecodeMesh/DecodeMeshWithColors's triangulated output
var mesh = chunk.DecodeMesh(step: 1, components: world.Comps);
Console.WriteLine($"{mesh.VertexCount} verts, {mesh.TriangleCount} tris");
float[] pos = mesh.Positions;   // 3 floats/vertex
float[] nrm = mesh.Normals;     // 3 floats/vertex, analytic (height-gradient) normals
float[] col = mesh.Colors;      // 3 floats/vertex, holographic material blend
int[] idx = mesh.Indices;       // 3 per triangle

Obsolete / removed API

None. Every public member in this version is current; nothing is marked [Obsolete].

License

Proprietary — this package ships the compiled library only; see LICENSE for the full terms. Installing and using unmodified copies for internal evaluation and non-commercial development or testing is licensed; commercial, production, or revenue-generating use requires a separate commercial licence from the owner. No feature on this page is gated behind a tier or a licence key — every capability described works identically with or without one. Copyright (c) 2026 Dongyang Stephen Chen, trading as Evaluated Applications. All rights reserved.