API Reference

API 与接口文档

本页面整理 BlockOffensive 对外可用或可扩展的命令、Web API、Forge Event、地图类型、配置和依赖入口。

命令 API

比赛操作指令

注册位置：command/CSCommand.java

用途：

• /cs2 <action> 保留为兼容入口。
• /pause 保留为独立暂停入口。
• 其他普通玩家比赛操作挂载到 /fpsm：/fpsm p、/fpsm unpause|up、/fpsm agree|a、/fpsm disagree|da、/fpsm drop|d。
• 命令检查执行者是否为 ServerPlayer。
• 通过 FPSMCore.getInstance().getMapByPlayer(player) 获取玩家当前地图。
• 仅当地图是 CSGameMap 时，将 action 传入 csGameMap.handleChatCommand(action, player)。

失败情况：

情况	行为
执行者不是玩家	返回 command.cs.onlyPlayer。
玩家不在 CS 爆破地图	返回 command.cs.noMap。

爆破模式 action

CSGameMap.registerCommands() 注册以下 action。它们仍可通过 /cs2 <action> 与地图聊天点号命令调用；除完整名 pause 外，玩家入口也已挂载到 /fpsm。

action	别名	权限	说明
pause	p	玩家	暂停请求或设置暂停状态。
unpause	up	玩家	发起取消暂停投票。
agree	a	玩家	同意当前投票。
disagree	da	玩家	反对当前投票。
drop	d	玩家	执行丢弃/切刀相关逻辑。
debug_1	-	权限 2	调整比分到测试状态。
debug_2	-	权限 2	强制换边。
debug_3	-	权限 2	显示玩家当前队伍。
debug_4	-	权限 2	显示胜利回合与加时计数。

/cs2 与 /pause 按项目约定不显示在 /fpsm help。其余 /fpsm 分支由实际 Brigadier 指令树生成帮助，并根据执行者权限过滤。

地图聊天点号命令

CSGameEvents.onChat 会监听 FPSMatch 地图聊天事件。消息包含 . 时，会截取点号之后的内容作为地图 action 执行。

示例：

.a
.da
.pause

/fpsm mvp <targets> <sound>

注册位置：command/BOCommandRegister.java

用途：

• 通过 FPSMatch 的 RegisterFPSMCommandEvent 向 /fpsm 添加 mvp 子命令。
• 给目标玩家写入 MVP 音乐。
• sound 使用 Minecraft ResourceLocation，并接入可用声音建议。

示例：

/fpsm mvp @p minecraft:music_disc.pigstep

入场与换边演出管理

管理分支固定为 /fpsm blockoffensive halftime，要求权限等级 2：

/fpsm blockoffensive halftime reload
/fpsm blockoffensive halftime select <map> <side> <from> <to>
/fpsm blockoffensive halftime facing <map> <side> <yaw> [pitch]
/fpsm blockoffensive halftime duration <map> <side> <ticks>
/fpsm blockoffensive halftime enable <map> <phase> <enabled>
/fpsm blockoffensive halftime preview <map> <side>
/fpsm blockoffensive halftime debug_halftime_switch <map> [ct_score] [t_score]
/fpsm blockoffensive halftime clear <map> <side>

side 使用 ct 或 t；时长范围为 60–140 tick。select、facing、duration、enable 和 clear 会更新世界 serverconfig/blockoffensive-halftime-intro.json，reload 从该文件重新加载。

完整运行流程见演出、死亡镜头与观战。

Web API

类：web/BOClientWebServer.java

启用条件

配置：

webServerEnabled=true
webServerPort=8080

运行条件：

• 客户端处于地图内。
• 客户端处于比赛中。
• 当前客户端为旁观者。
• 配置已启用 Web Server。

这是客户端本地 API，不是服务端全局 API。

GET /api/data

默认地址：

http://localhost:8080/api/data

方法：

GET

非 GET 请求返回：

405 Method Not Allowed

响应类型：

application/json

顶层字段

字段	类型	说明
currentMapSupportShop	boolean	当前地图是否支持商店。
cTWinnerRounds	number	CT 已胜回合数。
tWinnerRounds	number	T 已胜回合数。
time	number	当前同步时间。
isDebug	boolean	是否 debug 状态。
isStart	boolean	游戏是否开始。
isError	boolean	是否错误状态。
isPause	boolean	是否暂停。
isWaiting	boolean	是否等待中。
isWarmTime	boolean	是否热身中。
isWaitingWinner	boolean	是否等待胜者阶段。
canOpenShop	boolean	当前玩家是否可打开商店。
shopCloseTime	number	商店关闭时间。
nextRoundMoney	number	下一回合最低经济。
dismantleBombProgress	number	拆弹进度。
bombFuse	number	C4 剩余引信。
bombTotalFuse	number	C4 总引信。
tabData	object	玩家 TAB 数据，以 UUID 为键。

