rivencraft/docs/RUINS_COMPATIBILITY.md

Optional Ruins template pages (issue #91)

Rivencraft supports Ruins 1.21.1.2NF as an optional mod. When it is installed, every .tml template in Ruins' active config/ruins_config/<generic-or-biome>/ folders receives a separate Ruins page in Rivencraft's creative and JEI page feeds. New templates added to Ruins' config appear after a restart; removing a template makes its page unavailable to new books. With Ruins absent, no Ruins pages or structure integration are active.

An authored Age with Ruins pages is admitted through Ruins' dimension gate. Rivencraft also admits the authored templates through their individual dimensionsToSpawnIn gates, which usually list only overworld and would otherwise prevent them from loading in an Age. Ruins still owns chunk inspection, spawn chance, surface validation, biome pools, and spacing. Rivencraft filters Ruins' weighted template choice to the exact pages in that Age and vetoes an unauthorized template in Ruins' pre-spawn event. A page therefore selects which template may appear; it does not guarantee a structure in every chunk. Manual /testruin placements are unaffected.

Repeating a template page multiplies that template's Ruins selection weight by its page count and adds one spawn attempt per chunk for each duplicate page. The extra attempts are capped at 32 per chunk (or Ruins' configured count if higher). Distinct template pages do not add attempts, and Ruins' spacing and surface checks still apply. As with Rivencraft's standard structure pages, the first three copies of each template are instability-free; each additional copy adds 100 instability. Ruins retains its own biome and surface checks, so the standard structure forced-biome penalty does not apply.

Ruins' event identifies a template only by its filename. If two active folders contain the same .tml basename, Rivencraft cannot distinguish them and disables all Ruins pages for that configuration. Give each template a unique filename to restore support. Ruins must also be able to parse the template and find a suitable surface in the selected biome; a page cannot repair an invalid or biome-incompatible template.

The adapter and dimension/selection mixin are version-sensitive to Ruins 1.21.1.2NF. The published Rivencraft jar does not include Ruins. To include it in a development run, use -PwithRuins=true.

Manual check

1. Start a client with Ruins 1.21.1.2NF and Rivencraft 0.6.9.3. Confirm the Ruins Pages tab contains one page per configured .tml file, and search a distinctive template name in JEI.
2. Bind a new Descriptive Book with a Link Panel, Standard Terrain, a suitable surface biome, and one Ruins page (for example ZombieHut). Enter the Age and explore unvisited chunks. Ruins marks inspected chunks and will not retry chunks explored under the earlier broken build. Only the selected Ruins template should appear. Ruins' own chance and distance settings still determine how far exploration takes.
3. For duplicate weighting, bind an Age with one copy of one template page and three copies of a second template page valid in the same biome. Across enough new candidate chunks, the second should be selected more often relative to the first, and there should be two additional spawn attempts per inspected chunk. Four copies of one template should add 100 instability, visible through the OP Age instability diagnostic, while three copies add none.
4. Make another Age without a Ruins page and confirm Ruins structures do not appear there. Restart the game and confirm the authored Age keeps its page selection. Then remove Ruins and confirm Rivencraft starts normally without a Ruins tab.

The Ruins-enabled GameTest server passed all 90 required tests and loaded the template-dimension and attempt mixins. Its test world was removed afterward. Use the client check above to verify actual Ruins generation and the increased attempt rate.