# ============================================================
# MailboxGUI Configuration
# ============================================================
# This file controls mailbox behavior, Post Office mailboxes,
# Dynmap markers, language behavior, mail systems, packages,
# money mail, and update checking.
#
# Important:
# - Use spaces, not tabs.
# - Minecraft color codes use '&'.
# - Text placeholders such as %player%, %sender%, and %number%
#   are replaced by the plugin where supported.
# - When config-version changes, this file is synchronized with
#   the bundled defaults while preserving matching existing settings.
# ============================================================

config-version: 12

# ============================================================
# Data Storage
# ============================================================
# Controls how MailboxGUI stores persistent plugin data.
#
# Available storage types:
# - YAML   = flat YAML files under plugins/MailboxGUI/data/playerdata and data/postofficedata
# - SQLITE = local database file under plugins/MailboxGUI/data/data.db
# - MYSQL  = remote MySQL database storage
#
# New installs default to SQLITE.
# Upgrades with legacy mailboxdata from 3.1.2 or older default to YAML unless storage.type already existed.
# ============================================================

storage:
  type: SQLITE

  sqlite:
    file: data/data.db

  mysql:
    host: localhost
    port: 3306
    database: mailboxgui
    username: root
    password: ''
    use-ssl: false

# ============================================================
# Player Mailboxes
# ============================================================
# Player mailboxes are private physical mailbox locations owned
# by a specific player.
#
# A valid player mailbox must use:
# - one normal single chest
# - one attached sign
#
# Trapped chests and double chests are not valid mailbox blocks.
# ============================================================

mailbox:
  # Maximum number of physical player mailboxes one player may register.
  max-mailboxes-per-player: 3

  # If true, players may send letters, packages, and money mail
  # to themselves through normal player recipient menus.
  #
  # If false, the sender is hidden from their own recipient lists.
  allow-player-self-send: true

  # Allows players to open the main MailboxGUI menu by command with
  # /mailbox open or /mb open.
  #
  # This is disabled by default so physical mailbox, Post Office box,
  # and Post Office NPC access remains the normal access flow.
  # Enable it for backend servers that do not have mailbox access points.
  command-open:
    enabled: false

  # Shows a floating paper item above registered physical player mailboxes
  # when the mailbox owner has new unread mail.
  #
  # The notification clears only when the player opens their Inbox GUI.
  # Opening the main MailboxGUI menu does not clear it.
  #
  # This uses a no-gravity dropped item for 1.18+ compatibility.
  new-mail-notification:
    enabled: true
    item: PAPER
    vertical-offset: 1.35
    refresh-interval-seconds: 60

  detection:
    # If true, player mailbox signs are refreshed on startup/reload
    # when the saved world, chest, and sign are physically available.
    #
    # This keeps mailbox sign numbers accurate after unregistering
    # or renumbering mailboxes.
    refresh-signs-on-load: true

  sign-format:
    # Sign format used when a normal player mailbox is registered.
    #
    # Available placeholders:
    # %player% = mailbox owner's player name
    #
    # Number placeholders are still supported for older/custom configs,
    # but are no longer used in the default sign format:
    # %number% = mailbox number for that owner
    # %mailbox_number% = mailbox number for that owner
    # %mailboxnumber% = mailbox number for that owner
    #
    # Keep all four lines present.
    line-1: '&6[&lMailbox&r&6]'
    line-2: '%player%'
    line-3: '&bPersonal Mail'
    line-4: '&7Right Click'

# ============================================================
# Admin Mail Sending
# ============================================================
# Controls how Admin Tools bulk mail audiences behave.
# ============================================================

admin-mail:
  # If true, the admin who sends bulk admin mail is included in
  # All Players and Online Players deliveries.
  #
  # This is useful for testing server-wide letters, packages,
  # money mail, and package/COD behavior.
  include-sender-in-bulk-audiences: true

# ============================================================
# Post Office System
# ============================================================
# Post Office mailboxes are public mailbox access points.
#
# They are useful for:
# - players who do not have a private mailbox yet
# - spawn/mailroom access points
# - servers that do not want to rely only on Citizens NPCs
#
# A valid Post Office mailbox must use:
# - one normal single chest
# - one wall sign attached to the front of the chest
#
# Post Office boxes do not use a fence-post base.
# ============================================================

