Configuration

Main sections

SectionPurpose
networkStandalone, same-proxy or cross-proxy behavior and server identity.
storageSQLite, MySQL, MariaDB or MongoDB persistence.
redisRedis settings required by cross-proxy mode.
homesMaximum/default slots, which locked slots the menu shows, names, icons, colour rules and disabled worlds.
guiAUTO/DIALOG/CHEST selection, the Bedrock chest menu, custom buttons, sprite/glyph icons and dialog/chest layout.
teleportWarmup, cooldown, movement/damage cancellation, safe teleport and sounds.
textsMenu titles, button labels and tooltips. PlaceholderAPI placeholders work here.

Safe teleport

With safe-teleport: NEAREST under teleport: (the default), a player whose home is in the air, inside blocks or in lava or fire is moved to the nearest safe spot instead: within 3 blocks, or straight down to the ground, or up out of the blocks. If there is no safe spot, the teleport is cancelled with a message. CANCEL always cancels when the spot is unsafe, and OFF always uses the exact spot. The saved home never changes.

Custom buttons

Add buttons to the homes menu that run commands, for example one that opens your shop. In the chest menu a button goes in its slot (0 is the top left). In the modern menu it shows after the homes. A button without a slot only shows in the modern menu.

Commands run as the player. Start a command with console: to run it from the console. {player} is the player's name. The name and lore support PlaceholderAPI placeholders.

yaml
gui:
  custom-buttons:
    shop:
      slot: 51
      item: "minecraft:emerald"
      name: "<green>Buy more homes"
      lore:
        - "<gray>You have %homes_count%/%homes_limit% homes."
      commands:
        - "shop"

Chest layout

border draws an item around the edge of every chest menu. home-slots sets which slots hold homes, with single slots or ranges like "10-16". Leave it empty and Homes uses every free slot above the bottom row, skipping the border and custom buttons. The bottom row always holds the page arrows.

yaml
gui:
  chest:
    rows: 6
    border: "minecraft:black_stained_glass_pane"
    home-slots: ["10-16", "19-25", "28-34", "37-43"]

config.yml

yaml
# Paste your license key below, then restart the server.
# No key yet? Join my Discord: https://discord.gg/nRjDw9k2vJ
license-key: "AP-XXXX-XXXX-XXXX-XXXX"

# Homes
#
# Colours work everywhere: &c &l style codes, &#ff0000 hex,
# or <red> <bold> <gradient:#ff0000:#0000ff> tags.
#
# Chat messages live in messages.yml.

network:
  # single-server           - one server. Leave this if you have no proxy.
  # cross-server-same-proxy - several servers behind one proxy.
  # cross-proxy             - several proxies. Needs Redis switched on below.
  mode: single-server

  # This server's name. Must match the name in your velocity.toml.
  server-name: "lobby"

  # Only used for cross-proxy. Every server behind the same proxy shares this.
  proxy-name: "proxy-1"

  # How long a cross-server teleport stays valid after sending the player.
  handoff-timeout-seconds: 30

storage:
  # SQLITE | MYSQL | MARIADB | MONGODB
  # SQLITE needs no setup, but only works for a single server.
  type: SQLITE

  # SQLITE only. A file inside this plugin's folder.
  file: "homes.db"

  host: "127.0.0.1"
  port: 3306
  database: "homes"
  username: "root"
  password: ""
  table-prefix: "homes_"
  pool-size: 8

  # Extra database connection options. Leave alone unless told otherwise.
  properties:
    useSSL: "false"
    characterEncoding: "utf8"

  mongo:
    # Fill this in to use a full connection string instead of the settings above.
    uri: ""
    collection: "homes"

redis:
  # Required for cross-proxy. Optional otherwise.
  enabled: false
  host: "127.0.0.1"
  port: 6379
  username: ""
  password: ""
  database: 0
  ssl: false
  channel: "homes:network"

