Bridge - 服务器对象

Bridge 类是 EasyBot 的核心桥接实现，他表示一个在线的MC服务器，继承自 WebSocketBehavior，提供了与 Minecraft 服务器交互的完整 API 接口。

信息

Bridge 是一个抽象类，不能直接实例化，要获取到此对象，请通过 Sessions 获取

类概述

declare class Bridge extends WebSocketBehavior {
    readonly Session: Session;
    // ... 方法定义
}

属性

Session

• 类型: Session (只读)
• 描述: 获取当前的会话对象，包含连接状态和会话相关信息

方法详解

UpdateSyncSetting()

功能描述: 更新同步设置，用于刷新客户端与服务器之间的同步配置。

语法:

UpdateSyncSetting(): void

参数: 无

返回值: 无

使用示例:

bridge.UpdateSyncSetting();

注意事项:

• 通常在配置变更后调用
• 确保服务器连接正常时调用

---

SendAndWaitForCallbackAsync()

功能描述: 发送数据包并异步等待服务器回调响应，支持泛型返回类型。

语法:

SendAndWaitForCallbackAsync<T extends object>(packet: PacketWithCallBackId): Promise<T>

参数:

• packet (PacketWithCallBackId): 包含回调ID的数据包对象

返回值: Promise<T> - 返回指定类型的回调结果

使用示例:

const packet = { callbackId: "123", data: "test" };
const result = await bridge.SendAndWaitForCallbackAsync<MyResponseType>(packet);
logger.info(result);

注意事项:

• 需要在异步上下文中使用
• 确保数据包包含有效的回调ID
• 超时处理需要在调用方实现

---

NotifyPlayerUnBind()

功能描述: 通知指定玩家解除账户绑定，服务器收到消息后会认为玩家解绑，并执行相对应操作。

语法:

NotifyPlayerUnBind(playerName: string, kickMessage: string): void

参数:

• playerName (string): 要解绑的玩家名称
• kickMessage (string): 踢出玩家时显示的消息

返回值: 无

使用示例:

bridge.NotifyPlayerUnBind("Steve", "您的账户已解绑，请重新登录");

注意事项:

• 玩家名称必须精确匹配
• 踢出消息会显示给被踢出的玩家

---

NotifyPlayerBindSuccess()

功能描述: 通知玩家账户绑定成功，建立玩家与账户的关联关系。

语法:

NotifyPlayerBindSuccess(playerName: string, accountId: string, accountName: string): void

参数:

• playerName (string): 玩家名称
• accountId (string): 绑定的账户ID
• accountName (string): 绑定的账户名称

返回值: 无

使用示例:

bridge.NotifyPlayerBindSuccess("Steve", "12345", "steve_account");

注意事项:

• 确保账户ID的唯一性
• 绑定成功后玩家将获得相应权限

---

SendPlaceholderApiQueryAsync()

功能描述: 异步查询 PlaceholderAPI 变量值，支持动态变量解析。

语法:

SendPlaceholderApiQueryAsync(playerName: string, text: string): Promise<PlaceholderApiQueryResultPacket>

参数:

• playerName (string): 目标玩家名称
• text (string): 包含占位符的查询文本

返回值: Promise<PlaceholderApiQueryResultPacket> - 查询结果数据包

使用示例:

const result = await bridge.SendPlaceholderApiQueryAsync("Steve", "%player_name% 的等级是 %player_level%");
logger.info(result.Text);

注意事项:

• 需要服务器安装 PlaceholderAPI 插件
• 查询文本中的占位符格式为 %placeholder_name%
• 玩家必须在线才能获取准确信息

---

GetPlayerListAsync()

功能描述: 异步获取当前服务器在线玩家列表及其详细信息。

语法:

GetPlayerListAsync(): Promise<GetPlayerInfoResultPacket>

参数: 无

返回值: Promise<GetPlayerInfoResultPacket> - 包含玩家信息的结果数据包

使用示例:

const playerInfo = await bridge.GetPlayerListAsync();
logger.info(`在线玩家数量: ${playerInfo.players.length}`);
playerInfo.players.forEach(player => {
    logger.info(`玩家: ${player.name}, UUID: ${player.uuid}`);
});

注意事项:

• 返回的是实时在线玩家信息
• 包含玩家基本信息如名称、UUID等

---

SendRunCommandAsync()

功能描述: 异步执行服务器命令，支持以指定玩家身份运行命令。

语法:

SendRunCommandAsync(playerName: string, command: string, enablePapi: boolean): Promise<RunCommandResultPacket>

参数:

• playerName (string): 执行命令的玩家名称
• command (string): 要执行的命令文本
• enablePapi (boolean): 是否启用 PlaceholderAPI 变量解析

返回值: Promise<RunCommandResultPacket> - 命令执行结果数据包

使用示例:

// 执行普通命令
const result = await bridge.SendRunCommandAsync("Steve", "gamemode creative", false);

// 执行带PAPI变量的命令
const result2 = await bridge.SendRunCommandAsync("Steve", "tell %player_name% 你好", true);

注意事项:

• 命令不需要包含前缀斜杠 /
• 启用PAPI时命令中的占位符会被自动解析
• 需要确保玩家有执行该命令的权限

---

SendMessageWithExtra()

功能描述: 向聊天频道发送包含额外信息的富文本消息，支持复杂的消息格式。

语法:

SendMessageWithExtra(text: string, extra: any[]): void

参数:

• text (string): 基础消息文本
• extra (any[]): 额外信息对象数组，可包含格式化、点击事件等

返回值: 无

使用示例:

