基于 XML 驱动的自定义战斗架构：瞬时范围伤害、多级分裂飞行物与持续性滞留伤害场

   

注意：该文章为    CAF-CustomActionFramework    -自定义作战框架的开发指南，给Mod开发者提供详细参数和应用范围，因此需要先安装本框架生效。

                   

CAF框架开发指南

1. 框架概述

CAF（Custom Action Framework）框架是一套为《7 Days to Die》设计的统一武器动作与特效模组开发框架。它的核心目标是让 Mod 开发者无需修改游戏核心代码，仅通过 XML 配置即可创建功能丰富的自定义远程武器、近战技能以及事件驱动型特效。

框架由两大子系统构成：

• Hub 统一开火调度系统：以 ItemActionFireModuleHub 为总入口，集成四大开火模块，支持多弹药 → 多模板动态路由切换。

• MiniEvent 事件触发系统：不走传统武器 Action0 管线，深度对接原版触发机制，支持近战剑气、命中回弹等纯 XML 部署。

CAF 核心设计：性能优化与物理演算剥离。采用以下核心优化策略：

• 零方块物理演算：放弃地形碰撞模拟，采用轻量级扫描，极大地保护服务器帧率。但注意：无法破坏地形方块。

• 保留生物物理交互：保留对丧尸等实体的击飞、倒地等 Ragdoll 表现。

综上，CAF 框架提供了统一的快照参数体系（_add / _mult）和智能武器支持，让你专注于创意设计。

框架的核心组件包括：

组件	功能
ItemActionFireModuleHub	统一开火入口，调度四种开火模块
CAF_HubFetchRegistry	注册并管理所有可用的动态参数
CAF_SnapshotBuilder	运行时聚合武器属性快照
CAFSmartWeaponSystem	虚拟弹夹、能量池、UI锁定环

---

1.2 架构总览

1. Hub (ItemActionFireModuleHub)：拦截 Action0 调用，分发开火逻辑。

2. Snapshot (CAF_WeaponSnapshot)：合并 XML 属性生成的参数快照。

3. 开火模块 (Fire Modules)：包括 CR、DR、Laser、ContLaser 四类模块。

2. 框架部署与文件结构

框架自动扫描 Config/CAF_Templates.xml。结构如下：

YourMod/
├── Config/
│   ├── items.xml
│   ├── CAF_Templates.xml
│   └── item_modifiers.xml
└── Resources/
    └── your_assets.unity3d

框架在游戏启动时会自动加载所有模板：

“CAF Hub 正在扫描 Mod XXX 的模板文件...”
“CAF Hub 成功加载来自 XXX 的模板文件，模板数量: N”

---

2.1. 参数体系

每个模块和系统都有一组注册在 CAF_HubFetchRegistry 中的标准参数。下面的”常用配置属性”表格仅列出了部分代表性参数。所有可用的 _add / _mult 修饰符及其完整列表，请参考帖子下的 字典表。

核心概念: 属性覆盖优先级与 _base / _add / _mult

框架并不直接使用 _base 后缀。属性的最终值由三个来源按以下优先级从上到下合并得出：

1. 模板默认值 (CAF_Templates.xml)：提供基础设定。

2. 直接设定值：在 item_modifiers.xml 或 items.xml 的 Action0 中使用不带后缀的属性名，会覆盖模板的默认值。

3. 增量修正值：

• 属性名_add: 在直接设定值的基础上加一个值。

• 属性名_mult: 在直接设定值的基础上乘一个值。

快照系统会在运行时按照 ActionProps → TemplateProps → ModifierProps 的优先级合并这些参数。

2.2 弹药类型路由 – 一个武器，多种开火模式

