HuskHomes API 文档

内容来源：SnowCutieOwO – Wiki

概述

HuskHomes API 提供了一系列方法用于获取、编辑和更新玩家的家和地标传送点，同时包含了创建和执行（跨服）传送的功能。

包名和核心类

主要包结构

net.william278.huskhomes.api.HuskHomesAPI – 主API类
net.william278.huskhomes.api.HuskHomesAPIHook – API钩子类
net.william278.huskhomes.user.User – 用户类
net.william278.huskhomes.user.OnlineUser – 在线用户类
net.william278.huskhomes.position.Home – 家传送点类
net.william278.huskhomes.position.Warp – 地标传送点类
net.william278.huskhomes.position.Position – 位置类
net.william278.huskhomes.position.World – 世界类
net.william278.huskhomes.teleport.TeleportBuilder – 传送构建器
net.william278.huskhomes.teleport.Teleport – 传送类
net.william278.huskhomes.teleport.TimedTeleport – 延时传送类
net.william278.huskhomes.teleport.Target – 目标类

平台支持

bukkit – Bukkit、Spigot、Paper等（提供Bukkit API事件监听器）
fabric – Fabric、Quilt等（提供Fabric API回调）
sponge – Sponge等（提供Sponge API事件）
common – 全平台可用的通用API

API 核心用法

1. 初始化API连接

// 创建API钩子类
public class HuskHomesAPIHook {
    private final HuskHomesAPI huskHomesAPI;
    
    public HuskHomesAPIHook() {
        this.huskHomesAPI = HuskHomesAPI.getInstance();
    }
}

// 在主插件中实例化钩子
public class MyPlugin extends JavaPlugin {
    public HuskHomesAPIHook huskHomesHook;
    
    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().getPlugin("HuskHomes") != null) {
            this.huskHomesHook = new HuskHomesAPIHook();
        }
    }
}

2. 获取玩家信息

// 获取OnlineUser对象
OnlineUser user = huskHomesAPI.adaptUser(Bukkit.getPlayer(uuid));

// 通过UUID获取在线用户（返回Optional）
Optional<OnlineUser> optionalUser = huskHomesAPI.getOnlineUser(uuid);

3. 家和地标操作

获取玩家的家列表

// 获取玩家所有家（返回CompletableFuture<List<Home>>）
huskHomesAPI.getUserHomes(user).thenAccept(homeList -> {
    for (Home home : homeList) {
        System.out.println(home.meta.name);
    }
});

// 获取特定名称的家
huskHomesAPI.getUserHome(user, "example").thenAccept(optionalHome -> {
    if (optionalHome.isPresent()) {
        Home home = optionalHome.get();
        System.out.println("Found home: " + home.getName());
    }
});

获取所有地标

// 获取所有地标
huskHomesAPI.getWarps().thenAccept(warpList -> {
    for (Warp warp : warpList) {
        System.out.println(warp.meta.name);
    }
});

创建家传送点

try {
    huskHomesAPI.createHome(onlineUser, "example", onlineUser.getPosition());
} catch (ValidationException e) {
    // 处理验证异常（如名称无效、家数量超限等）
    owner.sendMessage(ChatColor.RED + "Failed to create home: " + e.getType());
}

4. 传送功能

构建传送

// 创建位置对象
Position position = Position.at(
    128, 64, 128,
    World.from("world", UUID.randomUUID()), "server"
);

// 构建并执行传送
huskHomesAPI.teleportBuilder()
    .teleporter(onlineUser)  // 被传送者
    .target(position)        // 目标位置
    .buildAndComplete(false); // 立即执行传送

构建延时传送

Target targetUsername = Target.username("William278");

try {
    huskHomesAPI.teleportBuilder()
        .teleporter(onlineUser)
        .target(targetUsername)
        .toTimedTeleport()  // 转换为延时传送
        .execute();         // 执行延时传送
} catch(TeleportationException e) {
    // 处理传送异常（如玩家移动、目标未找到等）
    e.displayMessage(onlineUser);
}

5. 异步处理

HuskHomes API 大量使用 CompletableFuture 进行异步操作：

// 正确使用方式
huskHomesAPI.getUserHomes(user).thenAccept(homeList -> {
    // 异步处理结果
    for (Home home : homeList) {
        // 处理每个家
    }
});

