Package io.github.theword.queqiao.core.platform

Class AbstractPlatformContext<S,C,P>

java.lang.Object
io.github.theword.queqiao.core.platform.AbstractPlatformContext<S,C,P>
Type Parameters:
S - 服务端实例类型
C - 消息组件类型
P - 玩家类型
public abstract class AbstractPlatformContext<S,C,P> extends Object
平台上下文：core 与具体服务端之间的唯一接入点

平台侧继承本类并实现其中的抽象原语；core 侧只通过本类的公开方法访问平台能力， 因此 core 不依赖任何具体服务端的类型。

职责边界（重要）：本类只描述"平台本身能做什么"—— 平台元数据、玩家查询、组件转换、广播、私聊、Title、ActionBar。 不负责命令来源相关能力：回执（reply）与权限判定已归属 CommandExecutionContext，命令来源的类型转换也不在本类。 两者职责完全分离： 

 AbstractPlatformContext   平台整体能力
 CommandExecutionContext   命令来源能力（谁发起的 / 如何回复 / 其权限）

结果表达：平台操作统一返回 PlatformResult， 用 PlatformResultCode 表达"平台侧发生了什么"。 本类不依赖 ProtocolException、Response、 PrivateMessageResponse 或任何协议类型—— 把 PlatformResult 翻译成协议状态是 Api 层的职责。 因此其它模块（命令层、未来的非协议调用方）也可以直接调用本类并消费结果， 不需要经过 Api / WebSocket。

公开方法签名约定（重要）：core 侧调用的公开方法签名中不出现 S / C / P 这三个类型参数。这样 core 侧持有 AbstractPlatformContext<?, ?, ?> 时仍可直接调用， 无需到处传播通配符；凡是要用到平台类型 P / C 的操作， 都在本类内部一次性完成。

