Homes

Commands

Configuration

All home settings live under the home: section in config.yml.

home:
  # "command" — players type /home <name> directly.
  # "gui" — all home interactions go through an inventory GUI.
  mode: command

  # The home name used when no name argument is given in command mode,
  # and for the quick-create button in GUI mode.
  default-name: home

  # The default maximum number of homes a player can set.
  # This can be overridden per-player with LuckPerms permissions.
  max-homes: 3

  # Seconds a player must wait between home teleports.
  # Set to 0 to disable. Bypassed by: essentialsc.home.admin
  cooldown: 5

  # Seconds the player must stand still before being teleported.
  # Set to 0 to teleport instantly. Bypassed by: essentialsc.home.admin
  warmup: 3

  # Cancel the teleport if the player moves during the warmup.
  cancel-on-movement: true

  # Play particles on arrival.
  particles: true

  # Play sounds during home teleport events.
  sounds: true

  # Worlds where /home and /sethome are completely blocked.
  blocked-worlds:
    - world_example_blocked

Permissions

Home Names

Home names must follow these rules:

• Characters — Only letters, numbers, underscores, and hyphens: ^[a-zA-Z0-9_-]+$
• Length — Maximum 16 characters
• Case — Names are stored lowercase in the database. Base and base are the same home.
• Uniqueness — Each home name must be unique per player. You cannot have two homes named base.

If you try to set a home with an existing name, it will be overwritten with the new location.

Teleport Mechanics

When you run /home <name>, the teleport goes through several checks:

1. Blocked world check — If the home is in a world listed in home.blocked-worlds, the teleport is cancelled.
2. Cooldown check — If you have teleported to a home within the cooldown period (default 5s), you must wait. Bypassed by essentialsc.home.admin.
3. Warmup — If warmup is enabled (default 3s), you must stand still. Moving cancels the teleport if cancel-on-movement is true.
4. Async teleport — The actual teleport is performed asynchronously (safe for Folia).
5. Effects — Portal particles spawn at the destination and an Enderman teleport sound plays (if enabled in config).

Quitting the server while a warmup is active automatically cancels the pending teleport.

Admin Features

Admins with essentialsc.home.admin have extended home capabilities:

• Teleport to any player's home — /home <player> <homename>
• List other players' homes — /homes <player> (works for offline players too)
• Bypass cooldown and warmup — Admin teleports are instant
• Bypass blocked worlds — Can set and teleport to homes in any world
• Bypass home limits — Can set unlimited homes

Database

Homes are stored in plugins/EssentialsC/database/homes.db (SQLite). The schema is:

CREATE TABLE homes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid TEXT NOT NULL,
    name TEXT NOT NULL,
    world TEXT NOT NULL,
    x REAL NOT NULL,
    y REAL NOT NULL,
    z REAL NOT NULL,
    yaw REAL NOT NULL,
    pitch REAL NOT NULL,
    created_at INTEGER DEFAULT (strftime('%s', 'now')),
    UNIQUE(uuid, name)
);

CREATE INDEX idx_homes_uuid ON homes(uuid);

All database operations are async. A memory cache of home names is maintained per player for fast tab-completion and GUI rendering. The cache is cleared on /essc reload and server shutdown.

Additional tables for the notification system:

CREATE TABLE home_notifications (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    target_uuid TEXT NOT NULL,
    type TEXT NOT NULL,        -- DELETED, RENAMED, RELOCATED
    home_name TEXT NOT NULL,
    extra TEXT,                -- new name for RENAMED
    admin_name TEXT NOT NULL,
    created_at INTEGER NOT NULL
);

CREATE TABLE home_notification_settings (
    uuid TEXT PRIMARY KEY,
    enabled INTEGER NOT NULL DEFAULT 1
);

GUI Mode Details

When mode: gui is set in config, the home system switches to inventory-based interaction:

• /home — Opens the home list GUI showing all saved homes as clickable items
• /sethome — Opens the create GUI with a sign input for naming the new home
• /delhome — Opens a confirmation dialog before deleting
• Home items — Each home is represented by an icon showing the world and coordinates
• Navigation — Pagination for players with many homes
• Admin view — Admins can open other players' home GUIs

The GUI uses the same database and teleport mechanics as command mode — only the interface changes.

Migration from EssentialsX

When migrating from EssentialsX, homes are imported from plugins/Essentials/userdata/<uuid>.yml:

• Each entry under homes: in the YAML is converted to a database record
• World UUID is resolved first, falling back to world name if the UUID is invalid
• Coordinates, yaw, and pitch are preserved exactly
• Conflicting home names use the migration conflict strategy (skip, overwrite, or rename)

Run /migration essentialsx to start the import. See the Migration Guide for full details.

Troubleshooting

"You have reached the home limit"

The player has hit their maximum home count. Grant a higher essentialsc.sethome.<number> permission, or use essentialsc.sethome.unlimited.

"Home teleport blocked in this world"

The home is located in a world listed in home.blocked-worlds. Remove the world from the config, or grant essentialsc.sethome.admin to bypass.

Home not found after server restart

Check that the world folder name matches the world column in the database. If you renamed the world folder, homes in that world will fail to resolve. Use /essc dump to inspect the database.

Cooldown not resetting

Cooldowns are stored in-memory and reset on server restart. If a player reports cooldown issues, check that home.cooldown is not set to an unexpectedly high value.

GUI not opening

Ensure mode: gui is set in config.yml and run /essc reload. GUI mode requires no additional dependencies.

Next Steps