HuskHomes

https://github.com/wiiiiam278/huskhomes
Admin
HuskHomes is a powerful and intuitive teleportation plugin for Minecraft Java Edition servers,...
Tokens:40,014
Snippets:406
Trust Score:9.9
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install HuskHomes on Spigot/Paper

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Steps to install HuskHomes on Spigot or Paper servers. Download the JAR, place it in the plugins directory, and start the server to generate configuration files.

```bash
# For Spigot/Paper servers:
# 1. Download HuskHomes-Paper.jar from GitHub releases
# 2. Place in /plugins/ directory
# 3. Start server to generate config files
# 4. Configure plugins/HuskHomes/config.yml
```

--------------------------------

### Install HuskHomes on Fabric

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Steps to install HuskHomes on Fabric servers. Download the JAR, place it in the mods directory, and start the server to generate configuration files.

```bash
# For Fabric servers:
# 1. Download HuskHomes-Fabric.jar from GitHub releases
# 2. Place in /mods/ directory
# 3. Start server to generate config files
# 4. Configure config/huskhomes/config.yml
```

--------------------------------

### HuskHomes General Configuration Example

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Example configuration settings for the HuskHomes plugin in config.yml, covering language, updates, home limits, teleport settings, and more.

```yaml
# config.yml - General settings
language: en-gb
check_for_updates: true

general:
  # Home limits
  max_homes: 10
  max_public_homes: 10
  stack_permission_limits: false  # Stack multiple permission nodes

  # Warp restrictions
  permission_restrict_warps: false  # Require huskhomes.warp.<name>

  # Teleport warmup settings
  teleport_warmup_time: 5           # Seconds to wait
  teleport_warmup_cancel_on_damage: true
  teleport_warmup_cancel_on_move: true
  teleport_warmup_display: ACTION_BAR  # CHAT, ACTION_BAR, TITLE, SUBTITLE, NONE

  # Teleport settings
  teleport_invulnerability_time: 0  # Seconds of invulnerability after teleport
  teleport_request_expiry_time: 60  # Request timeout in seconds
  strict_tpa_here_requests: true
  list_items_per_page: 12
  always_respawn_at_spawn: false
  teleport_async: true

  # Name restrictions
  names:
    overwrite_existing: true
    case_insensitive: false
    restrict: true
    regex: '[a-zA-Z0-9-_]*'

  # Description restrictions
  descriptions:
    restrict: false
    regex: \A\p{ASCII}*\z

  # Back command settings
  back_command:
    return_by_death: true
    save_on_teleport_event: false
    restricted_worlds: []

  # Sound effects
  sound_effects:
    enabled: true
    types:
      TELEPORTATION_COMPLETE: entity.enderman.teleport
      TELEPORTATION_WARMUP: block.note_block.banjo
      TELEPORTATION_CANCELLED: entity.item.break
      TELEPORT_REQUEST_RECEIVED: entity.experience_orb.pickup

# Disable specific commands
disabled_commands: []  # e.g., ['/rtp', '/tpa']
```

--------------------------------

### Fabric Callback Example

Source: https://github.com/wiiiiam278/huskhomes/blob/master/docs/API-Events.md

Example of how to register a callback for HuskHomes events on the Fabric platform.

```APIDOC
### Fabric Callback Registration

Fabric uses callbacks for handling events. Below is an example of registering a callback for home creation.

```java
HomeCreateCallback.EVENT.register((player, home) -> {
    // Do something with the player and home
    return ActionResult.SUCCESS; // Return an appropriate ActionResult
});
```
```

--------------------------------

### HuskHomes Permission Nodes Example

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Example configuration for permission nodes in plugin.yml, controlling access to HuskHomes features.

```yaml
# plugin.yml - Example permission configuration

# Home commands
huskhomes.command.home: true           # Use /home
huskhomes.command.home.other: false    # Access other players' homes
huskhomes.command.sethome: true        # Set homes
huskhomes.command.delhome: true        # Delete own homes
huskhomes.command.delhome.other: false # Delete others' homes
huskhomes.command.homelist: true       # View home list
huskhomes.command.edithome: true       # Edit homes

# Warp commands
huskhomes.command.warp: true           # Use warps
huskhomes.command.setwarp: false       # Create warps (admin)
huskhomes.command.delwarp: false       # Delete warps (admin)
huskhomes.command.editwarp: false      # Edit warps (admin)

# Teleport requests
huskhomes.command.tpa: true            # Send teleport requests
huskhomes.command.tpahere: true        # Request others to teleport to you
huskhomes.command.tpaccept: true       # Accept requests
huskhomes.command.tpdecline: true      # Decline requests

# Admin teleports
huskhomes.command.tp: false            # Admin teleport
huskhomes.command.tphere: false        # Teleport others to you
huskhomes.command.tpall: false         # Teleport all players

# Home limits (numeric permissions)
huskhomes.max_homes.10                 # Max 10 homes
huskhomes.free_homes.5                 # 5 free home slots
huskhomes.max_public_homes.3           # Max 3 public homes
huskhomes.teleport_warmup.3            # 3 second warmup

# Bypass permissions
huskhomes.bypass_teleport_warmup       # Skip warmup timer
huskhomes.bypass_cooldowns             # Skip action cooldowns
huskhomes.bypass_economy_checks        # Skip economy costs
```

