rivencraft/docs/GAMETESTS.md

# GameTest suites

The default dedicated-server run is a small smoke suite. Its Rivencraft tests
cover core linking, deterministic Age definition, writing persistence, legacy
data migration, workstation transactions, and forged/replayed menu actions.

```shell
./gradlew runGameTestServer
```

The remaining Rivencraft tests are archived, not deleted. They cover
completed milestone details such as every Age terrain profile, Notebook and
Desk surface interactions, refill edge cases, book assembly controls, and
workstation break/drop behavior. Run only the relevant archive alongside the
core tests when investigating an issue:

```shell
./gradlew runGameTestServer -ParchivedGameTestSuites=desk
./gradlew runGameTestServer -ParchivedGameTestSuites=grammar,binder
```

Available suite names are `linking`, `environment`, `writing`, `grammar`, `desk`,
`binder`, `mixer`, and `recipe`. Run all Rivencraft tests before a
release or after broad cross-system changes:

```shell
./gradlew runGameTestServer -PwithArchivedGameTests=true
```

Each archive is selected by its `rivencraft_archive_<suite>` GameTest namespace.
The suites share the normal empty test structure and do not need Create, Ponder, or
Immersive Portals. The core suite delegates to the original regression methods
for its selected cases, so the two suites do not maintain duplicate test logic.

GameTest Ages are created in `build/gametest-run/world`, not in a development
client save. Every default GameTest invocation starts with a fresh world.
Minecraft 1.21.1's GameTest server uses the fixed seed `0`. Gradle deletes the
world after every run, whether tests pass or fail. A forcibly killed run may
leave `world` behind; the next run deletes it before starting.
Logs and configuration remain available. Cleanup never targets a custom
`-PgameTestRunDir` or a player world; callers using a custom directory manage
it themselves. The full suite should still be run
before shipping changes in the archived systems.

If a new GameTest stalls the server, stop that run, remove the offending
automated check, and hand its exact scenario to the player for in-game
verification. Do not keep retrying a stalled test or leave its process running.
Keep the narrower non-stalling plan, persistence, and runtime checks automated.

For issue #41, the combined archive and the focused `linking` archive initially
stalled during the multi-profile travel acceptance test. That test is no longer
registered with GameTest; the rerun passed all 116 registered tests before the
subsequent random-biome-count adjustment. The 51-test core suite passes after
that adjustment, but the full archive stalled again late in its first batch;
do not treat that interrupted run as a pass. Verify its
scenario manually: in a fresh world, bind
one Descriptive Book for each of Standard, Flat, Amplified, Island, Cave, and
Void terrain (use the corresponding Terrain Page to select each one). Visit
each Age, confirm a safe arrival platform and headroom, and
travel back using a bound Linking Book. The narrower creation, persistence,
terrain, and travel checks remain automated. See
[random Age weights](RANDOM_AGE_WEIGHTS.md) for the Legacy rank mapping and
the opt-in weighting regression.

Also bind several Link-Panel-only Descriptive Books with no authored biome
pages. Check that each Age retains its biome set after leaving, unloading, and
reopening it, and that the selected biome count varies between Ages without
exceeding the eligible pool. This covers the bounded random-biome path touched
after the last successful full-archive run.

The optional `-PwithSereneSeasons=true` runtime is for a real dev client, not
the GameTest server: Serene Seasons sends a season payload to GameTest mock
players, which cannot negotiate its channel. Follow the real-client Serene test in
`docs/SERENE_SEASONS_COMPATIBILITY.md` instead.

## Manual Ink Mixer modifier check (Milestone 5, issue #36)

With optional JEI installed, search for the Ink Mixer category. It should show
the base paper/ink/vial operation and separate entries for Gunpowder, Mushroom
Stew, Experience Bottle, Ender Pearl, Feather, and Fire Charge,
with their property chances. Black Dye and Clay Ball should not appear: the
former had no working Legacy effect, while Generate Platform is redundant
with default Age arrival. Without JEI, Rivencraft should still
start and the mixer should work normally.

