API Reference

API 与接口文档

本文整理 FPSMatch 面向开发者的主要 API、接口和数据结构。

`FPSMatch`

主 Mod 类，定义 Mod ID、网络通道、注册流程和发送辅助方法。

成员	说明
`MODID`	固定为 `fpsmatch`
`LOGGER`	FPSMatch 日志器
`INSTANCE`	Forge `SimpleChannel`
`sendTo(Player player, M message)`	根据当前端自动发送到服务端或指定服务端玩家
`sendToPlayer(ServerPlayer player, M message)`	发送 S2C packet
`sendToServer(M message)`	发送 C2S packet
`pullGameInfo()`	客户端请求当前游戏信息

网络通道：

项	值
Channel	`fpsmatch:main`
Protocol	`1.3.0`

`FPSMCore`

服务端核心单例。服务端启动后创建，服务端停止时保存数据并关闭地图队伍。

生命周期

阶段	行为
ServerStartedEvent	创建 `FPSMCore`，发布地图注册事件和数据注册事件，读取存档
ServerStoppingEvent	保存所有数据，关闭地图队伍
Server Tick	调用所有地图的 `mapTick()`

查询 API

方法	说明
`getInstance()`	获取核心单例，未初始化会抛出异常
`initialized()`	判断核心是否已初始化
`isRegistered(BaseMap map)`	判断地图实例是否已注册
`isRegistered(String type)`	判断地图类型是否已注册
`isRegistered(String type, String name)`	判断指定类型和名称的地图是否已注册
`isInGame(Player player)`	判断玩家是否在对局中
`getMapByPlayer(Player player)`	按玩家查询地图，不包含旁观
`getMapByPlayerWithSpec(Player player)`	按玩家查询地图，包含旁观
`getMapByTypeWithName(String type, String name)`	按类型和名称查询地图
`getMapByName(String name)`	按地图名查询地图
`getMapByClass(Class<T> clazz)`	按地图类查询所有实例
`getMapByPosition(ServerLevel level, BlockPos pos)`	按坐标查询地图区域
`getGameTypes()`	获取已注册游戏类型
`getMapNames()`	获取所有地图名
`getMapNamesWithType(String type)`	获取指定类型下的地图名
`getAllMaps()`	获取全部地图集合

注册 API

方法	说明
`registerGameType(String typeName, Function3<ServerLevel, String, AreaData, BaseMap> map)`	注册地图类型构造器
`registerMap(String type, BaseMap map)`	注册地图实例
`getPreBuildGame(String mapType)`	获取地图类型构造器

`BaseMap`

所有玩法地图的抽象基类。

构造函数

public BaseMap(ServerLevel serverLevel, String mapName, AreaData areaData)
public BaseMap(ServerLevel serverLevel, String mapName, AreaData areaData, List<Class<? extends MapCapability>> capabilities)

基础字段

字段	说明
`mapName`	地图实例名称
`isStart`	对局是否已开始
`serverLevel`	地图所在服务端世界
`mapTeams`	队伍管理器
`settings`	地图配置项列表
`capabilities`	地图能力容器
`mapArea`	地图区域

内置配置项

配置	默认值	说明
`minAssistDamageRatio`	`0.25f`	助攻伤害比例阈值
`allowJoinInProgress`	`true`	是否允许中途加入

关键方法

方法	说明
`mapTick()`	固定 tick 流程：胜利检查、地图 tick、队伍 tick、能力 tick、客户端同步
`tick()`	子类自定义 tick
`syncToClient()`	子类自定义同步
`start()`	发布 `FPSMapEvent.StartEvent`，返回是否未被取消
`startNewRound()`	新回合入口
`handleDeath(DeathContext context)`	默认设置玩家死亡并增加死亡数
`resolveDeathItem(ServerPlayer attacker, DamageSource source)`	默认返回攻击者主手物品
`victory()`	发布 `FPSMapEvent.VictoryEvent`
`victoryGoal()`	抽象胜利条件
`cleanupMap()`	发布可取消的 `FPSMapEvent.ClearEvent`
`reset()`	发布 `FPSMapEvent.ResetEvent`
`addTeam(TeamData data)`	添加队伍
`getMapTeams()`	获取队伍管理器
`settings()`	获取所有配置项

`MapTeams`

地图内队伍管理器。

默认行为

构造时会自动创建 spectator 队伍，并把地图中心点作为旁观出生点。

`JoinTeamResult`

状态	说明
`JOINED`	加入成功
`TEAM_NOT_FOUND`	队伍不存在
`TEAM_FULL`	队伍已满
`NO_AVAILABLE_TEAM`	没有可加入队伍
`MID_MATCH_JOIN_DISABLED`	禁止中途加入
`CANCELLED`	加入事件被取消