这是框架最强大的特性之一。通过在 items.xml 的 Action0 中定义 CAF_Ammo_XXX_Template 属性，并保留原版的 Magazine_items 来指定可用的弹药类型。Hub 会根据玩家当前选择的弹药，自动切换到对应的模板和开火模块。

 <property class="Action0">
        <property name="Class" value="ItemActionFireModuleHub, CustomAoeParticleEffect"/>

        <!-- 弹药 => 模板 映射 -->
        <property name="CAF_Ammo_ammo762mmBulletBall_Template" value="CAF_HybridMG_Ball"/>
        <property name="CAF_Ammo_ammo762mmBulletAP_Template"   value="CAF_HybridMG_AP"/>
        <property name="CAF_Ammo_ammo762mmBulletHP_Template"   value="CAF_HybridMG_contLaser_HP"/>

        <!-- 原版弹匣必须保留，Hub 依赖此字段判断弹药类型 -->
        <property name="Magazine_items"     value="ammo762mmBulletBall,ammo762mmBulletHP,ammo762mmBulletAP"/>

        <!-- 音效：Ball/HP 模式沿用 parallax 声效；AP 激光模式由模板覆盖 -->
        <property name="Sound_start"  value="parallax_fire"/>
        <property name="Sound_loop"   value="parallax_fire"/>
        <property name="Sound_empty"  value="dryfire"/>
        <property name="Sound_reload" value="m60_reload"/>
        <property name="Sound_end"    value="parallax_end"/>
        <property name="AutoReload"   value="false"/>
        <property name="InfiniteAmmo" value="true"/>

        <property name="triggerEffectTriggerPullDualsense"  value="RifleTrigger"/>
        <property name="triggerEffectTriggerPullXbox"       value="PistolTrigger"/>
        <property name="triggerEffectTriggerShootDualsense" value="MGShoot"/>
        <property name="triggerEffectTriggerShootXbox"      value="PistolShoot"/>
    </property>

    <!-- Action1：瞄准镜 -->
   
    <property class="Action1">
        <property name="Class"               value="Zoom"/>
        <property name="Zoom_max_out"         value="55"/>
        <property name="Zoom_max_in"          value="55"/>
        <property name="SightsCameraOffset"   value="0.08,-0.06,0"/>
        <property name="zoomTriggerEffectTriggerPullDualsense" value="RifleZoom"/>
        <property name="zoomTriggerEffectTriggerPullXbox"      value="PistolZoom"/>
    </property>

---

3. 开火模块 (Fire Modules) 详解

框架通过 ItemActionFireModuleHub 作为总入口，调度四种独立的开火模块。每种模块拥有独立的参数前缀，可通过CAF Template中的 CAF_FireModuleType 指定使用哪种模块。

3.1 CustomRanged (CR) 模块

最基础的远程模块。启用代码：

<property name="CAF_FireModuleType" value="CustomRanged"/>

核心参数（前缀 CR_）：

参数	类型	说明
CR_Delay	Float	射击间隔（秒）
CR_Count	Int	每次射击投射物数量
CR_Velocity	Float	投射物速度
CR_Gravity	Float	投射物重力
CR_HomingRadius	Float	追踪半径（0=关闭）
CR_HomingSpeed	Float	追踪转向速度
CR_PierceCount	Int	穿透次数
CR_ChainCount	Int	链式分裂层数
CR_ChainAmount	Int	每次分裂数量
CR_AOE_Radius	Float	AOE爆炸半径
CR_AOE_Damage	Int	AOE基础伤害

常用配置属性：

属性	分类	说明
CR_ConsumeMultiplier	弹药	单次射击消耗弹药的倍数
CR_DamageType	伤害	伤害类型 (如 “Piercing”)
CR_Proj_UseWeaponDamage	伤害	是否使用武器面板伤害
CR_Proj_WeaponDamagePercent	伤害	武器伤害百分比
CR_TargetTags	目标	可命中的实体标签 (如 “zombie,animal”)
CR_IgnoreSelf	目标	是否忽略自身
CR_HitBlocks	目标	是否能击中方块
CR_Particle	特效	投射物粒子特效路径
CR_HitParticle	特效	命中粒子特效路径
CR_FireStartAudio	音效	开火音效路径
CR_FireLoopAudio	音效	循环音效路径
CR_FireEndAudio	音效	停火音效路径
CR_CurveMode	弹道	是否启用曲线弹道
CR_CurveSpread	弹道	曲线弹道散布范围

