Paper plugin · v1.0.0
Turn ruins into progression
Turn ruins into progression — interact, journal, unlock. Define interaction anchors in YAML, grant journal entries and composable rewards, and broadcast first discoveries to your server Chronicle.
Paper 1.21.1+ · Java 21+
In-game
See it in action
Gameplay demos and screenshots from Paper 1.21 on the Theryn test server — pull physics, config GUI, tier lore, and commands.
Why Discovery Codex
Built for RPG and adventure servers
Most lore plugins hard-code quests or require dev work for every ruin. Discovery Codex gives builders YAML anchors, composable rewards, and a polished journal — battle-tested on the Theryn discovery stack.
Builder-friendly YAML
Define world anchors by coordinates and block type. Reload with /dc reload — no restarts for new ruins or lore drops.
Composable rewards
Grant journal entries, LuckPerms nodes, mcMMO skill XP, Quests flags, console commands, items, or ItemMagnet tiers from a single interaction.
Journal + Chronicle
Players browse discoveries in /journal. First server-wide catalogs broadcast to /chronicle — perfect for shared mystery progression.
Event API
EntryDiscoveredEvent, InteractionCatalogedEvent, GateUnlockedEvent, and RewardGrantedEvent let custom plugins react without forking the core.
Gameplay
For players
- Interaction state machine — sealed → disturbed → cataloged with configurable cooldowns
- Triggers — block right-click, lectern book read, or both
- Journal GUI — paginated discovery log with detail pages
- Chronicle — server-wide first-discovery feed with optional broadcast template
- Codex gates — milestone rules grant permission nodes (LuckPerms)
- Milestone rewards — entry-count thresholds with broadcast and chronicle hooks
- Theryn preset — battle-tested YAML pack shipped in the JAR
Administration
For server owners
- /dc reload — hot-reload entries, interactions, gates, and rewards YAML
- /dc list [radius] — find indexed anchors near staff
- /dc discover <player> <entry-id> — grant entries for testing
- /dc reset <player> — wipe player journal, interactions, gates, and milestones
- Presets — theryn or roll your own config overlay
- PlaceholderAPI — journal count, gate progress, next milestone
Integrations
Works with your stack
Every integration is optional. DiscoveryCodex runs standalone on Paper with no extra plugins required.
LuckPerms
Gate and reward permission grants
PlaceholderAPI
Journal, codex, and milestone placeholders (2.11.6+)
Quests
Quest flag rewards and optional first-entry quest give
mcMMO
Skill point rewards via reflection (softdepend)
WorldGuard
Optional region gating for interactions (softdepend)
CMI
Stat-based gate unlocks and kit rewards
ItemMagnet
Milestone tier unlock + give via Theryn preset
Developer API
Five Bukkit events with stable payloads
Quick start
Up and running in minutes
- 1Download DiscoveryCodex-1.0.0.jar from GitHub Releases or Hangar
- 2Place the JAR in your server's plugins/ folder and restart
- 3Edit plugins/DiscoveryCodex/interactions/*.yml — set world, coords, block, and grants-entries
- 4Run /dc reload and /dc list to verify anchors index correctly
- 5Right-click the anchor (or read the lectern book) — entries appear in /journal
Optional: run /dc config to open the in-game editor.
Requirements
Compatibility
| Server | Paper 1.21.1 or newer (required) |
|---|---|
| Java | 21 or newer |
| Tested on | Paper 1.21.1, 1.21.4, 26.1 |
| Not supported | Spigot, CraftBukkit, Folia |
Paper is required — the plugin uses the Paper API for lectern book-read detection and modern inventory events. Paper is a drop-in replacement for Spigot on most hosts.
Reference
Commands
Staff commands use /discoverycodex — alias /dc. Player commands: /journal, /chronicle
| Command | Permission | Description |
|---|---|---|
| /journal | discoverycodex.journal | Open the discovery journal GUI |
| /chronicle | discoverycodex.chronicle | View the server discovery Chronicle |
| /dc reload | discoverycodex.reload | Reload all YAML catalogs and re-index anchors |
| /dc list [radius] | discoverycodex.list | List interaction anchors near you |
| /dc discover <player> <entry-id> | discoverycodex.discover | Grant a journal entry without visiting an anchor |
| /dc reset <player> | discoverycodex.reset | Reset a player's discovery progress |
LuckPerms
Key permissions
| Node | Default | Purpose |
|---|---|---|
| discoverycodex.journal | true | Open /journal |
| discoverycodex.chronicle | true | Open /chronicle |
| discoverycodex.codex.1–6 | false | Codex volume access (granted by gates) |
| discoverycodex.admin | op | All staff commands |
| discoverycodex.bypass.gates | op | Skip gate evaluation |
Get DiscoveryCodex
Download & documentation
Discovery Codex is free and open source under the MIT license. Grab the latest JAR, read the full docs on GitHub, or install from Hangar.
Help
Request support
Running into a bug or need help configuring DiscoveryCodex? Send us the details — include your Paper version and plugin version if you can. You can also open a GitHub issue.