const extra = [
    {
        text: "点击这里",
        color: "blue",
        clickEvent: {
            action: "run_command",
            value: "/help"
        }
    }
];
bridge.SendMessageWithExtra("欢迎来到服务器！", extra);

注意事项:

• extra 数组支持 Minecraft 原版文本组件格式
• 可以包含颜色、样式、点击事件、悬停事件等

---

SendMessageToAllPlayer()

功能描述: 向服务器所有在线玩家发送广播消息。

语法:

SendMessageToAllPlayer(text: string): void

参数:

• text (string): 要发送的消息文本

返回值: 无

使用示例:

bridge.SendMessageToAllPlayer("服务器将在5分钟后重启，请做好准备！");

注意事项:

• 消息会发送给所有当前在线的玩家
• 支持 Minecraft 颜色代码（如 &c 表示红色）

---

GetServerInfo()

功能描述: 异步获取服务器连接和配置的详细信息。

语法:

GetServerInfo(): Promise<ServerConnectionInfo>

参数: 无

返回值: Promise<ServerConnectionInfo> - 服务器连接信息对象

使用示例:

const serverInfo = await bridge.GetServerInfo();
logger.info(`服务器名称: ${serverInfo.ServerName}`);
logger.info(`服务器版本: ${serverInfo.ServerVersion}`);
logger.info(`支持PAPI: ${serverInfo.IsPapiSupported}`);
logger.info(`正版验证: ${serverInfo.IsOnlineMode}`);

注意事项:

• 返回的信息反映服务器当前状态
• 可用于判断服务器功能支持情况

---

RpcInvoke()

功能描述: 执行远程服务器中的命令。

语法:

RpcInvoke(identifier: string, method: string, args: any): Promise<any>

参数:

• identifier (string): 扩展标识符
• method (string): 方法名称
• args (any): 方法参数

返回值: Promise<any> - 如果执行成功,返回方法执行结果;否则报错

使用示例:

try {
    const result = await bridge.RpcInvoke("com.example.extension", "MyMethod", { key: "value" });
    console.log(result);
} catch (e) {
    console.error("RPC调用失败", e);
}

---

GetExtensions()

功能描述: 获取服务器安装的扩展列表。

语法:

GetExtensions(): Promise<GetExtensionsResultPacket>

参数: 无

返回值: Promise<GetExtensionsResultPacket> - 包含服务器已安装扩展信息的数据包

使用示例:

const result = await bridge.GetExtensions();
result.Extensions.forEach((ext, id) => {
    console.log(`扩展: ${ext.Name} (${ext.Version})`);
});

ServerConnectionInfo 接口

描述与服务器连接相关的元数据信息：

interface ServerConnectionInfo {
    /** 服务器显示名称（通常为配置文件中的名称） */
    ServerName: string;
    
    /** 服务器核心版本号（例如：Paper 1.19.2） */
    ServerVersion: string;
    
    /** 客户端插件要求的协议版本 */
    PluginVersion: string;
    
    /** 指示服务器是否支持PAPI(PlaceholderAPI)变量替换功能 */
    IsPapiSupported: boolean;
    
    /** 标识服务器是否支持自定义命令扩展 */
    IsCommandSupported: boolean;
    
    /** 标记服务器是否安装了GeyserMC跨平台桥接插件 */
    HasGeyser: boolean;
    
    /** 表示服务器是否处于正版验证模式（true=仅正版账号可进入） */
    IsOnlineMode: boolean;
}

扩展相关接口

BridgeRpcManifest

RPC 方法清单定义，描述了扩展中可调用的方法信息：

interface BridgeRpcManifest { 
    /** 唯一标识符 */
    Identifier: string; 
    /** 方法名称 */
    Method: string; 
    /** 方法描述 */
    Description: string; 
    /** 显示名称 */
    DisplayName: string; 
    /** 所属类名 */
    ClassName: string; 
} 

BridgeExtensions

扩展信息定义，描述了服务器上安装的扩展详情：

interface BridgeExtensions { 
    /** 扩展标识符 */
    Identifier: string; 
    /** 扩展名称 */
    Name: string; 
    /** 作者 */
    Author: string; 
    /** 版本号 */
    Version: string; 
    /** 描述信息 */
    Description: string; 
    /** 包含的RPC方法集合 */
    Rpc: Map<string, BridgeRpcManifest>; 
    /** 依赖的插件列表 */
    RequiredPlugins: string[]; 
} 

GetExtensionsResultPacket

获取扩展结果数据包：

interface GetExtensionsResultPacket extends CallBackPacket { 
    /** 服务器扩展映射表，key为扩展ID */
    Extensions: Map<string, BridgeExtensions> 
} 

最佳实践

1. 错误处理: 对所有异步方法使用 try-catch 进行错误处理
2. 连接检查: 在调用方法前确保 WebSocket 连接正常
3. 权限验证: 执行命令前检查玩家权限
4. 资源管理: 合理使用异步方法，避免过多并发请求

完整示例

// 完整的使用示例
async function handlePlayerJoin(playerName: string) {
    try {
        // 获取服务器信息
        const serverInfo = await bridge.GetServerInfo();
        
        // 发送欢迎消息
        bridge.SendMessageToAllPlayer(`欢迎 ${playerName} 加入 ${serverInfo.ServerName}！`);
        
        // 如果支持PAPI，查询玩家信息
        if (serverInfo.IsPapiSupported) {
            const papiResult = await bridge.SendPlaceholderApiQueryAsync(
                playerName, 
                "玩家 %player_name% 等级: %player_level%"
            );
            logger.info(papiResult.Text);
        }
        
        // 更新同步设置
        bridge.UpdateSyncSetting();
        
    } catch (error) {
        logger.error("处理玩家加入时出错:", error);
    }
}