自定义武器动作框架_V2.0.0|

战斗框架 V2.0.0

1. 核心架构重构：武器中枢系统（HUB）

在过去的版本中，一把武器若要使用自定义开火模块，必须将所有参数（可能超过100个）全部写进 items.xml 的 Action 0 中。这会导致物品文件极其臃肿，且难以维护。

为解决此问题，本次更新全面引入了 HUB（中央调度器）系统。

统一调度： 武器现在只需挂载 ItemActionFireModuleHub。HUB 会根据配置自动路由到对应的子模块（如常规射击、动态射速、激光等）。

独立模板文件（CAF_Templates.xml）： 所有的开火参数从物品文件中剥离，转移至专用的模板文件中。

多对一复用： 任何一把枪现在只需要在代码中调用一个“开火模板名称”。你可以让十把不同的突击步枪共用同一套射击逻辑模板，极大简化了 XML 的编写工作。

2. 核心机制新增：武器快照机制（Snapshot）-多态自适应武器系统

为了让框架武器能够兼容七日杀原版的武器配件（插件）系统，并提升游戏性能，底层加入了“快照机制”。

极致性能优化： 当玩家手持武器时，系统会读取武器基础参数、模板参数以及当前安装的所有武器配件属性，打包生成一个“快照缓存”。每次开火时，底层逻辑会直接读取该缓存，彻底免去了过去每次开火都要重新计算上百个参数的过程，大幅降低了计算开销。

多态自适应： 如果玩家在游戏中给武器安装或拆卸配件，系统会重新计算哈希值（Hash）并自动刷新快照。这意味着 Mod 开发者可以利用原版配件，动态修改 CAF 框架的参数（例如用配件改变激光颜色，伤害，范围或动态射速上限）。

多人联机数据隔离： 快照系统与实体（EntityID）严格绑定。每一个玩家或怪物都有一个专属的缓存ID，彻底杜绝了多人模式下玩家之间相互串载、导致数据污染的问题。

3. 全新子系统：智能武器模块 (Smart Weapon)

本次更新引入了全新的智能武器系统，旨在突破原版游戏的实体弹药机制限制。

虚拟弹夹与自动充能： 武器可以不再依赖背包里的实体子弹。停止开火并经过设定的延迟后，弹匣会随着时间自动充能恢复。

储备能源池： 充能过程可以设定为消耗玩家身上的“储备能量池”，能量池耗尽则停止恢复子弹。

界面定制 (UI)： 允许在配置中直接隐藏游戏原版右下角的实体弹药条，并内置了 UI 锁定环（Lock Ring）的参数接口，方便制作高科技自瞄武器。

动态属性兼容： 智能武器的弹匣容量、充能速度等参数，完全支持读取玩家的内置变量（@CVar），并完美兼容原版武器配件的直接修改（支持增加 _add 和乘算 _mult）。

适配状态： 该模块目前已与动态射速模块 (Dynamic Ranged) 深度绑定并完美运行。其他开火模块（如激光类）目前虽已完成接口连接，但仍在精调阶段，使用时可能会有少许表现异常。

4. 开火模块全面升级

原有的开火模块进行了整体重构，并新增了三个独立的射击模块：

动态射速模块 (Dynamic Ranged)： 允许武器的射速随开火时间发生动态变化（例如越射越快），并支持与射速联动的专用音效和特效植入（包括充能音效、最高射速音效等）。

瞬时激光模块 (Instant Laser)： 基于射线检测制作。支持穿透、反弹、定制粗细与视觉留存时间。

持续激光模块 (Continuous Laser)： 提供持续输出的光束模式。增加了源点特效跟随枪口或视角的逻辑，弹药耗尽时会自动清理光束残留。

5. 投射物与实体系统补充

对自定义物理弹道发射器（MinEventActionCustomProjectile）进行了补充：

扫掠碰撞盒 (Swept Box Collision)： 为高速飞行的投射物添加了连续碰撞检测，防止子弹在帧率波动时穿过较薄的墙壁或怪物。

怪物发射模式： 开放了实体权限，现在丧尸和 NPC 也可以调用该发射器，允许开发者制作能发射复杂弹幕或追踪弹的怪物。

6. 精准部位判定系统 (CAFHitPartUtil)

新增了精确的命中部位判定工具。

机制说明： 当投射物或激光击中目标时，系统会穿透扫描碰撞体的标签和名称，精准识别击中的是目标的头部（Head）还是躯干（Body）。

效果： 确保了框架内的所有武器都能向游戏原版的伤害系统正确传递部位标签，正常触发“爆头”的额外伤害倍率。

V2.1.0

05/24/2026

1. 智能武器系统上线，具体部署方案已经在指南更新