Grims Deep Discoveries

Setup, settings, and day-to-day running for server owners and admins. Players have their own Player Wiki, and every built-in fossil is in the Fossil List.

Contents: At a glance · Install and update · Permissions · Commands · Launch checklist · Configuration · Fossil packs · Custom art for Java and Bedrock · Professor Flint · Mags Bonewright · Museum chapters · Linked blocks · Menus and mobile players · Economy · Item protection · How discoveries are rolled · Data and backups · Troubleshooting

At a glance

Install and update

1. Stop the server.
2. Put GrimsDeepDiscoveries-0.4.1.jar in plugins/. Never install two copies.
3. Start the server. The plugin creates config.yml, discoveries.db, and a fossils/ folder holding grims_originals.yml and example_pack.yml.example.

Items are ordinary vanilla items with plugin data, and menus are chest-style inventories, so the plugin works with no resource pack. For custom art, see Custom art for Java and Bedrock.

Updating from 0.3.0

Stop the server, back up plugins/GrimsDeepDiscoveries/, replace the JAR, and start.

• Journals, museums, balances, appraisal jobs, linked blocks, and existing fossils keep working with no migration. The 22 original fossils move into fossils/grims_originals.yml with the same ids.
• Your settings are kept, and new sections such as appearance and assembly are added. Any appraisal.seconds-by-species times now override the pack's times.
• Players no longer assemble fragments from their inventory; they hand them to Mags Bonewright. /dig assemble now needs deepdiscoveries.admin.assemble.
• The Primeval Cycad is now trunk, frond, and crown. Cycad trunks from 0.3.0 still work; 0.3.0 roots, fronds, and cones no longer fit any recipe.
• Items made before custom art was installed keep their vanilla look, and gems made with and without art don't stack.

Permissions

Commands

Player commands are in the Player Wiki. Admin commands:

Demo items are ordinary specimens that count toward journals and museums, so use them in a test chapter.

Launch checklist

1. Install the JAR and, for custom art, the pack content and Geyser files. Restart.
2. In config.yml, set mining.worlds, the depth settings, and economy.mode. Restart if you changed the economy mode.
3. Curate fossils/: edit or delete grims_originals.yml, add packs, run /dig packs reload, and fix anything /dig packs reports.
4. Check /dig packs odds at a few depths.
5. Build desks at spawn and link them with dig, flint, bench, museum, and archives. Let visitors interact with those blocks in your region plugin.
6. Test with /dig kit and /dig demo.
7. Before opening, start a clean museum chapter with /dig museum archive <name> and /dig museum confirm.

Configuration

config.yml is commented. /dig reload checks every setting before applying anything: if one is invalid, you get the reason and the old settings stay active. At startup, an invalid file stops the plugin, with the reason in the console. Updates add new settings without changing yours. Durations are whole seconds from 1 to 604800 (seven days).

Mining

Loot and excavation

Pickaxe, Emberforged, and Stonebinder

Flint, Mags, and discovery gravel

The 0.4.1 brushing update requires only a JAR replacement and restart. Existing 0.4.0 texture packs and mappings remain compatible. The assist applies to marked Deep Discoveries gravel, including discoveries made before the update. It does not brush ordinary suspicious blocks. If Paper's internal brush operation is unavailable, one warning with the cause is logged and ordinary brushing remains available. Set discovery-gravel.bedrock-brush-assist: false and /dig reload to disable the assist.

Appearance and economy

Fossil ids in the seconds-by-species settings are bare for the built-in pack (sea_reptile) and pack_id:fossil_id for others (frost_wyrms:wyrm_scale).

Fossil packs

Fossils come from YAML files in fossils/. Each file is a pack; packs load in file-name order and share one drop pool. The full authoring reference is FOSSIL_PACKS.md, included with the plugin.

• Add a pack: drop in a .yml file, run /dig packs reload, and check /dig packs.
• Curate the originals: edit grims_originals.yml, or delete it. It's only created when fossils/ doesn't exist, so a deletion sticks.
• Errors: a file with any error doesn't load, and /dig packs and the console name the setting with "did you mean" suggestions. Unknown settings count as errors, so an indentation slip can't quietly hide a fossil. While the file is still in fossils/, its last good version keeps dropping until you fix it, so a stray comma, quote, tab, or space never takes content away from players.
• Removing a pack: delete its file. Only then do its fossils stop dropping and move to No Longer Collectable. Specimens players own keep working, and adding the file back restores them.
• Removing one fossil: delete its entry from the file. It retires once the file loads cleanly, and a later error in the file won't bring it back.
• Safe changes: names, lore, weights, values, times, location rules, and art. Changing a fossil id or pack id creates a different species.
• Tuning: /dig packs odds [y] shows each fossil's share at a spot. A pack with big weights crowds out the rest.