--------------------------------

### Redis Configuration Options

Source: https://github.com/wiiiiam278/huskhomes/wiki/Redis

Example configuration block for Redis settings in config.yml. Adjust host, port, password, and SSL usage as per your Redis server setup.

```yaml
redis:
  host: localhost
  port: 6379
  # Password for your Redis server. Leave blank if you're not using a password.
  password: ''
  use_ssl: false
  # Settings for if you're using Redis Sentinels.
  # If you're not sure what this is, please ignore this section.
  sentinel:
    master_name: ''
    # List of host:port pairs
    nodes:
    password: ''
```

--------------------------------

### Gradle Repository Setup for HuskHomes API

Source: https://github.com/wiiiiam278/huskhomes/wiki/API

Add this repository to your build.gradle file to fetch HuskHomes API artifacts. Development builds can be accessed via '/snapshots'.

```groovy
allprojects {
	repositories {
		maven { url 'https://repo.william278.net/releases' }
	}
}
```

--------------------------------

### Maven Repository Setup for HuskHomes API

Source: https://github.com/wiiiiam278/huskhomes/wiki/API

Add this repository to your pom.xml to access HuskHomes API releases. For development builds, use the '/snapshots' URL.

```xml
<repositories>
    <repository>
        <id>william278.net</id>
        <url>https://repo.william278.net/releases</url>
    </repository>
</repositories>
```

--------------------------------

### GET /spawn

Source: https://github.com/wiiiiam278/huskhomes/wiki/Commands

Teleport to the spawn position or teleport another user to spawn.

```APIDOC
## GET /spawn

### Description
Teleport to the spawn position or teleport another online user to the spawn position.

### Method
GET

### Endpoint
/spawn [teleporter_name]

### Parameters
#### Path Parameters
- **teleporter_name** (string) - Optional - The name of the online user to teleport.
```

--------------------------------

### Get a HuskHomes API instance

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

Retrieve the API instance using the static getInstance method within your hook class.

```java
import net.william278.huskhomes.api.HuskHomesAPI;

public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    public HuskHomesAPIHook() {
        this.huskHomesAPI = HuskHomesAPI.getInstance();
    }

}
```

--------------------------------

### HuskHomes General Configuration (config.yml)

Source: https://github.com/wiiiiam278/huskhomes/wiki/Config-Files

This is the main configuration file for HuskHomes. It controls general plugin settings such as language, update checks, and database connection details. Ensure database credentials are correct for your setup.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃       HuskHomes Config       ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ Information: https://william278.net/project/huskhomes/
# ┣╸ Config Help: https://william278.net/docs/huskhomes/config-files/
# ┗╸ Documentation: https://william278.net/docs/huskhomes/

# Locale of the default language file to use. Docs: https://william278.net/docs/huskhomes/translations
language: en-gb
# Whether to automatically check for plugin updates on startup
check_for_updates: true
# Database settings
database:
  # Type of database to use (SQLITE, H2, MYSQL, MARIADB, or POSTGRESQL)
  type: SQLITE
  # Specify credentials here if you are using MYSQL, MARIADB, or POSTGRESQL
  credentials:
    host: localhost
    port: 3306
    database: huskhomes
    username: root
    password: pa55w0rd
    parameters: ?autoReconnect=true&useSSL=false&useUnicode=true&characterEncoding=UTF-8
  # MYSQL / MARIADB / POSTGRESQL database Hikari connection pool properties
  # Don't modify this unless you know what you're doing!
  pool_options:
    size: 12
    idle: 12
    lifetime: 1800000
    keep_alive: 30000
    timeout: 20000
  # Names of tables to use on your database. Don't modify this unless you know what you're doing!
  table_names:
    PLAYER_DATA: huskhomes_users
    PLAYER_COOLDOWNS_DATA: huskhomes_user_cooldowns
    POSITION_DATA: huskhomes_position_data
    SAVED_POSITION_DATA: huskhomes_saved_positions
    HOME_DATA: huskhomes_homes
    WARP_DATA: huskhomes_warps
    TELEPORT_DATA: huskhomes_teleports

```

--------------------------------

### Build HuskHomes from Source

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Instructions for building HuskHomes from source code using Gradle. Requires Java 21.

```bash
# Build from source (requires Java 21):
./gradlew clean build
```

--------------------------------

### Build HuskHomes from Source

Source: https://github.com/wiiiiam278/huskhomes/blob/master/README.md

Execute this command in the root directory of the repository to build the project. Requires Java 21.

```bash
./gradlew clean build
```

--------------------------------

### Configure Redis Host and Bindings

Source: https://github.com/wiiiiam278/huskhomes/wiki/Redis

Access the Redis configuration file to set the host and bind settings.

```bash
nano /etc/redis/redis.conf
```

--------------------------------

### GET /tp

Source: https://github.com/wiiiiam278/huskhomes/wiki/Commands

Teleport to users or specific coordinates.

```APIDOC
## GET /tp

### Description
Teleport to an online user, teleport another user to a target, or teleport to specific coordinates.

### Method
GET

### Endpoint
/tp <target_name | teleporter_name | coordinates>

