Lv.5

萌新驾到

该内容使用了刷新卡，原发布时间：2个月前

CAF V2.3.0 · XML MOD 作者文档

Custom Action Framework

自定义作战框架开发指南

从原版 XML 触发器到 CAF HUB（武器中枢）、自定义投射物、持续区域、智能武器和暴击分支的完整接入说明。

对应公开版本：V2.3.0 Base（基础框架）

语法分层 HUB 接入四个模块 MinEventAction 智能武器暴击与触发器资源路径排错附件下载

阅读对象：准备使用 CAF 制作武器、技能、Buff 或战斗效果的 XML MOD 作者。

本页只讲解 CAF V2.3.0 Base（基础框架）的公开能力。按照本文配置的 MOD 不需要额外的词缀组件。

术语格式：中文说明与英文代码标识并列。英文类名、XML 字段、模块名和 CVar（自定义变量）保持原样，便于直接检索和复制。

Custom Action Framework（CAF，自定义作战框架）是一套由 DLL 提供运行能力、由 XML 负责配置和组合的战斗框架。它不是某一把武器的成品配置，也不是用来替代原版 XML；它为 XML 作者补充了原版难以直接完成的射击模块、自定义投射物、范围伤害、持续伤害区、智能武器资源系统以及命中事件。

本指南只涵盖 CAF V2.3.0 已公开的 Base（基础框架）能力。文中的配置示例和附件均不需要 CAF Affix（词缀系统）；该组件不包含在 V2.3.0 中。

1. CAF 的四层语法

CAF 项目通常会同时出现四种 XML 或代码层。先分清它们，可以避免大部分接线错误。

层级	中文说明	典型写法	是否需要 CAF DLL
Vanilla XML（原版 XML）	原版物品、Buff、XPath、effect group（效果组）与 trigger（触发器）	<item>、<buff>、<effect_group>	否
CAF MinEventAction（CAF 小型事件动作）	在原版 triggered_effect 中调用 CAF 新动作	action=”AOEDamage, CustomAoeParticleEffect”	是
CAF HUB Template（CAF 中枢模板）	把武器 Action0 交给 HUB，再按弹药选择射击模块与参数模板	ItemActionFireModuleHub、CAF_Templates.xml	是
DLL Extension（DLL 扩展）	新增 C# 类、Harmony 补丁或游戏 API 行为	自定义 DLL 工程	是，且需要 C# 开发

这四层不是互相替代的关系。最常见的项目结构是：

1 用原版 XML 定义物品、弹药、Buff 和触发条件。

2 用 HUB Template（中枢模板）负责武器主射击。

3 用 MinEventAction（小型事件动作）补充一次性爆炸、额外飞行物或持续区域。

4 只有 CAF 现有接口无法表达需求时，才另外编写 DLL。

注意：正确术语是 MinEventAction。旧文档中的 “MiniEvent” 只是历史称呼，不是实际类名或 XML 名称。

2. 安装、依赖与发行边界

2.1 玩家、主机与服务器

凡是使用 CAF DLL-backed（由 DLL 支持）能力的 MOD，运行环境都必须加载与该 MOD 版本匹配的 CAF。联机时不要只给服务器或只给某一位玩家安装；参与运行和显示 CAF 行为的客户端、主机或服务器应使用相同版本的框架与资源文件。

若 XML 中出现以下任一内容，就不能把它当成“纯原版 XML MOD”发布：

• ItemActionFireModuleHub, CustomAoeParticleEffect

• AOEDamage, CustomAoeParticleEffect

• CustomProjectile, CustomAoeParticleEffect

• SpawnZone, CustomAoeParticleEffect

• AddWeaponAmmo, CustomAoeParticleEffect

• VPCriticalChance、VPCriticalDamage

• onCriticalDamageHit、onCAFWeaponHitResolved 等 CAF 自定义 trigger（触发器）

2.2 推荐目录

配置格式 / 计算规则

YourCAFMod/
├─ ModInfo.xml
├─ Config/
│  ├─ items.xml
│  ├─ item_modifiers.xml
│  ├─ buffs.xml
│  ├─ Localization.txt
│  └─ CAF_Templates.xml
└─ Resources/
   └─ your_effects.unity3d

• 只有使用 HUB 武器模板时才需要 Config/CAF_Templates.xml。

• CAF_Templates.xml 必须准确使用这个文件名和位置；CAF 会直接扫描所有已加载 MOD 的该路径。

• 其他 Config 文件仍按《七日杀》原版 XML 与 XPath 规则加载。

• 资源包放在自己的 Resources 目录，路径尽量使用 #@modfolder:，不要写死用户机器上的绝对路径。

2.3 发布时如何声明依赖

你的发行包可以把 CAF 作为前置框架，也可以按 CAF 的授权与发布约定提供对应依赖；无论采用哪种方式，都应在说明中写清：

• 目标游戏版本与 CAF 版本。

• 单机和联机的安装位置。

• 是否需要所有客户端安装资源包。

• 不要同时混装旧版 CAF DLL。

• 按本指南制作的 MOD 只需声明 CAF V2.3.0 Base，不需要额外的词缀组件。

3. 两条主要接入路线

路线 A：HUB Weapon Template（中枢武器模板）

适合接管一把武器的主射击流程。HUB 会根据当前弹药选择模板，然后把本次开火路由到以下四个模块之一：

• CustomRanged（自定义远程模块）

• DynamicRanged（动态射速远程模块）

• Laser（瞬时激光模块）

• ContinuousLaser（持续激光模块）

同一把枪可以让不同弹药走不同模块。新建 CAF 武器时，这是 V2.3.0 推荐的主路线。

路线 B：MinEventAction（小型事件动作）

适合在普通 effect_group（效果组）中追加一次动作，例如：

• 近战命中后产生一次范围伤害。

• Buff 启动时发射额外投射物。

• 命中后留下持续燃烧区。

• 暴击时返还弹药。

• 暴击后让附近敌人丢失目标。

触发条件仍由原版或 CAF trigger（触发器）决定，CAF 只负责执行新增动作。

路线 C：组合使用

HUB 和 MinEventAction 可以同时存在。HUB 负责武器主射击，triggered_effect 负责命中后的 Buff、返弹、状态清理或额外效果。组合时要特别注意：同一效果如果在模块 payload（实际效果载荷）和 triggered effect（触发效果）中各写一次，会执行两次。

4. HUB：从模板发现到模块开火

4.1 CAF_Templates.xml 的正确结构

CAF_Templates.xml 是 CAF 自己读取的专用配置，不是原版 XPath 补丁文件。推荐使用清晰的根节点，并让每个 <template> 成为根节点的直接子节点：

XML 配置示例

