HPatchNotes - Interactive Patch Notes Books for Paper & Folia
HPatchNotes is a lightweight, high-performance patch notes plugin for modern Minecraft servers. It allows you to design custom, interactive in-game books (changelogs, guides, or server updates) complete with clickable buttons.Books can be configured to open automatically when a player first joins the server, or on-demand using the /patchnotes command. Highly optimized for high-traffic networks, it features smart caching, multi-threaded safety, and an adaptive configuration updater.
Technical Specifications
- Supported Platforms: Paper, Folia, CanvasMC, Leaf, PaperShredded (specifically optimized for version 1.21.11 with api-version: 1.21 and folia-supported: true).
- Java Requirement: Java 21+
- Dependencies: None. Features soft-dependency support for PlaceholderAPI (used automatically if installed).
- Native Components: Built on Paper's native Adventure, MiniMessage, and Book APIs, ensuring zero shaded library overhead.
Core Features
- YAML-Driven Book Design: Every .yml file in your books folder represents a distinct in-game book. The file name acts as the unique Book ID.
- Interactive Button Actions: Buttons can be mapped to trigger complex behaviors such as opening other books, running player commands, suggesting text, opening external URLs, copying text to the clipboard, or jumping to specific pages.
- First-Join Auto-Open: Configurable popup system that delivers a book to players the first time they log in.
- O(1) Global Reset: Re-arm the first-join book popup for all players instantly. By bumping a global version variable ($O(1)$ complexity), the system bypasses heavy database updates. It can also be targeted to individual players.
- Hybrid Formatting Engine: Seamlessly mix legacy formatting codes (&7 &l), hex color styles (&#FFAA00, <#FFAA00>, #FFAA00), and advanced MiniMessage tags (<gradient:...>, <rainbow>) in the same line of text.
- Smart Caching System: Book templates are pre-rendered once at startup. If a book does not contain dynamic placeholders, it is fully cached and shared among all readers, resulting in zero execution cost even with 500+ concurrent players.
- Auto-Updating Config: Newly introduced configuration keys are automatically appended during plugin updates, leaving your custom values untouched while creating a secure config.yml.bak backup.
Commands and Permissions
Alias options: /patchnote, /pn, /changelog.| Command | Description | Permission |
| /patchnotes | Opens the default configured book | hpatchnotes.use (Default: true) |
| /patchnotes <book> | Opens a specific book by its ID | hpatchnotes.use (Default: true) |
| /patchnotes list | Lists all available books (clicking a name opens it) | hpatchnotes.use (Default: true) |
| /patchnotes reload | Reloads the general config and book templates | hpatchnotes.admin (Default: OP) |
| /patchnotes reset | Reset first-join state for everyone (they will see the book again) | hpatchnotes.admin (Default: OP) |
| /patchnotes reset <player> | Reset first-join state for a single player | hpatchnotes.admin (Default: OP) |
| /patchnotes show <player> [book] | Forces a book to open on another player's screen | hpatchnotes.admin (Default: OP) |
Book Syntax and Formatting (books/<id>.yml)
Below is an example of a book configuration file demonstrating static lines, clickable buttons, and multi-component rows:YAML
title: "&6&lPatch Notes" # The title displayed at the top of the book UI
author: "&eHoneyMC" # The author listed on the book metadata
permission: "" # Required permission to open ("" allows all players)
pages:
- lines: # Defines a page (supports up to ~14 lines maximum)
# 1) Standard Text Line
- "&7Welcome back, %player%!"
# 2) Full-Line Clickable Button
- text: "&c&l ▶ BUG FIXES"
hover: "&7View our latest bug fixes"
action: OPEN_BOOK
value: bugs
# 3) Composite Row (Combine clickable and non-clickable elements)
- row:
- text: "&7Join our: "
- text: "&9&n[Discord]"
value: "https://discord.gg/example"
Available Click Actions (action
| Action Key | Description | Target Value (value |
| OPEN_BOOK | Opens another book | The target Book ID (e.g., updates) |
| RUN_COMMAND | Runs a command as the player | Command to execute (e.g., /spawn) |
| SUGGEST_COMMAND | Fills the player's chat box | Text/Command to suggest (e.g., /report ) |
| OPEN_URL | Prompts to open an external link | Target URL (e.g., https://...) |
| COPY | Copies text to the player's clipboard | Text to copy |
| PAGE | Navigates to a page in the current book | Target page index (e.g., 2 - 1-based) |
| NONE | Disables click action (hover-only) | — |
Technical and Performance Notes
- Folia & Multi-Thread Safety: All player-specific operations (such as rendering and opening books) run directly on the player's owning region thread. Storage and file I/O operations are offloaded entirely to Folia's asynchronous scheduler to prevent ticks from stalling.
- State-Free Design: Aside from the minimal tracking map of players who have viewed the first-join book, the plugin maintains no active state. This design avoids memory leaks or resource buildup as players join and leave.
- Safe Name Resolution: The /patchnotes reset <player> command utilizes the local server cache to match player names, avoiding thread-blocking web queries to Mojang servers.
- Performance Tip: Any line containing no dynamic placeholders (like %player% or PAPI variables) is parsed once on startup and fully cached. For maximum performance under massive player loads, design your informational pages without dynamic placeholders to take full advantage of this caching mechanism.
