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方法都是线程安全的，但需要正确处理异步结果