<?xml version=”1.0″ encoding=”UTF-8″?>
<caf_templates>
  <template name=”YourMod_CustomBolt”>
    <property name=”CAF_FireModuleType” value=”CustomRanged” />
    <property name=”CR_Proj_Ammo” value=”ammoYourEnergyBolt” />
    <property name=”CR_Count” value=”1″ />
    <property name=”CR_Particle” value=”#@modfolder:Resources/your_effects.unity3d?bolt.prefab” />
    <property name=”CR_Velocity” value=”60″ />
    <property name=”CR_Gravity” value=”0″ />
    <property name=”CR_ProjectileLifetime” value=”4″ />
    <property name=”CR_HitRadius” value=”1.5″ />
    <property name=”CR_Proj_UseWeaponDamage” value=”true” />
    <property name=”CR_Proj_WeaponDamagePercent” value=”1″ />
    <property name=”CR_TargetTags” value=”zombie,animal” />
    <property name=”CR_IgnoreSelf” value=”true” />
  </template>
</caf_templates>

不要在这个文件里写：

XML 配置示例

<append xpath=”/caf_templates”>…</append>

CAF 的模板扫描器只读取根节点下的直接 <template>。把模板包在 <append> 中，扫描器不会找到它。

模板命名建议带 MOD 前缀，例如 YourMod_。如果两个 MOD 注册同名模板，后加载的模板会覆盖先加载的模板，并在日志中给出警告。

4.2 把武器 Action0 接到 HUB

XML 配置示例

<property class=”Action0″>
  <property name=”Class” value=”ItemActionFireModuleHub, CustomAoeParticleEffect” />
  <property name=”CAF_Ammo_ammoYourEnergyBolt_Template” value=”YourMod_CustomBolt” />
  <property name=”CAF_Default_Template” value=”YourMod_CustomBolt” />
  <property name=”Magazine_items” value=”ammoYourEnergyBolt” />
  <!– 其余原版 Action0 属性照常保留 –>
  <property name=”Sound_empty” value=”dryfire” />
  <property name=”AutoReload” value=”false” />
</property>

修改原版物品时，应尽量使用小范围 XPath：

XML 配置示例

<set xpath=”/items/item[@name='gunMGT1AK47']/property[@class='Action0']/property[@name='Class']/@value”>ItemActionFireModuleHub, CustomAoeParticleEffect</set>
<append xpath=”/items/item[@name='gunMGT1AK47']/property[@class='Action0']”>
  <property name=”CAF_Ammo_ammo762mmBulletBall_Template” value=”YourMod_AK_Ball” />
  <property name=”CAF_Default_Template” value=”YourMod_AK_Ball” />
</append>

这里的 <append> 属于普通 items.xml XPath 补丁，因此是正确的；不要把它和上一节的专用 CAF_Templates.xml 混淆。

4.3 Ammo Routing（弹药路由）

弹药映射键必须精确写成：

配置格式 / 计算规则

CAF_Ammo_[ammo item name]_Template

例如弹药 item 的真实名称是 ammo762mmBulletBall：

XML 配置示例

<property name=”CAF_Ammo_ammo762mmBulletBall_Template” value=”YourMod_AK_Ball” />

这里使用的是 items.xml 中的 item name，不是中文显示名、Localization key（本地化键）或弹药组名称。

一把武器可以注册多个弹药模板：

XML 配置示例

<property name=”CAF_Ammo_ammoYourBall_Template” value=”YourMod_Ball” />
<property name=”CAF_Ammo_ammoYourPlasma_Template” value=”YourMod_Laser” />
<property name=”CAF_Ammo_ammoYourBeamCell_Template” value=”YourMod_ContinuousLaser” />

CAF_Default_Template 是没有专属映射时的 fallback（回退模板）。如果不同弹药必须保持完全不同的行为，仍建议给每种弹药显式配置 CAF_Ammo_*_Template。

4.4 Snapshot（武器参数快照）是什么

HUB 不会在每一帧把所有 XML 从头解析一遍。它会把当前武器、所选模板和已安装部件的 CAF 参数合并为一个 Snapshot（武器参数快照），供实际射击模块读取。

对公开 Base 能力，可把合并过程理解为：

1 读取 Action0 中的 CAF 基础值。

2 读取当前弹药选中的 CAF_Templates.xml 模板。

3 读取武器已安装的普通 item modifier（物品部件）中的 CAF 参数。

4 对已经注册的字段建立 Snapshot，并在武器、弹药或部件状态改变后重建。

数值字段在允许动态叠加时使用：

配置格式 / 计算规则

最终值 =（基础值 + 所有 _add 加值）× 所有 _mult 乘值

示例：

XML 配置示例

<!– 模板基础值 –>
<property name=”CR_Velocity” value=”40″ />
<!– item modifier 中的加值与乘值 –>
<property name=”CR_Velocity_add” value=”10″ />
<property name=”CR_Velocity_mult” value=”1.2″ />

结果为 (40 + 10) × 1.2 = 60。

不是所有字段都支持 _add、_mult 或动态 CVar。请以四份模块字段手册中的“可叠加”列为准；字符串、路径、标签和大多数布尔字段通常只做 set（覆盖赋值）。

4.5 Dynamic Value（动态值）与 @CVar

允许动态数值的字段可以写成：

XML 配置示例

<property name=”DR_MaxDelay” value=”@myDynamicDelay” />

运行时会从持有者的 CVar（自定义变量）读取 myDynamicDelay。若 CVar 不存在或该字段并未实现动态读取，则不能假定它会自动工作。

同理，_add 与 _mult 不是任意 XML 属性的通用语法。它们只在 CAF 已注册并允许叠加的 HUB 数值字段，以及智能武器明确支持的数值属性中生效。

5. 四个 HUB 射击模块

CAF_FireModuleType	中文说明	参数前缀	适合场景
CustomRanged	自定义远程	CR_*	固定节奏投射物、制导、穿透、分裂、枪口 AOE、命中 Zone
DynamicRanged	动态射速远程	DR_*	连射升速、停火降速、动态散布、旋转机枪
Laser	瞬时激光	LASER_*	单次射线、穿透、反弹、起点/命中 AOE 与 Zone
ContinuousLaser	持续激光	LASER_* + CONTLASER_*	按住射击持续存在的光束与周期结算

字段总数代表运行时注册字典规模，不代表一个模板必须把所有字段全部写出。正确做法是从最小 payload（实际效果载荷）开始，再逐组添加追踪、分裂、AOE 或 Zone。

详细默认值、字段类型、依赖条件和组合规则请在文末附件区下载：

• CustomRanged 模块 XML 开发指南

• DynamicRanged 模块 XML 开发指南

• Laser 模块 XML 开发指南

• ContinuousLaser 模块 XML 开发指南

5.1 CustomRanged（自定义远程）

CustomRanged 可以在一次开火中组合自定义投射物与枪口范围效果。它适合常速枪械、法术弹、剑气、榴弹、制导弹和多级分裂弹。

最小模板至少应明确：模块类型、可用弹药、一个可见或不可见投射物，以及有效伤害载荷。

XML 配置示例

