# FFGS / 落英 枪战服 · 后期开发规划 v1

> 2026-09-13 23:50 起稿 · 基于 **FPSMatch 1.3.0 snapshot（1.20.1 Forge）实机反编译核查**（不是猜的）
> 输入：9/13 公告（签到/赛季/称号/旧服福利/三货币/后续玩法规划/个人基地）

---

## 0. 结论速览

1. **玩法内核写 mod，外围系统用 KJS**。KJS 只能"反应"（监听事件、发奖励、播报），**不能定义新模式**——`registerGameType` 是纯 Java API，1.3.0 也没给 KJS 注册绑定。
2. **1.3.0 是 snapshot（作者还在高频提交）**：dev 分支跟进可以，生产服别急着上；建议锁定单个 snapshot（如 `20260913-0618`）并在 mod 里包一层适配，防止 API 变动炸掉线上。
3. **最大隐藏风险不是技术，是数据**：公告承诺"旧服游玩数据可兑换新服专属奖励"，但**旧服的货币持有量/赛季等级/称号数量得先能导出来**。没有数据源，这个福利就是空头支票。这件事应该排在所有开发前。

---

## 1. 技术底座核查（实测数据）

对 `fpsmatch-1.20.1-1.3.0-forge-snapshot-20260913-0618.jar`（2.2 MB）解包核查：

| 项 | 结果 |
|---|---|
| modId / version | `fpsmatch` / `1.3.0` |
| Forge | `[47.4.10,)` |
| MC | `[1.20.1,1.21)` |
| **ldlib2** | **mandatory** `[2.2.27+1.20.1]` → 服务端+客户端都必须装 LDLib2 runtime/all jar |
| **kotlinforforge** | **mandatory** `[4.11.0,)` → 新增硬依赖（1.2.5 时代没有） |
| tacz | optional `[1.1.4,)` |
| jarjar 内嵌 | java-json-canonicalization 1.1、mixinextras-forge 0.5.3 |
| 混入（mixin） | `fpsmatch.mixins.json` + `fpsmatch.refmap.json` → **dev 环境老问题（SRG/mojmap 不匹配）仍要留意**，修补流程见 MEMORY.md |

**Action**：版本矩阵必须锁死（MC / Forge / FPSMatch / LDLib2 / KotlinForForge / KubeJS / TACZ / TACZ 枪包）。

---

## 2. KJS vs Mod 决策矩阵

| 需求类型 | 选型 | 原因（实测依据） |
|---|---|---|
| 注册新**游戏类型 / 地图类型** | **Mod** | `RegisterFPSMapEvent.registerGameType(String, Function3<ServerLevel,String,AreaData,BaseMap>)` 是 Java API；KJS 插件只注册事件（`FPSMatchKubeJSPlugin.registerEvents()`），**没有任何注册绑定** |
| **回合流程 / 胜负判定 / 复活** | **Mod** | 要继承 `BaseMap` / `BaseRoundMap<W,R>` / `RoundLifecycle`，抽象类必须 Java |
| 模式"叠加层"：奖励、经验、连杀播报、货币掉落、统计 | **KJS** | 1.3.0 已提供 `FPSMatchEvents` 事件组（下节），足够挂一切外围逻辑，脚本热重载、不重启客户端 |
| 自定义持久化数据（赛季/货币/称号） | KJS `persistentData` 或 Mod `SaveHolder` | 1.3.0 有 `RegisterFPSMSaveDataEvent.registerData(Class,String,SaveHolder<T>)`；简单数据用 KJS 更省事 |
| 皮肤 / 枪皮 / HUD / 音效 / 文案 | 资源包（+ 可选客户端 mod） | 资源包走 KJS 托管/下发即可；要改 HUD 布局才需要客户端 mod |
| 网页后台、兑换、排行榜、福利发放 | 独立 PHP/MySQL（复用现有站点） | 服务器已有站点与运维体系，游戏内别直连数据库；游戏侧定时批量同步 |

**三句话判据**
- 需要**新游戏类型**或**新回合状态机** → 写 mod
- 不改规则、只挂奖励/统计/播报/文案 → KJS
- 改枪械手感、命中判定、新实体/新装备 → mod（或 TACZ 数据包）

---

## 3. 好消息：1.3.0 的 KubeJS 兼容已经可用（1.2.5 完全没有）

