ScriptIrc

ViaVersion API 文档

2026年1月9日 ·

ViaVersion API 文档

概述

ViaVersion 是一个 Minecraft 服务器插件，允许较新的客户端版本连接到较旧的服务器版本。该 API 提供了跨平台支持，包括 Paper、Velocity、Fabric、Sponge 等平台。

主要包结构

核心包

  • com.viaversion.viaversion.api – 核心 API 接口
  • com.viaversion.viaversion.api.command – 命令系统
  • com.viaversion.viaversion.api.configuration – 配置管理
  • com.viaversion.viaversion.api.connection – 连接管理
  • com.viaversion.viaversion.api.data – 数据映射
  • com.viaversion.viaversion.api.protocol – 协议处理
  • com.viaversion.viaversion.api.platform – 平台抽象

Minecraft 相关包

  • com.viaversion.viaversion.api.minecraft – Minecraft 基础类型
  • com.viaversion.viaversion.api.minecraft.chunks – 区块相关
  • com.viaversion.viaversion.api.minecraft.entities – 实体类型
  • com.viaversion.viaversion.api.minecraft.item – 物品系统
  • com.viaversion.viaversion.api.minecraft.entitydata – 实体数据

类型系统

  • com.viaversion.viaversion.api.type – 类型系统
  • com.viaversion.viaversion.api.type.types – 具体类型实现

核心 API 类

1. Via (核心入口点)

包名: com.viaversion.viaversion.api.Via

主要方法:

// 获取 API 实例
static ViaAPI getAPI()

// 获取配置
static ViaVersionConfig getConfig()

// 获取管理器（提供更多功能）
static ViaManager getManager()

// 获取平台实例
static ViaPlatform getPlatform()

// 初始化 ViaManager
static void init(ViaManager viaManager)

使用示例:

// 获取 API 实例
ViaAPI api = Via.getAPI();

// 获取玩家协议版本
ProtocolVersion version = api.getPlayerProtocolVersion(playerUUID);

// 获取服务器支持的协议版本
SortedSet<ProtocolVersion> supportedVersions = api.getSupportedProtocolVersions();

2. ViaAPI (主要 API 接口)

包名: com.viaversion.viaversion.api.ViaAPI<T>

泛型参数: T – 平台特定的玩家类型（如 Bukkit 的 Player）

主要方法:

版本信息

// 获取插件版本
String getVersion()

// 获取主版本号
default int majorVersion()

// 获取内部 API 版本
default int apiVersion()

玩家相关

// 获取玩家协议版本（返回整数）
default int getPlayerVersion(UUID uuid)
default int getPlayerVersion(T player)

// 获取玩家协议版本（返回 ProtocolVersion 对象）
ProtocolVersion getPlayerProtocolVersion(UUID uuid)
ProtocolVersion getPlayerProtocolVersion(T player)

// 检查玩家是否被注入
boolean isInjected(UUID uuid)

// 获取玩家连接
@Nullable UserConnection getConnection(UUID uuid)

服务器版本

// 获取服务器协议版本信息
ServerProtocolVersion getServerVersion()

// 获取支持的协议版本（排除被阻止的版本）
SortedSet<ProtocolVersion> getSupportedProtocolVersions()

// 获取所有支持的协议版本（包括被阻止的版本）
SortedSet<ProtocolVersion> getFullSupportedProtocolVersions()

数据包操作

// 发送原始数据包给玩家
void sendRawPacket(T player, ByteBuf packet)
void sendRawPacket(UUID uuid, ByteBuf packet)

遗留 API

// 获取遗留 API（仅适用于旧版本）
LegacyViaAPI<T> legacyAPI()

3. ProtocolVersion (协议版本)

包名: com.viaversion.viaversion.api.protocol.version.ProtocolVersion

主要功能: 表示 Minecraft 协议版本，实现了 Comparable<ProtocolVersion>

常量字段（部分）:

// 未知版本
static final ProtocolVersion unknown

// 各版本常量
static final ProtocolVersion v1_8      // 协议版本 47
static final ProtocolVersion v1_9      // 协议版本 107
static final ProtocolVersion v1_12     // 协议版本 335
static final ProtocolVersion v1_16     // 协议版本 735
static final ProtocolVersion v1_17     // 协议版本 755
static final ProtocolVersion v1_18     // 协议版本 757
static final ProtocolVersion v1_19     // 协议版本 759
static final ProtocolVersion v1_20     // 协议版本 763
static final ProtocolVersion v1_21     // 协议版本 767
// ... 更多版本常量

主要方法:

版本比较

// 比较方法
boolean equalTo(ProtocolVersion other)
boolean newerThan(ProtocolVersion other)
boolean newerThanOrEqualTo(ProtocolVersion other)
boolean olderThan(ProtocolVersion other)
boolean olderThanOrEqualTo(ProtocolVersion other)

// 范围检查
boolean betweenInclusive(ProtocolVersion min, ProtocolVersion max)
boolean betweenExclusive(ProtocolVersion min, ProtocolVersion max)

版本信息

// 获取版本信息
String getName()                    // 版本名称，如 "1.16.4/1.16.5"
int getVersion()                    // 发布版本号
int getSnapshotVersion()           // 快照版本号（无快照指示位）
int getFullSnapshotVersion()       // 快照版本号（有快照指示位）
VersionType getVersionType()       // 版本类型

// 检查版本类型
boolean isSnapshot()               // 是否为快照版本
boolean isRange()                  // 是否为版本范围
boolean isVersionWildcard()        // 是否为通配符版本（如 1.8.x）
boolean isKnown()                  // 是否为已知版本（非 unknown）

静态方法

// 获取协议版本实例
static ProtocolVersion getProtocol(int version)
static ProtocolVersion getProtocol(VersionType versionType, int version)