<template name=”YourMod_CustomRanged”>
  <property name=”CAF_FireModuleType” value=”CustomRanged” />
  <property name=”CR_Proj_Ammo” value=”ammoYourBolt” />
  <property name=”CR_Count” value=”1″ />
  <property name=”CR_Particle” value=”#@modfolder:Resources/your_effects.unity3d?bolt.prefab” />
  <property name=”CR_Velocity” value=”60″ />
  <property name=”CR_Gravity” value=”0″ />
  <property name=”CR_ProjectileLifetime” value=”4″ />
  <property name=”CR_HitRadius” value=”1″ />
  <property name=”CR_Proj_UseWeaponDamage” value=”true” />
  <property name=”CR_Proj_WeaponDamagePercent” value=”1″ />
  <property name=”CR_IgnoreSelf” value=”true” />
</template>

若模板没有有效投射物或 AOE payload，或者弹药筛选不匹配，模块可能回退原版开火。调试时不要一开始同时启用追踪、穿透、分裂与 Zone。

5.2 DynamicRanged（动态射速远程）

DynamicRanged 的投射物体系与 CustomRanged 接近，但增加了 wind-up（连续开火升速）和 wind-down（停火降速）控制。

XML 配置示例

<template name=”YourMod_DynamicRanged”>
  <property name=”CAF_FireModuleType” value=”DynamicRanged” />
  <property name=”DR_MinDelay” value=”0.06″ />
  <property name=”DR_MaxDelay” value=”0.25″ />
  <property name=”DR_WindUpPerShot” value=”0.025″ />
  <property name=”DR_WindDownTime” value=”0.8″ />
  <property name=”DR_SpreadMultiplierMax” value=”2″ />
  <property name=”DR_Count” value=”1″ />
  <property name=”DR_Particle” value=”#@modfolder:Resources/your_effects.unity3d?dynamic_bolt.prefab” />
  <property name=”DR_Velocity” value=”90″ />
  <property name=”DR_Gravity” value=”0″ />
  <property name=”DR_ProjectileLifetime” value=”4″ />
  <property name=”DR_Proj_UseWeaponDamage” value=”true” />
  <property name=”DR_Proj_WeaponDamagePercent” value=”1″ />
  <property name=”DR_IgnoreSelf” value=”true” />
</template>

DR_MinDelay 是升速后的最快开火间隔，DR_MaxDelay 是初始或降速后的较慢间隔。这里的 delay（间隔）越小，射速越快。

5.3 Laser（瞬时激光）

Laser 使用射线即时结算，可以配置穿透、反弹、视觉光束、命中效果，以及起点或命中点的 AOE/Zone。

XML 配置示例

<template name=”YourMod_Laser”>
  <property name=”CAF_FireModuleType” value=”Laser” />
  <property name=”LASER_Ammo” value=”ammoYourPlasma” />
  <property name=”LASER_Delay” value=”0.3″ />
  <property name=”LASER_Range” value=”60″ />
  <property name=”LASER_PierceCount” value=”1″ />
  <property name=”LASER_BounceCount” value=”0″ />
  <property name=”LASER_UseWeaponDamage” value=”true” />
  <property name=”LASER_WeaponDamagePercent” value=”1″ />
  <property name=”LASER_TargetTags” value=”zombie,animal” />
  <property name=”LASER_IgnoreSelf” value=”true” />
  <property name=”LASER_BeamPrefab” value=”#@modfolder:Resources/your_effects.unity3d?beam.prefab” />
  <property name=”LASER_OriginPrefab” value=”#@modfolder:Resources/your_effects.unity3d?beam_origin.prefab” />
  <property name=”LASER_HitPrefab” value=”#@modfolder:Resources/your_effects.unity3d?beam_hit.prefab” />
</template>

视觉 beam（光束）与实际伤害是两回事。没有可见 prefab 时仍可能有逻辑命中；反过来，能看到光束也不代表伤害字段已经正确接通。

5.4 ContinuousLaser（持续激光）

ContinuousLaser 复用 LASER_* 的射线、伤害与资源字段，使用少量 CONTLASER_* 字段控制持续模式。

XML 配置示例

<template name=”YourMod_ContinuousLaser”>
  <property name=”CAF_FireModuleType” value=”ContinuousLaser” />
  <property name=”CONTLASER_Enable” value=”true” />
  <property name=”LASER_Ammo” value=”ammoYourBeamCell” />
  <property name=”LASER_Range” value=”45″ />
  <property name=”LASER_UseWeaponDamage” value=”true” />
  <property name=”LASER_WeaponDamagePercent” value=”0.25″ />
  <property name=”LASER_IgnoreSelf” value=”true” />
  <property name=”LASER_BeamPrefab” value=”#@modfolder:Resources/your_effects.unity3d?continuous_beam.prefab” />
  <property name=”LASER_OriginPrefab” value=”#@modfolder:Resources/your_effects.unity3d?continuous_origin.prefab” />
  <property name=”LASER_HitPrefab” value=”#@modfolder:Resources/your_effects.unity3d?continuous_hit.prefab” />
  <property name=”CONTLASER_OriginFollowMuzzle” value=”true” />
  <property name=”CONTLASER_OriginUseLookDirection” value=”true” />
  <property name=”CONTLASER_StopLoopOnNoAmmo” value=”true” />
</template>

不要把共享字段误写成 CONTLASER_Range 或 CONTLASER_BeamPrefab；这些字段不存在。断弹、切枪或对象销毁时应让循环视觉和音频正常收束，通常保留 CONTLASER_StopLoopOnNoAmmo=”true”。

6. CAF MinEventAction（小型事件动作）

V2.3.0 Base 对 XML 作者需要重点掌握的动作共有五类：

Action（动作）	中文说明	主要用途
AOEDamage	瞬时范围伤害	球形、箱形或锥形范围伤害，可附带短时 Zone
CustomProjectile	自定义投射物	飞行物、追踪、曲线、穿透、分裂、Monster Mode
SpawnZone	生成持续区域	固定或跟随目标的周期伤害/加 Buff 区域
AddWeaponAmmo	向当前武器返还弹药	命中、暴击或爆头后回弹
VPCLoseEnemyTargets	让敌人丢失目标	清除攻击/复仇/调查状态并临时降低侦测

这些动作可以放在 items.xml、item_modifiers.xml、buffs.xml 或 progression（进度系统）的 effect_group 中，但必须由一个有效 trigger（触发器）调用。

MinEventAction 的动态值支持是逐字段开放的，不是所有属性都能写 @CVar。只有本指南或对应字段字典明确标注支持动态取值的字段才能使用这种形式；其余字段应填写普通数值、向量或布尔字面量。布尔值统一推荐使用 true/false，以保持配置清晰并避免不同动作之间的解析差异。

6.1 AOEDamage（瞬时范围伤害）

XML 配置示例

