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

RPG Lore

Data-driven lore books that drop from mobs. Collect them all in the Lore Codex.

RPG Lore lets modpack makers and server owners add custom lore books to their world using simple JSON files. Books drop from mobs based on configurable conditions -- entity type, biome, dimension, time of day, weather, Y-level, and more. No coding required.

Key Features

Lore Books

• Fully data-driven -- each .json file in the config folder becomes a lore book. Add, edit, or remove books without recompiling.
• Conditional drops -- control exactly which mobs drop which books with 11 different filter types.
• Custom styling -- per-book title color, author color, description, enchantment glint toggle, and generation labels.
• Stylized title page -- every book opens with an auto-generated title page featuring the book's title (scaled, bold, colored) and author.
• Custom book GUI -- lore books use a unique texture distinct from vanilla written books.
• Per-player copy limits -- optionally restrict how many times each player can receive a specific book.
• Looting scaling -- optionally increase drop chance with the Looting enchantment.

Lore Codex

• Personal collection book -- a soul-bound item that stores your lore books directly inside it.
• Books go into the Codex -- when you pick up a new lore book, it's consumed from the world and stored in the Codex. No inventory clutter.
• Browsable GUI -- custom parchment-styled screen with paginated book list, collection counter (n/N), and per-book Read and Copy actions.
• Copy mechanic -- create a physical copy of any collected book into your inventory. Copies always go to your inventory with generation incremented.
• Soul-bound -- granted on first login, kept on death, cannot be dropped.
• Duplicate prevention -- toggle to block picking up lore books you've already collected.
• Curios API support -- equip the Codex in a dedicated "codex" Curios slot. Soft dependency -- works without Curios installed.

For Pack Makers

• Hot-reloadable -- use /rpglore reload to apply changes without restarting.
• 11 drop condition types -- entity type, entity tags, biome, biome tags, dimension, Y-range, time of day, weather, player kill requirement, per-book chance override, and per-player copy limits.
• Book categories -- organize books with the category field for clean Codex grouping.
• Codex exclusion -- hide debug or temporary books from the Codex with codex_exclude.
• Per-book glint -- toggle the enchantment shimmer on/off per book.
• Comprehensive README -- auto-generated _README.txt in the config folder documents every field.

Administration

• /rpglore reload -- hot-reload all book definitions
• /rpglore give -- give books to players (with optional copy-limit tracking)
• /rpglore list -- list all loaded books with categories
• /rpglore collection -- players can view their own collection (no OP required)
• /rpglore codex give/reset/add/remove/status -- full Codex administration

Quick Start

1. Drop the JAR into your mods/ folder.
2. Start the game once -- the mod generates example configs and a sample book.
3. Add your .json book files to config/rpg_lore/books/.
4. Use /rpglore reload to apply changes.
5. Players receive a Lore Codex on first join. Right-click to browse your collection.

Example Book Definition

{
  "title": "The Ancient Battle",
  "author": "Unknown Chronicler",
  "weight": 5,
  "title_color": "FFD700",
  "description": "A faded account of a great battle.",
  "category": "History",
  "drop_conditions": {
    "mob_types": ["minecraft:zombie", "minecraft:skeleton"],
    "biome_tags": ["minecraft:is_overworld"],
    "time": "NIGHT_ONLY"
  },
  "pages": [
    "Long ago, in these very fields...",
    "The battle raged for three days..."
  ]
}

Configuration

All settings are in config/rpg_lore/server.toml and config/rpg_lore/client.toml. Every Codex feature can be individually toggled on or off.

Compatibility

• Curios API (optional) -- equip the Codex in a dedicated Curios slot. All features work from either inventory or Curios slot. The mod functions fully without Curios installed.

Localization

Localized in 60 languages including English, Chinese, Spanish, Hindi, Arabic, French, German, Russian, Japanese, Korean, and 50 more.

Requires: Minecraft 1.20.1 | Forge 47.3.0+ | Java 17 Optional: Curios API 5.4.7+ License: MIT Source: GitHub