SimpleHomes

SimpleHomes is a home plugin that does exactly what you expect: /sethome, /home, /delhome and /homes. It is set up in a minute, but every message, sound, particle, delay and limit can be changed in the config.

How many homes a player may have is controlled with permissions, so it works with LuckPerms or any other permission plugin. All homes are saved in a single homes.yml file. Saving happens in the background, so the server never waits for the disk.

Features

• /sethome, /home, /delhome and /homes - nothing more you have to learn
• Home limits through permissions: a number (simplehomes.limit.5), a named group from the config (simplehomes.limit.vip) or unlimited
• Homes list in chat, clickable to teleport, with world and coordinates on hover
• /home without a name picks the only home or the default home, otherwise it shows the list
• Teleport delay with countdown and a cooldown
• Teleport gets cancelled when the player moves or takes damage
• Particles and sounds for teleporting, waiting, setting and deleting homes
• Chat and actionbar messages, all editable, with hex colors and gradients
• PlaceholderAPI support: placeholders in all messages and own placeholders for scoreboards, tabs and menus
• Manage homes of other players (/home Steve:base, /homes Steve, /delhome Steve:base), also for offline players
• Optional respawn at home after death
• World blacklists for /sethome and /home
• Optional: players that lost a rank can only use their oldest homes up to their new limit (nothing gets deleted)
• Bypass permissions for every restriction
• Update notification in the console and for admins on join
• /simplehomes updateconfig adds new options to an old config without touching your settings

Compatibility

• Paper, Purpur, Folia and Spigot
• Minecraft 1.20.1 up to 26.x
• Java 17 or newer

On Paper, Purpur and Folia the target chunk is loaded async before teleporting, so teleporting to a far away home won't lag the server. On Folia every teleport and countdown runs on the player's own region thread.

Particle and sound names from old and new versions both work (for example VILLAGER_HAPPY and HAPPY_VILLAGER), so you don't have to change your config when you update the server.

Colors: normal & codes, hex like &#00a4fc or <#00a4fc> and gradients like <gradient:#4facfe:#00f2fe>Text</gradient>.

Commands

/shomes is short for /simplehomes. /deletehome and /removehome work as /delhome, /listhomes as /homes.

Permissions

Home limits

Every player gets home-limits.default homes. Give more with permissions, the highest value a player has wins:

Groups can be renamed, removed or added freely in home-limits.groups. Example with LuckPerms:

/lp group vip permission set simplehomes.limit.vip true
/lp user Steve permission set simplehomes.limit.8 true

If a player loses a rank, their homes are never deleted. They just can't set new ones until they are below their limit again. With restrict-excess-homes: true they can also only use their oldest homes up to the new limit.

/home without a name

PlaceholderAPI

The texts for unlimited, no homes and yes/no can be changed in the placeholders section of the config. Placeholders from other plugins (%player_name%, %vault_eco_balance%, ...) work in every SimpleHomes message.

Message placeholders

Storage

All homes are stored in plugins/SimpleHomes/homes.yml, grouped by player UUID, so name changes don't lose any homes. Every change is saved right away on a background thread. The file is written to a temporary file first and then replaced, so a crash during saving can't break it. Only edit the file while the server is stopped.

Configuration

# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃             SimpleHomes Configuration v1.0.0            ┃
# ┃                     SimplePlugins                       ┃
# ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

ConfigVersion: 1.0.0 # Used for automatic config updates (/simplehomes updateconfig) don't change this!

# Colors: &a &l ... | hex: &#00a4fc or <#00a4fc> | gradients: <gradient:#4facfe:#00f2fe>Text</gradient>
# PlaceholderAPI placeholders (%player_name% etc.) work in all messages if PlaceholderAPI is installed
# particles: https://jd.papermc.io/paper/org/bukkit/Particle.html (old names like VILLAGER_HAPPY still work)
# sounds: https://jd.papermc.io/paper/org/bukkit/Sound.html

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Update:
  Notification:
    enabled: true # Check Modrinth for new versions (console message)
    notify-on-join: true # Tell players with simplehomes.update about new versions when they join

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

homes: default-name: "home" # Name used by /sethome and /home without a name name-pattern: "^[A-Za-z0-9_-]{1,16}$" # Allowed home names (regex) overwrite-existing: true # /sethome moves that home. false = player has to /delhome first

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

How many homes a player may have. The highest value a player has wins.

simplehomes.limit. e.g. simplehomes.limit.5

simplehomes.limit. a group from below, e.g. simplehomes.limit.vip

simplehomes.limit.unlimited no limit (default: op)

home-limits: default: 3 # Homes everyone has without a limit permission groups: vip: 5 mvp: 10 staff: 25

Players that lost a rank keep their homes. true = they can only use their oldest homes