post-office:
  # Enables or disables the Post Office system.
  #
  # If false, Post Office mailbox opening and registration tools
  # are disabled.
  enabled: true

  mailboxes:
    # Enables or disables public Post Office mailbox registration
    # and opening.
    enabled: true

    # If true, any player may open a registered Post Office mailbox.
    #
    # If false, players need:
    # mailboxgui.player.postoffice.pobox
    allow-any-player-open: true

    # If true, removing a Post Office mailbox from one Post Office
    # renumbers the remaining boxes for that same Post Office and
    # refreshes their signs when loaded.
    #
    # Example:
    # - PO Box #1 is removed
    # - old PO Box #2 becomes new PO Box #1
    renumber-after-remove: true

    # If true, Post Office mailbox signs are refreshed on startup/reload
    # when their saved world, chest, and sign are physically available.
    refresh-signs-on-load: true

    sign-format:
      # Sign format used when a Post Office mailbox is registered.
      #
      # Available placeholders:
      # %postofficename% = Post Office name typed by the admin
      #
      # Number placeholders are still supported for older/custom configs,
      # but are no longer used in the default sign format:
      # %number% = PO Box number inside that Post Office group
      # %po_box_number% = PO Box number inside that Post Office group
      # %pobox_number% = PO Box number inside that Post Office group
      # %po_box% = PO Box number inside that Post Office group
      # %pobox% = PO Box number inside that Post Office group
      #
      # Keep all four lines present.
      line-1: '&6[&lMailbox&r&6]'
      line-2: '%postofficename%'
      line-3: '&6Public Access'
      line-4: '&7Right Click'

# ============================================================
# Dynmap Support
# ============================================================
# Dynmap support is optional.
#
# If Dynmap is installed and this section is enabled, MailboxGUI
# creates a Dynmap marker layer for player mailboxes and Post
# Office mailboxes.
#
# If Dynmap is missing, MailboxGUI continues normally.
# ============================================================

dynmap:
  # Enables or disables MailboxGUI Dynmap support.
  enabled: true

  marker-set:
    # Internal Dynmap marker set ID.
    #
    # Keep this stable once markers exist on your map.
    id: 'mailboxgui-mailboxes'

    # Visible layer name in Dynmap's marker selector.
    #
    # This is the checkbox name players/admins can toggle.
    label: 'Mailboxes/PO Boxes/NPC'

    # If true, the Mailboxes/PO Boxes/NPC layer is hidden by default.
    #
    # If false, the layer is visible by default.
    hide-by-default: false

    # Dynmap layer priority.
    #
    # Higher values can appear higher in Dynmap's layer list.
    layer-priority: 10

  markers:
    player-mailboxes:
      # If true, registered player mailboxes appear on Dynmap.
      enabled: true

      # Dynmap marker icon ID for player mailboxes.
      #
      # If this icon is missing, MailboxGUI falls back to another
      # available Dynmap icon.
      icon-id: 'chest'

      # Marker label shown on the map.
      #
      # Available placeholders:
      # %player% = mailbox owner
      # %number% = mailbox number for that owner
      label-format: '%player% Mailbox #%number%'

      # Marker description shown when clicking the marker.
      #
      # Basic HTML is supported by Dynmap descriptions.
      #
      # Available placeholders:
      # %player% = mailbox owner
      # %number% = mailbox number
      # %world% = world name
      # %status% = Loaded/Unloaded status text
      description:
        - '<b>MailboxGUI Player Mailbox</b>'
        - 'Player: %player%'
        - 'Mailbox: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

    post-office-mailboxes:
      # If true, registered Post Office mailboxes appear on Dynmap.
      enabled: true

      # Dynmap marker icon ID for Post Office mailboxes.
      icon-id: 'chest'

      # Marker label shown on the map.
      #
      # Available placeholders:
      # %postofficename% = Post Office name
      # %number% = PO Box number
      label-format: '%postofficename% PO Box #%number%'

      # Marker description shown when clicking the marker.
      #
      # Available placeholders:
      # %postofficename% = Post Office name
      # %number% = PO Box number
      # %world% = world name
      # %status% = Loaded/Unloaded status text
      description:
        - '<b>MailboxGUI Post Office Box</b>'
        - 'Post Office: %postofficename%'
        - 'PO Box: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

    post-office-npcs:
      # If true, Citizens Post Office NPCs appear on Dynmap.
      #
      # Citizens must be installed and the NPC must be marked as a
      # MailboxGUI Post Office NPC.
      enabled: true

      # Dynmap marker icon ID for Post Office NPCs.
      #
      # Dynmap's default "walk" marker icon is used for NPCs.
      icon-id: 'walk'

      # Marker label shown on the map.
      #
      # Available placeholders:
      # %npc% = NPC name
      # %id% = Citizens NPC ID
      label-format: 'Post Office NPC: %npc%'

      # Marker description shown when clicking the marker.
      #
      # Available placeholders:
      # %npc% = NPC name
      # %id% = Citizens NPC ID
      # %world% = world name
      description:
        - '<b>MailboxGUI Post Office NPC</b>'
        - 'NPC: %npc%'
        - 'NPC ID: %id%'
        - 'World: %world%'

  update:
    # If true, markers are refreshed when the plugin starts
    # and Dynmap becomes available.
    refresh-on-startup: true

    # If true, markers are refreshed when MailboxGUI reloads.
    refresh-on-reload: true

    # If true, markers are refreshed after registering a mailbox.
    refresh-on-register: true

    # If true, markers are refreshed after unregistering a mailbox.
    refresh-on-unregister: true