<triggered_effect
    trigger=”onSelfPrimaryActionEnd”
    action=”AOEDamage, CustomAoeParticleEffect”
    shape=”cone”
    radius=”4″
    cone_angle=”110″
    offset=”0,1,0.5″
    damage=”25″
    damage_type=”Bashing”
    force=”8″
    target_tags=”zombie,animal”
    ignore_self=”true”
    hit_blocks=”false”
    particle=”#@modfolder:Resources/your_effects.unity3d?shockwave.prefab”
    particle_lifetime=”1″ />

常用参数：

参数	中文说明
shape=”sphere”	球形范围
shape=”box” + box_size=”x,y,z”	箱形范围
shape=”cone” + cone_angle=”90″	锥形范围
damage / damage_mult	基础伤害 / 额外伤害倍率
use_weapon_damage / weapon_damage_percent	是否叠加武器面板伤害 / 占比
target_tags / ignore_tags	必须命中的标签 / 排除标签
zone_lifetime	大于 0 时在本次范围效果后生成持续 Zone（区域）

hit_blocks 表示是否允许以方块命中上下文继续执行，不等于对方块或地形造成破坏。CAF 自定义 AOE 的伤害目标是实体；不要把它当作爆破地形接口。

当前直接 AOE 路径中，target_tags 与 ignore_tags 的判定不是简单的“先包含、再排除”：当 target_tags 非空时应以它作为主要白名单，不要再依赖 ignore_tags 做第二层排除。需要复杂阵营筛选时，优先把允许目标写得更明确并实际测试。

6.2 CustomProjectile（自定义投射物）

XML 配置示例

<triggered_effect
    trigger=”onSelfSecondaryActionStart”
    action=”CustomProjectile, CustomAoeParticleEffect”
    count=”1″
    direction_mode=”look”
    use_muzzle=”true”
    particle=”#@modfolder:Resources/your_effects.unity3d?projectile.prefab”
    velocity=”25″
    gravity=”0″
    projectile_lifetime=”5″
    homing_radius=”8″
    homing_speed=”120″
    hit_radius=”2″
    hit_damage=”30″
    hit_force=”10″
    hit_particle=”#@modfolder:Resources/your_effects.unity3d?impact.prefab”
    target_tags=”zombie,animal”
    ignore_self=”true”
    hit_blocks=”true” />

它可以组合以下能力：

• emission（发射）：数量、水平散布、垂直角度、枪口或事件位置。

• movement（运动）：速度、重力、自旋、随时间缩放。

• curve（曲线转向）：延迟后向目标点转向。

• homing（制导）：在半径内追踪或重新选取目标。

• hitbox（自定义命中盒）：球形或其他运行时支持的体积、扫掠检测、多目标冷却。

• pierce（穿透）：命中后继续飞行。

• chain / split（链式 / 分裂）：穿透或命中后生成子投射物。

• on-hit Zone（命中持续区）：在撞击位置生成持续伤害区域。

如果启用：

XML 配置示例

use_weapon_damage=”true”
weapon_damage_percent=”1″

则会把武器面板伤害加入 hit_damage。不要同时保留过高的固定伤害，除非确实希望两者叠加。

#### Monster Mode（怪物发射模式）

Monster Mode 是 CustomProjectile 内的一套完整发射与选敌模式，不能只理解成“自动找最近玩家”。它让非玩家实体从自身世界坐标发射投射物，并使用怪物目标上下文决定方向。

最小示例：

XML 配置示例

<triggered_effect
    trigger=”onSelfBuffStart”
    action=”CustomProjectile, CustomAoeParticleEffect”
    monster_mode=”true”
    direction_mode=”closest_player”
    monster_prefer_other=”true”
    monster_target_players_only=”true”
    monster_scan_radius=”30″
    monster_scan_angle=”180″
    monster_aim_height=”1.5″
    monster_require_los=”true”
    particle=”#@modfolder:Resources/your_effects.unity3d?monster_bolt.prefab”
    velocity=”18″
    gravity=”0″
    projectile_lifetime=”6″
    hit_radius=”1″
    hit_damage=”20″
    ignore_self=”true” />

核心字段：

字段	中文说明	默认/边界
monster_mode	开启怪物发射模式	false
direction_mode	发射方向模式	Monster Mode 省略时默认 closest_player
monster_prefer_other	优先使用事件参数中的 Other（另一实体）	true
monster_target_players_only	Monster 候选是否限制为玩家	true
monster_scan_radius	搜索半径	30，支持 @CVar
monster_scan_angle	最终最近玩家扫描角度	360
monster_aim_height	无明确瞄准点时的目标高度偏移	1.5
monster_require_los	是否要求 LOS（视线可达）	false
target_tags	候选必须匹配的标签	可选
ignore_tags	必须排除的标签	可选

direction_mode=”closest_player” 时，在 monster_prefer_other=”true” 的常见配置下，选取优先级是：

1 当前 MinEvent 参数中的 Other。

2 怪物 AI 当前的 attack target（攻击目标）。

3 在 monster_scan_radius 与 monster_scan_angle 内扫描最近玩家。

direction_mode=”attacker” 主要使用 Other，随后回退到当前 AI 攻击目标。look 和 forward 仍可用于按实体朝向发射。

几个容易误解的边界：

• monster_scan_angle 约束的是最后一步“最近玩家扫描”，不会重新否决已经采用的 Other 或当前 AI 攻击目标。

• monster_target_players_only=”false” 允许 Other 或 AI 攻击目标为非玩家实体；最后的 nearest-player（最近玩家）扫描仍然只遍历玩家。

• target_tags、ignore_tags、半径与可选 LOS 会参与候选验证。

• Monster Mode 使用发射实体的世界位置作为起点，不读取玩家眼睛、LookRay（视线射线）或枪口模型。use_muzzle 是普通玩家模式的功能。

• 在非 Monster Mode 中写 closest_player 或 attacker 不会获得怪物选敌行为，运行时会回退到普通方向逻辑。

6.3 SpawnZone（生成持续区域）

XML 配置示例

<triggered_effect
    trigger=”onSelfPrimaryActionEnd”
    action=”SpawnZone, CustomAoeParticleEffect”
    offset=”0,0,1.5″
    radius=”3″
    zone_lifetime=”6″
    zone_damage=”10″
    zone_force=”1″
    zone_tick_rate=”1″
    zone_id=”YourMod_FireZone”
    zone_can_overlap=”false”
    zone_is_ground=”true”
    zone_buff=”buffBurningMolotov”
    particle=”#@modfolder:Resources/your_effects.unity3d?fire_zone.prefab”
    target_tags=”zombie,animal”
    ignore_self=”true” />

重要字段：

• zone_lifetime（区域寿命）必须大于 0，否则不创建。

• zone_tick_rate（结算间隔）越小，结算越频繁。

• zone_id（区域标识）与 zone_can_overlap（是否允许重叠）共同控制同类 Zone 的重复结算。

• zone_box_size 非零时使用 box（箱形）检测，否则使用 radius 的 sphere（球形）检测。

• track_target=”self” 或 track_target=”other” 可让区域跟随实体。