实测 `com.ptcrys.fpsmatch.compat.kubejs` 包存在，事件组名 **`FPSMatchEvents`**，已注册事件（`FPSMatchCommonEvents.init()` 实证）：

| 事件 | 关键字段 |
|---|---|
| `mapStart` / `mapVictory` / `mapClear` / `mapReset` | `map` |
| `playerJoin` / `playerLeave` / `playerLoggedIn` / `playerLoggedOut` | `map`, `player` |
| `playerHurt` | + `source`, `amount`（**可 `setAmount()` 改写伤害**） |
| `playerDeath` / `playerKill` | + `source`（kill 还有 `dead`） |
| `teamJoin` / `teamLeave` | `team`, `player` |

KJS 侧样例（server 脚本）：

```js
FPSMatchEvents.mapStart(e => {
  e.server.tell(`§e开局：${e.map.mapName}`)
})
FPSMatchEvents.playerKill(e => {
  const p = e.player
  p.persistentData.kills = (p.persistentData.kills || 0) + 1
  // 赛季经验 / 货币掉落 / 连杀播报都挂这里
})
FPSMatchEvents.playerHurt(e => {
  if (someCondition) e.amount = 0   // 可改伤害
})
```

**限制（务必写进团队共识）**
- KJS 能**监听**、能**改伤害**、能**取消可取消事件**，但**不能注册模式/地图**。
- KubeJS 版本（1.20.1 Forge，2001.x）需与 1.3.0 要求的 API 对齐，上线前实测一次。
- 外围逻辑放 KJS 的代价：多一个 mod 依赖 + 逻辑分散。建议只放"奖励/统计/播报/文案"，**玩法判定一律回 mod**。

---

## 4. 五个玩法逐个判定（公告四·后续规划）

### 4.1 爆破模式（拆弹）——**先别写，先评估原生**
- 1.3.0 **已内置**：`DemolitionModeCapability`（含 `Data` / `DemolitionCommand`）、`BlastBombState` / `BlastBombItem` / `BlastBombEntity`、地图配置工具里的**炸弹区域编辑**（`MapRoomActionService$DemolitionEdit`），客户端/网络同步也补齐了。
- 路径：**先纯配置跑通一把原生爆破**（地图工具圈炸弹区 → 设回合 → 试玩），不够再写 capability 改造（拆除时长、经济、回合数、半场交换、加时）。
- 工作量：配置化 3–5 天；深度改造（半场交换 + 加时 + 经济）1–2 周。
- 风险：1.3.0 snapshot 的爆破 API 还在动，**改造要等相对稳定的版本**。

### 4.2 团队竞技 TDM ——**建议第一个做，最快见效**
- 路径：Mod（`BaseRoundMap` + 击杀目标/时间目标）。也可先用现有模式 + 自定义胜利条件起步。
- 工作量：1–2 周（含一张测试图）。
- 价值：验证"自有 gameType 注册 → 结算 → KJS 发奖励"整条链，是后面所有玩法的地基。

### 4.3 1v1 单挑 ——**两条路，先上快糙猛版**
- 路线 A（KJS 版，3–5 天）：竞技场区域 + 计分板 + 传送 + 排队命令，不改 FPSMatch。
- 路线 B（Mod 版，1–2 周）：小地图 + 单回合 + 排队/观战/认输/重赛，正式但慢。
- 建议：先 A 上活动（限时 1v1 赛），数据好再 B。

### 4.4 鞘翅空战 ——**最贵，放最后，先做 spike**
- 需要：空中重生点/边界、鞘翅+枪械交互规则（瞄准/后坐力）、坠落伤害与击杀判定、小地图/雷达、性能（大量实体与飞行玩家）。
- 工作量：3–5 周（且不保证好玩）。
- 建议：**先做 2–3 天技术 spike**（能不能在 FPSMatch 地图里稳定 10v10 飞起来不掉 TPS），可行再立项。

### 4.5 比赛模式 ——**别写进 mod，用「KJS + 网页后台」**
- 需求先定义清楚：裁判/观战 OB、暂停、BO3、地图 ban-pick、战队注册、弃权判定、结算与发放。
- 1.3.0 有 `compat/spectate` 观战包可用；赛程/报名/结算走现成的网站模式（像考试/委托/工单系统那样），游戏侧只做"进服准备 + 开始比赛 + 读结果"。
- 工作量：后台 1 周 + 游戏侧 1 周。**这个可以尽早做，性价比高、运营效果好。**

