VoxelForge/Standalone/Research/WorldAssemblerM3/Research10/REPORT.md

# Research R10 — Ore and resources as a material channel

Read-only review; no code or files changed. The GDD asks for recipe-critical resources to be guaranteed by density within reach of the spine, while optional materials remain random and depth-locked by difficulty tier rather than fixed to particular strates. [GDD §9](</home/jahni/VoxelM/Plugins/VoxelForge/GDD.md:209>) The current edit layer changes density only, and its documentation leaves saving and loading to the game layer. [VoxelDiffLayer.h](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Public/VoxelDiffLayer.h:1>)

## Representation choice

**Rank 1 — Bounded vein records in the resolved layout, queried analytically for material.** Treat each vein as immutable, versioned data with a stable ID, resource ID, shape and bounds, material, and yield density. Generate the records before tile jobs, then use a per-tile candidate list to restrict membership checks. This is deterministic, uses memory proportional to the number of veins rather than world voxels, and costs roughly one membership test per nearby candidate. Keep the records separate from density so ore does not alter rock or passage topology. Resolve overlaps by stable ID order.

At exposed mesh points, query the material and blend across a configured vein boundary. Mesh attributes need an explicit material identity and blend weight: current F6 vertex color already carries biome, slope, edge blend, and neighboring-biome data, while F17’s two material groups separate ground from sky-cap. [VoxelMarchingCubesMesher.cpp](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelMarchingCubesMesher.cpp:213>) · [VoxelWorld.cpp](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelWorld.cpp:697>) Far LODs will naturally undersample narrow veins; define a minimum visible feature size or a distance fade so they don’t flicker. Do not create one mesh section per vein.

**Rank 2 — Material IDs stored or sampled per voxel alongside density.** This is conceptually simple, and a joint density/material sample can reuse the mesher’s lattice work. But storing IDs per chunk adds memory, cache invalidation, save/load, and cross-LOD rules. A sampled ID alone also produces hard boundaries; blending still needs boundary distances or weights. If sampled on demand rather than stored, it is effectively the material query in Rank 1, with the vein records still needed as its source.

**Rank 3 — A separate general resource field.** A continuous field can blend smoothly and represent broad concentrations, but adds another evaluation path or sampled volume. A general noise field also makes exact deposit bounds, resource yields, and recipe guarantees harder to author and audit. It may suit diffuse materials later; it is a poor first representation for countable veins.

## Mining and authority