// 警告：不要使用 #join() 方法，可能导致线程死锁

API 事件

Bukkit 事件列表

事件类	添加版本	可取消	描述
`HomeCreateEvent`	4.0	✅	玩家创建家时调用
`HomeListEvent`	3.0	✅	玩家查看家列表时调用
`HomeEditEvent`	4.0	✅	玩家编辑家时调用
`HomeDeleteEvent`	3.0	✅	玩家删除家时调用
`DeleteAllHomesEvent`	3.2.1	✅	玩家删除所有家时调用
`WarpCreateEvent`	4.0	✅	玩家设置地标时调用
`WarpListEvent`	3.0	✅	玩家查看地标列表时调用
`WarpEditEvent`	4.0	✅	玩家编辑地标时调用
`WarpDeleteEvent`	3.0	✅	玩家删除地标时调用
`DeleteAllWarpsEvent`	3.2.1	✅	玩家删除所有地标时调用
`SendTeleportRequestEvent`	4.1	✅	玩家发送传送请求时调用
`ReceiveTeleportRequestEvent`	4.1	✅	玩家收到传送请求时调用
`ReplyTeleportRequestEvent`	4.1	✅	玩家回复传送请求时调用
`TeleportWarmupEvent`	3.0	✅	玩家开始传送预热时调用
`TeleportWarmupCancelledEvent`	4.6.3	❌	玩家取消传送预热时调用
`TeleportEvent`	3.0	✅	玩家被传送时调用
`TeleportBackEvent`	4.1	✅	玩家使用/back命令时调用
`RandomTeleportEvent`	4.8	✅	玩家被随机传送时调用

Fabric 回调示例

HomeCreateCallback.EVENT.register((player, home) -> {
    // 处理家创建事件
    return ActionResult.SUCCESS;
});

重要类和接口

User 接口

getUsername() – 获取用户名
getUuid() – 获取UUID

OnlineUser 类（继承 User）

getPosition() – 获取当前位置
getWorld() – 获取当前世界

Home 和 Warp 类（继承 SavedPosition）

getName() – 获取名称
getDescription() – 获取描述
getPosition() – 获取位置
getMeta() – 获取元数据

Position 类

getX(), getY(), getZ() – 获取坐标
getWorld() – 获取世界
getServer() – 获取服务器

TeleportBuilder 类

teleporter(OnlineUser) – 设置被传送者
target(Target) – 设置目标
toTeleport() – 构建普通传送
toTimedTeleport() – 构建延时传送
buildAndComplete(boolean) – 构建并执行传送

异常处理

ValidationException

当创建或编辑家/地标时验证失败抛出
使用 getType() 获取验证失败类型

TeleportationException

当传送执行失败时抛出
使用 displayMessage(OnlineUser) 向玩家显示错误信息

最佳实践

异步处理：始终使用 thenAccept() 处理异步结果，避免使用 join()
错误处理：妥善处理 ValidationException 和 TeleportationException
依赖检查：在使用API前检查HuskHomes插件是否已加载
线程安全：注意Bukkit主线程和异步线程的交互

版本兼容性

API版本	HuskHomes版本	支持状态
v4.x	v4.0—当前版本	✅
v3.x	v3.0—v3.2.1	❌
v2.x	v2.0—v2.11.2	❌
v1.x	v1.5—v1.5.11	❌

注意事项

对于v4.6之前的版本，HuskHomes仅通过Bukkit平台分发
v4.3.1之前的版本发布在JitPack，需要使用 https://jitpack.io 仓库
Fabric平台使用回调而非事件系统
所有API方法都是线程安全的，但需要正确处理异步结果

Overview

HuskHomes API 文档

概述

包名和核心类

主要包结构

平台支持

API 核心用法

1. 初始化API连接

2. 获取玩家信息

3. 家和地标操作

获取玩家的家列表

获取所有地标

创建家传送点

4. 传送功能

构建传送

构建延时传送

5. 异步处理

API 事件

Bukkit 事件列表

Fabric 回调示例

重要类和接口

User 接口

OnlineUser 类（继承 User）

Home 和 Warp 类（继承 SavedPosition）

Position 类

TeleportBuilder 类

异常处理

ValidationException

TeleportationException

最佳实践

版本兼容性

注意事项