Hidden ruins, careful excavation, and discoveries with a history.
Archaeo brings archaeological fieldwork to TF-Minecraft. Players follow the sound of a tracker, survey the ground, and establish a camp beside a buried ruin. Finds occupy shapes in the earth: careless digging can damage or destroy them before they ever reach the surface.
- Discovery by sound — tracker pulses guide explorers toward unclaimed ruins, while prospecting confirms a site's location.
- Excavation camps — direct a dig, manage its workers, and follow progress through camp boards and a site dossier.
- Careful digging — different tools, ground layers, and timed sound cues turn each cut into a choice between speed and precision.
- Fragile finds — expose and brush out buried objects whose condition reflects both their age in the ground and damage during excavation.
- Study and preservation — clean recovered pieces, draw field sketches, and register finds at the camp cabinet.
- Museum stories — read the history of displayed finds and keep a field book of a site's discoveries after closing its camp.
Track → Survey → Establish camp → Excavate → Recover → Study and display
Field sketches use WASD to move, sneak to paint, and right-click to erase. Space
opens a 27-colour palette of dyed leather swatches, arranged in nine pigment
columns and three shade rows (light, normal, dark). Choose charcoal, red, ochre,
brown, slate, moss, ivory, turquoise, or violet; clicking a swatch selects it and
closes the palette. Escape keeps the current ink. Switch the map away to save;
left-click and type sign to lock the drawing.
Staff can give any configured artifact with /archaeo give artifact <artifact> <#serial> [player].
Tab completion lists IDs from artifacts.yml, ruin serials, and online players. The player
defaults to the issuer; console must specify one. The command creates one recovered piece,
records it in the selected ruin's archive, and includes that ruin in its item metadata and
label. It uses the configured item pool and conservation rules, and the piece can be studied
at the cabinet as usual. If the inventory is full, the piece drops at the recipient's feet.
Access uses config.yml permissions.staff (default archaeo.admin).
Staff can look up sites with /archaeo ruin list [player|all] [page]. Every row
shows its serial, name, state, and director; click a row to prepare find list
for that serial. Omit the player to list all sites. A player filter includes
sites where any recorded character of that account directed or participated,
including closed digs. This directory never teleports or edits a site.
/archaeo ruin info <name|#serial> opens the camp inventory for staff, including
other players' excavations and closed records. Omit the query while standing in
the ruin or camp chunk. The menu keeps the usual director and staff permissions;
viewing another excavation does not grant director tools. Hidden ruins without
a camp, and commands issued from console, still show the dossier as text.
Staff can inspect and remove individual recovered pieces:
/archaeo find list <#serial> [page]lists recovered pieces and their stored/current item IDs./archaeo find infoinspects the piece in the main hand; add<#serial> <number|uuid>for an explicit record./archaeo find delete <#serial> <number|uuid> confirmbacks up the dossier, deletes that recovered row, and removes matching physical pieces in online inventories and loaded locations. Omitconfirmto preview. Offline inventories and unloaded chunks are not edited./archaeo find restore <#serial> <number|uuid> <player> confirmrecreates a lost or consumed physical item from its existing recovered row, preserving its UUID, inventory number, stored item, condition, and study history. Omitconfirmto preview. The recipient must be online with an empty slot; known copies in online inventories, ender chests, and cursors prevent recovery. Staff must confirm that no stored or offline copy remains. This command does not alter money balances.
See artifact migration and TFMC equivalences before replacing old pieces with give artifact. Reissuing creates a new find; it does not transfer the original study or recovery history.
Technical documentation is maintained in TF-Minecraft/Docs.
With Java 21 and Maven installed, run mvn clean verify. JUnit 4, Mockito and
MockBukkit test domain rules, YAML persistence and plugin workflows. Surefire
results are in target/surefire-reports/. JaCoCo reports all production classes
in target/site/jacoco/index.html and target/site/jacoco/jacoco.xml; no minimum
coverage gate is enforced. The Build workflow uploads both report directories.
The ordinary suite needs no private plugin JARs and does not start a live Paper server. See the testing guide for optional adapter contract tests with ItemsAdder and MMOItems API JARs.
Copyright (c) 2026 TF-Minecraft contributors.
TF-Minecraft-authored material in this repository is licensed under the Artistic License 2.0. Third-party dependencies and bundled material retain their own licenses.