homes:
  # The most homes anyone can ever have.
  max: 20

  # How many homes a player gets without a homes.limit.<number> permission.
  default-limit: 3

  # Which slots the menu shows:
  # ALL - every slot up to max. Slots above a player's limit show as locked.
  # ONE - the player's own slots and one locked slot after them.
  locked-slots: ALL

  # Name given by /sethome when you don't type one. {slot} is the slot number.
  default-name: "&fHome {slot}"

  # Icon every new home starts with. Any item.
  default-icon: "minecraft:white_bed"

  # Allow colours in home names. Players also need homes.rename.colors.
  allow-colors: true
  max-name-length: 32

  # Close the gaps after a home is deleted, so homes are always 1, 2, 3...
  # Off by default, because it would move everyone's homes onto other buttons.
  reindex-slots-on-delete: false

  # Worlds where /sethome is not allowed. Not case sensitive.
  # Example:
  #   disabled-worlds:
  #     - "world_nether"
  #     - "minigames"
  disabled-worlds: []

gui:
  # AUTO   - modern menu for new clients, chest menu for old ones. Recommended.
  # DIALOG - always try the modern menu.
  # CHEST  - always use the chest menu.
  mode: AUTO

  # Leave these alone unless the wrong menu is showing up.
  dialog-min-protocol: 772
  use-viaversion: true

  # Bedrock players (Geyser/Floodgate) always get the chest menu, even when
  # mode is DIALOG. Set to false to treat them like Java players.
  bedrock-chest: true

  # Extra buttons in the homes menu, for example a link to your shop.
  # They show in both menus. "slot" is where the button goes in the chest
  # menu (0 is the top left). Without a slot it only shows in the modern menu.
  # Commands run as the player. Start a command with "console:" to run it
  # from the console. {player} is the player's name.
  # Example:
  #   custom-buttons:
  #     shop:
  #       slot: 51
  #       item: "minecraft:emerald"
  #       name: "<green>Buy more homes"
  #       lore:
  #         - "<gray>Opens the shop."
  #       commands:
  #         - "shop"
  custom-buttons: {}

  icons:
    # AUTO  - show item icons on the buttons where possible. Recommended.
    # GLYPH - use your resource pack's characters from the list at the bottom.
    # NONE  - no icons, text only.
    style: AUTO
    sprite-min-protocol: 773

    # Leave as "auto". Only change if icons look wrong.
    atlas: "auto"
    block-atlas: "auto"

    # Some items share a texture with another item - a fence gate looks like
    # planks, a banner looks like wool - because that is how Minecraft draws
    # them. Set this to false to hide icons for those instead.
    approximate-icons: true

    # Force a certain icon for one item. Run /homes icontest <item> in game
    # if you need to work one out.
    overrides: {}

    # Only used when style is GLYPH. Your resource pack's characters.
    glyphs:
      minecraft:white_bed: ""
      minecraft:amethyst_shard: ""

  dialog:
    # Buttons per row, and how wide each one is.
    # The menu cannot scroll sideways, so too many wide buttons run off screen.
    columns: 6
    button-width: 65

    # How many home slots show before the "Show More" button.
    initial-slots: 9

    # How many extra slots each "Show More" click reveals.
    show-more-step: 9

    # Let players collapse the list again.
    allow-show-less: true

    # ESC closes the menu.
    can-close-with-escape: true

    icon-picker:
      # false - choose icons in the modern menu.
      # true  - choose icons in a chest instead.
      use-chest: false

      columns: 4
      button-width: 130

      # 0 shows every item in one scrolling list, which takes a few seconds to open.
      # A number splits the items into pages of that size, which open instantly.
      per-page: 0

      # Items nobody can pick as an icon. Empty by default so every obtainable item is shown.
      blacklist: []

  chest:
    # 6 is a double chest. The bottom row is used for the arrows.
    rows: 6

    # How many home slots show before the "Show More" button.
    initial-slots: 3

    # Background item. Set to "" for empty slots.
    filler: "minecraft:gray_stained_glass_pane"

    # Item drawn around the edge of every chest menu. Set to "" for none.
    border: ""

    # Slots the homes go in, 0 is the top left. Ranges like "10-16" work.
    # The bottom row is kept for the arrows. Leave empty to use every free
    # slot above the bottom row.
    # Example for 6 rows with a border:
    #   home-slots: ["10-16", "19-25", "28-34", "37-43"]
    home-slots: []

    # The items used for each button.
    items:
      show-more: "minecraft:lime_dye"
      show-less: "minecraft:gray_dye"
      new-home: "minecraft:lime_stained_glass_pane"
      locked: "minecraft:red_stained_glass_pane"
      next-page: "minecraft:arrow"
      previous-page: "minecraft:arrow"
      back: "minecraft:barrier"
      teleport: "minecraft:ender_pearl"
      move-here: "minecraft:compass"
      change-icon: "minecraft:item_frame"
      rename: "minecraft:name_tag"
      delete: "minecraft:red_dye"
      search: "minecraft:oak_sign"
      reset-icon: "minecraft:white_bed"