### Parameters
#### Path Parameters
- **target_name** (string) - Optional - The user to teleport to.
- **teleporter_name** (string) - Optional - The user to be teleported.
- **coordinates** (string) - Optional - The target coordinates (x, y, z, yaw, pitch, world_name, server_name).
```

--------------------------------

### GET /phomelist

Source: https://github.com/wiiiiam278/huskhomes/wiki/Commands

View the list of public homes.

```APIDOC
## GET /phomelist

### Description
View the list of public homes.

### Method
GET

### Endpoint
/phomelist [page]

### Parameters
#### Path Parameters
- **page** (integer) - Optional - The page number of the list to view.
```

--------------------------------

### GET /warp

Source: https://github.com/wiiiiam278/huskhomes/wiki/Commands

Teleport to a warp or teleport another user to a warp.

```APIDOC
## GET /warp

### Description
Teleport to a warp or teleport another online user to a warp.

### Method
GET

### Endpoint
/warp [name] [teleporter_name]

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the warp.
- **teleporter_name** (string) - Optional - The name of the online user to teleport.
```

--------------------------------

### Get Player Home Slot Limits

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Retrieves the maximum, free, and public home slot limits for an online player.

```java
    // Get home slot limits for online player
    public void getHomeLimits(org.bukkit.entity.Player player) {
        var user = api.adaptUser(player);

        int maxHomes = api.getMaxHomeSlots(user);
        int freeSlots = api.getFreeHomeSlots(user);
        int maxPublic = api.getMaxPublicHomeSlots(user);

        System.out.println("Max homes: " + maxHomes);
        System.out.println("Free slots: " + freeSlots);
        System.out.println("Max public: " + maxPublic);
    }
}
```

--------------------------------

### Configure Global Spawn

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Set up a network-wide spawn point using a warp.

```yaml
# config.yml - Global spawn settings
cross_server:
  enabled: true
  global_spawn:
    enabled: true
    warp_name: Spawn  # Name of the warp to use as global spawn
  global_respawning: false  # Cross-server respawn positions
```

--------------------------------

### Spawn Commands

Source: https://github.com/wiiiiam278/huskhomes/blob/master/docs/Commands.md

Commands for managing and teleporting to the spawn point.

```APIDOC
## GET /spawn

### Description
Teleport to the spawn position.

### Method
GET

### Endpoint
/spawn

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of successful teleportation.
```

```APIDOC
## POST /spawn

### Description
Teleport another online user to the spawn position.

### Method
POST

### Endpoint
/spawn [teleporter_name]

### Parameters
#### Path Parameters
- **teleporter_name** (string) - Optional - The name of the user to teleport.
```

```APIDOC
## POST /setspawn

### Description
Set the spawn position to your current location.

### Method
POST

### Endpoint
/setspawn
```

--------------------------------

### Initialize HuskHomes API

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Initialize the HuskHomes API in your plugin. Check for the plugin's presence before attempting to use the API to prevent ClassNotFoundExceptions.

```java
import net.william278.huskhomes.api.HuskHomesAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    private HuskHomesAPIHook huskHomesHook;

    @Override
    public void onEnable() {
        // Check if HuskHomes is present before using API
        if (Bukkit.getPluginManager().getPlugin("HuskHomes") != null) {
            this.huskHomesHook = new HuskHomesAPIHook();
            getLogger().info("HuskHomes integration enabled!");
        }
    }
}

// Separate hook class to avoid ClassNotFoundException if HuskHomes isn't installed
public class HuskHomesAPIHook {
    private final HuskHomesAPI api;

    public HuskHomesAPIHook() {
        this.api = HuskHomesAPI.getInstance();
    }

    public HuskHomesAPI getAPI() {
        return api;
    }
}
```

--------------------------------

### Get User Data by Username

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Retrieves user data by their username. This method uses a lambda to process the optional user data if found.

```java
    // Get saved user data by username
    public void getUserByName(String username) {
        api.getUserData(username).thenAccept(optionalUser -> {
            optionalUser.ifPresent(user -> {
                System.out.println("Found user: " + user.getUserUuid());
            });
        });
    }
```

--------------------------------

### Get Specific Warp by Name with HuskHomes API

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Retrieves a specific warp by its name and prints its details if found. The result is returned asynchronously.

```java
    // Get a specific warp by name
    public void getWarp(String warpName) {
        api.getWarp(warpName).thenAccept(optionalWarp -> {
            if (optionalWarp.isPresent()) {
                Warp warp = optionalWarp.get();
                System.out.println("Warp: " + warp.getName());
                System.out.println("Position: " + warp.getX() + ", " + warp.getY() + ", " + warp.getZ());
                System.out.println("Server: " + warp.getServer());
            } else {
                System.out.println("Warp not found");
            }
        });
    }
```

--------------------------------

### Configure Analytics and Permissions Hooks

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Enable integration with Plan or LuckPerms.

```yaml
# config.yml - Plan hook settings
plan:
  enabled: true
```

```yaml
# config.yml - LuckPerms hook settings
luckperms:
  enabled: true