• 跟随目标时使用 offset；旧片段中的 track_offset 当前不会被解析。

• drop_on_death=”true” 表示跟随目标死亡后把 Zone 留在最后位置；false 表示销毁。

大量实体同时创建短 tick（高频结算）Zone 是最容易造成性能问题的配置之一。

6.4 AddWeaponAmmo（武器返弹）

XML 配置示例

<triggered_effect
    trigger=”onCriticalDamageHit”
    action=”AddWeaponAmmo, CustomAoeParticleEffect”
    count=”1″
    require_headshot=”true” />

count 可以写整数，也可以写 @CVar：

XML 配置示例

<triggered_effect
    trigger=”onCriticalDamageHit”
    action=”AddWeaponAmmo, CustomAoeParticleEffect”
    count=”@myAmmoRefundCount” />

兼容旧 VPC XML 时，也可以使用：

XML 配置示例

<triggered_effect trigger=”onCriticalDamageHit” action=”VPCAddWeaponAmmo” count=”1″ />

兼容名包括 VPCAddWeaponAmmo 与 MinEventActionVPCAddWeaponAmmo，它们最终映射到 CAF 的返弹实现。headshot_only、only_headshot 是 require_headshot 的兼容别名；headshot_compat 控制宽松的头部/弱点识别，默认 true。

不要在同一个 effect_group 里同时写 AddWeaponAmmo 和 VPCAddWeaponAmmo 来表示“兼容”。两条动作会各执行一次，导致双倍返弹。

该动作修改的是当前 ItemValue.Meta 对应的原版物理弹匣，并按 MagazineSize 限制上限。它不会自动补充 Smart Weapon（智能武器）的虚拟弹匣或储备能源池；智能武器补能应使用自身充能流程或 ItemActionChargeHeldWeapon。

6.5 VPCLoseEnemyTargets（敌人丢失目标）

XML 配置示例

<triggered_effect
    trigger=”onCriticalDamageHit”
    action=”VPCLoseEnemyTargets”
    range=”24″
    duration=”3″
    detect_scale=”0.35″
    only_targeting_self=”true” />

常用字段：

字段	中文说明	默认值
range	搜索半径	30
duration	玩家侦测压制持续时间	0
detect_scale	临时侦测倍率，限制在 0～1	1
all / all_enemies	是否扫描全部敌人	false
enemies_only	是否只处理 EntityEnemy	true
clear_investigate	清除调查位置	true
clear_alert	清除警戒 ticks	true
clear_revenge	清除复仇目标	true
only_targeting_self	只清理当前正在锁定自己的敌人	false

动作会对符合条件的实体清除 attack target（攻击目标），并按字段决定是否清除复仇、调查与警戒状态。只有执行者是玩家，且 duration > 0、detect_scale < 1 时，才会额外应用临时侦测缩放。

all_enemies=”true” 或 range <= 0 时会改为扫描世界实体列表。范围扫描已经足够时不要无理由启用全世界扫描。

7. Smart Weapon（智能武器系统）

智能武器不是单独的第五种射击模块。它是一层可叠加到 CustomRanged、DynamicRanged、Laser 和 ContinuousLaser 上的武器资源、充能、锁定与 HUD 系统。

7.1 如何启用智能武器

CAF 以 CAF_SW_VirtualMagCVar（虚拟弹匣变量名）是否存在来判断一把武器是否启用智能武器。

最小物品属性：

XML 配置示例

<property name=”CAF_SW_VirtualMagCVar” value=”YourMod_Rifle_Mag” />
<property name=”CAF_SW_VirtualMagMax” value=”40″ />
<property name=”CAF_SW_EnergyPoolCVar” value=”YourMod_Rifle_Energy” />
<property name=”CAF_SW_EnergyPoolMax” value=”500″ />
<property name=”CAF_SW_ChargeTimeFull” value=”3″ />
<property name=”CAF_SW_ChargeDelay” value=”1″ />
<property name=”CAF_SW_ChargeUsesAmmo” value=”true” />
<property name=”CAF_SW_HideVanillaAmmo” value=”true” />

这些属性写在武器 item 上；HUB 模板继续负责 CR_*、DR_*、LASER_* 或 CONTLASER_* 的实际射击方式。

7.2 Virtual Magazine（虚拟弹匣）与独立实例

CAF_SW_VirtualMagMax 定义虚拟弹匣容量。CAF 不直接让所有同名武器共享一个 CVar，而是给具体 ItemValue 写入 CAF_SW_InstanceId（智能武器实例标识），再把基础 CVar 名扩展为实例专属名称。

因此，两把同名智能武器可以分别保存自己的虚拟弹匣和能源池状态。不要在 XML 或脚本里手工写死、复制或清理 CAF_SW_InstanceId；它属于框架维护的物品元数据。

7.3 Energy Pool（储备能源池）与自动充能

CAF_SW_EnergyPoolCVar 与 CAF_SW_EnergyPoolMax 定义储备能源。玩家停止射击并经过 CAF_SW_ChargeDelay 后，虚拟弹匣开始恢复；从空弹匣充满所需时间由 CAF_SW_ChargeTimeFull 控制。

当前充能逻辑按“1 点能源恢复 1 发虚拟弹药”扣除储备能源。CAF_SW_ChargeUsesAmmo=”false” 时可以不消耗能源池；true 时能源不足会停止恢复。

CAF_SW_ChargeAudio 可指定充能循环音效资源：

XML 配置示例

<property name=”CAF_SW_ChargeAudio” value=”#@modfolder:Resources/your_effects.unity3d?charge_audio.prefab” />

7.4 Energy Canister（能量罐）

CAF 提供 ItemActionChargeHeldWeapon（为当前手持武器补充能源的物品动作）。示例：

XML 配置示例

<item name=”itemYourEnergyCanister”>
  <property name=”Extends” value=”drinkJarBoiledWater” />
  <property class=”Action0″>
    <property name=”Class” value=”ItemActionChargeHeldWeapon, CustomAoeParticleEffect” />
    <property name=”CAF_EnergyAmount” value=”500″ />
  </property>
</item>

CAF_EnergyAmount 默认是 500。使用时玩家必须手持配置了 CAF_SW_EnergyPoolCVar 的智能武器；补充量不会超过该武器的 CAF_SW_EnergyPoolMax。

上例的 Extends 只是演示物品骨架，正式 MOD 应根据消耗、动画、图标和配方需求选择合适的原版父项。

7.5 Target Lock（目标锁定）

XML 配置示例

<property name=”CAF_SW_LockEnabled” value=”true” />
<property name=”CAF_SW_LockRingRadius” value=”180″ />
<property name=”CAF_SW_LockAimPart” value=”head” />

• CAF_SW_LockEnabled：是否启用智能锁定。

• CAF_SW_LockRingRadius：屏幕锁定环半径。

• CAF_SW_LockAimPart：锁定瞄准部位，例如 head 或 body。