The games point to two useful patterns: material-bearing terrain that yields resources when mined, and deposit objects that produce collectible units. Minecraft’s ore blocks yield specific items, with Fortune affecting yield and Silk Touch preserving the block. Space Engineers maps mined voxel materials to ore types and ratios. 7 Days to Die harvests resources as blocks are damaged or destroyed, with tools affecting mining efficiency. [Minecraft ores](https://minecraft.wiki/w/Ore) · [Space Engineers voxel materials](https://spaceengineers.wiki.gg/wiki/Modding/Reference/SBC/VoxelMaterial_Definition) · [7 Days to Die mining](https://7daystodie.wiki.gg/wiki/Mining)

Deep Rock Galactic makes mining and carrying part of the mission loop: mined veins enter a limited carried inventory, then get deposited or carried to extraction for team rewards. Astroneer’s terrain tool breaks natural deposits into resource nuggets, while automated extractors increase the yield. [DRG pickaxe](https://deeprockgalactic.wiki.gg/wiki/Pickaxe) · [DRG resources](https://deeprockgalactic.wiki.gg/wiki/Minerals) · [Astroneer resources](https://astroneer.wiki.gg/wiki/Atmospheric_Resources) **For VoxelForge, the useful combination is material-bearing rock plus a carry-and-return inventory loop.**

Recommended flow:

1. The client requests a mining action with a unique sequence, brush, and tool.
2. The server validates reach, tool, limits, and sequence; determines which solid material the edit actually removes at a fixed canonical resolution.
3. In one ordered transaction, the server applies the carve and grants yield only for newly removed solid resource material. A repeated request must not award it twice.
4. The server persists the accepted edit and reward, then replicates the edit and result so all players see the same depleted vein. Late joiners load the same edit state.

The current legacy path writes to `DiffLayer` in `AVoxelWorld::ApplyModification`; it is not a mining-reward flow. [VoxelWorld.cpp](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelWorld.cpp:14453>) Core’s edit transaction already has a sequence and digest, but its adapter comment calls that boundary a future authority path. It currently returns a digest and affected tiles, not harvested material. [VoxelWorld.cpp](</home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelWorld.cpp:14659>) · [VoxelForgeCore.h](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:1396>) So persistence, replication, and server-side reward accounting remain game-layer work.

## Contract extension

Add a **companion `materialAt(xUm, yUm, zUm) -> MaterialSample` query** to the immutable evaluator bound to the resolved strate. Return the host material, up to two resource material IDs, and a blend weight. Include a material detail envelope if the mesher needs to suppress or fade veins below a safe LOD size.

Resolve versioned vein records and their stable IDs in the director’s snapshot; give tiles a conservative candidate list. Sample materials at mesh surface vertices and during the mining transaction. Keep density culling certificates density-only: materials do not create geometry, so they should not change solid/air proofs. This extends R6’s immutable, coordinate-stable evaluator contract without adding resource work to every density call. [Research6 §2](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research6/REPORT.md:24>)

For mining, extend the edit result with deterministic removed-material quantities. Calculate them from the before/after solid state at a fixed world resolution; Unreal awards inventory only after the server accepts the edit. This prevents yield from already-air space and makes replay and duplicate-sequence handling auditable.

## Placement and authoring

- Guarantee a minimum reachable density of every recipe-critical material in each **eligible** strate. Keep depth eligibility tagged by difficulty tier, as the GDD specifies; don’t assign every resource to a fixed strate. Measure “reachable” against the spine and feasible side-pocket dig distance, rather than a coordinate promise. [GDD §9](</home/jahni/VoxelM/Plugins/VoxelForge/GDD.md:209>)
- Bias veins along passage routes and toward side pockets, with a mix of visible surface outcrops and material just behind the wall. Keep the clear passage, landings, and landmark footprints open. Use resolved passage and landmark bounds as placement inputs so resource placement follows planned content rather than tile order.
- The owner authors resource definitions and looks, rarity and depth-tier tables, vein size and yield, and guarantee quotas for recipe-critical materials. The Unreal material palette supplies the visual blend and emissive treatment.

## Implementation plan

1. **Core data:** add versioned vein records to the resolved layout, deterministic generation and stable overlap ordering, plus a tile candidate index. Include the records and material-table version in world identity.
2. **Core query:** add `materialAt` and a material detail envelope. Verify repeatability at fixed physical coordinates across worker counts, tile order, and LOD.
3. **Core mesh:** add explicit material IDs and weights to mesh output; sample at surface vertices and blend at boundaries. Leave density and geometry hashes unchanged.
4. **Core mining result:** return removed-material quantities with the edit result, using a fixed canonical sampling resolution and an idempotent edit sequence.
5. **Unreal integration:** connect ore assets and the new mesh stream/material shader; route mining through server validation, edit persistence, reward persistence, and replication. Ensure both supported edit paths use the same authority flow.

## Measurements for implementation

- Material-query and mesh cost versus the density-only baseline; candidate counts by tile; peak vein-index memory; additional bytes per vertex and upload time.
- Material ID and weight repeatability across workers and tile order; density and topology hash parity; boundary consistency across neighboring tiles.
- Ore visibility and popping across LODs, especially for veins near the minimum feature size; boundary blend width at close and far LOD.
- Yield for each brush shape against newly removed solid ore; zero yield from air and no duplicate yield on replay; persistence and late-join agreement.
- Per eligible strate: recipe-critical yield density, distance to spine, travel and dig distance, and counts of blocked passages or overlapping landmark footprints.

## Owner questions

1. Should yield be proportional to newly removed solid resource volume (recommended for freeform carving), or awarded once per deposit?
2. What spine distance and side-pocket digging effort count as “within reach” for recipe guarantees?