// 检查版本是否已注册
static boolean isRegistered(int version)
static boolean isRegistered(VersionType versionType, int version)

// 获取所有已注册的协议版本
static List<ProtocolVersion> getProtocols()

// 根据名称获取最接近的协议版本
static ProtocolVersion getClosest(String protocol)

4. ViaManager (管理器接口)

包名: com.viaversion.viaversion.api.ViaManager

主要功能: 提供比 ViaAPI 更高级的管理功能

相关接口:

  • ProtocolManager – 协议管理器
  • ConnectionManager – 连接管理器
  • ViaPlatform – 平台接口

5. UserConnection (用户连接)

包名: com.viaversion.viaversion.api.connection.UserConnection

主要功能: 表示玩家的连接状态和协议信息

6. ProtocolManager (协议管理器)

包名: com.viaversion.viaversion.api.protocol.ProtocolManager

主要功能: 管理协议转换和版本映射

常用使用模式

1. 获取玩家版本

// 通过 UUID 获取
UUID playerUUID = ...;
int version = Via.getAPI().getPlayerVersion(playerUUID);
ProtocolVersion protocolVersion = Via.getAPI().getPlayerProtocolVersion(playerUUID);

// 通过玩家对象获取（平台特定）
Player player = ...;
int version = Via.getAPI().getPlayerVersion(player);
ProtocolVersion protocolVersion = Via.getAPI().getPlayerProtocolVersion(player);

2. 检查版本支持

// 获取支持的版本
SortedSet<ProtocolVersion> supportedVersions = Via.getAPI().getSupportedProtocolVersions();

// 检查特定版本是否支持
ProtocolVersion targetVersion = ProtocolVersion.v1_16;
boolean isSupported = supportedVersions.contains(targetVersion);

// 检查版本范围
ProtocolVersion playerVersion = Via.getAPI().getPlayerProtocolVersion(playerUUID);
boolean isInRange = playerVersion.betweenInclusive(ProtocolVersion.v1_16, ProtocolVersion.v1_18);

3. 版本比较

ProtocolVersion v1_16 = ProtocolVersion.v1_16;
ProtocolVersion v1_18 = ProtocolVersion.v1_18;
ProtocolVersion playerVersion = ...;

// 比较版本
if (playerVersion.newerThan(v1_16)) {
    // 玩家版本高于 1.16
}

if (playerVersion.olderThan(v1_18)) {
    // 玩家版本低于 1.18
}

if (playerVersion.equalTo(v1_16)) {
    // 玩家版本等于 1.16
}

4. 发送原始数据包

// 创建 ByteBuf 数据包
ByteBuf packet = Unpooled.buffer();
// 写入 VarInt 数据包 ID
PacketWrapper.writeVarInt(packetId, packet);
// 写入数据包内容
// ...

// 发送给玩家
Via.getAPI().sendRawPacket(player, packet);

注意事项

1. 版本检查

  • 使用 majorVersion() 检查主版本兼容性
  • 使用 apiVersion() 检查 API 兼容性
  • 建议在插件启动时检查版本兼容性

2. 连接管理

  • 优先使用 ConnectionManager 而不是 getConnection()
  • isInjected() 方法在客户端实现中可能不可靠

3. 协议版本

  • 使用 ProtocolVersion 对象而不是原始整数版本号
  • 注意快照版本和发布版本的区别
  • 使用版本比较方法而不是直接比较整数

4. 平台兼容性

  • API 设计为跨平台，但某些方法可能因平台而异
  • 注意泛型参数 T 表示平台特定的玩家类型

版本常量参考

版本 协议版本 常量名
1.8-1.8.8 47 v1_8
1.9 107 v1_9
1.9.1 108 v1_9_1
1.9.2 109 v1_9_2
1.9.3 110 v1_9_3
1.10-1.10.2 210 v1_10
1.11-1.11.2 315 v1_11
1.12-1.12.2 335 v1_12
1.13 393 v1_13
1.13.1 401 v1_13_1
1.13.2 404 v1_13_2
1.14 477 v1_14
1.14.1 480 v1_14_1
1.14.2 485 v1_14_2
1.14.3 490 v1_14_3
1.14.4 498 v1_14_4
1.15 573 v1_15
1.15.1 575 v1_15_1
1.15.2 578 v1_15_2
1.16 735 v1_16
1.16.1 736 v1_16_1
1.16.2 751 v1_16_2
1.16.3 753 v1_16_3
1.16.4 754 v1_16_4
1.17 755 v1_17
1.17.1 756 v1_17_1
1.18 757 v1_18
1.18.2 758 v1_18_2
1.19 759 v1_19
1.19.1 760 v1_19_1
1.19.3 761 v1_19_3
1.19.4 762 v1_19_4
1.20 763 v1_20
1.20.2 764 v1_20_2
1.20.3 765 v1_20_3
1.20.5 766 v1_20_5
1.21 767 v1_21

最佳实践

  1. 版本兼容性检查: 在插件启动时检查 ViaVersion 的主版本和 API 版本
  2. 优雅降级: 当 ViaVersion 不可用时提供备用方案
  3. 异步操作: 避免在主线程中执行耗时的版本检查
  4. 错误处理: 正确处理玩家未连接或版本未知的情况
  5. 资源清理: 及时释放 ByteBuf 等资源

扩展开发

对于需要更高级功能的开发者，建议：

  1. 使用 Via.getManager() 获取更多管理功能
  2. 实现协议重写器（Rewriter）来处理特定版本的数据转换
  3. 使用映射系统（Mappings）处理版本间的数据映射
  4. 参考 ViaVersion 的源代码了解内部实现细节

文档基于 ViaVersion API 5.7.1-SNAPSHOT 版本生成，适用于开发参考。