# ============================================================
# Language / Locale
# ============================================================
# MailboxGUI can use the player's Minecraft client locale when
# a matching language file exists.
#
# Language files are stored in:
# plugins/MailboxGUI/language/
#
# Supported locale.default codes:
# en, es, fr, de, sv, nl, it, ja, ko, pl, ru, uk, zh_cn, zh_tw
# ============================================================

locale:
  # Default language code.
  #
  # Used when automatic locale detection is disabled or when a
  # player's locale is not supported by MailboxGUI.
  default: en

  # If true, MailboxGUI attempts to use the player's Minecraft
  # client language.
  #
  # If false, all players use locale.default.
  auto-detect-player-locale: true

# ============================================================
# Letters
# ============================================================
# Letters are text mail sent from one player to another or from
# admin tools.
# ============================================================

letter:
  # Enables or disables player letter sending.
  enabled: true

  # Delivery delay for player letters in seconds.
  #
  # 0 = immediate delivery.
  delivery-delay-seconds: 0

  # Sender name used for admin/server-created letters.
  admin-server-name: '&a&lServer'

# ============================================================
# Packages
# ============================================================
# Packages can contain items and optional package experience.
#
# Cash On Delivery packages use Vault/economy when available.
# ============================================================

package:
  # Enables or disables package sending.
  enabled: true

  # If true, shulker boxes that already contain items cannot be
  # placed inside packages.
  #
  # This prevents using packages as nested portable storage.
  deny-loaded-shulker-box: true

  # Number of package content rows used in package compose and
  # receive GUIs.
  #
  # 1 = 7 content slots
  # 2 = 14 content slots
  # 3 = 21 content slots
  size-in-rows: 3

  # Delivery delay for player packages in seconds.
  #
  # 0 = immediate delivery.
  delivery-delay-seconds: 0

  # Sender name used for admin/server-created packages.
  admin-server-name: '&a&lServer'

  experience:
    # Enables or disables adding experience to packages.
    #
    # Experience is stored as a special MailboxGUI package item
    # using Bottle o' Enchanting as the default material.
    enabled: true

    # Maximum raw experience points a normal player may add to one
    # package.
    #
    # -1 = no plugin cap.
    #
    # Normal players are still limited by how much experience they
    # currently have. Admin package experience does not depend on
    # the admin's personal experience amount.
    max-experience-per-package: -1

    # If true, normal player senders must already have the experience
    # they add to a package.
    #
    # The experience is removed when the package is actually sent,
    # not when the chat amount is typed.
    withdraw-from-sender-on-send: true

    item:
      # Bukkit material used for the special package experience item.
      #
      # EXPERIENCE_BOTTLE = Bottle o' Enchanting.
      material: EXPERIENCE_BOTTLE

      # Display name for the experience item when it is inside a
      # received package.
      display-name: '&aExperience Package'

      # Lore for the experience item when it is inside a received
      # package.
      #
      # Compose GUIs use language-file lore instead so they can say
      # "Right-click to remove experience" while receive GUIs say
      # "Any click to claim."
      #
      # Available placeholders:
      # %experience% = raw experience points stored in the item
      lore:
        - '&7Stored Experience: &a%experience%'
        - '&e&lAny click to claim'

      # Lore for the experience item only while previewing an unpaid
      # COD package.
      #
      # This prevents the preview GUI from telling players they can
      # claim XP before accepting the COD package.
      #
      # Available placeholders:
      # %experience% = raw experience points stored in the item
      cod-preview-lore:
        - '&7Stored Experience: &a%experience%'
        - '&cAccept COD Package before you can claim this XP'

  cash-on-demand:
    # Enables or disables Cash On Delivery packages globally.
    #
    # If false, both Vault/economy COD and item-currency COD are disabled.
    enabled: true

    # Enables or disables Vault/economy currency as a COD payment option.
    #
    # If Vault or an economy provider is not available, MailboxGUI hides
    # only the Vault/economy COD option and can still allow item-currency COD.
    vault-economy-currency: true

    # Enables or disables item-currency payments as a COD payment option.
    #
    # Item-currency COD supports normal material names, XP entries, and
    # saved item templates using t:<id>:# syntax.
    item-currency: true

    # If true, successful player-origin Vault/economy COD payments are returned
    # to the sender as money mail.
    #
    # If false, successful player-origin Vault/economy COD payments are deposited
    # directly into the sender's economy account.
    #
    # Admin-origin COD packages always act as a sink cost. They do
    # not send money back to an admin/server sender.
    send-reward-in-mail: true

  lore:
    # Lore shown on normal standard package icons.
    #
    # Available placeholders:
    # %sender% = sender name shown on the package
    standard-package:
      - '&7From: &f%sender%'
      - '&7Right-click to open'

    # Lore shown on unpaid COD package icons.
    #
    # Available placeholders:
    # %sender% = sender name shown on the package
    cash-on-demand-package:
      - '&7From: &f%sender%'
      - '&7Right-click to preview contents'