teleport:
  # Seconds to wait before teleporting. 0 teleports instantly.
  warmup-seconds: 3

  # Seconds before a player can teleport again. 0 turns this off.
  cooldown-seconds: 0

  cancel-on-move: true
  cancel-on-damage: true

  # How far a player can move before the teleport cancels, in blocks.
  move-threshold: 0.3

  # What to do when a home's spot is unsafe: in the air, inside blocks, or in
  # lava, fire or other harmful blocks.
  # NEAREST - move the player to the nearest safe spot: within 3 blocks, or
  #           straight down to the ground, or up out of the blocks. Cancels
  #           with a message if there is none.
  # CANCEL  - cancel the teleport with a message.
  # OFF     - always teleport to the exact spot.
  safe-teleport: NEAREST

  # Staff can skip the wait with homes.bypass.warmup / homes.bypass.cooldown.
  sounds:
    # Plays once every second while counting down.
    countdown:
      enabled: true
      key: "minecraft:block.note_block.hat"
      volume: 1.0
      pitch: 1.0
      # Makes each beep a little higher. 0 keeps them all the same.
      pitch-step: 0.15
    arrive:
      enabled: true
      key: "minecraft:entity.enderman.teleport"
      volume: 1.0
      pitch: 1.0
    cancelled:
      enabled: true
      key: "minecraft:entity.villager.no"
      volume: 1.0
      pitch: 1.0
    click:
      enabled: true
      key: "minecraft:ui.button.click"
      volume: 0.5
      pitch: 1.0

# Menu titles and button labels. PlaceholderAPI placeholders work here.
texts:
  homes-title: "Homes"
  picker-title: "Choose Icon"
  new-home: "<dark_gray>New Home"
  locked: "<red>Locked"
  show-more: "Show More"
  show-less: "Show Less"
  back: "Back"
  close: "Close"
  teleport: "Teleport"
  move-here: "Move Here"
  change-icon: "Change Icon"
  rename: "Rename"
  delete: "<red>Delete"
  search: "Search"
  search-label: "Search"
  reset-icon: "Default"
  next-page: "Next Page"
  previous-page: "Previous Page"
  rename-title: "Rename Home"
  rename-label: "New name"
  confirm-delete-title: "Delete {name}?"
  confirm-delete-yes: "<red>Delete"
  confirm-delete-no: "Cancel"

  # The staff menu (/home-admin).
  # You can use: {player} {count} {name} {slot} {world} {server} {x} {y} {z}
  admin-players-title: "Player Homes"
  admin-search-label: "Player name"
  admin-player: "<green>● <white>{player}"
  admin-player-offline: "<red>● <gray>{player}"
  admin-no-players: "<gray>No players found."
  admin-homes-title: "{player}'s Homes <gray>({count})"
  admin-no-homes: "<gray>{player} has no homes."
  admin-home-info: "<gray>{player} <dark_gray>| <gray>{world} <white>{x} {y} {z}"

  # Text shown when hovering a button. Set any to "" to hide it.
  # You can use: {name} {slot} {world} {server} {x} {y} {z}
  tooltips:
    locked: "<gray>Unlock more home slots to use this."
    new-home: "<gray>Click to set new home"
    home: "<white>{name}<newline><gray>Click to manage"
    admin-home: "<white>{name}<newline><gray>{world} <white>{x} {y} {z}"
    home-chest: "<gray>Slot <white>{slot}"
    show-more: "<gray>Reveal <white>{amount}</white> more slots."
    picker-entry: "<gray>{icon}"