常用 API

方法	说明
`tick()`	tick 队伍、同步能力和玩家数据
`addTeam(TeamData data)`	添加普通队伍
`getSpectatorTeam()`	获取旁观队伍
`getTeamByName(String team)`	按名称获取队伍
`getTeamByPlayer(Player player)`	获取玩家所在队伍
`getNormalTeams()`	获取非旁观队伍
`getJoinedUUID()`	获取已加入玩家 UUID
`getSpecPlayers()`	获取旁观玩家 UUID
`defineSpawnPoint(String teamName, SpawnPointData data)`	为队伍添加出生点
`resetSpawnPoints(String teamName)`	清空指定队伍出生点
`resetAllSpawnPoints()`	清空所有队伍出生点
`randomSpawnPoints()`	为所有普通队伍分配出生点
`switchAttackAndDefend(BaseMap map, ServerTeam attackTeam, ServerTeam defendTeam)`	交换攻防双方数据

`BaseTeam`

队伍基类。服务端使用 ServerTeam，客户端使用 ClientTeam。

方法	说明
`join(Player player)`	发布 `FPSMTeamEvent.JoinEvent`，返回是否未被取消
`leave(Player player)`	发布 `FPSMTeamEvent.LeaveEvent`，返回是否未被取消
`getCapabilityMap()`	获取队伍能力容器
`getPlayerLimit()`	玩家上限
`getRemainingLimit()`	剩余人数
`getScores()` / `setScores(int)`	队伍分数
`getFixedName()`	生成计分板队伍名：`gameType_mapName_teamName`
`getColor()` / `setColor(Vector3f)`	队伍颜色
`isSpectator()` / `isNormal()`	判断队伍类型
`clean()`	重置能力、分数和玩家数据

Capability API

`FPSMCapability<H>`

方法	说明
`tick()`	每 tick 执行
`init()`	初始化
`reset()`	重置
`destroy()`	销毁
`getHolder()`	获取能力持有者
`isImmutable()`	是否禁止从能力容器移除
`getName()`	默认返回类名

`FPSMCapability.Factory<H, T>`

方法	说明
`isOriginal()`	是否作为原始能力自动加入 holder
`create(H holder)`	创建能力实例
`command()`	返回可选能力命令

`FPSMCapabilityManager`

方法	说明
`register(CapabilityType type, Class<T> capabilityClass, Factory<H, T> factory)`	注册能力
`isRegistered(Class<T> capabilityClass)`	判断能力是否注册
`getFactory(Class<T> capabilityClass)`	获取能力工厂
`createInstance(H holder, Class<T> capabilityClass)`	为 holder 创建能力实例
`getRegisteredCapabilities()`	获取所有能力
`getRegisteredCapabilities(CapabilityType type)`	获取指定 MAP 或 TEAM 能力
`getCapabilityClassByName(String className)`	按简单类名查找能力
`createFromNetwork(H holder, String className, FriendlyByteBuf buf)`	从网络数据创建同步能力

内置能力

类型	能力
TEAM	`CompensationCapability`
TEAM	`PauseCapability`
TEAM	`SpawnPointCapability`
TEAM	`TeamSwitchRestrictionCapability`
TEAM	`StartKitsCapability`
TEAM	`ShopCapability`
MAP	`DemolitionModeCapability`
MAP	`GameEndTeleportCapability`

Shop API

`FPSMShop<T extends Enum<T> & INamedType>`

方法	说明
`registerShopType(String typeId, Class<? extends INamedType> typeClass)`	注册商店类型
`getRegisteredShopTypes()`	获取已注册商店类型 ID
`getShopTypeClass(String typeId)`	根据类型 ID 获取枚举类
`isShopTypeRegistered(String typeId)`	判断商店类型是否已注册
`createWithTypeId(String typeId, String name, int startMoney)`	按类型 ID 创建商店
`create(Class<T> enumClass, String name)`	创建默认 800 金钱商店
`create(Class<T> enumClass, String name, int startMoney)`	创建指定初始金钱商店
`syncShopData()`	同步全部玩家槽位
`syncShopMoneyData()`	同步全部玩家金钱

`ShopData<T>`

保存单个玩家的商店状态：金钱、槽位、购买次数、分组索引等。主要处理购买、退款、金钱上下限和槽位合法性。

`ShopSlot`

商店槽位，Codec 字段包括：

字段	说明
`ItemStack`	出售物品
`defaultCost`	默认价格
`maxBuyCount`	最大购买次数
`groupId`	分组 ID
`listenerModule`	监听模块

数据模型

`AreaData`

