rivencraft/docs/LIVE_BLOCK_INSTABILITY.md

Live block-instability profiling (0.5.8.11–0.5.8.15)

Mystcraft Legacy measures the abundance of watched blocks in generated chunks, compares that abundance with a baseline, and adds only positive excess to the Age's instability. Its InstabilityBlockManager and ChunkProfiler are available in the user's local 0.13.7.06 archive. Legacy's Age-side threshold is more than 400 profiled chunks; its default tolerance is 1.05. The Legacy watched blocks include coal, lapis, iron, emerald, redstone, gold and diamond ores, quartz ore, glowstone, and crystal blocks. Diamond blocks are not on that default list, but are included here at the player's request.

Rivencraft samples up to 1,024 distinct loaded chunks per dimension, at most four per server tick. While a player is in an Age, it also gradually generates unsampled chunks around that Age's spawn and the Overworld spawn, at most one chunk per second across both dimensions, until their minimum sample counts are reached. The Overworld is sampled as the baseline; an Age needs 401 samples and the baseline needs 500 before the live block component contributes points. Counts and sampled chunk positions persist per dimension, preventing reloads from double-counting. For each watched block, Rivencraft compares average blocks per sampled chunk and charges max(0, Age average − 1.05 × Overworld average) × weight, rounded to the nearest point. The block component is capped at 100,000 points.

Legacy weights are used for its watched blocks: coal/lapis 5, iron 60, emerald 200, redstone 250, gold 750, diamond 4,000, quartz/crystal 20, and glowstone 50. Deepslate variants inherit their ore's weight. Modern/high-value extensions include diamond, emerald, gold, iron, raw gold, raw iron and netherite storage blocks, plus ancient debris. Netherite blocks cost 8,000 per excess block per sampled chunk; ancient debris costs 4,000. Modded blocks are not automatically classified as valuable; this avoids charging unknown decorative materials.

The authored score and provider plan remain saved as the Age's immutable base. Only Ages created with instability schema v2 participate; existing v1 Ages retain their previously frozen scores/plans, including neutral pre-scoring Ages. This avoids silently rescoring existing worlds. The live block component creates a deterministic effective score and provider plan from that base plus the persisted profile; new cards can become active as sampled abundance rises. The command /rivencraft age instability shows both the saved base and the currently profiled block component. An unloaded Age has no active profile view until its dimension is loaded again. Turning an effect off does not delete counts or reroll the same effective plan.

This is not byte-for-byte Legacy profiling. Legacy has a spatial accessibility map and two factors per block, actively builds a dummy-world baseline, and can recompute after subsequent chunk profiling. Rivencraft uses a simpler per-chunk abundance metric, a real-world Overworld baseline, a sample/work cap, and a saved authored base so modern servers remain bounded and restart-safe. The greater-than-400-chunk activation delay is retained. Already-explored chunks count when reloaded, but the bounded spawn-area pass can generate additional terrain. A mod that mutates blocks after the chunk-load event may not be reflected in the first sample.

Manual check handed to the player

The first focused GameTest run after adding the chunk-load listener stalled in its initial 50-test batch and was stopped. It is not a passing test result. Do not retry that stalled scenario automatically. In a disposable world:

1. Create one Age with an authored Diamond Block + Rocks (or Floating Islands) combination and a comparison Age using Stone for the same feature. Explore enough distinct chunks in each Age for /rivencraft age instability to show a profiled-block contribution. Explore the Overworld too if its baseline has not reached 400 chunks. The diamond Age should score higher and can gain provider cards; the stone Age should not get a diamond-block contribution.
2. Leave and restart the world. Re-enter both Ages and compare their scores and provider IDs/levels. Reloading old chunks must not increase the sample count or score by itself. Generating more diamond-rich chunks may change the effective score and provider set; disabling instability must suppress their effects without erasing the profile.
3. Check a naturally generated diamond-ore Age without authored diamond-block features. If its ore abundance is near the Overworld baseline, it should receive little or no ore contribution. Check that profiling does not make chunk loading noticeably stall, and report any exception or server hang.

Do not use a valued save for this check. The game jar builds, but live chunk profiling still needs this player-run validation before issue #73 is closed.