# Extra console output for troubleshooting.
debug: false

messages.yml

Each message can independently use chat and action-bar output. Set a channel to an empty list to silence it.

yaml
# Homes - chat messages
#
# Every message has two independent channels:
#
#   chat:      "..."   sent in chat
#   actionbar: "..."   sent above the hotbar
#
# Fill in one, the other, or both. To silence a channel set it to []
# (or leave it as an empty string) - the other channel still fires.
# Setting BOTH to [] disables the message completely.
#
# A prefix is defined below but is NOT used by default. Add {prefix} to
# the front of any message you want it on.
#
# Home names carry the player's own colours and formatting, so every
# placeholder that expands to a name is followed by <reset> and the colour
# re-applied. Without that, a home named "&lBase" would turn the rest of
# the line bold. Keep the <reset> if you edit these.

prefix: "<dark_gray>[<gray>Homes<dark_gray>] <reset>"

messages:

  # Generic
  no-permission:
    chat: "<red>You don't have permission to do that."
    actionbar: []

  player-only:
    chat: "<red>Only players can use this command."
    actionbar: []

  # {usage}
  usage:
    chat: "<gray>Usage: <white>{usage}"
    actionbar: []

  reload-success:
    chat: "<gray>Configuration reloaded."
    actionbar: []

  storage-error:
    chat: "<red>Something went wrong reading your homes. Try again in a moment."
    actionbar: []

  loading:
    chat: []
    actionbar: "<gray>Loading your homes..."

  # Creating / editing
  # {name} {slot}
  home-set:
    chat: "<gray>Saved <white>{name}<reset><gray> in slot <white>{slot}<reset><gray>."
    actionbar: "<gray>Home saved"

  # {limit}
  home-limit-reached:
    chat: "<red>You've used all <white>{limit}<reset><red> of your home slots."
    actionbar: []

  # {name}
  home-deleted:
    chat: "<gray>Deleted <white>{name}<reset><gray>."
    actionbar: []

  # {old} {new}
  home-renamed:
    chat: "<gray>Renamed <white>{old}<reset><gray> to <white>{new}<reset><gray>."
    actionbar: []

  # {name}
  home-moved:
    chat: "<gray>Moved <white>{name}<reset><gray> to where you're standing."
    actionbar: []

  # {name}
  home-not-found:
    chat: "<red>You don't have a home called <white>{name}<reset><red>."
    actionbar: []

  # Staff (/home-admin)
  # {player}
  admin-unknown-player:
    chat: "<red>No player called <white>{player}<reset><red> has been seen here."
    actionbar: []

  # {player} {name}
  admin-home-not-found:
    chat: "<red><white>{player}<reset><red> has no home called <white>{name}<reset><red>."
    actionbar: []

  # {player} {name}
  admin-home-teleport:
    chat: "<gray>Going to <white>{player}<reset><gray>'s home <white>{name}<reset><gray>."
    actionbar: []

  # {player} {name}
  admin-home-deleted:
    chat: "<gray>Deleted <white>{player}<reset><gray>'s home <white>{name}<reset><gray>."
    actionbar: []

  # {player} {old} {new}
  admin-home-renamed:
    chat: "<gray>Renamed <white>{player}<reset><gray>'s home <white>{old}<reset><gray> to <white>{new}<reset><gray>."
    actionbar: []

  # {player} {name}
  admin-home-name-taken:
    chat: "<red><white>{player}<reset><red> already has a home called <white>{name}<reset><red>."
    actionbar: []

  # {usage}
  admin-dialog-unsupported:
    chat: "<red>Your client can't show this menu. Use <white>{usage}<reset><red> instead."
    actionbar: []

  # Staff (/homes import essentials)
  import-started:
    chat: "<gray>Importing EssentialsX homes..."
    actionbar: []

  import-running:
    chat: "<red>An import is already running."
    actionbar: []

  # {path}
  import-not-found:
    chat: "<red>No EssentialsX homes found in <white>{path}<reset><red>."
    actionbar: []

  # {players} {imported} {replaced} {full} {invalid}
  import-done:
    chat: "<gray>Imported <white>{imported}<reset><gray> homes and replaced <white>{replaced}<reset><gray> for <white>{players}<reset><gray> players. Skipped <white>{full}<reset><gray> (no free slot) and <white>{invalid}<reset><gray> (unknown world or name too long)."
    actionbar: []

  # {name}
  home-name-taken:
    chat: "<red>You already have a home called <white>{name}<reset><red>."
    actionbar: []

  # {max}
  rename-too-long:
    chat: "<red>That name is too long (max <white>{max}<reset><red> characters)."
    actionbar: []

  rename-no-colors:
    chat: "<red>You aren't allowed to use colour codes in home names."
    actionbar: []

  rename-prompt:
    chat: "<gray>Type the new name in chat, or <white>cancel<reset><gray> to abort."
    actionbar: "<gray>Type the new name in chat"

  rename-cancelled:
    chat: "<gray>Cancelled."
    actionbar: []

  # Chest GUI only - the dialog GUI has a real text field.
  search-prompt:
    chat: "<gray>Type what you're looking for in chat, or <white>cancel<reset><gray> to abort."
    actionbar: "<gray>Type your search in chat"

  # {icon} - the item's translated name, e.g. "Acacia Door"
  icon-changed:
    chat: "<gray>Icon changed to <white>{icon}<reset><gray>."
    actionbar: []

  # {icon}
  icon-invalid:
    chat: "<red><white>{icon}<reset><red> isn't a valid item."
    actionbar: []

  # {world}
  world-blacklisted:
    chat: "<red>You can't set a home in <white>{world}<reset><red>."
    actionbar: []

  # Teleporting
  # {name} {seconds}
  teleport-warmup:
    chat: "<gray>Teleporting to <white>{name}<reset><gray> in <white>{seconds}<reset><gray>..."
    actionbar: "<gray>Teleporting in <white>{seconds}<reset><gray>..."

  # {name}
  teleport-success:
    chat: "<gray>Welcome to <white>{name}<reset><gray>."
    actionbar: "<gray>Teleported"

  teleport-cancelled-move:
    chat: "<red>Teleport cancelled - you moved."
    actionbar: "<red>Teleport cancelled"

  teleport-cancelled-damage:
    chat: "<red>Teleport cancelled - you took damage."
    actionbar: "<red>Teleport cancelled"

  teleport-already-queued:
    chat: "<red>You already have a teleport in progress."
    actionbar: []

  # {seconds}
  teleport-cooldown:
    chat: "<red>Wait <white>{seconds}s<reset><red> before teleporting again."
    actionbar: "<red>{seconds}s cooldown"

  # {server}
  teleport-cross-server:
    chat: "<gray>Sending you to <white>{server}<reset><gray>..."
    actionbar: "<gray>Connecting..."

  teleport-target-offline:
    chat: "<red>The server that home lives on is offline right now."
    actionbar: []

  teleport-world-missing:
    chat: "<red>That home's world no longer exists."
    actionbar: []

  teleport-unsafe:
    chat: "<red>That home isn't safe to teleport to right now."
    actionbar: []

  # GUI
  dialog-unsupported:
    chat: "<gray>Your client is too old for the new menu - showing the classic one."
    actionbar: []

  # {page} {pages}
  page-changed:
    chat: []
    actionbar: "<gray>Page <white>{page}<reset><gray>/<white>{pages}"

  no-more-pages:
    chat: []
    actionbar: "<red>No more pages"