```

--------------------------------

### Manage Player Homes with HuskHomes API

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Demonstrates various operations for managing player homes, including listing, creating, deleting, and updating home properties. All asynchronous operations return CompletableFutures.

```java
import net.william278.huskhomes.api.HuskHomesAPI;
import net.william278.huskhomes.position.Home;
import net.william278.huskhomes.position.Position;
import net.william278.huskhomes.user.OnlineUser;
import net.william278.huskhomes.user.User;
import org.bukkit.entity.Player;
import java.util.List;
import java.util.UUID;

public class HomeManager {
    private final HuskHomesAPI api = HuskHomesAPI.getInstance();

    // Get all homes for a player
    public void listPlayerHomes(Player player) {
        OnlineUser user = api.adaptUser(player);

        api.getUserHomes(user).thenAccept(homes -> {
            System.out.println(user.getUsername() + " has " + homes.size() + " homes:");
            for (Home home : homes) {
                System.out.println("- " + home.getName() +
                    (home.isPublic() ? " (public)" : " (private)"));
            }
        });
    }

    // Get a specific home by name
    public void getHome(Player player, String homeName) {
        OnlineUser user = api.adaptUser(player);

        api.getHome(user, homeName).thenAccept(optionalHome -> {
            if (optionalHome.isPresent()) {
                Home home = optionalHome.get();
                System.out.println("Found home: " + home.getName());
                System.out.println("Position: " + home.getX() + ", " + home.getY() + ", " + home.getZ());
                System.out.println("World: " + home.getWorld().getName());
                System.out.println("Description: " + home.getMeta().getDescription());
            } else {
                System.out.println("Home not found");
            }
        });
    }

    // Create a new home for a player
    public void createHome(Player player, String homeName) {
        OnlineUser user = api.adaptUser(player);
        Position position = user.getPosition();

        api.createHome(user, homeName, position)
            .thenAccept(home -> {
                System.out.println("Created home: " + home.getName());
            })
            .exceptionally(e -> {
                // ValidationException if name invalid, too many homes, etc.
                System.out.println("Failed to create home: " + e.getMessage());
                return null;
            });
    }

    // Create home with additional options
    public void createHomeAdvanced(Player player, String homeName) {
        OnlineUser user = api.adaptUser(player);
        Position position = user.getPosition();

        api.createHome(
            user,
            homeName,
            position,
            true,   // overwrite existing home with same name
            true,   // buy additional slots if needed
            false,  // don't ignore max homes limit
            false   // don't ignore home slots
        ).thenAccept(home -> {
            System.out.println("Created home: " + home.getName());
        });
    }

    // Delete a home
    public void deleteHome(Player player, String homeName) {
        OnlineUser user = api.adaptUser(player);
        api.deleteHome(user, homeName);
        System.out.println("Deleted home: " + homeName);
    }

    // Rename a home
    public void renameHome(Player player, String oldName, String newName) {
        OnlineUser user = api.adaptUser(player);
        api.renameHome(user, oldName, newName);
    }

    // Set home privacy (make public/private)
    public void setHomePublic(Player player, String homeName, boolean isPublic) {
        OnlineUser user = api.adaptUser(player);
        api.setHomePrivacy(user, homeName, isPublic);
    }

    // Set home description
    public void setHomeDescription(Player player, String homeName, String description) {
        OnlineUser user = api.adaptUser(player);
        api.setHomeDescription(user, homeName, description);
    }

    // Relocate a home to new position
    public void relocateHome(Player player, String homeName) {
        OnlineUser user = api.adaptUser(player);
        Position newPosition = user.getPosition();
        api.relocateHome(user, homeName, newPosition);
    }

    // Get public homes
    public void listPublicHomes() {
        api.getPublicHomes().thenAccept(homes -> {
            System.out.println("Public homes:");
            for (Home home : homes) {
                System.out.println("- " + home.getOwner().getUsername() + "." + home.getName());
            }
        });
    }
}
```

--------------------------------

### Get User Data by UUID

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Retrieves saved user data using their unique identifier (UUID). Handles the case where the user might not be found.

```java
import net.william278.huskhomes.api.HuskHomesAPI;
import net.william278.huskhomes.user.SavedUser;
import java.util.UUID;

public class UserDataManager {
    private final HuskHomesAPI api = HuskHomesAPI.getInstance();

    // Get saved user data by UUID
    public void getUserByUUID(UUID uuid) {
        api.getUserData(uuid).thenAccept(optionalUser -> {
            if (optionalUser.isPresent()) {
                SavedUser savedUser = optionalUser.get();
                System.out.println("User: " + savedUser.getUsername());
                System.out.println("Home slots: " + savedUser.getHomeSlots());
                System.out.println("Ignoring requests: " + savedUser.isIgnoringTeleports());
            }
        });
    }
```

--------------------------------

### Get OnlineUser by UUID

Source: https://github.com/wiiiiam278/huskhomes/blob/master/docs/API-Examples.md

Retrieve an OnlineUser object for a player currently on the server using their UUID. This method returns an Optional, which will be empty if the player is offline.

```java
import net.william278.huskhomes.api.HuskHomesAPI;
import net.william278.huskhomes.user.OnlineUser;
import java.util.Optional;
import java.util.UUID;
import org.bukkit.Bukkit;

public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    public HuskHomesAPIHook() {
        this.huskHomesAPI = HuskHomesAPI.getInstance();
    }

