更新示例代码

Author: hobobo

Docs/Moba技能开发流程设计文档.md

@@ -0,0 +1,126 @@
+# MOBA 技能开发流程设计文档
+
+## 1. 目标
+
+建立一套可重复、可追踪、可分层收敛的技能开发流程，覆盖单元测试、冒烟测试、DSL 环境测试与严格模式验收，避免技能只“能跑”但缺少配置正式化、跨模块契约和回归保障。
+
+## 2. 流程分层
+
+### 2.1 单元测试
+
+单元测试面向最小逻辑单元，验证技能参数解析、配置引用、时序计算、伤害/BUFF/区域触发等核心规则。
+
+作用：
+- 快速定位代码级回归。
+- 保障技能逻辑在不依赖完整战斗环境下仍可验证。
+- 适合补齐边界条件，例如 `DurationMs`、`IntervalMs`、`position_mode`、触发链路、配置缺失等。
+
+典型覆盖：
+- `SpawnAreaSchema` 参数解析。
+- `SpawnAreaPlanActionModule` 生命周期计算。
+- `MobaBattleConfigReferenceValidator` 配置引用合法性。
+- 技能 trace 断言与 HP 变化断言。
+
+### 2.2 冒烟测试
+
+冒烟测试面向最短闭环，验证技能从输入到结果的主链路是否仍可运行。
+
+作用：
+- 检查基础战斗入口、UI、运行时服务、输入流是否可用。
+- 用最少样本发现集成层破坏。
+- 适合作为继续开发前的 P0 门禁。
+
+典型覆盖：
+- 启动战斗环境。
+- 释放一个技能。
+- 观察最基本的 trace、伤害、BUFF、区域生成是否出现。
+
+### 2.3 DSL 环境测试
+
+DSL 测试面向场景化、可读性更强的验收样本，使用 scenario JSON 描述 actor、timeline、setup、stateExpectations 和 contextExpectations。
+
+作用：
+- 让设计、策划、开发共享同一份场景描述。
+- 便于复现复杂技能过程，例如延迟区域、周期伤害、复合触发链。
+- 适合作为技能“正式需求”的验收载体。
+
+典型覆盖：
+- Xiao Qiao 技能 2 的延迟区域命中。
+- Xiao Qiao 技能 3 的持续 BUFF + 间隔伤害。
+- 复杂位置模式、目标模式、持续时间语义。
+
+## 3. 这套流程带来的好处
+
+### 3.1 开发效率
+
+- 单测能最快反馈参数和逻辑错误。
+- 冒烟测试能快速确认主链路没有断。
+- DSL 测试能让复杂技能一次性验证完整行为。
+
+### 3.2 需求正式化
+
+- area 的 `DelayMs`、`DurationMs`、`VfxId`、触发数组不再只停留在约定层。
+- `position_mode` 的语义可以被明确写进 scenario 与解析层。
+- 配置缺字段、字段混用、隐式默认值问题更容易暴露。
+
+### 3.3 回归控制
+
+- 每个技能都有可回放样本。
+- 重构 runtime、view、config、triggering 时不会只靠人工验证。
+- 适合阶段性收口和批量回归。
+
+### 3.4 协作成本下降
+
+- 策划看 DSL 就能理解技能预期。
+- 开发看单测就能定位实现缺陷。
+- QA 看冒烟和 scenario 结果就能判断回归范围。
+
+## 4. 推荐门禁链路
+
+### 4.1 开发前
+
+必须通过：
+- 单元测试
+- MOBA console smoke
+
+目的：确保继续写功能之前，基础 runtime 没坏。
+
+### 4.2 技能实现阶段
+
+必须补齐：
+- 参数解析单测
+- 关键 trace 断言
+- 场景级 stateExpectation
+
+目的：把“能跑”提升为“行为正式”。
+
+### 4.3 技能收口阶段
+
+必须通过：
+- DSL 场景验收
+- 关键分支回归
+- 配置引用校验
+
+目的：确认技能在真实输入、真实时序、真实配置下稳定。
+
+## 5. 适用对象
+
+这套流程适用于：
+- 子弹技能
+- 区域技能
+- 持续效果技能
+- 召唤物技能
+- 表现/特效驱动技能
+- 需要 `position_mode`、目标集合、偏移、持续时间等参数的复合技能
+
+## 6. 当前实践建议
+
+- 新技能先写最小单测，再补 DSL scenario。
+- area 必须区分 `DelayMs` 和 `DurationMs`，不能混用。
+- `VfxId`、触发效果数组、位置参数必须进入配置校验。
+- 复杂技能优先用 scenario JSON 固化期望，再补充 trace 和状态断言。
+- 回归时优先跑 P0 门禁，再跑技能相关 acceptance，最后做批量回归。
+
+## 7. 结论
+
+单元测试负责“逻辑正确”，冒烟测试负责“链路可用”，DSL 环境测试负责“需求正式化与可读验收”。三者组合后，技能开发从“修到能跑”升级为“按需求稳定交付、可持续回归”的工程化流程。