3.2 DynamicRanged (DR) 模块 

动态射速武器模块，支持射速渐变（暖枪加速/冷却减速）和动态后坐力。

Template 中启用：

<property name="CAF_FireModuleType" value="DynamicRanged"/>

动态射速参数（前缀 DR_）：

参数	类型	说明
DR_MinDelay	Float	最小射击间隔（最快射速）
DR_MaxDelay	Float	最大射击间隔（最慢射速）
DR_WindUpPerShot	Float	每枪减少的延迟量
DR_WindDownTime	Float	停火后退化时间
DR_SpreadMultiplierMax	Float	最大散布倍率

常用配置属性：

属性	分类	说明
DR_ConsumeMultiplier	弹药	单次射击消耗弹药的倍数
DR_DamageType	伤害	伤害类型
DR_Count	投射物	每次射击投射物数量
DR_Velocity	投射物	投射物速度
DR_Gravity	投射物	投射物重力
DR_HomingRadius	追踪	追踪半径
DR_HomingSpeed	追踪	追踪转向速度
DR_HitDamage	伤害	命中基础伤害
DR_PierceCount	穿透	穿透次数
DR_ChainCount	链式	链式分裂层数
DR_AOE_Shape	AOE	AOE形状 (cone/sphere/box)
DR_AOE_Radius	AOE	AOE爆炸半径
DR_AOE_Damage	AOE	AOE基础伤害
DR_Particle	特效	投射物粒子特效路径
DR_HitParticle	特效	命中粒子特效路径
DR_MaxFireAudio	音效	满射速音效路径
DR_FireEndAudio	音效	停火音效路径
DR_Proj_UseWeaponDamage	伤害	是否使用武器面板伤害
DR_AOE_UseWeaponDamage	AOE	AOE是否使用武器面板伤害

3.3 Laser 模块

即时命中激光/光束武器模块，支持穿透、弹射和命中爆炸。

Template 中启用：

<property name="CAF_FireModuleType" value="Laser"/>

核心参数（前缀 LASER_）：

参数	类型	说明
LASER_Range	Float	激光射程
LASER_PierceCount	Int	穿透次数（每穿透一次伤害缩放）
LASER_BounceCount	Int	弹射次数
LASER_BounceReturnToShooter	Bool	是否弹回射击者
LASER_Thickness	Float	激光命中判定宽度

常用配置属性：

属性	分类	说明
LASER_Delay	射击	射击间隔（秒）
LASER_ConsumeMultiplier	弹药	单次射击消耗弹药的倍数
LASER_UseWeaponDamage	伤害	是否使用武器面板伤害
LASER_WeaponDamagePercent	伤害	武器伤害百分比
LASER_DamageType	伤害	伤害类型
LASER_IgnoreSelf	目标	是否忽略自身
LASER_HitBlocks	目标	是否能击中方块
LASER_Rayhit	命中	命中判定模式 (“primary”)
LASER_BeamPrefab	特效	激光束粒子特效路径
LASER_OriginPrefab	特效	激光源点特效路径
LASER_HitPrefab	特效	激光命中特效路径
LASER_AudioStart	音效	开火音效路径
LASER_AudioLoop	音效	循环音效路径
LASER_AudioEnd	音效	停火音效路径

Laser 模块还支持子级系统：

• LASER_Hit_AOE_* ：命中点 AOE 爆炸参数

• LASER_Origin_AOE_* ：源点 AOE 爆发参数

• LASER_Hit_Zone_* ：命中后持续灼烧区参数

• LASER_Proj_* ：激光伴随飞弹参数

3.4 ContinuousLaser 模块