Custom art for Java and Bedrock

The release's packs/ folder holds art for all 22 fossils, 15 fragments, 4 gems, and all three Prospector's Pick appearances—base, Emberforged, and Stonebinder—under the gdd namespace. Install it before players start finding things:

1. Install the bundle’s gdd content folder in Packforge, run /pf zip, and serve the resulting pack.
2. Copy packs/GrimsDeepDiscoveries-Bedrock-0.4.0.mcpack into Geyser's packs/ folder.
3. Copy packs/geyser/custom_mappings/gdd_items.json into Geyser's custom_mappings/ folder.
4. Set enable-custom-content: true in Geyser's config, restart, and have Bedrock players reconnect.

appearance.item-models decides when items carry the art. Item identity lives in plugin data, never in the look, so changing this never breaks items.

Custom packs bring their own art. Add it to your own pack content, build a Bedrock pack for it, then run /dig packs bedrock. That writes plugins/GrimsDeepDiscoveries/bedrock/gdd_items.json, which covers the built-in art too and replaces the shipped file, plus an item_texture.json for your Bedrock pack.

packs/IDENTIFIERS.md lists every model, base item, Bedrock identifier and texture key. The standalone Java ZIP is useful for checking the art; the server should serve the combined pack.

Professor Flint

Flint's appraisals are saved with a fixed result and a set finish time, so they keep running while players are offline or the server is stopped. Players get a chat message when a job is ready, checked every second, and a reminder when they log in. They collect through his menu, /dig appraisals, or /dig claim <ID>. A finished fossil is never dropped into a full inventory; Flint holds it until the player has space.

Each fossil's time comes from appraisal.seconds-by-species if it's listed there, then the pack's appraisal-seconds, then appraisal.default-seconds. The built-in pack sets Ancient Fern 15, Ammonite 30, Ancient Tooth 45, Ancient Sea Reptile and Primeval Cycad 90, Ancient Ichthyosaur 120, and Woolly Mammoth 150 seconds.

appraisal:
  maximum-pending-per-player: 1
  default-seconds: 30
  seconds-by-species:
    sea_reptile: 3600
    frost_wyrms:wyrm_scale: 600

Changes apply to new jobs; running jobs keep the finish time they were promised. Time depends only on the species, never on the hidden condition.

Mags Bonewright

Players hand fragments to Mags through /dig bench, the bench tile in /dig, or a linked block. She stores each piece until every part of the recipe has arrived.

• Pieces arrive in any order. If she already holds that part, only a better-condition piece replaces it, and the old piece goes back to the player.
• Players can take stored pieces back until the last piece arrives.
• The last piece starts a timed job with a fixed result: the average condition of the pieces, rounded down. Those pieces are used up. Each player has at most one running job per fossil.
• Timers keep running while players are offline or the server is stopped. Players get a chat message when the fossil is done, and a reminder when they log in.
• Finished fossils are never dropped into a full inventory. Mags keeps them until the player has space. Flint still has to appraise them.

assembly:
  default-seconds: 3600
  seconds-by-species:
    woolly_mammoth: 7200
    sea_reptile: 1800

Run /dig reload after editing. Running jobs keep their finish time.

If a pack update removes a part from a recipe, pieces of that part stay on the bench for players to take back. When the remaining pieces already complete the shorter recipe, the fossil's bench screen offers Ask Mags to start. Fossils from a removed pack stay on the bench and still assemble.

/dig assemble <fossil-id> is for testing. It lists the matching fragments in your inventory and the expected condition; /dig assemble <fossil-id> confirm within 60 seconds uses them and gives the fossil immediately.

Museum chapters