Unity/Assets/Resources/moba/aoes.json

@@ -18,15 +18,19 @@
     "Id": 40020201,
     "Name": "小乔-甜蜜恋风-目标点击飞区域-配置先行",
     "ModelId": 0,
-    "VfxId": 0,
+    "VfxId": 10020201,
     "AttachMode": 0,
     "OffsetX": 0,
     "OffsetY": 0,
     "OffsetZ": 0,
     "Radius": 4.0,
     "DelayMs": 300,
+    "DurationMs": 1200,
     "CollisionLayerMask": 1,
     "MaxTargets": 10,
-    "OnDelayTriggerIds": [10020211]
+    "OnDelayTriggerIds": [10020211],
+    "OnEnterTriggerIds": [10020211],
+    "OnExitTriggerIds": [],
+    "OnIntervalTriggerIds": []
   }
 ]

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Application/Services/Triggering/MobaStageTriggerService.cs

@@ -9,7 +9,9 @@
 using AbilityKit.Ability.World.DI;
 using AbilityKit.Ability.World.Services;
 using AbilityKit.Ability.World.Services.Attributes;
+using AbilityKit.Demo.Moba.Config.BattleDemo.MO;
 using AbilityKit.Demo.Moba.Config.Core;
+using AbilityKit.Demo.Moba.Services;
 using AbilityKit.Demo.Moba.Services.Area;
 using AbilityKit.Demo.Moba.Services.Projectile;
 using AbilityKit.Demo.Moba.Services.Triggering;
@@ -34,7 +36,40 @@ public sealed class MobaStageTriggerService : IService, IMobaStageTriggerService
 
         public void ExecuteAreaStage(string eventId, int areaId, int templateId, object raw, in MobaAreaRuntimeInfo info, int ownerActorId, int targetActorId, int frame, in Vec3 center, float radius, ColliderId collider, int collisionLayerMask, int maxTargets)
         {
-            // omitted
+            if (_triggers == null || _configs == null) return;
+            if (templateId <= 0 || string.IsNullOrEmpty(eventId)) return;
+            if (!_configs.TryGetAoe(templateId, out var aoe) || aoe == null) return;
+
+            var triggerIds = ResolveAreaTriggerIds(eventId, aoe);
+            if (triggerIds == null || triggerIds.Length == 0) return;
+
+            var payload = new AreaEventArgs
+            {
+                EventId = eventId,
+                AreaId = areaId,
+                TemplateId = templateId,
+                OwnerActorId = ownerActorId,
+                TargetActorId = targetActorId,
+                Frame = frame,
+                SourceContextId = info.SourceContextId,
+                RootContextId = info.RootContextId,
+                OwnerContextId = info.OwnerContextId,
+                TraceKind = ResolveAreaTraceKind(eventId),
+                Center = center,
+                Radius = radius,
+                Collider = collider,
+                CollisionLayerMask = collisionLayerMask,
+                MaxTargets = maxTargets,
+                Raw = raw,
+            };
+
+            for (var i = 0; i < triggerIds.Length; i++)
+            {
+                var triggerId = triggerIds[i];
+                if (triggerId <= 0) continue;
+                var request = MobaTriggerExecutionRequest<AreaEventArgs>.Create(triggerId, payload, eventId);
+                _triggers.ExecuteDirectTrigger(in request);
+            }
         }
 
         public void ExecuteProjectileSpawn(in ProjectileSpawnEvent evt)
