BookEditor - The Easiest Way to Create Interactive Books

settings:
language: "en" # Default language
check-for-updates: true
debug-mode: false

hooks:
use-placeholderapi: true
use-vault: true

features:
enable-open-on-join: true
enable-open-on-first-join: true

###################################################################################
# BookEditor - Book Configuration File
# ID: test
#
# This file serves as a comprehensive test case and example guide
# for the BookEditor plugin's features.
###################################################################################

# This is the unique identifier for the book.
# It is used in commands like /be open <player> test and in click events.
# It MUST match the filename (test.yml).
book-id: "test"

###################################################################################
# ITEM SECTION
# This section defines the visual appearance of the book item itself.
###################################################################################
item:
  # The material of the item. Can be WRITTEN_BOOK, WRITABLE_BOOK, or any other item.
  material: "WRITTEN_BOOK"

  # The display name of the item, which also serves as the book's title when opened.
  # This field supports MiniMessage formatting for gradients, colors, etc.
  title: "<gradient:#00C6FF:#0072FF><b>Plugin Test Menu</b></gradient>"

  # The author's name, displayed in the book's UI.
  # This field also supports MiniMessage formatting.
  author: "<gold>BookEditor</gold>"

  # The "generation" of the book.
  # 0 = Original, 1 = Copy of Original, 2 = Copy of Copy, 3 = Tattered.
  # For most uses, '0' is standard.
  generation: 0

###################################################################################
# SETTINGS SECTION
# This section controls the plugin's automatic opening features for this book.
###################################################################################
settings:
  # If true, the plugin will automatically open this book for a player
  # the very first time they join the server.
  open-on-first-join: false

  # If true, the plugin will automatically open this book for a player
  # *every* time they join the server (except the first if the above is true).
  open-on-join: false

###################################################################################
# PAGES SECTION
# This is the main content of your book.
# Each entry that starts with a hyphen ('-') represents one new page.
###################################################################################
pages:

  # This is Page 1.
  - |
    # The pipe character '|' is a YAML feature called a "Literal Block Scalar."
    # It allows you to write a multi-line string easily without needing quotes ("").
    # All text indented below it will be treated as a single string,
    # preserving all your line breaks exactly as you see them.
    # This is the recommended way to write book pages.
   
    # All text in pages is parsed using the MiniMessage format.
    <dark_aqua><b>TEST MENU - CORE</b></dark_aqua>
    <dark_gray><st>                     </st></dark_gray>
   
    # Placeholders from PlaceholderAPI (like %player_name%) are supported
    # if you have PlaceholderAPI installed.
    <gray>Welcome, <aqua>%player_name%</aqua>!</gray>
    <gray>Select an action to test.</gray><reset>
   
    # This line demonstrates a "hover" and "click" event.
    # <hover:show_text:'...'>: Shows 'TEXT' when a player hovers their mouse over it.
    # <click:run_command:'...'>: Executes a command when the text is clicked.
    #
    # The command '/be action test action-command' tells BookEditor to find the
    # book with ID 'test' and execute the action with ID 'action-command'.
    <hover:show_text:'<green>Test [player_command]<newline>Runs the command: /help'><click:run_command:'/be action test action-command'><aqua>► Test Player Command (/help)</aqua></click></hover><reset>
    <hover:show_text:'<gold>Test [money] (Requires Vault)<newline><gray>Book will NOT close.'><click:run_command:'/be action test action-get-money'><gold>► Test Economy (No Close)</gold></click></hover><reset>
    <hover:show_text:'<blue>Test "close-on-click: true"<newline><gray>Book WILL close on click.'><click:run_command:'/be action test action-tp-spawn'><blue>► Test Teleport (Closes)</blue></click></hover><reset>
    <hover:show_text:'<light_purple>Test [give_item]<newline>Gives 1 Nether Star.'><click:run_command:'/be action test action-give-item'><light_purple>► Test Give Item</light_purple></click></hover><reset>
    <newline>
   
    # '<click:change_page:2>' is a built-in MiniMessage tag for books.
    # It navigates the player directly to the specified page number (Page 2).
    <hover:show_text:'<gray>View Page 2 (Effects)'><click:change_page:2><gray>[Next Page →]</gray></click></hover>

  # This is Page 2.
  - |
    <dark_aqua><b>TEST MENU - ADVANCED</b></dark_aqua>
    <dark_gray><st>                     </st></dark_gray>
    <gray>Test visual and advanced actions.</gray><reset>
    <hover:show_text:'<yellow>Test [firework]<newline>Launches a firework.'><click:run_command:'/be action test action-firework'><yellow>► Test Firework Effect</yellow></click></hover><reset>
    <hover:show_text:'<blue>Test [particle]<newline>Spawns 50 flame particles.'><click:run_command:'/be action test action-particle'><blue>► Test Particle Effect</blue></click></hover><reset>
    <hover:show_text:'<dark_purple>Test [console_command]<newline>Runs /say from console.'><click:run_command:'/be action test action-console-cmd'><dark_purple>► Test Console Command</dark_purple></click></hover><reset>
   
    # This action is linked to 'action-permission-test' which requires a permission.
    <hover:show_text:'<red>Test Permission Node<newline>Requires: <yellow>bookeditor.test.testpermission</yellow>'><click:run_command:'/be action test action-permission-test'><red>► Test Permission (Fails)</red></click></hover><reset>
    <newline>
    <hover:show_text:'<gray>View Page 1'><click:change_page:1><gray>[← Previous Page]</gray></click></hover>

