RustNotMC/docs/carving.md

Carving

Horizon implements Java Edition 26.3 carving-mask storage and traversal. CarvingMask packs cells in Y/Z/X order into 64-bit words. Its column iterator finds contiguous marked runs and splits them into inclusive vertical intervals, using word scans without allocating a list of individual cells or columns.

try_visit_mut retains vanilla callback behavior: adding cells during traversal changes subsequent run searches, while an already selected run keeps its original boundaries. Callback failures stop immediately and retain prior mutations. Coordinate arithmetic wraps like Java, including positive out-of-range aliases; negative indices return an error. Rust bounds height to 1–4,064 and positive growth to 2^24 bits. Invalid construction and allocation limits are explicit errors.

Run python3 tools/test_carving_mask_parity.py. The local report records 45,742 matching output lines per reference JAR, across 28 fixtures and 6,988 operations. The native CarvingMask supplies all reference results. The corpus includes sparse and fully filled masks, duplicate insertions, word and column boundaries, extreme signed coordinates, positive aliases, negative-index failures, and successful or failing callbacks that add cells during traversal. All corpus indices remain below 2^20. Reference artifacts remain private and source/fixture hashes guard validation.

This comparison covers masks. The combined generation check below also covers neighbor biome selection and carver seeding; complete generated worlds remain pending.

Applying masks to terrain

apply_carving_mask traverses each marked interval from top to bottom, applying an optional caller-supplied predicate before block or aquifer queries. The resolved minecraft:uncarvable tag prevents replacement. Grass and mycelium mark a surface encountered within the current interval, including when the aquifer returns no replacement. Subsequent exposed dirt beneath carved cells is restored through top_material. Block changes update WG heightmaps; fluid postprocessing retains vanilla order and duplicates. Later errors preserve prior effects.

The combined surface-stage report records 6,733,382 matching lines per JAR, including 158 carving passes and 21,757,952 block values across noise filling, surface building and carving. Actual NoiseBasedChunkGenerator.applyCarvingMask supplies the reference results; its existing aquifer is wrapped to trace ordered requests, results and fluid scheduling decisions. The test applies explicit masks, filtered and unfiltered, with grass/mycelium/dirt and uncarvable blocks, repeated writes and disjoint runs. The filter is synthetic; native blending-filter generation remains pending.

Run python3 tools/test_material_stage_parity.py. Unit tests additionally verify that filters and uncarvable tags skip aquifer calls, a surface observation survives an absent aquifer result, and later aquifer failure preserves earlier surface restoration and its fluid postprocessing even when aquifer scheduling is disabled.

Shared shape primitives

carve_ellipsoid visits candidate cells in X/Z/descending-Y order, retaining vanilla's exclusive lower Y bound, Y−0.5 normalization, chunk clipping and ordered skip callbacks. Output failures preserve earlier marked cells. can_reach uses wrapped step differences and float-rounded thickness before double-distance math. Traversal has a 2^24-candidate work bound.

Run python3 tools/test_carving_geometry_parity.py. The geometry report records 106,699 matching lines per JAR, across 690 ellipsoids and 5,536 reachability queries. Actual WorldCarver.carveEllipsoid and canReach supply the reference results. Tests compare normalized skip inputs, marked-cell order, partial failures and final mask intervals, with distant/overflowing coordinates, clipped bounds, degenerate radii, NaNs, infinities and subnormals. NaN trace values are canonicalized. The seeded cave/canyon paths below use these primitives. Gaussian provider codecs remain separate work.

Seeded cave and canyon paths

CaveCarver decodes cave definitions and reproduces start selection, rooms, thickness bias, randomized tunnel movement and branching. CanyonCarver decodes canyon definitions and reproduces height-dependent width factors, varying radii and randomized path movement. Both preserve float/double operation order and vanilla's quantized trigonometry. Their local path RNG is always the legacy algorithm, independently of the caller's outer random mode.

Run python3 tools/test_cave_carver_parity.py and python3 tools/test_canyon_carver_parity.py. The cave report records 882,005 matching lines per JAR across 415 fixtures and 739 requested carve invocations. All three bundled cave definitions are independently imported from both JARs. The canyon report records 1,094,517 matching lines per JAR for the bundled canyon and custom shapes across four generation heights.

The native WorldCarver.DIRECT_CODEC and actual cave/canyon methods supply reference results. Comparisons include ordered cell writes with duplicates, mask intervals, partial output failures and subsequent random longs. Both random modes, repeated invocation, distant/overflowing coordinates and neighboring/far origins are covered. Custom shapes force branching, floor and width variation, degenerate radii and failure boundaries; malformed selected fields are tested.

Rust bounds a cave call to 4,096 starts, a canyon to 4,096 steps and 4,064 width entries, and either call to 2^24 candidate cells through a shared traversal budget. Budget exhaustion retains prior mask writes. Gaussian provider codecs, encoding, blending and complete worlds remain pending; these suites invoke individual carvers directly. The combined stage check covers neighbor selection and seeding.

Biome-selected neighboring carvers

CarverCatalog resolves named and inline carvers while preserving ordered holder lists and repeated references. generate_carving_mask visits the 17×17 origin neighborhood in X/Z order. Each carver receives a legacy random stream initialized from the world seed plus its list ordinal and the origin chunk coordinates, then runs its native start-selection and shape path. The mask clips below the ceiling with vanilla's seven-block allowance, or without that allowance for upgrading chunks. Source errors stop generation before mask application.

The combined stage report includes 42 procedural carving passes through actual NoiseBasedChunkGenerator.generateCarvers, after noise filling and surface work and before the explicit-mask stress passes. Biome selection uses uncached quart queries and retains the source's prior search state from biome filling. Carved surface restoration switches fuzzy lookup to that raw source. All four bundled carvers and all seven terrain settings are available to biome selection; the native biome settings retain actual carver lists with empty placed-feature lists.

Unit tests cover origin order with coordinate overflow, upgrading bounds, invalid bounds before source calls, early source failure and duplicate holder identity. Tagged carver sets, region-neighbor caching, nonempty blending, retrogen integration, placed features and complete generated worlds remain pending.