@@ -60,5 +95,45 @@ public void ExecuteProjectileHit(in ProjectileHitEvent evt, int hitActorId)
         public void Dispose()
         {
         }
+
+        private static int[] ResolveAreaTriggerIds(string eventId, AoeMO aoe)
+        {
+            if (aoe == null || string.IsNullOrEmpty(eventId)) return Array.Empty<int>();
+
+            switch (eventId)
+            {
+                case "area.spawn":
+                    return aoe.OnDelayTriggerIds;
+                case "area.enter":
+                    return aoe.OnEnterTriggerIds;
+                case "area.exit":
+                    return aoe.OnExitTriggerIds;
+                case "area.tick":
+                case "area.stay":
+                    return aoe.OnIntervalTriggerIds;
+                default:
+                    return Array.Empty<int>();
+            }
+        }
+
+        private static MobaTraceKind ResolveAreaTraceKind(string eventId)
+        {
+            switch (eventId)
+            {
+                case "area.spawn":
+                    return MobaTraceKind.AreaSpawn;
+                case "area.enter":
+                    return MobaTraceKind.AreaEnter;
+                case "area.exit":
+                    return MobaTraceKind.AreaExit;
+                case "area.tick":
+                case "area.stay":
+                    return MobaTraceKind.AreaStay;
+                case "area.expire":
+                    return MobaTraceKind.AreaExpire;
+                default:
+                    return MobaTraceKind.None;
+            }
+        }
     }
 }

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Application/Services/Triggering/PlanActions/Core/MobaActionTargetRequest.cs

