跳到主要内容

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

跨平台绑定相关数据包​

v0.4.0 新增：跨平台社交账号绑定功能，支持在 QQ、Telegram 等平台间同步玩家绑定信息。

ConfirmBindPacket​

确认跨平台绑定请求包。

declare class ConfirmBindPacket extends PacketWithCallBackId {
    Operation: "CONFIRM_BIND";
    PlayerName: string;  // 玩家名称
    Code: string;        // 确认码
}

CrossBindNotifyPacket​

跨平台绑定通知包，当一个平台完成绑定后通知其他平台。

declare class CrossBindNotifyPacket extends PacketWithCallBackId {
    Operation: "CROSS_BIND_NOTIFY";
    PlayerName: string;      // 玩家名称
    Code: string;            // 确认码
    TargetPlatform: string;  // 目标平台
    OriginPlatform: string;  // 来源平台
}

QueryBindStatusPacket​

查询玩家绑定状态请求包。

declare class QueryBindStatusPacket extends PacketWithCallBackId {
    Operation: "QUERY_BIND_STATUS";
    PlayerName: string;  // 玩家名称
}

ConfirmBindResultPacket​

确认绑定结果回调包。

declare class ConfirmBindResultPacket extends CallBackPacket {
    Success: boolean;        // 是否确认成功
    Message: string;         // 结果消息
    BoundPlatforms: string;  // 已绑定的平台列表（逗号分隔）
}

BindStatusAccount 接口​

绑定状态查询中的单个社交账号信息：

interface BindStatusAccount {
    Platform: string;  // 平台名称
    Name: string;      // 账号名称
    Uuid: string;      // 平台UUID
}

QueryBindStatusResultPacket​

绑定状态查询结果包。

declare class QueryBindStatusResultPacket extends CallBackPacket {
    IsBound: boolean;                    // 是否已绑定
    SocialAccounts: BindStatusAccount[]; // 已绑定的社交账号列表
}

CrossBindRequest 接口​

跨平台绑定请求数据：

interface CrossBindRequest {
    Code: string;                   // 确认码
    PlayerName: string;             // 玩家名称
    TargetSocialAccountId: number;  // 目标社交账号ID
    TargetPlatform: string;         // 目标平台
    OriginPlatform: string;         // 来源平台
    RequestGroupId: string;         // 发起绑定的群组ID
    ExpiryTime: Date;               // 过期时间
}

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

遇到麻烦了？

有偿服务

我们提供有偿代安装服务，解决您的环境配置烦恼。

了解详情
Miku

少年，买服务器吗？

持证经营

专注高性价比游戏云VPS，铂金 / I7 / R9 / 物理机

💰 最低六元起、买不了吃亏买不了上当，快来看看吧~

快来看看
Copyright © 2024-2026 易栈