跳到主要内容

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}`);

注意事项:

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

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;
}

最佳实践​

  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);
    }
}
Copyright © 2024-2025 易栈