@@ -184,11 +184,15 @@ private static SearchQueryTemplateMO BuildInlineTemplate(in MobaActionTargetRequ
             var rules = BuildRules(in request);
             var scorer = BuildScorer(in request);
             var selector = new SearchTargetSelectorConfig(0, (int)request.SelectCode);
+            var explicitTargetPolicy = request.TargetActorId > 0 || request.SourceCode == MobaActionTargetSourceCode.ExplicitActor
+                ? SearchQueryExplicitTargetPolicy.PreferExplicitTarget
+                : SearchQueryExplicitTargetPolicy.IgnoreExplicitTarget;
+
             return new SearchQueryTemplateMO(
                 id: 0,
                 name: "inline_action_target_query",
                 maxCount: request.MaxCount > 0 ? request.MaxCount : 1,
-                explicitTargetPolicy: (int)SearchQueryExplicitTargetPolicy.IgnoreExplicitTarget,
+                explicitTargetPolicy: (int)explicitTargetPolicy,
                 provider: provider,
                 rules: rules,
                 scorer: scorer,

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Application/Services/Triggering/PlanActions/Skill/SpawnAreaPlanActionModule.cs

@@ -46,7 +46,7 @@ protected override void Execute(object triggerArgs, SpawnAreaArgs args, ExecCtx<
 
             center = center + new Vec3(aoe.OffsetX + args.OffsetX, aoe.OffsetY + args.OffsetY, aoe.OffsetZ + args.OffsetZ);
             var radius = args.RadiusOverride > 0f ? args.RadiusOverride : aoe.Radius;
-            var lifetimeFrames = ResolveLifetimeFrames(args, aoe.DelayMs, ctx.Context);
+            var lifetimeFrames = ResolveLifetimeFrames(args, aoe.DurationMs, ctx.Context);
             var collisionLayerMask = args.CollisionLayerMaskOverride != 0 ? args.CollisionLayerMaskOverride : aoe.CollisionLayerMask;
             var stayIntervalFrames = ResolveStayIntervalFrames(args, aoe.IntervalMs, ctx.Context);
             var frame = ResolveFrame(ctx.Context);

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Application/Services/Validation/MobaBattleConfigReferenceValidator.cs

@@ -318,6 +318,16 @@ private static void ValidateAreas(MobaConfigDatabase config, TriggerPlanJsonData
                 var path = $"aoe.{area.Id}";
 
                 OptionalRef(Ref<ModelMO>(config.TryGetModel), area.ModelId, report, path + ".modelId", "model", area.Id);
+                if (area.VfxId < 0)
+                {
+                    report.Warning(Source, path + ".vfxId", "area vfx id is negative.", area.Id.ToString());
+                }
+
+                if (area.AttachMode < 0)
+                {
+                    report.Warning(Source, path + ".attachMode", "area attach mode is negative.", area.Id.ToString());
+                }
+
                 ValidateTriggerRefs(triggers, area.OnDelayTriggerIds, report, path + ".onDelayTriggerIds", area.Id);
                 ValidateTriggerRefs(triggers, area.OnEnterTriggerIds, report, path + ".onEnterTriggerIds", area.Id);
                 ValidateTriggerRefs(triggers, area.OnExitTriggerIds, report, path + ".onExitTriggerIds", area.Id);
@@ -333,6 +343,11 @@ private static void ValidateAreas(MobaConfigDatabase config, TriggerPlanJsonData
                     report.Warning(Source, path + ".delayMs", "area delay is negative.", area.Id.ToString());
                 }
 
+                if (area.DurationMs <= 0)
+                {
+                    report.Error(Source, path + ".durationMs", "area duration must be positive.", area.Id.ToString());
+                }
+
                 if (area.MaxTargets < 0)
                 {
                     report.Warning(Source, path + ".maxTargets", "area max targets is negative.", area.Id.ToString());

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Infrastructure/Config/BattleDemo/MO/AoeMO.cs

@@ -17,6 +17,7 @@ public sealed class AoeMO
 
         public float Radius { get; }
         public int DelayMs { get; }
+        public int DurationMs { get; }
         public int CollisionLayerMask { get; }
         public int MaxTargets { get; }
 
@@ -41,6 +42,7 @@ public AoeMO(AoeDTO dto)
 
             Radius = dto.Radius;
             DelayMs = dto.DelayMs;
+            DurationMs = dto.DurationMs;
             CollisionLayerMask = dto.CollisionLayerMask;
             MaxTargets = dto.MaxTargets;
 

Unity/Packages/com.abilitykit.demo.moba.runtime/Runtime/Infrastructure/Config/Core/LubanConfigGroupDeserializer.cs

@@ -404,7 +404,7 @@ private static ProjectileDTO DeserializeProjectile(JObject obj)
 
         private static AoeDTO DeserializeAoe(JObject obj)
         {
-            // 妗嗘灦 DTO: Id, Name, ModelId, VfxId, AttachMode, OffsetX, OffsetY, OffsetZ, Radius, DelayMs, CollisionLayerMask, MaxTargets, OnDelayTriggerIds, OnEnterTriggerIds, OnExitTriggerIds, OnIntervalTriggerIds, IntervalMs
+            // 妗嗘灦 DTO: Id, Name, ModelId, VfxId, AttachMode, OffsetX, OffsetY, OffsetZ, Radius, DelayMs, DurationMs, CollisionLayerMask, MaxTargets, OnDelayTriggerIds, OnEnterTriggerIds, OnExitTriggerIds, OnIntervalTriggerIds, IntervalMs
             var dto = new AoeDTO
             {
                 Id = obj["Id"]?.Value<int>() ?? obj["Code"]?.Value<int>() ?? 0,
@@ -417,6 +417,7 @@ private static AoeDTO DeserializeAoe(JObject obj)
                 OffsetZ = obj["OffsetZ"]?.Value<float>() ?? 0,
                 Radius = obj["Radius"]?.Value<float>() ?? 0,
                 DelayMs = obj["DelayMs"]?.Value<int>() ?? 0,
+                DurationMs = obj["DurationMs"]?.Value<int>() ?? 0,
                 CollisionLayerMask = obj["CollisionLayerMask"]?.Value<int>() ?? 0,
                 MaxTargets = obj["MaxTargets"]?.Value<int>() ?? 0,
                 OnDelayTriggerIds = obj["OnDelayTriggerIds"]?.ToObject<int[]>() ?? Array.Empty<int>(),

Unity/Packages/com.abilitykit.demo.moba.share/Runtime/Game/Config/Dto/ProjectileAreaSummonDtos.cs

@@ -62,6 +62,7 @@ public sealed class AoeDTO
 
         public float Radius;
         public int DelayMs;
+        public int DurationMs;
         public int CollisionLayerMask;
         public int MaxTargets;