延迟绑定：getServerType() 与 getServerVersion() 只要求在本上下文被使用前（即 Runtime start() 之后）可用， 不要求构造时即可用。因此平台可以在服务端实例就绪之前先构造本上下文。

  • Field Details

    • server

      public final S server
      服务端实例

      平台需自行保证该实例在 getPlayers() 等原语被调用前可用。

  • Constructor Details

    • AbstractPlatformContext

      public AbstractPlatformContext(S server)

  • Method Details

    • getServerType

      public abstract String getServerType()
      平台类型

      应返回 ServerTypeConstant 中的规范值（如 "fabric" / "spigot"）， 而不是服务端返回的原始字符串（后者可能形如 "spigot-beta-satshop"，不可控）。

      Returns:
      平台类型

    • getServerVersion

      public abstract String getServerVersion()
      服务端版本
      Returns:
      服务端版本，未知时可返回 null

    • isModServer

      public boolean isModServer()
      是否为模组服务端

      默认按 getServerType() 推导。若某平台不符合"模组 = config 目录"这一规律， 覆盖本方法即可。

      Returns:
      是否为模组服务端

    • jsonToComponent

      public abstract C jsonToComponent(com.google.gson.JsonElement json)
      把 JSON 组件转换为平台自己的组件类型
      Parameters:
      json - JSON 组件
      Returns:
      平台组件

    • getPlayers

      public abstract Collection<P> getPlayers()
      Returns:
      当前在线玩家集合

    • getPlayerName

      public abstract String getPlayerName(P player)
      Parameters:
      player - 玩家
      Returns:
      玩家昵称

    • getPlayerUUID

      public abstract UUID getPlayerUUID(P player)
      Parameters:
      player - 玩家
      Returns:
      玩家 UUID

    • broadcast

      public abstract PlatformResult<Void> broadcast(C component)
      广播组件给所有玩家

      Core 语义只有"广播成功 / 广播失败"，因此不返回任何数据： 底层平台 API 的返回值（例如渲染后的文本）对 Core 调用者没有业务意义， 不应作为返回值暴露出来。

      C 本身不会离开平台层。

      若将来 Core 确实需要广播人数、消息 ID 等领域数据， 应引入专门的领域结果类型（如 BroadcastResult）， 而不是保留一个无法回答"这个值代表什么"的 String。

      Parameters:
      component - 平台组件
      Returns:
      成功 / 失败结果

    • sendPrivateMessage

      public abstract PlatformResult<Void> sendPrivateMessage(P player, C component)
      发送组件给指定玩家
      Parameters:
      player - 玩家
      component - 平台组件
      Returns:
      成功 / 失败结果

    • sendTitleComponent

      public PlatformResult<Void> sendTitleComponent(C title, C subtitle, int fadeIn, int stay, int fadeOut)
      向所有玩家发送标题（可选能力）

      默认返回 PlatformResultCode.UNSUPPORTED，表示当前平台不支持标题。 支持标题的平台覆盖本方法即可。

      Parameters:
      title - 主标题组件，可为 null
      subtitle - 副标题组件，可为 null
      fadeIn - 淡入时间（ticks）
      stay - 停留时间（ticks）
      fadeOut - 淡出时间（ticks）
      Returns:
      成功 / 失败结果

    • sendActionBarComponent

      public PlatformResult<Void> sendActionBarComponent(C component)
      向所有玩家发送 ActionBar（可选能力）

      默认返回 PlatformResultCode.UNSUPPORTED，表示当前平台不支持 ActionBar。 支持的平台覆盖本方法即可。

      Parameters:
      component - 平台组件
      Returns:
      成功 / 失败结果

    • broadcast

      public final PlatformResult<Void> broadcast(com.google.gson.JsonElement json)
      广播 JSON 组件给所有玩家
      Parameters:
      json - JSON 组件
      Returns:
      成功 / 失败结果

    • findPlayer

      public final P findPlayer(String name, String uuid)
      根据玩家名称或 UUID 查找在线玩家。

      当同时提供名称和 UUID 时，优先使用 UUID 进行查找，名称不参与匹配。 当未提供 UUID 时，才使用名称进行查找。

      如果名称和 UUID 均未提供，或未找到匹配的在线玩家，则返回 null。

      Parameters:
      name - 玩家名称，可以为 null 或空字符串
      uuid - 玩家 UUID 字符串，可以为 null 或空字符串
      Returns:
      匹配的在线玩家，未找到时返回 null

    • sendTitle

      public final PlatformResult<Void> sendTitle(com.google.gson.JsonElement title, com.google.gson.JsonElement subtitle, int fadeIn, int stay, int fadeOut)
      发送标题给所有玩家
      Parameters:
      title - 主标题，可为 null
      subtitle - 副标题，可为 null
      fadeIn - 淡入时间（ticks）
      stay - 停留时间（ticks）
      fadeOut - 淡出时间（ticks）
      Returns:
      成功 / 失败结果；平台不支持时返回 PlatformResultCode.UNSUPPORTED

    • sendActionBar

      public final PlatformResult<Void> sendActionBar(com.google.gson.JsonElement json)
      发送 ActionBar 给所有玩家
      Parameters:
      json - ActionBar 内容，JSON 格式
      Returns:
      成功 / 失败结果；平台不支持时返回 PlatformResultCode.UNSUPPORTED

    • sendPrivateMessage

      public final PlatformResult<PlayerModel> sendPrivateMessage(String nickname, UUID uuid, com.google.gson.JsonElement json)
      发送私聊消息，并返回结果

      查找玩家、发送、构造结果三步都在本方法内完成——只有平台侧认识玩家类型 P， 因此这类"碰 P"的操作统一在本类内部收口，不向外暴露泛型。

      成功时 data 为目标玩家的 Core DTO 快照（PlayerModel）， 因此调用方可以据此构造自己的响应，而不需要知道平台玩家类型。

      Parameters:
      nickname - 目标玩家昵称，可为 null
      uuid - 目标玩家 UUID，可为 null
      json - 消息内容，JSON 格式
      Returns:
      未找到玩家时为 PlatformResultCode.PLAYER_NOT_FOUND； 发送失败时透传发送结果码；成功时 data 为目标玩家快照