Table of Contents

1. Features
2. Installation
3. Configuration
   • Defining Books
   • Using MiniMessage Formatting
4. Commands
5. Permissions
6. Usage Examples
   • Opening a Book
   • Listing Available Books
   • Reloading Configuration
7. Advanced Setup
   • Linking Commands to Blocks or NPCs
   • Creating Command Aliases
8. Troubleshooting
9. Frequently Asked Questions
10. Support and Contribution

Features

• Custom Books from Config:
  • Define an unlimited number of books in config.yml.
  • Customize titles, authors, and pages.
  • Organize content easily for various purposes (e.g., welcome messages, rule books, guides).
• Simple Commands:
  • Players can open books using straightforward commands.
  • List all available books.
  • Reload the configuration without restarting the server.
• Permissions Support:
  • Control who can read specific books.
  • Manage access to commands and features with permission nodes.
• Formatting Support:
  • Utilize MiniMessage formatting for colors, styles, and interactive text.
  • Enhance the appearance of your books to engage players.
• Integration Friendly:
  • Link commands to blocks, NPCs, or create aliases for seamless integration.
  • Compatible with other plugins that execute commands (e.g., CommandSigns, Citizens).

Installation

1. Download the Plugin:
   • Obtain the latest version of the Books Plugin JAR file.
2. Install the Plugin:
   • Place the plugin JAR file into your server's plugins directory.
3. Start or Restart Your Server:
   • Launch your server or restart it if it's already running.
   • The plugin will generate a default config.yml file in the plugins/Books directory.

Configuration
Defining Books
Books are defined in the config.yml file under the books: section. Each book has a unique identifier (book name) and contains the following properties:

• title: The title of the book displayed to the player.
• author: The author of the book displayed to the player.
• pages: A list of strings, each representing a page in the book.

Example config.yml:


books:
WelcomeBook:
title: "<gold>Welcome to the Server</gold>"
author: "<yellow>Server Admin</yellow>"
pages:
- "<bold>Welcome!</bold>\nWe're glad you're here."
- "Check out the rules and enjoy your stay!"
RulesBook:
title: "<red>Server Rules</red>"
author: "Moderation Team"
pages:
- "1. Be respectful.\n2. No griefing.\n3. No cheating."
- "For detailed rules, visit our website."

Notes:

• Book Names:
  • Case-sensitive identifiers used in commands.
  • Avoid spaces and special characters for simplicity.
• Line Breaks:
  • Use \n to insert line breaks within pages.

Using MiniMessage Formatting
The plugin supports MiniMessage formatting, allowing you to add colors, styles, and interactive elements to your book content.

Basic Formatting Tags:

• Colors:
  • <black>, <dark_blue>, <dark_green>, <dark_aqua>, <dark_red>, <dark_purple>, <gold>, <gray>, <dark_gray>, <blue>, <green>, <aqua>, <red>, <light_purple>, <yellow>, <white>
• Styles:
  • <bold>, <italic>, <underlined>, <strikethrough>, <obfuscated>
• Reset Formatting:
  • </color>, </bold>, </italic>, etc.

Example with Formatting:


books:
StoryBook:
title: "<dark_purple><bold>The Great Adventure</bold></dark_purple>"
author: "<gold>Storyteller</gold>"
pages:
- "<italic>Once upon a time</italic>, in a land far away..."
- "Our hero <bold>embarked</bold> on a quest."

Commands
/books open <bookName>

• Description: Opens the specified book for the player.
• Permission: books.read.<bookName> or books.read.*

Usage:

• /books open WelcomeBook

/books list

• Description: Lists all available books that the player has permission to read.
• Permission: books.list

Usage:

• /books list

/books reload

• Description: Reloads the plugin's configuration from the config.yml file.
• Permission: books.reload

Usage:

• /books reload

Permissions
Permissions allow you to control access to the plugin's features.

• books.read.<bookName>
  • Allows a player to read the specified book.
  • Replace <bookName> with the actual name of the book.
  • Example: books.read.WelcomeBook
• books.read.*
  • Grants access to read all books.
• books.list
  • Allows a player to use the /books list command.
• books.reload
  • Allows a player to use the /books reload command.

Setting Permissions:

Use a permissions plugin like LuckPerms or PermissionsEx to assign permissions to players or groups.