持续伤害光束模块，适用于激光炮、火焰喷射器等。

Template 中启用：

<property name="CAF_FireModuleType" value="contlaser"/>

常用配置属性：

属性	分类	说明
LASER_Delay	射击	伤害触发间隔（秒）
LASER_Range	核心	光束射程
LASER_BounceCount	弹射	弹射次数
LASER_Thickness	核心	命中判定宽度
LASER_UseWeaponDamage	伤害	是否使用武器面板伤害
LASER_WeaponDamagePercent	伤害	武器伤害百分比
LASER_AudioStart	音效	开始音效路径
LASER_AudioLoop	音效	循环音效路径（持续播放）
LASER_AudioEnd	音效	结束音效路径

注意： ContinuousLaser 同样支持 LASER_Proj_* 和 LASER_Hit_Zone_* 等子级系统，可伴随飞弹或产生持续区域伤害。

---

4. 智能武器系统 (SmartWeapon System)

智能武器系统 CAFSmartWeaponSystem提供了一套虚拟弹夹 + 储备能量池的机制，使武器无需依赖物理弹药即可模拟复杂的充能/消耗系统。

核心配置属性（在 items.xml 中配置） 

属性	类型	说明
CAF_SW_VirtualMagCVar	String	虚拟弹夹CVar名称
CAF_SW_VirtualMagMax	Float	虚拟弹夹最大容量
CAF_SW_EnergyPoolCVar	String	能量池CVar名称
CAF_SW_EnergyPoolMax	Float	能量池最大容量
CAF_SW_ChargeTimeFull	Float	充满时间（秒）
CAF_SW_ChargeUsesAmmo	Bool	充能是否消耗弹药
CAF_SW_ChargeDelay	Float	开火后充能延迟
CAF_SW_LockEnabled	Bool	是否启用锁定环
CAF_SW_LockAimPart	String	锁定目标部位
CAF_SW_LockRingRadius	Float	锁定环半径
CAF_SW_HideVanillaAmmo	Bool	是否隐藏原版弹药条
CAF_SW_ChargeAudio	Path	充能音效路径
AutoChargeUI	String	自动充能UI（如 windowCAFEnergyBar）

UI 自定义属性 智能武器系统还支持丰富的UI颜色和位置自定义，包括弹药块颜色、能量条颜色、锁定环颜色等。

5. 武器配件系统 (Item Modifiers) 

框架完全兼容7DTD原生的武器配件系统，并扩展了Hub读取能力。配件可以通过 _add 和 _mult 后缀对CAF参数进行增量修正。

5.1 配件定义语法

<item_modifier name="modYourModule" installable_tags="yourTag" modifier_tags="yourModTag" 
type="attachment"> 
    
    <property name="CAF_Param_add" value="10"/>    
    <property name="CAF_Param_mult" value="1.5"/>  
    <property name="CAF_Param" value="true"/>  
      <!-- 例如：开启弹射返回射手 (归途效果) -->
    <property name="LASER_BounceReturnToShooter" value="true"/>
   
    <!-- 弹射次数 +1 -->
    <property name="LASER_BounceCount_add" value="1"/>
   
         
    <effect_group tiered="false">         
        <passive_effect .../>         
        <triggered_effect .../>     
    </effect_group> 
</item_modifier>

5.2 配件的 PropertyOverrides 机制

框架会读取配件的 PropertyOverrides ，支持按武器名称精确覆盖或使用通配符 * 全局覆盖。

<property name="LASER_Hit_AOE_Enable" value="true" param1="*"/

PS：可以直接使用七日杀原生的

installable_tags="yourTag"

来区分哪些武器需要覆盖数值，无需写入param1，除非你想让一个插件在不同武器有不同数值效果。

---

6. 实际案例分析

6.1 案例：混合弹药机枪（三弹切换）

参考 parallax_hybrid_machinegun 的实现，该机枪支持三种弹药模式，每种模式绑定不同的Template：

