docs: add Gathering, Infestations, Research and TrialRooms guides

PLATFORM.md

@@ -84,10 +84,12 @@ consumer set. Source builds must pass clean verification before publication.
 | [DrinkBuilder](projects/DrinkBuilder/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Dowsing](projects/Dowsing/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Games](projects/Games/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [Gathering](projects/Gathering/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [GeigerCounters](projects/GeigerCounters/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [GemInfusion](projects/GemInfusion/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Goldsmithing](projects/Goldsmithing/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [GunsAndGadgets](projects/GunsAndGadgets/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [Infestations](projects/Infestations/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [InteractibleFurniture](projects/InteractibleFurniture/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Magic](projects/Magic/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [MarketBlock](projects/MarketBlock/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
@@ -96,13 +98,15 @@ consumer set. Source builds must pass clean verification before publication.
 | [PermCleaner](projects/PermCleaner/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [PointShop](projects/PointShop/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Recycler](projects/Recycler/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [Research](projects/Research/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [RPCharacters](projects/RPCharacters/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [SimpleFactions](projects/SimpleFactions/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Surgery](projects/Surgery/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [TFMCCore](projects/TFMCCore/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [TFMCWeb](projects/TFMCWeb/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Thievery](projects/Thievery/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [TLibs](projects/TLibs/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
+| [TrialRooms](projects/TrialRooms/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [VehicleFramework](projects/VehicleFramework/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [VFBuilders](projects/VFBuilders/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |
 | [Woodworking](projects/Woodworking/README.md) | 21 | `paper-api` | `1.21.10-R0.1-SNAPSHOT` |

README.md

@@ -33,7 +33,9 @@ Choose a project to open its technical documentation and source repository link.
 | [Archaeo](projects/Archaeo/README.md) | Archaeology, hidden ruins, excavation, and fragile finds. |
 | [Cooking](projects/Cooking/README.md) | Interactive cooking stations and custom food crafting. |
 | [Dowsing](projects/Dowsing/README.md) | Resource nodes, production chains, and faction-based gathering. |
+| [Gathering](projects/Gathering/README.md) | Hidden gathering spots, character discovery, and weighted harvest drops. |
 | [GemInfusion](projects/GemInfusion/README.md) | Gem infusion and jewellery crafting mechanics. |
+| [Research](projects/Research/README.md) | Research stations, item experiments, and hidden-recipe discovery. |
 | [Woodworking](projects/Woodworking/README.md) | Woodworking stations, crafting projects, and material quality. |
 
 ### Roleplay and activities
@@ -67,7 +69,9 @@ Choose a project to open its technical documentation and source repository link.
 | Project | What it does |
 | --- | --- |
 | [GunsAndGadgets](projects/GunsAndGadgets/README.md) | Configurable firearms, ammunition, and gadgets. |
+| [Infestations](projects/Infestations/README.md) | Province infestations, ambient monsters, and lure raids. |
 | [SimpleFactions](projects/SimpleFactions/README.md) | Nations, diplomacy, taxation, and ProvinceSystem map integration. |
+| [TrialRooms](projects/TrialRooms/README.md) | Keyed dungeon rooms, levelled MythicMobs encounters, and rarity-rolled loot. |
 | [VehicleFramework](projects/VehicleFramework/README.md) | Configurable vehicles, movement physics, turrets, and weapons. |
 | [VFBuilders](projects/VFBuilders/README.md) | Vehicle construction stations and blueprints for VehicleFramework. |
 | [WorldBorder](projects/WorldBorder/README.md) | Configurable world borders, player warnings, and border damage. |

projects/Gathering/README.md

@@ -0,0 +1,28 @@
+# Gathering
+
+[Source repository](https://github.com/TF-Minecraft/Gathering) · [All projects](../../README.md)
+
+Hidden world gathering spots that roleplay characters discover and harvest for weighted drops.
+
+TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
+
+## Build and dependencies
+
+Gathering builds with Java **21** against
+`io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
+`2.0.1` and RPCharacters `2.0.2` release artifacts with the shared dependency
+installer. The build also prepares checksum-verified MMOCore `1.13.1` and
+MythicLib `1.7` inputs from the private ServerAssets repository.
+
+At runtime, `plugin.yml` requires TLibs and RPCharacters. MMOCore is optional;
+the profession bonus to discovery chance is only applied when that plugin is
+enabled. MythicLib is a compile input only and is not declared in `plugin.yml`.
+
+## Guides
+
+- [Behaviour, configuration, and operations](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts,
+release tags, private dependency access, and release verification.

projects/Gathering/overview.md

@@ -0,0 +1,107 @@
+# Behaviour, configuration, and operations
+
+[Gathering documentation](README.md) · [All projects](../../README.md)
+
+## System model
+
+Gathering places invisible spots on existing surface blocks. A spot records its
+world, block position, spot type, surface material, and the RPCharacters
+characters that have discovered it. Each chunk holds at most one active spot.
+Spots do not expire; a spot stays in place until someone gathers it.
+
+Every `spawn-interval-minutes`, the scheduler makes up to
+`spawn-attempts-per-tick` attempts in each configured world. Each attempt picks a
+random spot type that is below its `max-active` limit and outside its
+`cooldown-minutes` spawn cooldown. It then picks a random chunk within that
+world's bounds and skips it if the chunk already holds a spot, is on cooldown, or
+is excluded. Otherwise, the chunk is loaded and up to `probe-column-attempts`
+random columns are scanned from the top down. The first block that is solid, has
+two air blocks above it, and matches the type's surface block, altitude, and
+biome filters becomes the spot. This can be below the open surface, such as on
+a cave floor. If no column matches, the chunk is excluded for every spot type.
+
+## Configuration files
+
+The plugin copies its defaults into `plugins/Gathering/` on first start.
+
+| File | Purpose |
+| --- | --- |
+| `config.yml` | Spawn interval, attempts, column probes, chunk cooldown, per-world chunk bounds (`worlds.<world>.chunk-x-min` and so on), passive discovery, attribute and profession weights, particle ring, and gather effects. |
+| `categories.yml` | Named drop categories. Each is a `drops` list (or a bare list) of `<item-path> <min>-<max> <weight>` lines. |
+| `spot-types.yml` | Spot types with optional `biome` list, `altitude-min`, `altitude-max`, `spawn-block`, and `particle-dust`, plus `max-active`, `cooldown-minutes`, `profession-id`, and weighted `categories` entries (`id`, `weight`, and `drops` as `N` or `min-max` rolls). |
+
+Item paths are resolved through TLibs, so they use the prefixes understood by
+TLibs and the installed item providers. Biomes use Minecraft biome keys, and
+blocks use Bukkit material names. Unknown biomes, materials, and malformed drop
+lines are logged and skipped. Category references are not checked at load time.
+
+Run `/gathering reload` after editing these files. Reloading re-reads all three
+files but does not restart the scheduled tasks, so changes to
+`spawn-interval-minutes`, `passive-discovery.interval-seconds`, and
+`particles.interval-ticks` only apply after a restart. Existing spots keep their
+spot type identifier.
+
+## Discovery and gathering
+
+Only players with an active RPCharacters character take part. When
+`passive-discovery.enabled` is true, every `interval-seconds` the plugin rolls
+once for each undiscovered spot within `radius` blocks of each such player. The
+chance is `base-chance` plus wisdom × `wisdom-weight`, intelligence ×
+`intelligence-weight`, and, when `profession.enabled` is true and MMOCore is
+enabled, the profession level × `level-weight`. The chance is capped at 100%. The
+profession is the spot type's `profession-id`, or `profession.id` when that is
+not set. On success, the character is recorded against the spot and receives the
+configured message.
+
+Discovered spots within 32 blocks (or `radius`, if larger) show a two-particle
+ring coloured by `particle-dust` or the surface block. Right-clicking the spot's
+block with the main hand gathers it. The plugin chooses one weighted category,
+rolls the configured number of drops from it, and pops the items out of the spot.
+Harvesting a spot removes it and puts its chunk on cooldown for
+`chunk-cooldown-minutes`. If nothing can be rolled, the player sees "Nothing to
+gather here." and the spot remains. Interactions already cancelled by another
+plugin are ignored.
+
+## Commands and permissions
+
+All subcommands require `gathering.admin`, which defaults to operators.
+
+| Command | Effect |
+| --- | --- |
+| `/gathering reload` | Reload `config.yml`, `categories.yml`, and `spot-types.yml`. |
+| `/gathering status` | Show active spots, excluded chunks, and chunks on cooldown. |
+| `/gathering clearcache [world]` | Clear excluded chunks for one world, or for all worlds. |
+| `/gathering forcespawn <spotType> [chunkX chunkZ]` | Probe the player's current chunk, or the given chunk in the player's world, for the type. This ignores world bounds, `max-active`, and cooldowns. A failed probe excludes the chunk. |
+| `/gathering adminmode [on\|off]` | Toggle or set admin mode. Admin mode shows every nearby spot with an extra marker and allows gathering without a discovery or character. |
+
+Admin mode is held in memory and ends when the player leaves or the server stops.
+
+## Persistence and shutdown
+
+- Active spots and their character discoveries are stored in
+  `plugins/Gathering/Data/spots.json`.
+- Chunk cooldowns and excluded chunks, with reasons, are stored in
+  `plugins/Gathering/Data/chunk-cache.json`.
+
+Changed state is written every 60 seconds and again on a normal plugin disable.
+The per-type spawn cooldown is held in memory only and resets on restart. Back up
+the complete `plugins/Gathering/` directory before renaming spot types or
+migrating configuration, and stop the server cleanly before copying live state.
+
+## Validation
+
+For a server-side change, verify the following on Paper 1.21.10 with the pinned
+dependency set:
+
+1. Start with both an empty data directory and a copy of representative existing
+   spot and chunk-cache data.
+2. Confirm all definitions load without unknown biome, material, drop-line, or
+   item-path warnings.
+3. Force-spawn each spot type, and confirm scheduled spawning respects world
+   bounds, `max-active`, type cooldowns, and chunk cooldowns.
+4. Discover a spot with a character, with and without MMOCore, and confirm only
+   that character sees the particle ring.
+5. Gather the spot, and check drops, the chunk cooldown, and `/gathering status`.
+6. Exercise `adminmode`, `clearcache`, and `reload`.
+7. Restart cleanly and confirm spots, discoveries, cooldowns, and excluded chunks
+   are restored.

projects/Infestations/README.md

@@ -0,0 +1,30 @@
+# Infestations
+
+[Source repository](https://github.com/TF-Minecraft/Infestations) · [All projects](../../README.md)
+
+Province-scale MythicMobs infestations with ambient spawning, lure raids, and optional spread between SimpleFactions provinces.
+
+TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
+
+## Build and dependencies
+
+Infestations builds with Java **21** against
+`io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
+`2.0.1`, SimpleFactions `3.0.2`, and InteractibleFurniture `0.2.1` release
+artifacts with the shared dependency installer. The build also prepares a
+checksum-verified MythicMobs `5.8.0-SNAPSHOT` input from the private
+ServerAssets repository.
+
+At runtime, `plugin.yml` requires TLibs, SimpleFactions, MythicMobs,
+ItemsAdder, and InteractibleFurniture. The plugin code does not call ItemsAdder
+directly; the default lure is an ItemsAdder item (`ia.tfmc:lure`) placed as
+InteractibleFurniture.
+
+## Guides
+
+- [Behaviour, configuration, and operations](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts,
+release tags, private dependency access, and release verification.