RPG Lore

Turn exploration, combat, loot, and progression into opportunities to discover the history of your world.

RPG Lore is a data-driven lore and collectible book system for Minecraft. It lets modpack authors and server owners create custom books that players can discover naturally throughout their adventures, without requiring any custom Java code.

Lore books can drop from specific mobs, appear in selected loot tables, or be awarded through advancements. Players collect their discoveries in the Lore Codex, a persistent personal library with searching, categories, favorites, unread tracking, discovery hints, and more.

Whether you want scattered journals in dungeon chests, histories carried by ancient enemies, bestiary entries earned through combat, or an entire collectible library documenting your modpack's world, RPG Lore provides the tools to build it.

Features

Data-Driven Lore Books

Every lore book is defined through JSON, making RPG Lore especially suited for modpacks, adventure maps, and multiplayer servers.

Books can include:

• Custom titles and authors
• Any number of readable pages
• Plain text or Minecraft JSON text components
• Custom title, author, and description colors
• Optional descriptions
• Categories and searchable tags
• Series names and ordering
• Discovery hints
• Optional enchantment glint
• Original, Copy, Copy of Copy, and Tattered generations
• Per-book selection weights
• Optional exclusion from the Lore Codex

Definitions can be placed directly in:

config/rpg_lore/books/

RPG Lore also supports books supplied through datapacks:

data/<namespace>/rpg_lore/books/<path>.json

This makes lore packs distributable independently of the server's local configuration.

Multiple Ways to Discover Lore

A book is not limited to a single source. Multiple acquisition rules can be combined on the same entry.

Mob Drops

Books can drop from defeated entities with detailed conditions based on:

• Entity type
• Entity tags
• Biome
• Biome tags
• Dimension
• Y level
• Time of day
• Weather
• Whether a player made the kill
• Individual drop chance
• Per-player copy limits

Server owners can also configure global drop chances, maximum books per kill, Looting scaling, hostile-only drops, and other behavior.

Loot Tables

Lore can appear naturally inside selected Minecraft or modded loot tables, including locations such as:

• Dungeon chests
• Structures
• Fishing loot
• Other gameplay loot tables

Chance and selection weight can be configured separately for each rule.

Advancements

Books can be awarded when players earn selected advancements.

An advancement can either:

• Add the book directly to the player's Codex
• Give the player a physical copy

This makes lore useful as a reward for exploration, milestones, bosses, quests, or progression systems.

The Lore Codex

The Lore Codex is a personal collection that keeps discovered lore organized without filling the player's inventory with books.

By default, players receive one when they first join a world.

The Codex includes:

• A searchable library of discovered books
• Search across titles, authors, categories, and tags
• Category browsing
• Collected, Unread, Favorites, and Missing filters
• Sorting by default order, title, category, or recent discovery
• Persistent favorite books
• Persistent read and unread status
• Discovery timestamps
• Optional hints for undiscovered entries
• Series information
• Keyboard navigation
• Preserved search and browsing state after reading a book
• An optional keybind for opening the Codex directly

The Codex is soul-bound by default, so it stays with the player through death and cannot normally be dropped.

These behaviors can be changed through configuration.

Duplicate and Spare Copies

The first copy of a lore book becomes the player's permanent master entry.

Additional copies can be stored inside the Codex as spares, preventing duplicate books from cluttering the inventory.

Spare copies can later be extracted as physical books. Extracting a copy increases its book generation while leaving the permanent master entry untouched.

Players can also choose to leave duplicate books on the ground instead of storing them.

Physical Books Still Matter

RPG Lore does not replace physical books entirely.

Lore books can still exist as items and can be:

• Dropped into the world
• Extracted from the Codex
• Placed on Lecterns
• Stored in Chiseled Bookshelves
• Read through RPG Lore's custom book interface

The Lore Codex itself can also be stored in Chiseled Bookshelves or placed on a Lectern.

Interactive Book Content

Lore pages support Minecraft text components for more advanced presentation.

Pack authors can create:

• Hover text
• Clickable page navigation
• URLs
• Copy-to-clipboard actions
• Suggested commands
• Optional command-running interactions