字段/方法	说明
`pos1()`	第一个角点
`pos2()`	第二个角点
`aabb()`	派生 AABB
`isPlayerInArea(Player player)`	判断玩家是否在区域内
`isBlockPosInArea(BlockPos blockPos)`	判断方块坐标是否在区域内
`isEntityInArea(Entity entity)`	判断实体是否在区域内
`isInArea(Vec3 pos)`	判断坐标是否在区域内
`CODEC`	JSON/网络编解码

`PlayerData`

玩家对局统计数据。

字段	说明
`scores`	分数
`kills`	击杀
`deaths`	死亡
`assists`	助攻
`damage`	伤害
`mvpCount`	MVP 次数
`isLiving`	是否存活
`headshotKills`	爆头击杀
`_kills/_deaths/_assists/_damage`	回合临时字段
`damageData`	服务端伤害明细
`spawnPointsData`	玩家出生点
`dirty`	同步脏标记

当 enableRounds=true 时，回合内数据写入 _ 前缀临时字段，回合结束后通过 saveRoundData() 合并到基础字段。

`Setting<T>`

地图配置项。

方法	说明
`get()`	获取当前值
`set(T value)`	设置值
`getDefaultValue()`	获取默认值
`codec()`	获取 Codec
`getConfigName()`	获取配置名
`toJson()`	编码为 JSON
`fromJson(JsonElement json)`	从 JSON 解码
`parse(String value)`	从命令字符串解析
`readFromBuf(FriendlyByteBuf buf)`	网络读取
`writeToBuf(FriendlyByteBuf buf)`	网络写入

`SpawnPointData`

字段/方法	说明
`getDimension()`	维度
`getPosition()`	坐标
`getBlockPos()`	方块坐标
`getYaw()`	朝向 yaw
`getPitch()`	朝向 pitch
`CODEC`	JSON/网络编解码

`TeamData`

队伍定义 record：

public record TeamData(String name, int limit, List<String> capabilities)

工厂方法	说明
`new TeamData(String name, int limit)`	创建不带能力列表的队伍数据
`TeamData.of(String name, int limit)`	创建默认带 `SpawnPointCapability` 的队伍数据
`TeamData.of(String name, int limit, List<Class<? extends TeamCapability>> capabilities)`	创建指定能力队伍数据
`TeamData.of(ServerTeam team)`	从服务端队伍生成数据
`TeamData.of(ClientTeam team)`	从客户端队伍生成数据
`getCapabilities()`	把能力类名解析为能力类

`DeathContext`

统一死亡上下文。

字段/方法	说明
`getDeadPlayer()`	死亡玩家
`getAttacker()` / `getAttackerOptional()`	攻击者
`getDamageSource()`	伤害源
`getDeathItem()`	死亡武器/物品
`isGunKill()`	是否枪杀
`isHeadShot()`	是否爆头
`isPassWall()`	是否穿墙
`isPassSmoke()`	是否穿烟
`isScopedKill()`	是否开镜击杀
`getGunBullet()`	子弹实体
`getCreatedTick()`	上下文创建 tick

TaCZ 击杀事件到达后，死亡管线会补全枪击细节。

网络包约定

每个 packet 类必须满足：

public static void encode(MyPacket packet, FriendlyByteBuf buf)
public static MyPacket decode(FriendlyByteBuf buf)
public void handle(Supplier<NetworkEvent.Context> context)

注册器会检查：

encode 必须是静态方法。
decode 必须是静态方法。
decode 返回值必须是当前 packet 类型。
handle 必须存在。

S2C packet 需要避免直接引用 client-only 类型，专用客户端逻辑应放入客户端 packet registrar。

API Reference

API 与接口文档

FPSMatch

FPSMCore

生命周期

查询 API

注册 API

BaseMap

构造函数

基础字段

内置配置项

关键方法

MapTeams

默认行为

JoinTeamResult

常用 API

BaseTeam

Capability API

FPSMCapability<H>

FPSMCapability.Factory<H, T>

FPSMCapabilityManager

内置能力

Shop API

FPSMShop<T extends Enum<T> & INamedType>

ShopData<T>

ShopSlot

数据模型

AreaData

PlayerData

Setting<T>

SpawnPointData

TeamData

DeathContext

网络包约定

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`FPSMatch`

`FPSMCore`

`BaseMap`

`MapTeams`

`JoinTeamResult`

`BaseTeam`

`FPSMCapability<H>`

`FPSMCapability.Factory<H, T>`

`FPSMCapabilityManager`

`FPSMShop<T extends Enum<T> & INamedType>`

`ShopData<T>`

`ShopSlot`

`AreaData`

`PlayerData`

`Setting<T>`

`SpawnPointData`

`TeamData`

`DeathContext`