    // This method prints out a player's homes into console using stdout
    public void getAnOnlineUser(UUID uuid) {
        OnlineUser user = huskHomesAPI.adaptUser(Bukkit.getPlayer(uuid));
        System.out.println("Found " + user.getUsername() + "!");
        Optional<OnlineUser> otherMethod = huskHomesAPI.getOnlineUser(uuid);
    }

}
```

--------------------------------

### Back Command Configuration

Source: https://github.com/wiiiiam278/huskhomes/wiki/Back-Command

Configure the /back command's behavior, including return by death, saving on teleport events, and restricted worlds.

```yaml
# Settings for the /back command
back_command:
  # Whether /back should work to teleport the user to where they died
  return_by_death: true
  # Whether /back should work with other plugins that use the PlayerTeleportEvent (can conflict)
  save_on_teleport_event: false
  # List of world names where the /back command cannot RETURN the player to.
  # A user's last position won't be updated if they die or teleport from these worlds, but they still will be able to use the command while IN the world
  restricted_worlds: []
```

--------------------------------

### Configure Map Hooks

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Enable home and warp visibility on web maps.

```yaml
# config.yml - Map hook settings
map_hook:
  enabled: true
  show_public_homes: true
  show_warps: true
```

--------------------------------

### Create a Player Home

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

Creates a new home for a player at their current location. Includes error handling for validation exceptions, such as having too many homes or invalid metadata.

```java
public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This method creates a home with the name "example" at the player's current location
    public void createHome(Player owner) {
        // Use this to adapt an online player to an OnlineUser, which extends User (accepted by createHome).
        OnlineUser onlineUser = huskHomesAPI.adaptUser(player);
        
        // We can get an OnlineUser's Position with #getPosition, which we can pass here to createHome
        try {
            huskHomesAPI.createHome(onlineUser, "example", onlineUser.getPosition());
        } catch (ValidationException e) {
            // Homes will be validated, and if validation fails a ValidationException will be thrown.
            // This can happen if the user has too many homes, or if its metadata is invalid (name, description, etc)
            // You should catch ValidationExceptions, determine what caused it (#getType) and handle it appropriately.
            owner.sendMessage(ChatColor.RED + "Failed to create example home: " + e.getType());
        }
    }
}
```

--------------------------------

### Enable Economy Hook on Spigot/Paper

Source: https://github.com/wiiiiam278/huskhomes/blob/master/docs/Economy-Hook.md

To enable the Economy Hook on a Spigot/Paper server, install Vault and a compatible economy plugin. Then, set `enabled` to `true` under the `economy` section of `config.yml`.

```yaml
economy:
  enabled: true
```

--------------------------------

### Enable Return by Death

Source: https://github.com/wiiiiam278/huskhomes/wiki/Back-Command

Enable the 'return_by_death' option to allow players to use /back to return to their death location.

```yaml
back_command:
  # Whether /back should work to teleport the user to where they died
  return_by_death: true
```

--------------------------------

### HuskHomes Command Help

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Provides help and lists available commands for HuskHomes.

```minecraft-commands
/huskhomes help
```

--------------------------------

### Adapt Bukkit Players to HuskHomes Users

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Convert between Bukkit Player objects and HuskHomes OnlineUser objects. This allows you to retrieve user information like username, UUID, and position, or to get a Bukkit Player from an OnlineUser.

```java
import net.william278.huskhomes.api.HuskHomesAPI;
import net.william278.huskhomes.user.OnlineUser;
import org.bukkit.entity.Player;
import java.util.Optional;
import java.util.UUID;

public class PlayerAdapter {
    private final HuskHomesAPI api = HuskHomesAPI.getInstance();

    // Adapt Bukkit Player to OnlineUser
    public OnlineUser adaptPlayer(Player player) {
        return api.adaptUser(player);
    }

    // Get OnlineUser by UUID (returns Optional)
    public Optional<OnlineUser> getOnlineUser(UUID uuid) {
        return api.getOnlineUser(uuid);
    }

    // Convert OnlineUser back to Bukkit Player
    public Player getBukkitPlayer(OnlineUser user) {
        return api.getPlayer(user);
    }

    // Example usage
    public void showPlayerInfo(Player player) {
        OnlineUser user = api.adaptUser(player);
        System.out.println("Player: " + user.getUsername());
        System.out.println("UUID: " + user.getUuid());
        System.out.println("Position: " + user.getPosition());
    }
}
```

--------------------------------

### Build and Complete an Instant Teleport

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

Use this method to create and execute an instant teleport. Ensure the `World` object has the correct name and UID. The final boolean parameter determines if the teleport is instant (`true`) or timed (`false`).

```java
public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This teleports a player to 128, 64, 128 on the server "server"
    public void teleportPlayer(Player player) {
        OnlineUser onlineUser = huskHomesAPI.adaptUser(player);

        // The TeleportBuilder accepts a class that extends Target. This can be a Username or a Position (or a Home/Warp, which extends Position)
        // * Note that the World object needs the name and UID of the world.
        // * The UID will be used if the world can't be found by name. You can just pass it a random UUID if you don't have it.
        Position position = Position.at(
            128, 64, 128,
            World.from("world", UUID.randomUUID()), "server"
        );

        // To construct a teleport, get a TeleportBuilder with #teleportBuilder
        huskHomesAPI.teleportBuilder()
            .teleporter(onlineUser) // The person being teleported
            .target(position) // The target position
            .buildAndComplete(false); // This builds and executes the teleport instantly.
        
        // The `true` flag we passed above indicates we want an instant teleport (as opposed to a timed teleport)
    }

}
```

--------------------------------

### Instantiate the API hook in your plugin

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

Verify the presence of HuskHomes in the plugin manager before initializing the hook class.

```java
public class MyPlugin extends JavaPlugin {