For security, run_command click actions are disabled by default and must be explicitly enabled by the server.

Built for Modpacks and Servers

RPG Lore is designed to make large lore collections manageable.

Hot Reloading

Config-based books can be changed without restarting the server:

/rpglore reload

A normal Minecraft /reload also reloads datapack lore.

Validation Tools

Before deploying a large lore pack, use:

/rpglore validate

or:

/rpglore validate <book_id>

Validation checks for problems such as:

• Invalid JSON
• Unknown fields
• Incorrect field types
• Invalid values
• Unsupported format versions

Diagnostics provide useful paths and location information to make broken definitions easier to find.

Config Overrides

Datapacks and local configuration can be used together.

If a config book and datapack book use the same ID, the definition in:

config/rpg_lore/books/

takes priority.

This allows server owners and pack authors to override individual entries without editing the original datapack.

Generated Documentation

The books configuration directory includes generated field documentation to make creating new books easier without constantly referring back to external documentation.

Commands

RPG Lore includes administration and debugging commands for managing books and player collections.

/rpglore reload
/rpglore validate [book_id]
/rpglore give <players> <book_id> [track]
/rpglore list
/rpglore collection

/rpglore codex give <players>
/rpglore codex status <player>
/rpglore codex add <players> <book_id>
/rpglore codex remove <players> <book_id>
/rpglore codex reset <players>

/rpglore collection can be used by normal players. Administrative commands require the appropriate operator permission level.

Configuration

RPG Lore provides separate server and client configuration files:

config/rpg_lore/server.toml
config/rpg_lore/client.toml

Server configuration covers systems such as:

• Entity drops
• Loot table acquisition
• Advancement acquisition
• Global drop chance
• Looting behavior
• Maximum books per kill
• Codex availability
• Soul-binding
• Automatic collection
• First-join Codex grants
• Physical copy extraction
• Duplicate handling
• Discovery hints
• Whether undiscovered book names are revealed
• Interactive command permissions

Client configuration includes options for:

• Collection notifications
• Collection sounds
• Unread indicators
• Remembering Codex searches
• Displaying internal lore IDs for pack development

Mod Integration

RPG Lore exposes a public API for other mods that want to participate in the lore system.

Other mods can:

• Add a specific lore book directly to a player's Codex
• Detect when a player discovers a book for the first time
• Identify how that book was acquired

This makes RPG Lore suitable as a foundation for quest mods, custom progression, NPC systems, achievements, RPG mechanics, and other modpack-specific content.

Optional Curios Support

Curios API is optional.

When Curios is installed, RPG Lore adds a dedicated Codex slot where the Lore Codex can be equipped.

Codex collection, access, and soul-bound behavior work whether the Codex is stored in the player's inventory or Curios slot.

RPG Lore functions normally without Curios installed.

Localization

RPG Lore includes localization support for 60 locales, covering a wide range of European, Asian, African, and other languages.

Custom lore book content itself remains under the control of the pack author.

Quick Start for Pack Authors

1. Install RPG Lore and launch the game once.
2. Open:

config/rpg_lore/books/

1. Add or edit .json book definitions.
2. Use:

/rpglore validate

1. Apply the changes with:

/rpglore reload

1. Configure where each book can be discovered.
2. Let players build their collection naturally as they explore your world.

Books can also be packaged inside datapacks if you want to distribute a complete lore collection with a modpack or server.

Requirements

• Minecraft: 1.20.1
• Mod Loader: Forge 47.x
• Java: 17
• Curios API: Optional, version 5.x or newer

For Modpacks

RPG Lore is particularly well suited for modpacks that want worldbuilding without forcing players to stop and read walls of introductory text.

Lore can instead be scattered naturally throughout the game:

• Journals hidden in ruins
• Historical records inside structure chests
• Bestiary entries dropped by monsters
• Research notes earned through advancements
• Books tied to particular dimensions or biomes
• Rare manuscripts carried by specific enemies
• Multi-volume histories collected over an entire playthrough

Because nearly everything is data-driven and reloadable, the same framework can support anything from a handful of flavor books to a large, interconnected lore collection.

Links

Source Code: GitHub

License: MIT