items.xml 配置：

<property name="Magazine_items" value="ammo762mmBulletBall,ammo762mmBulletHP,ammo762mmBulletAP"/> 
<property name="CAF_Ammo_ammo762mmBulletBall_Template" value="CAF_HybridMG_Ball"/> 
<property name="CAF_Ammo_ammo762mmBulletAP_Template" value="CAF_HybridMG_AP"/> 
<property name="CAF_Ammo_ammo762mmBulletHP_Template" value="CAF_HybridMG_HP"/>

对应的 CAF_Templates.xml：

<?xml version="1.0" encoding="UTF-8"?>
<configs>

<template name="CAF_HybridMG_Ball">

    <!-- Hub 告诉 FireModuleHub 该用哪个模块 -->
    <property name="CAF_FireModuleType" value="DynamicRanged"/>

    <!-- DR 动态射速 -->
    <property name="DR_MinDelay"          value="0.05"/>
    <property name="DR_MaxDelay"          value="0.3"/>
    <property name="DR_WindUpPerShot"     value="0.05"/>
    <property name="DR_WindDownTime"      value="1.0"/>
    <property name="DR_SpreadMultiplierMax" value="3.0"/>

    <!-- DR 音效节点-->
    <property name="DR_MaxFireAudio"      value="#@modfolder:Resources/parallax_sounds.unity3d?parallax_max_fire.prefab"/>
    <property name="DR_MaxFireEnterAudio" value="#@modfolder:Resources/parallax_sounds.unity3d?parallax_max_start.prefab"/>
    <property name="DR_FireEndAudio"      value="#@modfolder:Resources/parallax_end.unity3d?parallax_end.prefab"/>
    <property name="DR_EmptyFireAudio"    value=""/>
    <property name="DR_BurstEffectName"   value="CAF_BurstEffect"/>
    <property name="DR_ChargeEffectName"  value="CAF_ChargeEffect"/>


    <!-- 通用开关 -->
    <property name="DR_ConsumeMultiplier" value="1"/>
    <property name="DR_DamageType"        value="Piercing"/>
    <property name="DR_TargetTags"        value="zombie,animal"/>
    <property name="DR_IgnoreSelf"        value="true"/>
    <property name="DR_HitBlocks"         value="true"/>
    <property name="DR_IgnoreBlock"       value="true"/>
    <property name="DR_EventOnBlock"      value="true"/>

    <!-- 武器面板伤害联动 -->
    <property name="DR_Proj_UseWeaponDamage"    value="true"/>
    <property name="DR_Proj_WeaponDamagePercent" value="1.0"/>

    <!-- 投射物核心 -->
    <property name="DR_Count"             value="3"/>
    <property name="DR_PierceCount"       value="1"/>
    <property name="DR_Particle"          value="#@modfolder:Resources/parallax_vfx.unity3d?parallax_projectile.prefab"/>
    <property name="DR_ParticleScale"     value="0.7"/>
    <property name="DR_Velocity"          value="50"/>
    <property name="DR_Gravity"           value="1"/>
    <property name="DR_ProjectileLifetime" value="3"/>
    <property name="DR_SpreadAngle"       value="50"/>
    <property name="DR_VerticalAngle"     value="0,0"/>

    <!-- 制导 -->
    <property name="DR_HomingRadius"       value="3"/>


    <!-- 曲射弧线弹道 -->
    <property name="DR_CurveMode"       value="true"/>
    <property name="DR_CurveSpread"     value="5,5"/>
    <property name="DR_CurveDelay"      value="0.05"/>
    <property name="DR_CurveTurnSpeed"  value="240"/>

    <!-- 命中参数 -->
    <property name="DR_HitDamage"   value="0"/>
    <property name="DR_HitRadius"   value="1"/>
    <property name="DR_HitForce"    value="1"/>
    <property name="DR_HitParticle" value="#@modfolder:Resources/parallax_vfx.unity3d?parallax_explosion.prefab"/>
    <property name="DR_HitLifetime" value="3"/>
    <property name="DR_RagdollTime" value="0"/>

    <!-- 链式（关闭）-->
    <property name="DR_ChainCount"       value="0"/>
    <property name="DR_ChainAmount"      value="5"/>
    <property name="DR_ChainScale"       value="0.7"/>
    <property name="DR_ChainVelocity"    value="15"/>
    <property name="DR_ChainGravity"     value="9.8"/>
    <property name="DR_ChainSpread"      value="360"/>
    <property name="DR_ChainVertical"    value="10,45"/>
    <property name="DR_ChainLifetime"    value="3"/>
    <property name="DR_ChainHomingRadius" value="0"/>
    <property name="DR_ChainHomingSpeed"  value="180"/>

    <!-- 枪口 AOE（视觉 cone，无伤害）-->
    <property name="DR_AOE_Shape"          value="cone"/>
    <property name="DR_AOE_Radius"         value="0.5"/>
    <property name="DR_AOE_ConeAngle"      value="160"/>
    <property name="DR_AOE_Damage"         value="0"/>
    <property name="DR_AOE_Force"          value="0"/>
    <property name="DR_AOE_Particle"       value="#@modfolder:Resources/parallax_vfx.unity3d?parallax_muzzle.prefab"/>
    <property name="DR_AOE_ParticleLifetime" value="0.5"/>
    <property name="DR_AOE_EventCooldown"  value="0.1"/>
    <property name="DR_AOE_HitBlocks"      value="true"/>
    <property name="DR_AOE_UseWeaponDamage" value="false"/>
    <property name="DR_AOE_WeaponDamagePercent" value="1.0"/>