模块中支持 locked target（锁定目标）或 curve/homing（曲线/制导）目标的字段，可以读取智能武器已经锁定的敌人。目标锁定不是无条件命中；射程、角度、目标标签、视线和各模块自己的筛选仍需按模块字段配置。

7.6 HUD（抬头显示）与标签

常用 UI 开关：

XML 配置示例

<property name=”CAF_SW_UIShowScope” value=”true” />
<property name=”CAF_SW_UIShowAmmoBlocks” value=”true” />
<property name=”CAF_SW_UIShowEnergyBar” value=”true” />
<property name=”CAF_SW_UIShowAmmoText” value=”true” />
<property name=”CAF_SW_UIShowEnergyText” value=”true” />
<property name=”CAF_SW_UIShowLockLabel” value=”true” />

还可以使用 CAF_SW_UIEnergyBarPos 调整能量条位置，并用 CAF_SW_UIColor* 属性设置弹匣、能量、准心、标记与文字颜色。颜色格式为 R,G,B,A，范围 0～255。

两个常用 item tag（物品标签）：

• nocrosshair：隐藏原版准心。

• cyber_scope：允许 CAF 的自定义智能准心界面工作。

例如：

XML 配置示例

<property name=”Tags” value=”weapon,ranged,gun,nocrosshair,cyber_scope” />

如果只写 UI 开关却没有正确的 HUD/XUi 接入、物品标签或智能武器属性，界面可能不显示；如果伤害正常但 HUD 不正常，应把它们作为两条独立链路排查。

7.7 Run and Shoot（跑射）

XML 配置示例

<property name=”CAF_SW_RunAndShoot” value=”true” />
<property name=”CAF_SW_RunWhileAiming” value=”true” />
<property name=”CAF_SW_NoAimMovePenalty” value=”true” />

• CAF_SW_RunAndShoot 是综合开关：允许瞄准时保持奔跑，并取消瞄准移动惩罚。

• CAF_SW_RunWhileAiming 只负责瞄准时保持奔跑。

• CAF_SW_NoAimMovePenalty 只负责取消瞄准移动惩罚。

• CAF_SW_DebugRunAndShoot 可打开相关调试日志，发布版通常保持关闭。

7.8 智能武器的动态数值与部件修正

以下数值类属性支持静态数字、@CVar 与 item modifier 的 _add / _mult：

• CAF_SW_VirtualMagMax

• CAF_SW_EnergyPoolMax

• CAF_SW_ChargeTimeFull

• CAF_SW_ChargeDelay

• CAF_SW_LockRingRadius

示例部件：

XML 配置示例

<property name=”CAF_SW_VirtualMagMax_add” value=”20″ />
<property name=”CAF_SW_ChargeTimeFull_mult” value=”0.8″ />
<property name=”CAF_SW_LockRingRadius_add” value=”30″ />

同样按 (基础值 + add) × mult 合并。字符串覆盖，例如 CAF_SW_LockAimPart，不使用 _add 或 _mult。

8. Critical Passive（暴击被动）与 CAF 自定义 Trigger（触发器）

CAF V2.3.0 Base 接管并兼容以下 VPC 风格的 XML 能力。它们不是原版 MinEventTypes 或原版 passive effect（被动效果），没有 CAF DLL 时原版解析器不认识这些名称。

8.1 VPCriticalChance（额外暴击率）

XML 配置示例

<passive_effect name=”VPCriticalChance” operation=”base_add” value=”0.05″ />

0.05 表示增加 5% 暴击率。它可用于 item、item modifier、progression 或 buff 的 effect_group，并遵守原版 passive effect 的 operation（运算）、标签和 requirement（条件）规则。

这组 VPC passive 与后续命中 trigger 主要服务于原版 ItemActionAttack.Hit 暴击桥接路径。AOEDamage、CustomProjectile 与 SpawnZone 有各自的 critical_chance、critical_damage 字段；不要假定 VPC passive 会自动改写所有自定义 AOE、投射物或 Zone tick。

合成概念为：

配置格式 / 计算规则

最终暴击率 = Clamp01（CAF 暴击率 + Vanilla 暴击率 + VPCriticalChance）

8.2 VPCriticalDamage（额外暴击伤害）

XML 配置示例

<passive_effect name=”VPCriticalDamage” operation=”base_add” value=”0.25″ />

它不是直接替换最终倍率。VPC passive 先按自己的默认倍率基线结算，再把相对默认 1.5 的增量加入 CAF/Vanilla Snapshot（武器快照）的暴击倍率。不要把它和 HUB 字段的 _mult 当作同一层运算。

8.3 命中分支触发器

XML 配置示例

<triggered_effect
    trigger=”onCriticalDamageHit”
    action=”AddBuff”
    target=”self”
    buff=”buffYourCriticalProc” />
<triggered_effect
    trigger=”onNonCriticalDamageHit”
    action=”ModifyCVar”
    cvar=”yourNonCritCounter”
    operation=”add”
    value=”1″ />

• onCriticalDamageHit（暴击伤害命中）：实体命中、最终判定为暴击，并且实际造成生命伤害后触发。

• onNonCriticalDamageHit（非暴击伤害命中）：同一路径实际造成伤害，但本次不是暴击。

8.4 onCAFWeaponHitResolved（CAF 武器命中结算完成）

XML 配置示例

<triggered_effect
    trigger=”onCAFWeaponHitResolved”
    action=”RemoveBuff”
    target=”self”
    buff=”buffYourReadyState” />

这个触发器适合在当前武器伤害已经结算后消费 ready（准备）、focus（专注）或 scope（瞄准）状态，避免在 RayHit（射线命中）阶段过早移除本次伤害需要的 passive。

边界必须明确：

• 它来自 CAF 对 ItemActionAttack.Hit 的命中后处理。

• 只有实际生命差值大于 0 时触发。

• 暴击与非暴击都会触发。

• 它不是所有 DamageEntity 的全局后置事件。

• 手榴弹、陷阱、燃烧瓶、DoT（持续伤害）和 AOE 后续 tick 不应假定会触发它。

8.5 命中后 CVar

CAF 会写入 cafLast… 与兼容的 vpcLast… CVar。新 XML 推荐使用 CAF 前缀：

配置格式 / 计算规则

cafLastHitWasCritical
cafLastHitDamage
cafLastHitChance
cafLastHitMultiplier
cafLastHitTarget
cafLastHitWeakpoint
cafLastCriticalDamage
cafLastCriticalChance
cafLastCriticalMultiplier
cafLastCriticalTarget
cafLastCriticalWeakpoint
cafLastNonCriticalDamage
cafLastNonCriticalChance
cafLastNonCriticalTarget
cafLastNonCriticalWeakpoint

例如仅在暴击弱点命中时加计数：

XML 配置示例

<triggered_effect
    trigger=”onCriticalDamageHit”
    action=”ModifyCVar”
    cvar=”yourCritWeakpointCount”
    operation=”add”
    value=”1″>
  <requirement name=”CVarCompare” cvar=”cafLastCriticalWeakpoint” operation=”GT” value=”0″ />