Put paper and an Ink Vial in the mixer. Hold Gunpowder on the cursor and
right-click the ink basin once; one Gunpowder should be consumed, and hovering
the basin should show a 20% Disarm chance. Black Dye, Clay Balls, and an
unrelated item such as Stone should remain untouched.
Closing and reopening the mixer should retain the chance. Taking a Link Panel
should consume one paper and one full Ink Vial, clear the current
mixture, and possibly give a panel with Disarm on its tooltip. Repeat until
a property-bearing panel appears, craft it with leather, and confirm the
unwritten Linking Book preserves the property tooltip. After binding it,
link to another dimension; inventory items should drop at the departure point.
With twenty Ender Pearls added to a fresh mixture, both Disarm and Intra
Linking should show about 96.1%, and the basin should animate both property
colors. Taking a panel should reset all three percentages and clear the color
effect; a near-certain modifier should show the brighter outer animation.
Also bind a Descriptive Book with a Disarm panel and check the same drop behavior.
Bind a Descriptive Book with both Intra Linking and Maintain Momentum on its
panel: the assembled book should retain Maintain Momentum but omit Intra
Linking. For Linking Books, try an unmodified book whose destination is the
current dimension: it should refuse travel. A Linking Book with Intra Linking
should work in the same dimension. A Descriptive Book does not require or use
Intra Linking, even if an older book retained that flag.
Automatic Return Links should still appear according to the existing setting
and work from an Age back to the Overworld. A full player inventory or blocked glass-bottle slot
must not duplicate or consume materials for an output that cannot be taken.

Link Panels should not enter Notebooks (folders) or Writing Desk tabs, whether
clicked, shift-clicked, or dragged onto the page surface. An old Notebook or
Desk already holding a Link Panel should still let the player take it out,
but the Desk must not offer a copy of it. The Desk should continue to copy
ordinary symbol Pages; JEI should show that example instead of Link Panel copying.

## Manual Age unload/reload check

The automated suite does not unload a freshly generated Age. Minecraft can
queue point-of-interest block updates after generation; closing that Age's
region storage while a queued update is still pending can leave the dedicated
GameTest server waiting forever in `SectionStorage.readColumn`. Plan save/load,
terrain generation, and safe spawn remain automated; runtime unload/reload is
checked in a normal game session:

1. Back up the test world. Bind one Link-Panel-only Descriptive Book and one
   Descriptive Book with a terrain page (for example, Island), using distinct
   names. Bring a working way back to the Overworld.
2. Travel through each book, confirm the named Age and expected terrain, then
   return to the Overworld. Close book screens and wait a few seconds.
3. With cheats enabled, run `/rivencraft age list` and record each Age's
   `rivencraft:age/...` dimension ID. Run `/rivencraft age unload <dimension>`
   for one Age at a time, then list again to confirm it is unloaded.
4. Reopen the same Descriptive Books and travel back. Confirm each book reaches
   its original Age, the terrain and safe arrival remain intact, and no extra
   Age entry was created. Save, restart the world, and repeat the book check.

## Manual feature-generation check (Milestone 5, issue #35)

The automated suite verifies feature pages, compiled and saved feature IDs,
vanilla registry mappings, unsupported combinations, and the runtime generator.
An automated scan across many newly generated chunks stalled the GameTest
server, so physical placement is handed to the player for in-game verification:

1. In a fresh world, bind a Descriptive Book with Link Panel, Standard Terrain,
   Plains Biome, Single Biome, Caves, and Rocks pages in that order.
   Missing weather/lighting/celestial branches may be seed-filled. Travel to
   the Age and explore several fresh surface chunks: boulders made from one
   seed-selected full-collision block should appear among the plains terrain.
   Then explore underground in fresh
   chunks; the Caves page should add a second cave-carving pass to Standard
   terrain, not switch the Age to Cave terrain.
2. Make a second book with Flat Terrain and Caves. The Binder should mark the
   Caves page unsupported and prevent assembly. Cave Terrain plus Caves should
   be accepted; Cave Terrain plus Rocks should be rejected.
3. Return, save, and restart the world. Re-enter the first Age and explore
   *new* chunks. The authored decorations should continue without rebinding.
   Previously generated chunks are intentionally unchanged.
4. Title-derived terrain regression (with Create installed): with no Terrain Page, assemble Link Panel,
   Glowstone, Rocks, Chocolate, Small Lakes in that order and name the Age
   `glow`. The Binder should accept it and generate compatible surface terrain;
   Glowstone should be the rock material and Chocolate should appear in authored
   Small Lakes across fresh chunks. Ordinary vanilla lava lakes may still occur.
   Repeat
   with `gl` or `glo` to confirm names do not change page validity. An explicit
   Flat or Cave Terrain Page with Rocks should still be rejected.