</template>

</configs>

弹药	对应模块	特性
Ball	DynamicRanged	标准弹道，动态射速
AP	Laser	穿甲激光，穿透+弹射+AOE爆炸
HP	DynamicRanged	近距空尖弹，球形AOE高伤爆发

6.2 案例：SMG智能武器

参考 parallax_smg 的智能武器配置：

<property name="CAF_SW_VirtualMagCVar" value="CAF_HybridSMG_Mag"/> 
<property name="CAF_SW_VirtualMagMax" value="50"/> 
<property name="CAF_SW_EnergyPoolCVar" value="CAF_HybridSMG_Energy"/> 
<property name="CAF_SW_EnergyPoolMax" value="500"/> 
<property name="CAF_SW_ChargeTimeFull" value="4"/> 
<property name="CAF_SW_HideVanillaAmmo" value="true"/>

该配置实现了：

• 50发虚拟弹夹

• 500点能量池，4秒充满

• 隐藏原版弹药显示

• 支持锁定环瞄准

6.3 案例：配件模式切换

参考 modNekomataAnnihilation 和 modNekomataPrecision 配件，它们通过设置 modifier_tags="nekomata_core_mode" 实现互相排斥的模式切换：

<property name="LASER_Hit_AOE_WeaponDmgMult" value="5.0"/> 
<property name="LASER_Hit_AOE_Radius" value="8"/> 
<property name="LASER_WeaponDamagePercent" value="0.5"/>  

<property name="LASER_Delay" value="0.25"/> 
<property name="LASER_WeaponDamagePercent" value="1.2"/> 
<property name="LASER_Hit_AOE_Enable" value="false"/>

7. 故障排查与调试

7.1 常见问题

问题	原因	解决方案
模板未加载	文件名不是 CAF_Templates.xml	确保文件名和路径完全正确
参数不生效	参数名未在Registry注册	检查参数前缀（CR_/DR_/LASER_）
模块不切换	CAF_FireModuleType值错误	检查支持的别名：cr/dr/laser/contlaser

7.2 调试建议

1. 检查日志：所有模块初始化和模板加载信息都会输出到游戏日志，请优先检查 output_log.txt。

