Multiverse-Core API 参考文档

概述

Multiverse-Core 是一个强大的 Minecraft 服务器插件，用于管理多个世界。本文档提供了完整的 API 参考，重点关注 API 用法和包名结构，适用于开发者进行插件开发。

核心 API 包结构

主要包

org.mvplugins.multiverse.core – 核心 API 接口
org.mvplugins.multiverse.core.world – 世界管理
org.mvplugins.multiverse.core.anchor – 锚点管理
org.mvplugins.multiverse.core.destination – 目的地管理
org.mvplugins.multiverse.core.teleportation – 传送管理

获取 API 实例

推荐方式：单例模式

MultiverseCoreApi api = MultiverseCoreApi.get();

备选方式：Bukkit ServicesManager

RegisteredServiceProvider<MultiverseCoreApi> provider = Bukkit.getServicesManager().getRegistration(MultiverseCoreApi.class);
if (provider != null) {
    MultiverseCoreApi api = provider.getProvider();
}

核心 API 接口

MultiverseCoreApi 类

位于 org.mvplugins.multiverse.core 包中，主要方法：

// 获取世界管理器
WorldManager getWorldManager();

// 获取锚点管理器
AnchorManager getAnchorManager();

// 获取目的地提供者
DestinationsProvider getDestinationsProvider();

// 获取安全传送器
AsyncSafetyTeleporter getSafetyTeleporter();

世界管理 API

WorldManager 接口

位于 org.mvplugins.multiverse.core.world 包中，主要方法：

// 创建新世界
Option<MultiverseWorld> createWorld(String worldName, WorldCreator creator);

// 克隆世界
Option<MultiverseWorld> cloneWorld(String sourceWorldName, String newWorldName);

// 删除世界
Try<Void> deleteWorld(String worldName);

// 获取已加载的世界
Option<MultiverseWorld> getWorld(String worldName);

// 获取所有已加载的世界
List<MultiverseWorld> getLoadedWorlds();

// 获取默认世界
MultiverseWorld getDefaultWorld();

世界操作示例

// 推荐方式：使用 peek() 回调
worldManager.getWorld("world").peek(world -> {
    // 执行世界操作
});

// 不推荐：使用 if 检查
Option<MultiverseWorld> optMVWorld = worldManager.getWorld("world");
if (optMVWorld.isDefined()) {
    MultiverseWorld mvWorld = optMVWorld.get();
    // 执行世界操作
}

// 不推荐：转换为可空对象
MultiverseWorld mvWorld = worldManager.getWorld("world").getOrNull();
if (mvWorld != null) {
    // 执行世界操作
}

锚点管理 API

AnchorManager 接口

位于 org.mvplugins.multiverse.core.anchor 包中，主要方法：

// 获取锚点
Option<Anchor> getAnchor(String anchorName);

// 设置锚点
Try<Void> setAnchor(String anchorName, Location location);

// 删除锚点
Try<Void> deleteAnchor(String anchorName);

// 获取所有锚点
List<Anchor> getAllAnchors();

// 获取玩家可访问的锚点
List<Anchor> getAnchors(Player player);

目的地管理 API

DestinationsProvider 接口

位于 org.mvplugins.multiverse.core.destination 包中，主要方法：

// 通过 ID 获取目的地
Option<Destination> getDestinationById(String id);

// 获取所有已注册的目的地
List<Destination> getDestinations();

// 解析目的地字符串
Try<Destination> parseDestination(String destinationString);

// 注册新目的地
Try<Void> registerDestination(Destination destination);

传送管理 API

AsyncSafetyTeleporter 接口

位于 org.mvplugins.multiverse.core.teleportation 包中，主要方法：

// 传送到指定位置或目的地
Try<Void> to(Entity entity, Location location);
Try<Void> to(Entity entity, Destination destination);

重要开发注意事项

版本控制

Multiverse 遵循语义化版本控制（Semantic Versioning），API 变更会在主要版本中明确标注。

线程安全

所有世界操作必须在主服务器线程执行。异步操作需要确保在主线程中执行世界相关的操作。

vavr 处理

Multiverse 使用 vavr 库处理可选值和异常，开发者需要适应这种函数式编程风格：

避免 null 检查：使用 peek() 回调而不是 if (xx == null) 检查
使用 Option 类型：所有可能为空的值都包装在 Option<T> 中
异常处理：使用 Try<T> 处理可能抛出异常的操作

示例：正确处理 vavr

// 正确：使用 peek() 回调
worldManager.getWorld("world").peek(world -> {
    // 执行世界操作
});

// 检查值是否存在
Option<MultiverseWorld> worldOpt = worldManager.getWorld("world");
if (worldOpt.isDefined()) {
    // 值存在
}

// 获取值或默认值
MultiverseWorld world = worldManager.getWorld("world").getOrElse(defaultWorld);

API 使用示例

创建新世界

MultiverseCoreApi api = MultiverseCoreApi.get();
WorldManager worldManager = api.getWorldManager();

WorldCreator creator = new WorldCreator("my_new_world");
creator.type(WorldType.NORMAL);
creator.environment(World.Environment.NORMAL);

worldManager.createWorld("my_new_world", creator).peek(world -> {
    // 世界创建成功
    Bukkit.getLogger().info("World created: " + world.getName());
});

管理锚点

MultiverseCoreApi api = MultiverseCoreApi.get();
AnchorManager anchorManager = api.getAnchorManager();

// 设置锚点
Location spawnLocation = player.getLocation();
anchorManager.setAnchor("spawn_point", spawnLocation).onSuccess(() -> {
    player.sendMessage("Anchor set successfully!");
});

// 获取锚点
anchorManager.getAnchor("spawn_point").peek(anchor -> {
    player.teleport(anchor.getLocation());
});

传送玩家

MultiverseCoreApi api = MultiverseCoreApi.get();
AsyncSafetyTeleporter teleporter = api.getSafetyTeleporter();

// 传送到位置
teleporter.to(player, targetLocation).onSuccess(() -> {
    player.sendMessage("Teleported successfully!");
});

// 传送到目的地
Destination destination = api.getDestinationsProvider()
    .getDestinationById("world_spawn")
    .getOrNull();
    
if (destination != null) {
    teleporter.to(player, destination);
}

最佳实践

始终使用单例模式获取 API 实例
在主线程执行世界操作
适应 vavr 的函数式编程风格
使用 peek() 回调处理可选值
正确处理异常和错误情况

参考资料

官方文档：https://mvplugins.org
Java 文档：https://mvplugins.org/javadocs/
GitHub 仓库：https://github.com/Multiverse/Multiverse-Core
vavr 文档：https://www.vavr.io/

本文档基于 Multiverse-Core 最新版本 API 生成，适用于插件开发者参考使用。

Multiverse-Core API 知识文档

Overview