### 4.6 个人专属基地系统（公告提到）
- 先 spike 对比现成方案（领地/家园类 mod 或数据包）vs 自研；自研主要是"分配 + 圈地 + 存取 + 传送 + 权限"。别急着自研，先看现成的够不够。

**建议顺序**：TDM → 比赛模式后台 → 爆破（配置化）→ 1v1（KJS 版）→ 爆破（深度改造）→ 鞘翅空战 → 基地。

---

## 5. 已上线系统（签到 / 赛季 / 称号 / 货币）架构建议

现状：签到 18 天满签、赛季 40 级、丐版称号、三货币（安山 / 黄铜 / 玫瑰石英 = 5:1:1）。入口靠**重生点功能物品**。

1. **数据真相只放一处**：游戏内为真相源（KJS persistentData 或 mod SaveHolder），定时（如每 5 分钟 + 关服）批量同步到官网后台 → 排行榜/兑换页/福利页读后台，不实时查游戏。
2. **补指令**：主人自己说了"懒得做指令"——但运营要批量发奖/查数据/补救，**管理指令是刚需**，至少要有 `/ffgs currency give|set|check`、`/ffgs season info`。这个放 mod 或 KJS 都行（KJS 更快）。
3. **经济健康度**：5:1:1 意味着安山贬值最快；先做一张"产出速率 vs 商城定价"的表（每类货币每天/每场能进多少），否则 40 级赛季一开就通胀。玫瑰石英既然不氪金，务必控制产出上限（签到+限时活动定量发放）。
4. **旧服福利兑换管道（最高优先级）**：
   - 旧服导出：货币持有量 / 赛季手册等级 / 解锁称号数（按玩家 ID）
   - 归一化 → 生成"兑换资格"名单（含"老资历""测试先锋"称号发放）
   - 游戏侧领取入口（KJS 命令或 NPC/物品）+ 网页查询页
   - 公式按公告：基础 = 1 皮肤 + 三类货币各 300 + 2 称号；进阶 = 综合排名每 +1 位 → 三类货币各 +200（无封顶，注意刷取风险与通胀）

---

## 6. 活动与赛季节奏

**赛季模板（建议 8 周）**
- W0 预热（公告 + 旧服福利兑换开放）
- W1–W2 开幕（新玩法首周双倍经验/货币）
- W3–W6 常规（周任务 + 双倍周末 + 周末限时模式）
- W7 冲刺（赛季末双倍、排行榜结算预告）
- W8 结算（发奖 + 兑换 + 版本维护 + 下季预告）

**活动类型库**：满勤签到奖、双倍货币周末、限时模式周（1v1/爆破）、截图/建造/创意赛、战队赛（比赛模式上线后）、旧服回流（已发）。

**配套工具**：活动发放后台（网页，一键给名单发奖 + 邮件/物品/货币），别再手动发。公告模板也沉淀成文，复制即用。

**节奏铁律**：新玩法**一次只上一个**，上线后观察 2 周（难度/经济/性能），别连发。

---

## 7. 路线图

| 阶段 | 内容 | 周期 | 验收标准 |
|---|---|---|---|
| **P0 底座** | dev 环境：Forge 47.4.10+ / LDLib2 all 2.2.27 / KotlinForForge 4.11 / TACZ 1.1.4 / KubeJS 2001.x / FPSMatch 1.3.0 snapshot（锁定 commit）；旧地图用 `MapImportService` 导入验证；KJS 收到 `FPSMatchEvents.mapStart` | 3–5 天 | dev 客户端能进图开一把；KJS 打印开局日志；旧地图数据不丢 |
| **P1 核心 mod** | `ffgs-core` 骨架：注册自有 gameType、注册自有 SaveData、capability 骨架、管理指令；KJS 桥接接口定稿 | 2–3 周 | "TDM·测试图"能跑完整一局，KJS 能发奖励 |
| **P2 玩法** | TDM 打磨 → 比赛模式（KJS + 网页后台）→ 爆破（配置化）→ 1v1（KJS 版） | 4–6 周 | 每个玩法可独立开房、正常结算 |
| **P3 进阶** | 鞘翅空战 spike → 立项；爆破深度改造（半场/加时/经济） | 4–6 周 | spike 报告给结论（做/不做/改方案） |
| **P4 系统** | 个人基地（先评估现成方案）；赛季/货币/称号数据与后台打通 | 4 周 | 官网能看到实时排行榜与个人数据 |

