RustNotMC/docs/material-rule-libraries.md

Material-rule libraries

MaterialRuleLibrary loads the pinned Java Edition 26.3 rule resources against block-state, condition, noise and density registries. It supports block rules, ordered sequences, conditional rules, terracotta bands, ore veins and nested named rule references. Loading is atomic; missing references, cycles and duplicate canonical names return errors. Limits are 8,192 registered definitions, 65,536 parsed nodes and 256 nested levels.

The library owns a density compiler configured for one world seed and random mode. rule(name) resolves a runtime tree and lazily compiles its density roots. Binding that tree to MaterialConditions performs per-chunk density sampling. named_density(name) shares the compiler with preliminary-surface sampling. compile_router and compile_aquifer bind configurations decoded into the same density registry before it is passed to the library. Their samplers share the material roots' cache namespace, so noise filling and surface application can reuse a worker context. Workers need matching world random settings and separate cached sampler contexts.

Run python3 tools/test_material_rule_library_parity.py. The local report records 678,174 matching output lines per reference JAR, including 665,712 rule applications and 142 codec inputs across 12 fixtures. The test loads all 42 bundled rules, 8 conditions, 55 densities, 64 noises, 67 biome climates and 86 biome tags from both authenticated reference JARs. It also checks synthetic forward references and constant-density ore rules.

Comparisons use actual seeded noise and ore densities, strided chunk caches, scalar fallback, varying biomes/depths/heights, possible-biome sets and distinct context/application coordinates. Surface depth and secondary noise are supplied context inputs; preliminary density is zero to isolate rule evaluation.

The surface stage now applies these rules to chunks. Rule/density encoding, live reload, registry-owner checks and playable integration remain pending. The report establishes this tested scope, not complete vanilla gameplay parity or an FPS improvement.