2. 开启快照日志：可以在代码中找到 VerboseSnapshotLog 标志，将其设为 true 可查看详细的参数合并过程。

3. 验证 Registry：检查字典表，确保使用的属性名已注册，并检查其是否允许 _add / _mult 操作 

CAF 框架 MiniEvent 模块开发指南 

1. MiniEvent 模块概述

MiniEvent 是 CAF 框架中轻量级的事件驱动动作执行系统。它与 Hub 系统并驾齐驱，专门负责执行那些“响应游戏事件而触发”的自定义特效与逻辑，例如近战剑气、命中爆炸、生成法阵、爆头回弹等。

需要明确区分的是：

• 触发器 (trigger)：是游戏原生的，例如 onSelfPrimaryActionStart，它们决定了什么时候执行动作。

• 动作 (action)：是CAF 框架扩展的核心，例如 CustomProjectile。它们决定了做什么。

关于 Action 语法的核心说明：
在 action 属性中，你通常会在自定义动作后面看到 , CustomAoeParticleEffect。这不是两个动作，而是“一个动作 + 它所属的 MOD 程序集标识”。所有属于本框架的 Action，都必须以此格式书写。

---

2. 框架提供的自定义动作 (Actions)

2.1 CustomProjectile — 自定义投射物系统

这是框架最核心的动作，用于从玩家或指定位置发射独立的、受框架底层物理演算的飞行物。

部署示例 (近战剑气/远程附加弹幕)：

<triggered_effect trigger="onSelfSecondaryActionStart"
    action="CustomProjectile, CustomAoeParticleEffect"
    particle="bloodkatana?BloodKatanaWave"
    particle_scale="0.6" spin_rate="90"
    velocity="15" gravity="0" projectile_lifetime="3"
    count="1" spread_angle="1" on_aim="true"
    hit_particle="bloodkatana?BloodExplosion" hit_lifetime="1"
    hit_radius="5" hit_damage="500" hit_force="20"
    rayhit="Secondary"
    target_tags="zombie,animal" ignore_tags="player" hit_blocks="true"
    chain_count="1" chain_amount="3" chain_scale="0.7"
    chain_velocity="10" chain_gravity="0" chain_spread="60"
/>

常用配置参数：

参数	说明
hit_radius / hit_damage	命中时产生的球形AOE范围和基础伤害。
use_weapon_damage	是否让伤害与武器面板联动（百分比）。
curve_mode / homing_radius	是否启用弧线弹道与追踪锁定功能。
chain_count / chain_amount	链式分裂的代数与每次分裂的子弹数量。

2.2 MinEventActionAOEDamage — 瞬时范围伤害动作

直接生成AOE区域的动作，无需飞行过程，适合做“震地冲击波”。

<triggered_effect trigger="onSelfPrimaryActionStart"
    action="MinEventActionAOEDamage, CustomAoeParticleEffect"
    shape="sphere" radius="3" damage="50" force="10" ... />

2.3 MinEventActionSpawnZone — 主动法阵生成器

创造一个持续的独立伤害场（法阵/Zone），处理实体进入/离开的复杂逻辑。

<triggered_effect trigger="onSelfSecondaryActionStart"
    action="MinEventActionSpawnZone, CustomAoeParticleEffect"
    radius="4" damage="20" duration="5"
    tick_rate="1"
    particle="#@modfolder:Resources...?zone.prefab"
    buff="buffBurning"
    target_tags="zombie,animal"
/>

2.4 AddWeaponAmmo — 命中反馈式弹药补给

配合射击命中事件使用，实现如“爆头回复一发弹药”的战术效果。

<triggered_effect trigger="onSelfPrimaryActionRayHit"
    action="AddWeaponAmmo, CustomAoeParticleEffect"
    count="1" require_headshot="true"
/>

2.5 实践：如何结合触发器高效工作

主攻击附加弹幕：用 onSelfPrimaryActionStart + CustomProjectile。适合给任何左键开火的武器增加额外飞行物。