</triggered_effect>

8.6 Movement Trigger（移动触发器）

累计移动距离：

XML 配置示例

<triggered_effect
    trigger=”onVPCMoveDistance”
    action=”AddBuff”
    target=”self”
    buff=”buffYourMovedState”
    value=”12″
    reset=”true”
    movement_tags=”walking,running” />

• value：累计距离阈值，必须大于 0。

• reset：触发后是否扣除阈值并继续累计，默认 true；false 表示只触发一次并锁定。

• movement_tags 或 mode：可选移动标签过滤。

静止计时：

XML 配置示例

<triggered_effect
    trigger=”onVPCStill”
    action=”AddBuff”
    target=”self”
    buff=”buffYourStillState”
    value=”2.5″
    tolerance=”0.05″
    reset_on_move=”true” />

• value：静止秒数，默认 1。

• tolerance：移动容差，默认 0.05。

• reset_on_move：移动后是否重置，默认 true。

当前移动触发器写入的是 VPC 兼容 CVar，例如 vpcMoveDistanceDelta、vpcMoveDistanceAccum、vpcStillSeconds 和 vpcMovementRunning。V2.3.0 文档未列出对应的 cafMove… 名称，请不要在 XML 中使用这类推测名称。

9. 资源路径与 Prefab Preload（预制体预加载）

推荐资源路径：

配置格式 / 计算规则

#@modfolder:Resources/your_effects.unity3d?projectile.prefab

含义：

• #@modfolder:：模板来源 MOD 的目录。

• Resources/your_effects.unity3d：AssetBundle（资源包）。

• ?projectile.prefab：包内 prefab（预制体）名称。

跨 MOD 引用可以写：

配置格式 / 计算规则

#@modfolder(OtherModFolderName):Resources/shared_fx.unity3d?shared.prefab

HUB 读取模板时会规范化受支持的资源短路径，并把注册为 Path（路径）类型的 prefab 字段交给预加载器。这样可以降低第一次开火时才同步加载资源造成的卡顿，但并不意味着任何字符串字段都会自动预加载。

排查资源问题时依次确认：

1 .unity3d 文件真实存在。

2 Bundle 名与 prefab 名大小写、后缀一致。

3 路径使用 /。

4 当前客户端也安装了资源包。

5 日志中模板来源 MOD 与补全后的路径正确。

6 逻辑伤害是否存在，以区分“资源加载失败”和“模块没有执行”。

10. 伤害、网络与性能边界

10.1 伤害与视觉分离

CAF 中的粒子、光束、命中特效属于 visual（视觉）；damage、buff、force 和 target filter 属于 gameplay（玩法逻辑）。调试时先确认逻辑，再确认视觉，不要只凭“看见粒子”判断伤害已经正确。

10.2 服务器权威

涉及伤害、目标选择与持续区域时，应在单机、主机和专服分别测试。CustomProjectile 的 server_only=”true” 可以把投射物逻辑限制在服务器侧，通常更利于权威伤害，但也可能让客户端缺少本地飞行视觉。是否使用它取决于该 MOD 的视觉同步方案，不应机械地全部开启。

10.3 高频配置的成本

重点控制以下乘法组合：

配置格式 / 计算规则

每秒开火次数 × 每发投射物数 × 分裂子弹数 × 穿透/多目标次数 × Zone tick 次数

建议：

• 先单发、单投射物、无分裂、无 Zone 测通。

• zone_tick_rate 不要无理由设得极低。

• homing（制导）半径、怪物扫描半径和自定义 hitbox 扫描频率只设到玩法需要的程度。

• 持续激光同时存在多段 AOE/Zone 时，分别计算每秒结算量。

• 调试日志只在定位问题时开启，发布版关闭高频日志。

10.4 地形边界

CAF 的自定义 AOE 与 Zone 面向实体伤害。hit_blocks、ignore_block 或 event_on_block 控制的是方块碰撞、事件上下文或投射物是否继续，不代表 CAF 会对地形施加方块伤害。需要破坏地形时，应使用经过验证的原版方块伤害机制或另外实现对应 DLL 行为。

11. 从旧版或旧文档迁移

11.1 从直连模块迁移到 HUB

旧项目可能直接把 Action0 写成 ItemActionCustomRanged、ItemActionDynamicRanged 或 ItemActionLaser。V2.3.0 新项目建议：

1 把 Action0/Class 改为 ItemActionFireModuleHub, CustomAoeParticleEffect。

2 新建 Config/CAF_Templates.xml。

3 把模块参数移动到根节点下的 <template>。

4 在 Action0 添加 CAF_Ammo_[ammoName]_Template。

5 在模板中写 CAF_FireModuleType。

6 验证换弹后是否路由到正确模板与模块。

11.2 清理历史术语与写法

• 旧说明或配置注释中的 “MiniEvent” 应改为准确名称 MinEventAction（小型事件动作）。

• SpawnZone 新 XML 优先使用 action=”SpawnZone, CustomAoeParticleEffect”。

• 跟随 Zone 使用 offset，不要继续使用未解析的 track_offset。

• 新模板使用 CAF_FireModuleType，不要同时重复写兼容键 CAF_ModuleType。

• 不要把 <append xpath=”/caf_templates”> 放进 CAF_Templates.xml。

11.3 VPC 兼容迁移

CAF 可以接管 VPCriticalChance、VPCriticalDamage、VPC 暴击触发器、移动触发器、VPCAddWeaponAmmo 与 VPCLoseEnemyTargets。迁移时保留一套执行者即可；不要同时强制旧 VPC DLL 与 CAF 重复接管同一命中路径。

12. 常见错误与定位顺序

模板完全没有加载

检查：

• 文件是否准确位于 Config/CAF_Templates.xml。

• <template> 是否是根节点直接子节点。

• 模板是否有 name。

• XML 是否可解析。

• 日志中是否出现 [CAF Hub] 的扫描与模板数量。

开枪没有 CAF 效果

检查：

• Action0/Class 是否为 ItemActionFireModuleHub, CustomAoeParticleEffect。

• 当前弹药 item name 是否与 CAF_Ammo_*_Template 完全一致。

• Magazine_items 是否包含当前弹药。

• 模板名是否拼写一致。

• CAF_FireModuleType 是否为四个完整模块名之一。

• 模板是否存在最小有效 payload。

能开枪，但总是使用错误模块

检查当前弹药的真实 item name、专属映射和 CAF_Default_Template。默认模板可能掩盖某个专属映射的拼写错误。

有伤害但没有特效

优先检查资源路径、Bundle/prefab 名、客户端资源是否安装，以及预加载日志。不要先改伤害字段。

有特效但没有伤害

检查 hit_damage、zone_damage、use_weapon_damage、weapon damage percent（武器伤害占比）、目标标签和 ignore_self。Laser 还应确认实际射线是否命中实体。