    public HuskHomesAPIHook huskHomesHook;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().getPlugin("HuskHomes") != null) {
            this.huskHomesHook = new HuskHomesAPIHook();
        }
    }
}
```

--------------------------------

### Configure RTP Settings

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Define radial boundaries and restricted worlds for random teleportation.

```yaml
# config.yml - RTP settings
rtp:
  # Radial region around /spawn position for RTP
  region:
    min: 500   # Minimum distance from spawn
    max: 5000  # Maximum distance from spawn

  # Distribution settings for random placement
  distribution_mean: 0.75
  distribution_standard_deviation: 2.0

  # Worlds where RTP is disabled
  restricted_worlds:
    - world_nether
    - world_the_end
```

--------------------------------

### Import Data from Other Plugins

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Initiates the process of importing home and warp data from other compatible plugins.

```minecraft-commands
/huskhomes import
```

--------------------------------

### HuskHomes Public Home Commands

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Commands for interacting with public homes. Players can make their homes public and others can view and teleport to them.

```bash
# Make a home public
/edithome mybase privacy public

# View public homes list
/phomelist
/phomes
/publichomelist

# Teleport to a public home
/phome playername.homename
/publichome playername.homename
```

--------------------------------

### Listen to HuskHomes Events (Bukkit)

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Implement this listener class to receive and handle HuskHomes events. Register the listener with your JavaPlugin instance.

```java
import net.william278.huskhomes.event.*;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public class HuskHomesListener implements Listener {

    public void register(JavaPlugin plugin) {
        plugin.getServer().getPluginManager().registerEvents(this, plugin);
    }

    // Called when a player creates a home
    @EventHandler
    public void onHomeCreate(HomeCreateEvent event) {
        System.out.println(event.getCreator().getUsername() +
            " created home: " + event.getHome().getName());

        // Cancel to prevent home creation
        // event.setCancelled(true);
    }

    // Called when a player deletes a home
    @EventHandler
    public void onHomeDelete(HomeDeleteEvent event) {
        System.out.println("Home deleted: " + event.getHome().getName());
    }

    // Called when a player edits a home
    @EventHandler
    public void onHomeEdit(HomeEditEvent event) {
        System.out.println("Home edited: " + event.getHome().getName());
        System.out.println("Edit type: " + event.getType());  // RENAME, RELOCATE, etc.
    }

    // Called when a player views their home list
    @EventHandler
    public void onHomeList(HomeListEvent event) {
        System.out.println(event.getListViewer().getUsername() +
            " viewing " + event.getHomes().size() + " homes");
    }

    // Called when a player creates a warp
    @EventHandler
    public void onWarpCreate(WarpCreateEvent event) {
        System.out.println("Warp created: " + event.getWarp().getName());
    }

    // Called when a player deletes a warp
    @EventHandler
    public void onWarpDelete(WarpDeleteEvent event) {
        System.out.println("Warp deleted: " + event.getWarp().getName());
    }

    // Called when a player sends a teleport request
    @EventHandler
    public void onSendTeleportRequest(SendTeleportRequestEvent event) {
        System.out.println(event.getSender().getUsername() +
            " sent request to " + event.getRecipient().getUsername());
    }

    // Called when a player receives a teleport request
    @EventHandler
    public void onReceiveTeleportRequest(ReceiveTeleportRequestEvent event) {
        System.out.println(event.getRecipient().getUsername() +
            " received request from " + event.getSender().getUsername());
    }

    // Called when a player accepts/declines a teleport request
    @EventHandler
    public void onReplyTeleportRequest(ReplyTeleportRequestEvent event) {
        System.out.println("Request " +
            (event.isAccepted() ? "accepted" : "declined"));
    }

    // Called when teleport warmup starts
    @EventHandler
    public void onTeleportWarmup(TeleportWarmupEvent event) {
        System.out.println(event.getTeleporter().getUsername() +
            " starting warmup for " + event.getWarmupTime() + " seconds");
    }

    // Called when teleport warmup is cancelled
    @EventHandler
    public void onTeleportWarmupCancelled(TeleportWarmupCancelledEvent event) {
        System.out.println("Warmup cancelled for " +
            event.getTeleporter().getUsername());
    }

    // Called when a teleport completes
    @EventHandler
    public void onTeleport(TeleportEvent event) {
        System.out.println(event.getTeleporter().getUsername() + " teleported");
    }

    // Called when a player uses /back
    @EventHandler
    public void onTeleportBack(TeleportBackEvent event) {
        System.out.println(event.getTeleporter().getUsername() +
            " returning to previous position");
    }

    // Called when a player uses /rtp
    @EventHandler
    public void onRandomTeleport(RandomTeleportEvent event) {
        System.out.println(event.getTeleporter().getUsername() +
            " randomly teleporting to " + event.getTarget());
    }

    // Called when all homes are deleted
    @EventHandler
    public void onDeleteAllHomes(DeleteAllHomesEvent event) {
        System.out.println(event.getUser().getUsername() +
            " deleted all their homes");
    }
}
```

--------------------------------

### PlaceholderAPI Placeholders

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

List of available placeholders for use in other plugins.

```text
%huskhomes_homes_count%          - Number of homes the user has set (e.g., 3)
%huskhomes_max_homes%            - Maximum homes the user can set (e.g., 10)
%huskhomes_max_public_homes%     - Maximum public homes allowed (e.g., 5)
%huskhomes_free_home_slots%      - Free home slots remaining (e.g., 5)
%huskhomes_home_slots%           - Additional purchased home slots (e.g., 2)
%huskhomes_homes_list%           - Comma-separated list of homes (e.g., home, castle, tower)
%huskhomes_public_homes_count%   - Number of public homes (e.g., 3)
%huskhomes_public_homes_list%    - Comma-separated public homes (e.g., castle, tower)
%huskhomes_ignoring_tp_requests% - Whether ignoring TP requests (e.g., true)
```

--------------------------------

### Implement Custom Random Teleport Engine

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Create and register a custom engine to define how random teleport locations are generated.

```java
import net.william278.huskhomes.random.RandomTeleportEngine;
import net.william278.huskhomes.position.Position;
import net.william278.huskhomes.position.World;
import net.william278.huskhomes.api.HuskHomesAPI;
import org.jetbrains.annotations.NotNull;
import java.util.Optional;
import java.util.Random;
import java.util.concurrent.CompletableFuture;