# ============================================================
# Money Mail
# ============================================================
# Money mail requires a working economy/Vault setup.
# ============================================================

money:
  # Enables or disables money mail.
  enabled: true

  # Sender name used for admin/server-created money mail.
  admin-server-name: '&a&lServer'

  # Controls how MailboxGUI displays economy amounts in money mail,
  # admin money mail, COD package prices, and COD return payments.
  #
  # PROVIDER = use the Vault economy provider's own format(amount) result.
  # CUSTOM = use the custom-format below.
  # RAW = show only the formatted number with no currency symbol/name.
  display-format-mode: PROVIDER

  # Used when display-format-mode is CUSTOM, and also used as the safe fallback
  # if PROVIDER mode cannot get a valid formatted value from Vault.
  #
  # Available placeholders:
  # %amount% = formatted number, such as 1,250.00
  # %raw_amount% = raw decimal amount, such as 1250.0
  # %currency_singular% = Vault provider singular currency name, if available
  # %currency_plural% = Vault provider plural currency name, if available
  custom-format: "$%amount%"

  # Decimal format used for %amount% and RAW mode.
  #
  # Common examples:
  # "#,##0.00" = 1,250.00
  # "#,##0" = 1,250
  # "0.00" = 1250.00
  amount-format: "#,##0.00"

# ============================================================
# Update Checker
# ============================================================
# Checks for plugin updates from the MailboxGUI website release system.
# ============================================================

updates:
  # Enables or disables the update checker.
  enabled: true

  # Release channel to request from the website release system.
  # Common values: release, beta, alpha
  channel: release

  # If true, MailboxGUI checks for updates during startup.
  check-on-startup: true

  # If true, admins with the notify permission are told when
  # an update is available when they join.
  notify-admins-on-join: true

  # Permission required to receive in-game update notifications.
  notify-permission: "mailboxgui.admin"