---

## 8. 工程规范（防技术债）

- **版本矩阵**：写一张表钉在仓库根目录，任何人升版本必须改注释。
- **仓库拆分**：`ffgs-core`（玩法 mod）、`ffgs-kjs`（脚本，可单独发布）、资源包独立仓库、后台独立。
- **分支**：`master`（线上）、`dev-1.3.0`（跟进）、`feature-*`。
- **双轨测试**：本地 dev → 线上白名单测试服；每次上线跑回归清单（进图/开局/结算/奖励/签到/货币/称号/兑换/基地）。
- **文档**：`forge-docs-zh/16-fpsmatch.md` 目前是 1.2.5 的修订版，**需要按 1.3.0 重写并补 KJS/爆破/地图工具章节**（这个我可以做）。
- **备份**：每个赛季结算后归档玩家数据；mod 发布留版本回滚包。

---

## 9. 待拍板决策（需要主人点头）

1. **1.3.0 上生产的时机**：建议 dev 立刻跟进，生产等作者出 RC 或至少连跑 2 周 snapshot 无破坏性改动。
2. **KJS 是否引入**：引入即多一依赖，但外围开发效率翻倍；我的建议是引入，并立法"玩法判定只能在 mod"。
3. **旧服数据能不能拿到**：货币/等级/称号导不出来 → 公告承诺要改口径。**建议今天就去确认旧服数据源还在不在。**
4. **比赛模式的定位**：业余娱乐赛（KJS+后台够用）还是要正经裁判/OB/BO3（要投入更多后台开发）。
5. **鞘翅空战是否值得**：先给 2–3 天 spike 预算，再决定。

## 10. 风险清单

- 1.3.0 是 snapshot，API 随时变 → 锁版本 + 适配层
- LDLib2 / KotlinForForge 新增硬依赖 → 玩家客户端安装门槛上升（要写清安装教程，可放 docx 文档站）
- 旧服数据缺失 → 福利承诺无法兑现（运营风险，最高）
- 天空玩法性能 → 现在服内存本就紧张，先测 TPS
- 枪皮/皮肤版权（TACZ 枪包来源）
- 经济通胀（三货币 + 无封顶排名加成）

---

## 附：1.3.0 实测 API 速查（写 mod 直接用）

- 注册：`RegisterFPSMapEvent.registerGameType(String, Function3<ServerLevel,String,AreaData,BaseMap>)`（包 `common.event.register`）
- 持久化：`RegisterFPSMSaveDataEvent.registerData(Class<T>, String, SaveHolder<T>)`
- 基类：`BaseMap(ServerLevel,String,AreaData[,List<Class<? extends MapCapability>>])`、`BaseRoundMap<W,R>`（`buildRoundLifecycle()` / `onRoundStart/End` / `handleRespawn`）、`RoundLifecycle`、`RoundContext`、`RoundResult`
- 能力系统（1.3.0 真实存在）：`FPSMCapability`、`FPSMCapabilityManager`、`CapabilityMap`、`MapCapability`、`TeamCapability`、内置 `DemolitionModeCapability`、`GameEndTeleportCapability`
- 事件（Java 侧）：`FPSMapEvent.{StartEvent,VictoryEvent,ClearEvent,ResetEvent,ReloadEvent}`、`FPSMapEvent.PlayerEvent.{Join,Leave,Hurt,Death,Kill,KillRecord,PickupItem,TossItem,Chat,LoggedIn,LoggedOut}`、`FPSMTeamEvent.{JoinEvent,LeaveEvent}`、`FPSMShopEvent`、`FPSMGunFireEvent` / `FPSMGunShootEvent` / `FPSMGunReloadEvent` / `FPSMGunKillEvent` / `FPSMGunDamageEvent` / `FPSMThrowGrenadeEvent` / `FPSMReloadEvent`
- KJS 事件组：`FPSMatchEvents` → `mapStart` `mapVictory` `mapClear` `mapReset` `playerJoin` `playerLeave` `playerHurt`(可 setAmount) `playerDeath` `playerKill` `playerLoggedIn` `playerLoggedOut` `teamJoin` `teamLeave`
- 地图侧工具：`MapLobbyController`、`MapImportService`（可导入旧地图设置/队伍商店/区域）、物品 `map_creator_tool` / `match_config_tool` / `spawn_point_tool`