Monster Mode 只朝前发射

检查 monster_mode=”true” 是否确实存在，direction_mode 是否为 closest_player 或 attacker，触发时是否有有效 Self，以及候选是否被 radius、tags、LOS 或存活检查排除。

智能武器 HUD 显示但不能射击

分别检查 CAF_SW_VirtualMagCVar、虚拟弹匣当前值、能源池、充能延迟、模块弹药消耗倍率与物理弹药清理。HUD 正常不等于模块 payload 或弹药路由正常。

返弹执行两次

搜索同一效果组中是否同时存在 AddWeaponAmmo 与 VPCAddWeaponAmmo，或者同一命中是否被两个 trigger 调用。

暴击触发器完全不解析

确认 CAF DLL 已加载。onCriticalDamageHit、onCAFWeaponHitResolved、VPCriticalChance 都不是原版 XML 名称。

持续效果造成卡顿

逐步关闭分裂、制导、自定义 hitbox、短 tick Zone、持续激光附加 AOE。一次只恢复一组功能，以确定真正的乘法来源。

13. 开发与发布检查清单

XML 与接线

□ ModInfo.xml、普通 Config XML 与 CAF_Templates.xml 均可解析。

□ CAF_Templates.xml 中的 <template> 是根节点直接子节点。

□ 所有模板名带 MOD 前缀且无意外重名。

□ 每个弹药 item name 与 CAF_Ammo_*_Template 一一对应。

□ 四个模块只使用各自真实存在的字段前缀。

□ 动态 @CVar、_add、_mult 只用于明确支持的字段。

□ 每个 MinEventAction 都有一个有效 trigger 和最小 payload。

单机与联机

□ 单机首次开火、换弹、切枪、死亡重生后正常。

□ 主机与客户端看到一致的投射物、光束和命中结果。

□ 专服伤害由正确一侧执行，没有重复结算。

□ 玩家离线重连后，智能武器实例状态符合设计。

□ 两把同名智能武器的虚拟弹匣和能源池不会互相串值。

性能

□ 高射速、最大分裂和最大实体密度场景经过测试。

□ Zone 数量与 tick rate 有明确上限。

□ Monster Mode 的扫描半径、角度与 LOS 成本合理。

发行包

□ 发布说明已写明目标游戏版本与 CAF V2.3.0 依赖。

□ 客户端所需的 AssetBundle 已包含，并注明正确安装位置。

□ 发行包只包含运行所需文件，不含旧版 DLL、测试存档、配置转储或本机绝对路径。

□ 已在不存在旧版 CAF 的干净 Mods 目录中验证安装与升级流程。

□ 联机项目已确认房主与客户端使用相同的 CAF、XML 配置和资源版本。

14. 推荐的学习顺序

第一次使用 CAF 时，按以下顺序最容易定位问题：

1 用 AOEDamage 做一个无粒子的固定范围伤害，确认 DLL 与 MinEvent 接线。

2 用 CustomProjectile 做一个无重力、无制导、单发投射物。

3 加入资源路径和命中特效。

4 把一把武器接到 HUB，只使用一个 CustomRanged 模板。

5 添加第二种弹药，验证 Ammo Routing（弹药路由）。

6 再学习 DynamicRanged、Laser 与 ContinuousLaser。

7 最后加入智能武器、暴击分支、Monster Mode、分裂与持续区域。

把复杂配置拆成可验证的小步骤，比一次复制整套大型示例更可靠。CAF 提供的是组合能力；最终效果是否稳定，仍取决于 XML 作者是否明确处理触发时机、目标过滤、伤害来源、资源路径、联机执行侧与性能预算。

15. 版本说明

本指南只描述 CAF V2.3.0 已公开的 Base 能力。

• CAF Affix（词缀系统）不包含在 CAF V2.3.0 Base 中，本指南及附件不介绍其字段或界面。

• 只使用本指南所列 XML 能力的 MOD，不需要安装 Affix 文件、词缀配置或相关 UI。

附件下载：四套模块字段字典

完整字段字典不在正文中重复展开。

请在本帖附件区下载以下四份文件。正文负责接入流程、最小示例和运行边界；附件提供各模块的字段说明、默认值、推荐起始值、动态叠加能力与组合规则。

CAF_V2.3.0参数字典.zip

2.14 MB,下载次数：3[记录]

附件文件名	内容
CAF_V2.3.0_CustomRanged_Module_XML_Guide_20260719.pdf	CustomRanged（自定义远程）模块字段字典与配置说明。
CAF_V2.3.0_DynamicRanged_Module_XML_Guide_20260719.pdf	DynamicRanged（动态射速远程）模块字段字典与配置说明。
CAF_V2.3.0_Laser_Module_XML_Guide_20260719.pdf	Laser（瞬时激光）模块字段字典与配置说明。
CAF_V2.3.0_ContinuousLaser_Module_XML_Guide_20260719.pdf	ContinuousLaser（持续激光）模块字段字典与配置说明。

附件对应 CAF V2.3.0 Base（基础框架）；按本文配置不需要安装其他 CAF 组件。

Custom Action Framework V2.3.0 XML 开发指南 · Base 公开能力

前置框架

开发文档

指南

1、本站所有内容由用户发表，作者与本站享有帖子版权；

2、转载或者引用本文内容请注明来源及原作者；

3、如内容侵犯到任何版权，请联系本站将及时予与删除；

4、遇到MOD提取码错误或链接失效，请检查提取码是否复制了空格，链接失效可以私信作者或站长进行补偿；

5、如遇到其他问题无法解决可以私信站长进行处理；

6、游戏MOD属于虚拟数字商品，一经购买即获得了内容，原则上不允许申请退款，购买即默认同意上述规则；

"点赞是美意，打赏是鼓励"

共1人打赏

置顶

更新日志楼

好想摸鱼啊...

Nanamі：已重新排版V2.0.0版本的CAF框架开发指南

拉黑 2个月前电脑端回复

Nanamі： V2.0.0版本目前仍然在整理XML部署方案和字典，目前参数过多(至少355个参数）仍在整理中，并且由于参数过多，以后的参数都将以PDF形式发布，不占用版面资源。

Nanamі：以补充V1.2.0版本的新增和修改的参数

展开更多回复（共4条）

0203

Lv.8

赠送了礼物[火箭]

万般皆是利

Nanamі： @露露天都建议右键这个网页另存为，或打印-保存成PDF，因为我大部分更新内容和演示示例都会在这个网页文章里，但如果你下载了框架，解压应该能看到一个HandBook.txt文件，你也可以看那个，那个是我之前写代码时留的备注，但里面的代码并不全面，有些新加的我就没写，另外就是我大概今天或明天机会更新武器系统的迭代，把上面的飞行物和爆炸Action彻底融入武器里，就不需要trigger effect来模拟子弹了。建议可以先研究其他类技能的释放，熟悉一下。

拉黑 3个月前电脑端回复