public class CustomRTPEngine implements RandomTeleportEngine {
    private final Random random = new Random();
    private final String serverName;

    public CustomRTPEngine(String serverName) {
        this.serverName = serverName;
    }

    @Override
    @NotNull
    public CompletableFuture<Optional<Position>> getRandomPosition(
            @NotNull World world,
            @NotNull String... args) {

        return CompletableFuture.supplyAsync(() -> {
            // Custom logic to find a random safe position
            double x = (random.nextDouble() * 10000) - 5000;  // -5000 to 5000
            double z = (random.nextDouble() * 10000) - 5000;
            double y = 64;  // Default Y level

            // You would add logic here to:
            // - Check for safe landing spot
            // - Avoid water/lava
            // - Find ground level
            // - Check biome restrictions

            Position position = Position.at(x, y, z, world, serverName);
            return Optional.of(position);
        });
    }

    // Register the custom engine
    public static void register() {
        HuskHomesAPI api = HuskHomesAPI.getInstance();
        api.setRandomTeleportEngine(new CustomRTPEngine(api.getServer()));
    }
}
```

--------------------------------

### Build and Execute a Timed Teleport

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

This method creates a timed teleport, which requires the player to remain still during a warmup period. It handles potential `TeleportationException`s that can occur if the player moves or the target becomes unavailable. Use `TeleportException#displayMessage()` to inform the user of the failure reason.

```java
public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This performs a timed teleport to tp a player to another online player with the username "William278"
    public void teleportPlayer(Player player) {
        OnlineUser onlineUser = huskHomesAPI.adaptUser(player);
        Target targetUsername = Target.username("William278"); // Get a target by a username, who can be online on this server/a server on the network (cross-server teleport).

        try {
            huskHomesAPI.teleportBuilder()
                .teleporter(onlineUser)
                .target(targetUsername)
                .toTimedTeleport() // Instead of running buildAndComplete, we can get the Teleport object itself this way.
                .execute(); // A timed teleport will throw a TeleportationException if the player moves/takes damage during the warmup, or if the target is not found.
        } catch(TeleportationException e) { // Since this doesn't catch the TeleportException (buildAndComplete does!), we need to do this.
            // Use TeleportException#displayMessage() to display why the teleport failed to the user.
            e.displayMessage(onlineUser);
        }
    }

}
```

--------------------------------

### HuskHomes Plugin Information

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Displays general information about the HuskHomes plugin.

```minecraft-commands
/huskhomes about
```

--------------------------------

### HuskHomes Player Home Commands

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Common player commands for managing personal homes in HuskHomes, including setting, teleporting, listing, deleting, and editing home properties.

```bash
# Set a new home at current location
/sethome mybase

# Teleport to a home
/home mybase

# View list of your homes
/homelist
/homes

# Delete a home
/delhome mybase

# Delete all homes
/delhome all confirm

# Edit home properties
/edithome mybase rename newname
/edithome mybase description "My awesome base"
/edithome mybase relocate
/edithome mybase privacy public

# Access another player's home (requires permission)
/home player.homename
/homelist playername
```

--------------------------------

### API Event Listening (Fabric)

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Listen to HuskHomes events on Fabric servers using callbacks. This allows you to react to various in-game actions performed by players.