Example with LuckPerms:

• Grant all players access to the WelcomeBook:
  
  arduino
  /lp group default permission set books.read.WelcomeBook true
  
  
• Allow moderators to reload the configuration:
  
  bash
  /lp group moderator permission set books.reload true

Usage Examples
Opening a Book
To open a book, a player can use the /books open command followed by the book's name.

Example:

• Command: /books open RulesBook
• The player must have the books.read.RulesBook permission.
• The book will open on their screen.

Listing Available Books
Players can view a list of books they have access to by using the /books list command.

Example:

• Command: /books list
  
  
• Output:
  
  diff
  Available books:
  - WelcomeBook
  - RulesBook

Reloading Configuration
If you've made changes to the config.yml while the server is running, you can reload the configuration without restarting.

Example:

• Command: /books reload
• The player must have the books.reload permission.
• The plugin will reload the books from the configuration file.

Advanced Setup
Linking Commands to Blocks or NPCs
For a more immersive experience, you can link the book-opening command to in-game elements like blocks or NPCs using other plugins.

Using CommandSigns:

1. Install the CommandSigns plugin.
   
   
2. Create a sign and assign the command:
   • Place a sign and write [CommandSign] on the first line.
     
     
   • Run the command:
     
     bash
     /commandsign setcommand 1 /books open WelcomeBook
3. Players can right-click the sign to open the book.

Using Citizens (NPC Plugin):

1. Install the Citizens plugin.
   
   
2. Create an NPC:
   
   bash
   /npc create Librarian
   
   
3. Assign the command to the NPC:
   
   bash
   /npc cmd add /books open WelcomeBook
   
   
4. Players can interact with the NPC to open the book.

Creating Command Aliases
You can create custom aliases for the book commands to simplify access.

Example with commands.yml:

1. Open your server's commands.yml file.
   
   
2. Add an alias:
   
   
   aliases:
   welcome:
   - books open WelcomeBook
   
   
3. Players can now use /welcome to open the WelcomeBook.

Troubleshooting
Book Doesn't Open

• Issue: When a player tries to open a book, nothing happens.
• Solutions:
  • Check that the book name is correct and matches the name defined in config.yml.
  • Ensure the player has the necessary permission (books.read.<bookName>).
  • Verify that the book is properly defined in the configuration without syntax errors.

Books Not Listed

• Issue: /books list doesn't show any books or shows incomplete list.
• Solutions:
  • Make sure books are correctly defined under the books: section.
  • Confirm the player has the books.list permission.
  • Check for any errors in the server console during plugin startup or when running /books reload.

Formatting Issues

• Issue: Formatting in the book doesn't display correctly.
• Solutions:
  • Verify that MiniMessage tags are correctly formatted and closed.
  • Ensure that special characters are properly escaped if necessary.
  • Test the formatting in smaller sections to isolate issues.

Configuration Reload Not Working

• Issue: Changes in config.yml aren't reflected after using /books reload.
• Solutions:
  • Check for syntax errors in config.yml that might prevent loading.
  • Review server console logs for error messages during reload.
  • If issues persist, consider restarting the server.

Frequently Asked Questions
Q: Can players write or edit books in-game with this plugin?

• A: No, the Books Plugin is designed for administrators to define books in the configuration file. Players cannot create or edit books through the plugin.

Q: Does the plugin support multiple languages?

• A: Yes, you can write content in any language supported by Minecraft. Ensure your config.yml is saved with UTF-8 encoding.

Q: Is there a limit to how many books I can create?

• A: There is no hard limit imposed by the plugin. You can define as many books as you need.

Q: Can I include interactive elements like clickable links in the books?

• A: Yes, using MiniMessage formatting, you can add interactive elements such as clickable text, hover events, and more.

Q: How can I restrict certain books to specific player groups?

• A: Use permissions to control access. Assign books.read.<bookName> to specific groups using your permissions plugin.

Support and Contribution
If you encounter any issues, have questions, or want to suggest new features, feel free to reach out:

• SpigotMC Comments: Leave a comment on the plugin's page.
• Direct Message: Send me a message through SpigotMC.
• Bug Reports: Provide detailed information, including error messages and steps to reproduce.

Contributions:

• Contributions are welcome! If you have improvements or fixes, consider sharing them.