restrict-excess-homes: false

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

homes-list: # /homes clickable: true # Click a home in the list to teleport there hover-coordinates: true # Show world and coordinates when hovering a home sort: created # created = oldest first | name = alphabetical separator: "&7, " # Text between two homes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

world-blacklist: sethome: # Worlds where /sethome is not allowed enabled: false worlds: - "world_the_end" teleport: # Worlds players can't use /home from enabled: false worlds: - "pvp_arena" # For custom worlds: Use the exact folder name! chat-message: true # Show message in chat actionbar-message: true # Show message in actionbar

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

respawn-at-home: enabled: false # Respawn at a home after death (needs simplehomes.respawnhome) home-name: "home" # Home to respawn at. If the player doesn't have it, their first home is used ignore-bed-anchor: false # true = home even if the player has a bed or respawn anchor

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

command_cooldown: enabled: true # Cooldown between two /home teleports seconds: 10 # Cooldown time in seconds

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

actionbar: enabled: true # Master switch for actionbar messages

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

teleport-delay: enabled: true # Wait before teleporting seconds: 3 # Delay time in seconds chat-countdown-messages: false # Show countdown messages in chat actionbar-countdown-messages: true # Show countdown messages in actionbar chat-teleport-delay: true # Show "Teleporting in ..." in chat actionbar-teleport-delay: false # Show "Teleporting in ..." in actionbar

particle_enabled: true # Particles every second while waiting particle_name: PORTAL # Particle name number_of_particles: 30 # Number of particles particle_size: 0.6 # Spread of the particles

sound_enabled: true # Sound every second while waiting sound_name: BLOCK_NOTE_BLOCK_HAT # Sound name sound_volume: 1.0 # Volume of the sound sound_pitch: 1.5 # Pitch of the sound sound_all_players: false # Play sound for all players nearby

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

movement-cancel: enabled: true # Cancel teleport if player moves sensitivity: 1.0 # How far (in blocks) the player can move before the teleport is cancelled cancel-on-block-change: false # Cancel as soon as the player walks onto another block chat-message: true # Show message in chat actionbar-message: true # Show message in actionbar

damage-cancel: enabled: true # Cancel teleport if player takes damage chat-message: true # Show message in chat actionbar-message: true # Show message in actionbar

teleport-cancel: sound_enabled: true # Sound when a teleport is cancelled sound_name: ENTITY_VILLAGER_NO # Sound name sound_volume: 1.0 # Volume of the sound sound_pitch: 1.0 # Pitch of the sound sound_all_players: false # Play sound for all players nearby

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

on_teleport: chat-message: true # Show "teleported" message in chat actionbar-message: true # Show "teleported" message in actionbar

particle_enabled: true # Particles after teleporting particle_name: END_ROD # Particle name number_of_particles: 40 # Number of particles particle_size: 0.8 # Spread of the particles

sound_enabled: true # Sound after teleporting sound_name: ENTITY_ENDERMAN_TELEPORT # Sound name sound_volume: 1.0 # Volume of the sound sound_pitch: 1.0 # Pitch of the sound sound_all_players: false # Play sound for all players nearby

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

on_sethome: particle_enabled: true # Particles when a home is set particle_name: HAPPY_VILLAGER # Particle name number_of_particles: 20 # Number of particles particle_size: 0.5 # Spread of the particles

sound_enabled: true # Sound when a home is set sound_name: ENTITY_PLAYER_LEVELUP # Sound name sound_volume: 0.7 # Volume of the sound sound_pitch: 1.6 # Pitch of the sound sound_all_players: false # Play sound for all players nearby

on_delhome: sound_enabled: true # Sound when a home is deleted sound_name: BLOCK_WOODEN_DOOR_CLOSE # Sound name sound_volume: 1.0 # Volume of the sound sound_pitch: 1.0 # Pitch of the sound sound_all_players: false # Play sound for all players nearby

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PlaceholderAPI: %simplehomes_count%, %simplehomes_limit%, %simplehomes_remaining%,

%simplehomes_list%, %simplehomes_cooldown%, %simplehomes_has_%

placeholders: unlimited: "∞" # Shown by %simplehomes_limit% and %simplehomes_remaining% for unlimited players no-homes: "-" # Shown by %simplehomes_list% if the player has no homes has-home: "yes" # %simplehomes_has_% when the player has that home has-not-home: "no" # %simplehomes_has_% when the player doesn't have it

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

actionbar_messages: # Actionbar messages teleported: "&7Teleported to &#00a4fc{home}" teleport-delay: "&7Teleporting in &#00a4fc{time}s &c(Don't move!)" countdown: "&7Teleporting in &#00a4fc{time}s" teleport-cancelled: "&cTeleport cancelled (movement)!" damage-cancelled: "&cTeleport cancelled (damage)!" blocked-world: "&cHomes are not allowed in this world!"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Placeholders: {home} {player} {time} {count} {limit} {world} {x} {y} {z} {version} {latest}

