⬇ 下载 Markdown 原文

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

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

0. 结论速览

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

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 脚本）：

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）。入口靠重生点功能物品。

数据真相只放一处：游戏内为真相源（KJS persistentData 或 mod SaveHolder），定时（如每 5 分钟 + 关服）批量同步到官网后台 → 排行榜/兑换页/福利页读后台，不实时查游戏。
补指令：主人自己说了"懒得做指令"——但运营要批量发奖/查数据/补救，管理指令是刚需，至少要有 /ffgs currency give|set|check、/ffgs season info。这个放 mod 或 KJS 都行（KJS 更快）。
经济健康度：5:1:1 意味着安山贬值最快；先做一张"产出速率 vs 商城定价"的表（每类货币每天/每场能进多少），否则 40 级赛季一开就通胀。玫瑰石英既然不氪金，务必控制产出上限（签到+限时活动定量发放）。
旧服福利兑换管道（最高优先级）： - 旧服导出：货币持有量 / 赛季手册等级 / 解锁称号数（按玩家 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.3.0 上生产的时机：建议 dev 立刻跟进，生产等作者出 RC 或至少连跑 2 周 snapshot 无破坏性改动。
KJS 是否引入：引入即多一依赖，但外围开发效率翻倍；我的建议是引入，并立法"玩法判定只能在 mod"。
旧服数据能不能拿到：货币/等级/称号导不出来 → 公告承诺要改口径。建议今天就去确认旧服数据源还在不在。
比赛模式的定位：业余娱乐赛（KJS+后台够用）还是要正经裁判/OB/BO3（要投入更多后台开发）。
鞘翅空战是否值得：先给 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

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