• A chapter's list of required fossils is frozen when the chapter opens.
• Donations are permanent and credited by player. Improving an exhibit keeps the earlier donation record and its credit.
• /dig museum archive <name>, then /dig museum confirm, preserves the chapter's exhibits, credits, and dates, and opens a new chapter requiring the fossils loaded right now. Journals, excavation progress, and balances are untouched. A confirmation for a chapter someone already archived is refused.
• After adding packs, startup and /dig packs reload report how many loaded fossils the active chapter doesn't include. Players can't donate those until you archive. Fossils that became No Longer Collectable can still be donated to a chapter that requires them.
• There's no command to delete or roll back a chapter.

Linked blocks

Players can open menus by right-clicking a block at spawn. Look at a solid block within six blocks and run /dig link <kind>:

• Linking never changes the block, but a linked container won't open, so use a decorative block or an empty lectern rather than a chest holding items.
• Links survive restarts. Breaking, burning, or exploding the block, or replacing it with another block, removes the link. Pistons can't move a linked block.
• Protection plugins still apply, so let visitors interact with the block in your region settings.

Menus and mobile players

Every menu has a real input slot beside a paper arrow. Players move items there from their inventory; everything else in the menu is a protected button. Review screens lock the input until the player confirms or cancels. Closing, changing screens, disconnecting, or a normal shutdown returns unsubmitted items, onto the floor if the inventory is full. On death, the input follows keep-inventory. Shift-click, collect-to-cursor, and creative cloning can't pull buttons out.

Touch layout. With GrimsClientChecker installed, players whose menu style is touch get a layout with seven slots per row that avoids the outer columns. Players choose with /gcc menu GrimsDeepDiscoveries <auto|classic|mobile>, and Java clients always get the standard layout. Deep Discoveries asks GrimsClientChecker each time a menu opens and does no device detection of its own.

GrimsClientChecker is a soft dependency. Without it, or if it fails, everyone gets the standard layout and the console gets a warning at most once a minute. Startup and /dig packs report the menu status. Slot maps for both layouts are in MOBILE_UI.md, included with the plugin.

Economy

Changing the mode needs a restart.

Item protection

• Fossils, fragments, gems, and the journal can't be used in crafting tables, crafters, furnaces (to smelt or as fuel), or smithing tables.
• Right-clicking with one never uses the item itself. Chests, doors, and workstations open normally. Blocks that would take or change the held item refuse it: signs, cauldrons, campfires, flower pots, composters, jukeboxes, lecterns, bookshelves and shelves, decorated pots, vaults, spawners, and beehives. With the journal, sneaking opens the menu instead of the block.
• Item frames, villagers, and wandering traders work normally with one in hand, so players can frame fossils and trade. Right-clicking any other entity with one in that hand does nothing, including mobs and armor stands.
• The Prospector's Pickaxe is a normal diamond pickaxe tagged by the plugin. Renaming a pickaxe doesn't tag it, and anvil repair and enchanting work.

How discoveries are rolled

1. Every eligible block broken in an allowed world marks its spot as used, whoever breaks it, so the spot never rolls again.
2. If a Survival player broke it with an eligible pickaxe at or below mining.maximum-y, it counts toward their excavation level and rolls the depth chance: 1.5% at Y32, rising evenly to 6.5% at Y-64 by default.
3. On a discovery, mining.fossil-share (45%) decides whether it tries for a fossil. Otherwise it's a gem.
4. A fossil is picked by weight among the fossils whose location rules match the spot. For an assembled fossil, one of its fragments is picked evenly. If no fossil can drop there, the discovery becomes a gem.
5. Gem and fragment amounts get the excavation bonus.
6. The reward is sealed in suspicious gravel or given directly, depending on mining.delivery.

Never rolls: blocks players placed, blocks formed by lava and water, blocks moved by falling or by mobs, both ends of every piston push, and any spot that already rolled, including after Silk Touch or re-placing the block.

Limits: WorldEdit, schematic pastes, and regeneration plugins that skip block events aren't tracked. A mine-reset plugin would need its reset spots cleared from the used-spot list, which this version doesn't do. Database writes are synchronous, so check performance before launching on a busy mining server.

Data and backups

discoveries.db holds the used block spots, excavation levels, test coins, journals, museum chapters and donations, Flint's jobs, Mags's pieces and jobs, linked blocks, and the fossil index that keeps removed packs' specimens working.

Stop the server and back up the whole plugins/GrimsDeepDiscoveries/ folder, including fossils/. If you must copy while it runs, copy discoveries.db-wal and discoveries.db-shm as well. Buried rewards live in the world's suspicious gravel, so back up worlds and the plugin folder together.

Troubleshooting