###################################################################################
# ACTIONS SECTION
# This section defines what happens when a player clicks a linked action.
# The ID here (e.g., "action-command:") MUST match the ID from the
# <click:run_command:'/be action test ID_HERE'> event in the pages section.
###################################################################################
actions:

  # ID: action-command
  # Demonstrates a basic player command and a feedback message.
  action-command:
    # "execute" is a list of all actions to run, in order, when triggered.
    execute:
      - "[player_command] help" # [player_command]: Runs the command as if the player typed it.
      - "[message] <green>Ran /help command." # [message]: Sends a MiniMessage-formatted message to the player.

  # ID: action-get-money
  # Demonstrates Vault integration, multiple commands, and the 'close-on-click' feature.
  action-get-money:
    # This is a key feature. If 'false', the plugin will actively prevent
    # the client from closing the book after the action. This is perfect for menus.
    # If 'true' or omitted, the book closes normally.
    close-on-click: false
    execute:
      - "[money] 1000" # [money]: Gives (or takes if negative) money. Requires Vault.
      - "[message] <gold>You received <yellow>$1,000</yellow>!</gold>"
      - "[sound] ENTITY_PLAYER_LEVELUP" # [sound]: Plays a sound for the player.
    # (Optional) The player must have this permission node to run this action.
    permission: bookeditor.test.testmoney

  # ID: action-tp-spawn
  # Demonstrates a standard action that closes the book.
  action-tp-spawn:
    close-on-click: true # Book will close as normal.
    execute:
      - "[player_command] tp @p 0 100 0"
      - "[message] <aqua>Teleported to 0, 100, 0!</aqua>"
      - "[sound] ENTITY_ENDERMAN_TELEPORT"
    permission: bookeditor.test.testtp

  # ID: action-give-item
  # Demonstrates giving an item with a custom name and lore.
  action-give-item:
    execute:
      # [give_item]: Gives an item.
      # Format: [give_item] <MATERIAL> <Amount> [name:<name>] [lore:<line1|line2...>]
      #
      # IMPORTANT: The pipe character '|' used inside the 'lore:' tag is a
      # *separator* for new lines in the item's lore.
      # This is different from the YAML '|' character used for multi-line strings.
      - "[give_item] NETHER_STAR 1 name:<gradient:blue:aqua>Test_Star lore:<gray>Line_1|&cLine_2_with_legacy"
      - "[message] <light_purple>You received 1x <aqua>Test Star</aqua>!</light_purple>"
    permission: bookeditor.test.testitem

  # ID: action-firework
  # Demonstrates the [firework] visual effect.
  action-firework:
    execute:
      - "[firework]" # [firework]: Spawns a default firework at the player's location.
      - "[message] <yellow>Launched a firework!</yellow>" # This message was "Pew pew!"

  # ID: action-particle
  # Demonstrates the [particle] visual effect.
  action-particle:
    execute:
      - "[particle] FLAME 50" # [particle]: Spawns particles. Format: [particle] <PARTICLE_TYPE> <Amount>
      - "[message] <blue>Spawned flame particles.</blue>" # This message was "Woosh!"

  # ID: action-console-cmd
  # Demonstrates running a command from the server console.
  action-console-cmd:
    execute:
      # [console_command]: Runs the command as the server console.
      # It supports %player_name% and other PAPI placeholders.
      - "[console_command] say Player %player_name% tested the console action!"
      - "[message] <dark_purple>Console command executed. Check the console.</dark_purple>"

  # ID: action-permission-test
  # Demonstrates a custom permission message for a failed action.
  action-permission-test:
    execute:
      - "[message] <green>You have the permission!</green>" # This only runs if the check passes.
    permission: bookeditor.test.testpermission

    # (Optional) If 'permission:' is set and the player lacks it, this
    # 'permission-message' will be sent instead of running the 'execute' list.
    # If this is not set, the action will just fail silently.
    permission-message: "<red><b>[!]</b> You lack the required permission: <yellow>bookeditor.test.testpermission</yellow></red>"