右键“大招”：用 onSelfSecondaryActionStart + CustomProjectile 或 MinEventActionAOEDamage 或 MinEventActionSpawnZone`。

命中反馈：用 onSelfPrimaryActionRayHit + AddWeaponAmmo 或 ModifyStats。

（注意：RayHit 事件在 Hub 模块和 CustomProjectile 中自动发射，前提是你的投射物开启了 rayhit=”Primary”）。

配件专属效果：在 item_modifiers.xml 的 effect_group 中编写上述 Action，通过 installable_tags 与武器绑定。

---

Monster Mode（怪物模式）参数与原理

1. 概述

Monster Mode 是专为非玩家实体（如怪物、Boss、炮塔）设计的独立发射逻辑。开启后，发射位置会使用怪物自身坐标，方向通过智能目标搜索（如最近玩家）自动决定，无需手动计算复杂向量。

2. 核心参数列表

参数名	说明
monster_mode	总开关。设为 true 后切换为怪物模式。
direction_mode	方向模式。可选 attacker (攻击目标)、closest_player (最近玩家)。
monster_scan_radius	怪物模式下搜索目标的最大半径（米）。
monster_scan_angle	搜索目标的视野角度（如 360 为全周天，90 为前方锥形）。
monster_aim_height	瞄准目标时的高度偏移，通常设为胸部/头部高度。
monster_require_los	是否要求视线畅通 (无障碍物遮挡)。

3. 工作原理

• 发射位置：不再使用玩家眼高，而是通过 Self.GetPosition() 取怪物坐标，配合 spawn_offset 调整高度。

• 方向解析：如果是 closest_player，系统会在指定半径和角度内寻找最近的玩家并计算世界空间方向向量。

• 曲线弹道：结合 curve_mode="true" 可实现类似“追踪飞弹”的追击效果。

4. 部署案例

案例：怪物发射追踪玩家的火焰球

<triggered_effect trigger="onSelfBuffUpdate"
    action="CustomProjectile, CustomAoeParticleEffect"
    monster_mode="true"
    direction_mode="closest_player"
    monster_scan_radius="50"
    monster_scan_angle="120"
    monster_aim_height="1.2"
    monster_target_players_only="true"
    monster_require_los="true"
    spawn_offset="0,1.5,0"
    particle="#@modfolder:Resources/fireball.unity3d?fireball.prefab"
    hit_particle="#@modfolder:Resources/fireball.unity3d?explosion.prefab"
    velocity="20" gravity="0" count="1" hit_radius="3" hit_damage="50"
    projectile_lifetime="5"
    curve_mode="true" curve_spread="15,15" curve_delay="0.2" curve_turn_speed="180"
    target_tags="player"
/>

解析：（放在怪物 Buff 中）每当 Buff 刷新时，怪物以 120° 锥形搜索 50 米内的玩家，从胸部高度发射 1 颗带曲线追踪的火球。

5. 重要注意事项

1. 必须设置 monster_mode="true" 才会启用怪物逻辑，否则会默认当做玩家处理导致发射点错误。

2. 使用 server_only="true" 时客户端看不到特效，通常用于无差别的全屏弹幕伤害判定。

3. 所有参数支持 CVar 动态读取（通过 @ 前缀实现），例如让 Boss 血量越低射速越快。

更新：05.12.2026 开发指南对应版本V2.1.0

下方我已经打包了本页面所有框架开发指南和相关字典，可以以PDF查看：

结语：

1. 欢迎来到魔法时代！

2. 只是为了做完拳套重修MOD，竟然做了如此大的框架。

3. 此框架为轻量Mod开发者提供了极大的便利，因此我决定完善并规范化分享。

4. 建议在Unity编辑特效时，标准设为1米左右，方便框架缩放。

5. 希望能帮助到大家！

04/12/2026已更新V1.1.0，请前往Mod贴查看更新日志。

如果你有什么想法和建议请回复评论区，谢谢！