LOCAL CONSTRUCTION PREVIEW
The land tool makes parcel cost and placement visible before shared state
The land tool starts with camera targeting and a Chunk count. The browser snaps the footprint to canonical 16 × 16 boundaries, shows chunksX × chunksZ and the matching contract requirement, then scans every covered column for equal-height opaque support, fluid, and ten voxels of clearance. A valid selection becomes a translucent land hologram. After registration, a selected NCM3 design is parsed and previewed at one world voxel per design voxel, normally through the building worker with a main-thread fallback.
Rotation is restricted to quarter turns, X and Z offsets remain integers, and a building that extends beyond the registered parcel stays previewable but cannot be submitted. Confirming land reserves the exact MarketUser contract balance and begins BuildSite indexing. These checks avoid obvious bad transactions, but the Building Program does not read the rendered scene, regenerated terrain, or local clearance scan.
Rotation and offsets are allowed; scaling is not.
The browser rejects local obstructions above the selected support surface.
The hologram remains visually distinct and never enters finalized collision.
BUILDSITE AND CHUNK INDEXES
Each purchased Chunk becomes one immutable protected land entry
A BuildSite v3 PDA binds one owner, global configuration, nonzero foundation ID, blank-contract type and count, fixed minimum X and Z, surface Y, width, depth, revision counters, and indexing progress. The Building Program invokes the Chunk Program through a PDA authority to register the same immutable rectangle once in every selected 16 × 16 Chunk. Only after every entry exists does Market consume the reserved contracts and the BuildSite switch from indexing to active.
Chunk indexes reject a different foundation whose XZ rectangle overlaps an existing one. The overlap rule is two-dimensional, so placing a second foundation at another height does not bypass the reservation. The protected mining layer is narrower: a coordinate is protected only when its XZ position lies inside the rectangle and its Y equals surfaceY minus one. The space above is not an immutable column.
An active BuildSite cannot be resized or canceled. If the initial registration stops partway, tag 6 changes only that incomplete site to canceling, removes its registered Chunk entries from the newest index backward, releases the complete reserved contract quantity, returns BuildSite rent to the session payer, and closes the incomplete account. This rollback cannot erase active land or recover already consumed contracts.
DECLARATIVE BUILDING FORMAT
NCM3 describes a bounded building without executing imported code
NCM3 is a compact declarative byte format. It declares dimensions and a bounded sequence of material-bearing construction commands such as boxes, repeats, roof families, trees, and fences. The parser expands those commands into canonical material voxels; it does not evaluate JavaScript or download executable building behavior.
The deployed validator accepts at most 256 voxels on each axis, 4,096 commands, and a total expansion budget of 262,144 operations. It rejects noncanonical or overflowing varints, out-of-bounds command geometry, invalid repeat steps, trailing bytes, and material IDs outside the canonical building allowlist. That bounded envelope makes a compact payload predictable enough to validate and reconstruct without storing a raw dense cube.
The manifest rejects zero length or any larger raw NCM3 payload.
Every command must remain within the declared envelope.
Repeated and procedural commands contribute their bounded expanded work.
ON-CHAIN BUILDING COMMIT
Upload is resumable; activation waits for every byte and every check
Beginning a building revision creates a 160-byte BuildingManifest PDA in uploading state and reserves the next BuildSite revision. The manifest stores owner, global configuration, foundation ID, revision, quarter turns, signed offsets, payload length, expected 32-byte hash, shard count, completion bitmap, and slots. Payload capacity is divided into at most eight BuildingShard PDAs of at most 8,192 bytes each.
Shard writes are sequential and limited to 700 payload bytes per instruction. A dropped wallet request can resume from the shard's uploaded length instead of restarting the entire design. Finalization requires every shard account in exact order, validates every PDA and completed length, reconstructs the ordered payload slices, recomputes SHA-256, parses NCM3, checks footprint and height, then activates both manifest and BuildSite revision in one atomic transaction.
Building upload instructions have no Backpack, material, or land-contract input accounts because the parcel is already active and its contracts were consumed during registration. Finalization proves that authorized bytes form an allowed building and fit that parcel; it does not prove that the owner collected or consumed the wood, stone, or glass represented by those material IDs.
The 65,535-byte payload ceiling fits within the bounded shard set.
Sequential offsets make partially uploaded shards safely resumable.
The program hashes the complete ordered raw NCM3 payload before activation.
CHAIN-NATIVE SPATIAL DISCOVERY
Visible Chunk indexes lead directly to complete building evidence
The client derives FoundationChunk v3 PDAs for the view distance, preload margin, and one extra edge ring. Every valid record is owned by the Chunk Program and points to one BuildSite v3 identity; foundations spanning several Chunks are deduplicated before building work begins.
For an active BuildSite revision, the chain loader derives the BuildingManifest v3 and ordered BuildingShard v2 PDAs. It verifies program ownership, seeds, owner, revision, shard completeness, and the exact 32-byte SHA-256 hash before Chunk.js parses NCM3. No Guardian endpoint, HTTP manifest, or regional digest participates in acceptance.
Verified IndexedDB entries are rehashed before reuse. A stale or tampered cache entry becomes a miss and falls back to direct RPC loading. Already verified buildings remain visible across temporary RPC failures; building sync waits five seconds before retrying, while an unchanged healthy view uses a 60-second refresh window.
HIGH-PERFORMANCE RECONSTRUCTION
Chunk.js turns a verified payload into light, meshes, and collision once
Chunk.js normally sends NCM3 parsing, placement, baked light, and greedy meshing to a dedicated worker; when Worker support is unavailable, the same deterministic operations fall back to the main thread. Placement preserves exact voxel scale, partitions output by canonical 16 × 16 world columns, removes hidden faces even across building Chunk boundaries, and separates opaque from glass or other visual materials. Packed vertices use a 20-byte stride, while collision occupies a compact Uint32Array bit mask instead of a second object per voxel.
Verified chain buildings are scheduled nearest first. Unchanged foundation, revision, hash, rotation, offset, and placement keys reuse previously built mesh data. A new snapshot cancels stale work and discards a replacement whose decode or meshing fails. The desktop cache is capped by both 64 entries and 48 MiB; the current mobile configuration is capped by both 16 entries and 16 MiB. Frustum bounds keep off-screen building Chunks out of the draw list.
Only finalized chain buildings enter the supplemental collision provider, so a player can stand on a building floor and cannot walk through its solid voxels. A local translucent preview neither writes depth nor becomes authoritative collision. Natural support-collapse planning remains a separate conservative terrain-mining feature; it does not simulate building loads, and the Building Program does not validate a structural support graph.
SPATIAL AND PLACEMENT MATH
Whole Chunks determine contract cost; exact voxels determine building fit
The first equation mirrors immutable 16-voxel Chunk registration, contract reservation, and bounded rollback. The second shows centered placement, quarter-turn swap, signed offsets, and the height limit checked when a revision is finalized.
Land-contract cost and immutable Chunk registration
chunksX = width / 16; chunksZ = depth / 16; requiredContracts = N = chunksX × chunksZ; T_register = ceil(N / 4); T_rollback = ceil(registeredChunks / 4)BuildSite v3 requires minX and minZ aligned to 16 and width and depth in complete 16-voxel multiples, including across negative coordinates. Creation reserves exactly N blank land contracts. The program indexes Chunks in stable row-major order with at most four accounts per transaction; the final batch consumes the reservation. Only an incomplete site may roll back, removing already registered entries in reverse order before releasing all N contracts.
- chunksX, chunksZ
- The immutable parcel width and depth measured in complete canonical Chunks.
- requiredContracts
- The exact blank-land balance reserved at creation and consumed only after every Chunk is indexed.
- T_register
- Minimum current four-account batches required after the separate BuildSite creation transaction.
- T_rollback
- Maximum reverse-order cleanup batches needed when an incomplete registration is canceled.
Exact-scale rotated building fit
(Bx, Bz) = (sizeX, sizeZ) if q mod 2 = 0 else (sizeZ, sizeX); ox = floor((Fw - Bx) / 2) + dx; oz = floor((Fd - Bz) / 2) + dz; accept iff 0 <= ox AND ox + Bx <= Fw AND 0 <= oz AND oz + Bz <= Fd AND surfaceY + sizeY - 1 <= maxBuildYA quarter turn swaps the horizontal dimensions but never rescales a voxel. Signed X and Z offsets move the centered origin. Finalization rejects any footprint crossing the protected rectangle or any declared NCM3 envelope above the configured build ceiling, even when the envelope's top layer contains no occupied voxel.
- q
- Quarter-turn count in the range zero through three.
- Fw, Fd
- Active foundation width and depth in world voxels.
- dx, dz
- Signed placement offsets stored in the BuildingManifest.
- Bx, Bz
- Rotated NCM3 footprint dimensions at exact 1:1 scale.
Finalization binds the full payload hash to an exact footprint
Rustprograms/nicechunk_building/src/lib.rs if hash_payload_slices(&payload_slices) != manifest_view.expected_hash {
return Err(NicechunkBuildingError::BuildingHashMismatch.into());
}
let dimensions = validate_ncm3_payload(&payload_slices)?;
let (footprint_width, footprint_depth) = if manifest_view.quarter_turns % 2 == 0 {
(dimensions.x, dimensions.z)
} else {
(dimensions.z, dimensions.x)
};
let max_build_y = i32::from(site.surface_y)
.checked_add(
i32::try_from(dimensions.y).map_err(|_| NicechunkBuildingError::BuildingDoesNotFit)?,
)
.and_then(|value| value.checked_sub(1))
.ok_or(NicechunkBuildingError::BuildingDoesNotFit)?;
if !building_axis_fits(site.width, footprint_width, manifest_view.offset_x)
|| !building_axis_fits(site.depth, footprint_depth, manifest_view.offset_z)
|| max_build_y > i32::from(context.config.max_build_y)
{
return Err(NicechunkBuildingError::BuildingDoesNotFit.into());
}The program reads every complete shard, hashes their ordered payload slices, parses the bounded NCM3 envelope, applies the quarter-turn footprint, and rejects a revision that does not fit before either the manifest or BuildSite becomes active.
Direct discovery requires the complete Building hash
JavaScriptplay/play-chain-buildings.jsexport function buildingMatchesFoundation(building, foundation) {
const fullHash = String(building?.contentHash || "").trim().toLowerCase();
const expectedHash = String(foundation?.contentHash || "").trim().toLowerCase();
return String(building?.foundationId) === String(foundation?.foundationId)
&& String(building?.owner || "") === String(foundation?.owner || "")
&& Number(building?.revision) === Number(foundation?.activeRevision)
&& /^[0-9a-f]{64}$/.test(fullHash)
&& /^[0-9a-f]{64}$/.test(expectedHash)
&& expectedHash !== ZERO_BUILDING_HASH
&& fullHash === expectedHash;
}BuildSite and BuildingManifest must agree on foundation, owner, revision, and the same complete 256-bit hash before the payload enters the verified render set. A truncated relay digest is not accepted.
IMPLEMENTATION EVIDENCE
Where these claims come from
Each claim is intentionally scoped to a concrete implementation path. These references are for verification, not decoration.
play/foundation-controller.js
Implements Chunk-aligned land sizing, contract-cost display, local level-ground, solid-support, fluid, clearance, overlap, hologram, and locked-anchor preflight.
programs/nicechunk_building/src/building.rs
Defines immutable BuildSite v3 land, one-contract-per-Chunk accounting, BuildingManifest v3, BuildingShard v2, exact-fit math, hashing, and bounded NCM3 validation.
programs/nicechunk_building/src/lib.rs
Validates sessions and MarketUser balances, reserves and consumes land contracts, reverses incomplete indexing, writes resumable shards, and atomically activates complete building revisions.
programs/nicechunk_chunk/src/state.rs
Stores per-Chunk foundation indexes, rejects overlapping XZ rectangles, and protects only the canonical support layer.
chunk.js/ncm/blueprint-codec.js
Defines canonical declarative NCM3 commands, varint encoding, material references, and raw Building PDA payload decoding.
chunk.js/construction/building-parser.js
Parses NCM3 without executable imports, preserves one-to-one scale, applies quarter turns and integer offsets, and builds compact placements.
chunk.js/construction/building-mesher.js
Partitions verified buildings into terrain-compatible Chunks with baked light, cross-boundary face removal, greedy quads, packed buffers, visual passes, frustum bounds, and collision masks.
chunk.js/construction/building-mesh-client.js
Runs parse, placement, and meshing in a cancellable, prioritized worker queue with transferable buffers and a main-thread fallback.
play/building-controller.js
Owns exact-scale preview state, fit gating, nearest-first chain meshing, stale-work cancellation, verified collision, and bounded mesh caching.
play/play-chain-foundations.js
Loads a bounded visible ring of FoundationChunk v3 PDAs, resolves BuildSite v3 records, deduplicates multi-Chunk land, and exposes only verified nearby foundations.
src/chain/nicechunkChain.js
Loads active BuildingManifest and shard PDAs, reconstructs ordered payloads, verifies complete SHA-256 values, decodes BuildSites, and submits staged foundation and building transactions.
play/play-chain-buildings.js
Filters, caches, and applies buildings whose foundation, owner, revision, and complete content hash match verified on-chain land, and rehashes cached payload bytes before reuse.