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`

最佳实践

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

扩展开发

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

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

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

Overview

ViaVersion API 文档

概述

主要包结构

核心包

Minecraft 相关包

类型系统

核心 API 类

1. Via (核心入口点)

2. ViaAPI (主要 API 接口)

版本信息

玩家相关

服务器版本

数据包操作

遗留 API

3. ProtocolVersion (协议版本)

版本比较

版本信息

静态方法

4. ViaManager (管理器接口)

5. UserConnection (用户连接)

6. ProtocolManager (协议管理器)

常用使用模式

1. 获取玩家版本

2. 检查版本支持

3. 版本比较

4. 发送原始数据包

注意事项

1. 版本检查

2. 连接管理

3. 协议版本

4. 平台兼容性

版本常量参考

最佳实践

扩展开发