【AI编码】自动生成规则说明

ProjectNLD/AI_Gen_Doc/canAttackNoReloadFull功能说明.md

@@ -0,0 +1,150 @@
+# canAttackNoReloadFull 功能说明
+
+> 本文档由 AI 生成，用于说明武器换弹中断攻击功能的设计与配置。
+
+## 功能定义
+
+`canAttackNoReloadFull` 控制**角色在换弹过程中，弹药未装满时是否可以中断换弹直接开枪**。
+
+**⚠️ 重要：这个功能只对角色（Character）有效，载具和建筑不使用此属性。**
+
+---
+
+## 使用场景
+
+这个属性用于**分段换弹武器**（如霰弹枪），这类武器通过 `perReloadCount` 逐发装填弹药。
+
+### 典型流程
+
+1. 角色弹药耗尽，进入换弹状态
+2. 每隔 `reloadTime` 时间装填 `perReloadCount` 发子弹
+3. 如果 `canAttackNoReloadFull = true`：装了部分弹药后，发现敌人可以立即中断换弹开枪
+4. 如果 `canAttackNoReloadFull = false`：必须等弹药完全装满才能开枪
+
+---
+
+## 代码实现位置
+
+只在角色的换弹状态机中使用：
+
+**文件**：`Assets/Code/Scripts/GamePlay/Character/State/UpState/UpStateReload.cs`
+
+```csharp
+// 第 98-107 行
+if (isNotFull)
+{
+    var canContinueAttack = _CheckCanContinueAttack();
+    if (canContinueAttack && owner.fightData.mainWeaponData.canAttackNoReloadFull)
+    {
+        // 直接开枪
+        nextState = EUpState.RaiseWeapon;
+    }
+    else
+    {
+        // 继续换弹
+        nextState = EUpState.Reload;
+    }
+}
+```
+
+---
+
+## 载具和建筑为什么不需要这个属性
+
+### 载具换弹逻辑
+
+**文件**：`Assets/Code/Scripts/GamePlay/Vehicle/Battery/BatteryStateReload.cs`
+
+```csharp
+// 第 53 行
+owner.bindWeaponData.SetBulletCount(owner.bindWeaponData.maxBulletCount);
+```
+
+- 载具炮台**一次性装满所有弹药**
+- 没有分段换弹机制
+- 不使用 `perReloadCount`
+- 不检查 `canAttackNoReloadFull`
+
+建筑武器逻辑类似，也是一次性装满。
+
+---
+
+## 配置方式
+
+在武器配置表的 `AttributeGroup` 中配置 `AllowShootAtNoFullReload` 属性（枚举值 = 25）：
+
+- 值 > 0：允许换弹中开枪
+- 值 = 0 或不配置：不允许换弹中开枪
+
+**代码读取位置**：`Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponConfigDataHelper.cs`
+
+```csharp
+configData.canAttackNoReloadFull = weaponConfig.AttributeGroup.GetValueOrDefault(AttributeType.AllowShootAtNoFullReload) > 0;
+```
+
+---
+
+## 配置错误可能导致的问题
+
+### 1. 配置为 false 但策划期望可以中断换弹
+
+**现象**：
+- 角色使用霰弹枪类武器时，必须等所有子弹装满才能开枪
+- 换弹过程中即使敌人近身也无法反击
+
+**影响**：战斗手感僵硬，玩家可能被近身敌人击杀
+
+### 2. 配置为 true 但策划期望必须装满才能开枪
+
+**现象**：
+- 角色可能只装了1发弹药就开始攻击
+- 对于某些设计为"蓄力攻击"的武器，会破坏预期的战斗节奏
+
+**影响**：战斗平衡被打破，DPS 不稳定
+
+### 3. perReloadCount 配置为 0 或负数
+
+**现象**：
+- 每次换弹补充 0 发子弹，角色永远无法装满弹药
+- 配合 `canAttackNoReloadFull = false` 会导致角色**永久卡在换弹状态**
+
+**影响**：角色完全无法攻击，战斗锁死
+
+### 4. 武器配置表没有配置 AllowShootAtNoFullReload 属性
+
+**现象**：
+- `weaponConfig.AttributeGroup.GetValueOrDefault(AttributeType.AllowShootAtNoFullReload)` 返回 0
+- 所有角色武器默认 `canAttackNoReloadFull = false`
+- 分段换弹武器无法中断换弹
+
+**影响**：需要策划在武器配置表的 `AttributeGroup` 中明确配置此属性
+
+---
+
+## 配置建议
+
+| 武器类型 | canAttackNoReloadFull | perReloadCount | 说明 |
+|---------|----------------------|----------------|------|
+| 步枪/冲锋枪 | false 或不配置 | 等于 maxBulletCount | 一次性装满 |
+| 霰弹枪 | **true** | 1~2 | 逐发装填，可中断 |
+| 狙击枪 | 视设计而定 | 1 | 可能需要装满才能开枪 |
+| 载具炮台 | **不适用** | 不适用 | 一次性装满，不使用此属性 |
+| 建筑炮台 | **不适用** | 不适用 | 一次性装满，不使用此属性 |
+
+---
+
+## 相关代码文件
+
+| 文件路径 | 说明 |
+|---------|------|
+| `Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponConfigData.cs` | 武器配置数据结构 |
+| `Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponData.cs` | 武器运行时数据 |
+| `Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponConfigDataHelper.cs` | 武器配置构建工具类 |
+| `Assets/Code/Scripts/GamePlay/Character/State/UpState/UpStateReload.cs` | 角色换弹状态机 |
+| `Assets/Code/Scripts/GamePlay/Vehicle/Battery/BatteryStateReload.cs` | 载具换弹状态机 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/ActorCfg/AttributeType.cs` | 属性类型枚举定义 |
+
+---
+
+*文档生成时间：2026-02-04*
+*生成工具：Cursor AI Agent*