tabData 玩家字段

每个玩家对象包含：

字段	类型	说明
name	string	玩家显示名。
team	string	队伍名。
money	number	玩家经济。
health	number	玩家血量百分比，0 到 100。
items	object	武器数据，按类别或槽位组织。
bpAttributeHasHelmet	boolean	防弹护甲是否含头盔。
bpAttributeDurability	number	防弹护甲耐久。

同时会合并 FPSMatch PlayerData.mappedInfo() 中的统计字段，例如击杀、死亡、助攻、伤害等。

响应示例

{
  "currentMapSupportShop": true,
  "cTWinnerRounds": 3,
  "tWinnerRounds": 2,
  "time": 1200,
  "isStart": true,
  "isPause": false,
  "canOpenShop": false,
  "dismantleBombProgress": 0.0,
  "bombFuse": 600,
  "bombTotalFuse": 800,
  "tabData": {
    "00000000-0000-0000-0000-000000000000": {
      "name": "Player",
      "team": "ct",
      "money": 3200,
      "health": 100.0,
      "items": {},
      "bpAttributeHasHelmet": true,
      "bpAttributeDurability": 100
    }
  }
}

地图类型 API

MapRegister 注册两个 FPSMatch 游戏类型：

类型	Java 类	说明
cs	CSGameMap	爆破模式。
csdm	CSDeathMatchMap	死斗模式。

商店类型：

类型	ItemType
cs	map/shop/ItemType.java
csdm	map/shop/ItemType.java

持久化数据 ID：

数据 ID	类
CSGameMaps	CSGameMap
CSDeathMatchMaps	CSDeathMatchMap

Forge Event API

事件均通过 Forge EventBus 使用。

CSGameMapEvent

基类事件。

方法	返回	说明
getMap()	CSGameMap	事件关联的爆破地图。

CSGameMapEvent.TeamSwitchEvent

触发时机：爆破模式换边时。

字段和方法继承自 CSGameMapEvent。

CSGameMapEvent.PlayerEvent.PlacedC4Event

触发时机：玩家成功放置 C4 后。

方法/字段	类型	说明
getMap()	CSGameMap	地图。
getTeam()	ServerTeam	玩家所在队伍。
getPlayer()	ServerPlayer	放置 C4 的玩家。

CSGameRoundEndEvent

触发时机：爆破模式回合结束。

方法	返回	说明
getMap()	CSGameMap	地图。
getWinner()	ServerTeam	获胜队伍。
getReason()	CSGameMap.WinnerReason	胜利原因。
isCancelable()	false	不可取消。

CSGamePlayerGetMvpEvent

触发时机：玩家获得 MVP。

方法	返回	说明
getPlayer()	Player	MVP 玩家。
getMap()	BaseMap	所属地图。
getReason()	MvpReason	MVP 原因。
isCancelable()	false	不可取消。

CSHUDRenderEvent.RenderMvpHud.Pre

触发时机：MVP HUD 渲染前。

方法	返回	说明
getGuiGraphics()	GuiGraphics	渲染上下文。
getScreenWidth()	int	屏幕宽度。
getScreenHeight()	int	屏幕高度。
getHud()	CSMvpHud	当前 MVP HUD。

CSHUDRenderEvent.RenderMvpHud.Post

触发时机：MVP HUD 渲染后。字段同 Pre。

CSHUDRenderEvent.RenderMvpHud.TriggeredAnimation

触发时机：MVP HUD 动画触发。

方法	返回	说明
getReason()	MvpReason	动画触发原因。

事件订阅示例

@Mod.EventBusSubscriber(modid = "yourmod", bus = Mod.EventBusSubscriber.Bus.FORGE)
public class YourEvents {
    @SubscribeEvent
    public static void onRoundEnd(CSGameRoundEndEvent event) {
        CSGameMap map = event.getMap();
        ServerTeam winner = event.getWinner();
        CSGameMap.WinnerReason reason = event.getReason();
    }
}

配置 API

配置类：BOConfig

类	说明
BOConfig.Client	客户端 HUD 和击杀图标配置。
BOConfig.Common	脚步声、C4、游戏规则、Web Server 配置。

详情见 配置说明。

依赖坐标

如果使用项目自身 Maven 发布配置生成的源码构建产物：

dependencies {
    modImplementation "com.phasetranscrystal:blockoffensive:<BlockOffensive version>"
}

公开平台依赖示例见 README。