prefix_enabled: true messages: # Chat messages prefix: "&8[gradient:#4facfe:#00f2feSimpleHomes&8] " home-set: "&7Home &#00a4fc{home} &7set. &8({count}/{limit})" home-moved: "&7Home &#00a4fc{home} &7moved to your location." home-exists: "&cYou already have a home called &f{home}&c. Delete it first with /delhome {home}." home-deleted: "&7Home &#00a4fc{home} &7deleted." home-not-found: "&cYou don't have a home called &f{home}&c." no-homes: "&cYou don't have any homes yet. Use &f/sethome &cto set one." limit-reached: "&cYou reached your home limit of &f{limit}&c. Delete a home first." invalid-name: "&cInvalid home name &f{home}&c. Use letters, numbers, _ or - (max 16)." usage-delhome: "&cUsage: /delhome " home-over-limit: "&cYou can only use your first &f{limit} &chomes with your current rank." world-not-loaded: "&cThe world &f{world} &cof this home is not loaded." teleported: "&7Teleported to &#00a4fc{home}&7." teleport-delay: "&7Teleporting to &#00a4fc{home} &7in &#00a4fc{time} seconds&7. &c(Don't move!)" countdown: "&7Teleporting in &#00a4fc{time}s" teleport-cancelled: "&cTeleport cancelled (movement)!" damage-cancelled: "&cTeleport cancelled (damage)!" teleport-failed: "&cTeleport failed." cooldown: "&cYou must wait &#00a4fc{time} seconds &cbefore teleporting again." sethome-blocked-world: "&cYou can't set homes in this world!" teleport-blocked-world: "&cYou can't use /home in this world!" respawned-at-home: "&7You respawned at your home &#00a4fc{home}&7."

/homes

homes-header: "&7Your homes &8({count}/{limit})&7:" homes-header-other: "&7Homes of &#00a4fc{player} &8({count}/{limit})&7:" homes-entry: "&#00a4fc{home}" homes-entry-locked: "&8{home}" homes-hover: "&7World: &f{world}\n&7X: &f{x} &7Y: &f{y} &7Z: &f{z}\n&8Click to teleport" homes-hover-locked: "&cAbove your home limit" no-homes-other: "&c{player} doesn't have any homes."

other players

player-not-found: "&cPlayer &f{player} &cwas not found." other-home-set: "&7Home &#00a4fc{home} &7of &#00a4fc{player} &7set." other-home-deleted: "&7Home &#00a4fc{home} &7of &#00a4fc{player} &7deleted." other-home-not-found: "&c{player} doesn't have a home called &f{home}&c."

general

no-permission: "&cYou don't have permission." player-only: "&cOnly players can run this command." unknown-command: "&cUnknown command. Try /simplehomes help." config-reloaded: "&aConfiguration reloaded." config-updated: "&aThe config has been updated to the latest version!" config-up-to-date: "&7Your config is already up-to-date." config-recreated: "&aNew config.yml has been created. The old one was saved as &eoldconfig.yml&a." recreateconfig-failed: "&cCould not back up the old config.yml. Nothing was changed." version: "&7You are running &#00a4fcSimpleHomes v{version}&7." update-available: "&7A new version is available: &c{version} &8-> &a{latest}\n&7Download: &#00a4fc/plugins/simplehomes1"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

help-messages: # /simplehomes help

• "&8&m--------------------------------"
• "gradient:#4facfe:#00f2feSimpleHomes Help"
• "&7/sethome [name] &8- &fSet a home. (simplehomes.sethome)"
• "&7/home [name] &8- &fTeleport to a home. (simplehomes.home)"
• "&7/delhome &8- &fDelete a home. (simplehomes.delhome)"
• "&7/homes [player] &8- &fList homes. (simplehomes.homes)"
• "&7/home : &8- &fUse homes of others. (simplehomes.home.others)"
• "&7/simplehomes reload &8- &fReload the config. (simplehomes.admin.reload)"
• "&7/simplehomes updateconfig &8- &fAdd new options to the config. (simplehomes.admin.updateconfig)"
• "&7/simplehomes recreateconfig &8- &fCreate a fresh config. (simplehomes.admin.recreateconfig)"
• "&7/simplehomes version &8- &fPlugin version. (simplehomes.admin.version)"
• "&8&m--------------------------------"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

</details>

## Metrics

SimpleHomes uses bStats to collect anonymous usage data, for example how many homes servers have and which features are used. You can turn it off for all plugins in `plugins/bStats/config.yml`.