```APIDOC
## API Event Listening (Fabric)

### Description
Listen to HuskHomes events on Fabric servers using callbacks.

### Method
N/A (Callback registration)

### Endpoint
N/A (Client-side registration)

### Parameters
N/A

### Request Example
```java
import net.william278.huskhomes.event.*;
import net.minecraft.util.ActionResult;

public class FabricHuskHomesEvents {

    public void registerCallbacks() {
        // Home creation callback
        HomeCreateCallback.EVENT.register((player, home) -> {
            System.out.println(player.getUsername() + " created home: " + home.getName());
            return ActionResult.SUCCESS;  // Allow home creation
            // return ActionResult.FAIL;  // Block home creation
        });

        // Teleport callback
        TeleportCallback.EVENT.register((teleporter, target) -> {
            System.out.println(teleporter.getUsername() + " teleporting...");
            return ActionResult.SUCCESS;
        });

        // Teleport request callback
        SendTeleportRequestCallback.EVENT.register((sender, recipient, request) -> {
            System.out.println(sender.getUsername() + " -> " + recipient.getUsername());
            return ActionResult.SUCCESS;
        });

        // Warp creation callback
        WarpCreateCallback.EVENT.register((creator, warp) -> {
            System.out.println("Warp created: " + warp.getName());
            return ActionResult.SUCCESS;
        });
    }
}
```

### Response
N/A (Callbacks do not return direct responses in this context)

### Error Handling
N/A
```

--------------------------------

### POST /setspawn

Source: https://github.com/wiiiiam278/huskhomes/wiki/Commands

Set the spawn position to the current location.

```APIDOC
## POST /setspawn

### Description
Set the spawn position to your current location.

### Method
POST

### Endpoint
/setspawn
```

--------------------------------

### Print Player Homes to Console

Source: https://github.com/wiiiiam278/huskhomes/wiki/API-Examples

Retrieves a player's homes and prints their names to the console. Handles asynchronous operations using CompletableFuture. Also demonstrates retrieving a specific home by name.

```java
public class HuskHomesAPIHook {

    private final HuskHomesAPI huskHomesAPI;

    // This method prints out a player's homes into console using stdout
    public void printPlayerHomes(UUID uuid) {
        // Use this to adapt an online player to an OnlineUser, which extends User (accepted by getUserHomes).
        // To get the homes of an offline user, use: User.of(uuid, username);
        OnlineUser user = huskHomesAPI.adaptUser(Bukkit.getPlayer(uuid));
        
        // A lot of HuskHomes' API methods return as futures which execute asynchronously.
        huskHomesAPI.getUserHomes(user).thenAccept(homeList -> { // Use #thenAccept(data) to run after the future has executed with data
            for (Home home : homeList) {
                // The home and warp object both extend SavedPosition, which maps a position object to a name and description
                System.out.println(home.meta.name); // It's best to use your plugin logger, but this is just an example.
            }
        });
        
        // You can also get a specific home by name using #getUserHome(user, name)
        huskHomesAPI.getUserHome(user, "example").thenAccept(optionalHome -> {
            // #getUserHome returns an Optional wrapper, so we need to run #ifPresent() first and call #get() to retrieve it if it exists
            if (optionalHome.isPresent()) {
                System.out.println("Found " + user.getUsername() + "'s home: " + optionalHome.get().getName());
            } else {
                System.out.println("Home not found");
            }
        });
    }

}
```

--------------------------------

### Register Fabric Event Callbacks

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Use event callbacks to intercept and handle home creation, teleportation, and warp creation on Fabric servers.

```java
import net.william278.huskhomes.event.*;
import net.minecraft.util.ActionResult;

public class FabricHuskHomesEvents {

    public void registerCallbacks() {
        // Home creation callback
        HomeCreateCallback.EVENT.register((player, home) -> {
            System.out.println(player.getUsername() + " created home: " + home.getName());
            return ActionResult.SUCCESS;  // Allow home creation
            // return ActionResult.FAIL;  // Block home creation
        });

        // Teleport callback
        TeleportCallback.EVENT.register((teleporter, target) -> {
            System.out.println(teleporter.getUsername() + " teleporting...");
            return ActionResult.SUCCESS;
        });

        // Teleport request callback
        SendTeleportRequestCallback.EVENT.register((sender, recipient, request) -> {
            System.out.println(sender.getUsername() + " -> " + recipient.getUsername());
            return ActionResult.SUCCESS;
        });

        // Warp creation callback
        WarpCreateCallback.EVENT.register((creator, warp) -> {
            System.out.println("Warp created: " + warp.getName());
            return ActionResult.SUCCESS;
        });
    }
}
```

--------------------------------

### Execute Timed Teleport with Warmup

Source: https://context7.com/wiiiiam278/huskhomes/llms.txt

Initiates a timed teleportation sequence that includes a warmup period. Catches `TeleportationException` if the player moves or takes damage during warmup.

```java
    // Timed teleport (requires warmup)
    public void timedTeleport(Player player, Position destination) {
        OnlineUser user = api.adaptUser(player);

        try {
            api.teleportBuilder()
                .teleporter(user)
                .target(destination)
                .toTimedTeleport()  // Create timed teleport
                .execute();  // Execute with warmup
        } catch (TeleportationException e) {
            // Player moved, took damage, or target not found
            e.displayMessage(user);
        }
    }
```
Tokens:
Raw