星火 2.0 开发文档

主题

效果目标解析与 TargetType ​

GameDataEffect.TargetLocation 选择从效果上下文的哪个位置取目标，TargetType 决定把取到的目标保留为原类型、要求单位，还是转换成坐标点。

先选目标来源，再选目标类型 ​

TargetLocationExpression 可以从默认目标、施法者、来源、投射物、主目标或局部变量等位置取值；设置 Effect 时，会先找到对应的祖先效果再取值。

TargetType解析结果常见用途
Any保留所选目标的天然类型继续传递单位或点，由具体效果验证能否使用
Unit取所选目标的 Unit后续操作需要单位；纯坐标不能自动反查成单位
Point取所选目标当时的 Position保存当前位置，后续不再通过该目标引用跟随单位

解析不到目标时，效果可能返回 InvalidTarget；目标已解析但不满足具体效果要求时，会返回该效果的验证错误。祖先效果不存在或目标来源无效，也可能产生配置异常。

只调整 TargetType 不会改变目标来源。例如需要施法者为中心时，还需把 TargetLocation 指向施法者。

位置固定与跟随的区别 ​

以下是修改已有搜索效果定义的片段；searchEffect 是项目中的 GameDataEffectSearch：

csharp
// 以施法者当前坐标为目标，记录解析瞬间的位置。
searchEffect.TargetLocation = new() { Value = TargetLocation.Caster };
searchEffect.TargetType = TargetType.Point;
csharp
// 保留施法者单位作为目标，持续效果可以据此继续取得单位位置。
searchEffect.TargetLocation = new() { Value = TargetLocation.Caster };
searchEffect.TargetType = TargetType.Unit;

两种配置都可以用于范围效果：固定地面爆炸可以选 Point，附着单位的爆炸或移动光环可以选 Unit。范围效果没有统一的“必须用 Point”规则。瞬时搜索只在执行时搜索；改变目标类型不会自动把它变成持续搜索。

附带表现也会受到目标类型影响，但最终挂接、偏移与跟随还受 ActorScope、挂点、AttachForwardOnce 等配置影响。不要仅凭 TargetType 判断所有 Actor 都会如何移动。

单位效果不能把目标改成点 ​

伤害、Buff、单位属性修改等操作需要单位目标。把目标先转成 Point 后，原单位引用不会因坐标相同而自动恢复。

csharp
// 错误：damageEffect 是已有的 GameDataEffectDamage 定义。
damageEffect.TargetType = TargetType.Point;
csharp
// 改为要求单位；传入的目标来源也必须能提供单位。
damageEffect.TargetType = TargetType.Unit;

GameDataEffectUnit.Validate 要求有效实体，否则返回 MustTargetEntity；添加/移除 Buff 的验证则可能返回 MustTargetUnit。具体以效果类型的验证结果为准。Any 也不会绕过这些验证：保留下来的目标若仍是点，单位效果依然不能执行。

范围伤害通常分为“搜索中心”和“命中单位子效果”：搜索使用中心点或单位，找到单位后再对每个结果执行伤害。不能把搜索中心点直接当作伤害目标，也不能把“搜索效果与伤害效果放进同一个集合”当作搜索结果自动传递。

不要混淆技能层与效果层 ​

AbilityTargetType 控制技能的选目标方式；效果内部的 TargetLocation / TargetType 控制该效果节点如何解析上下文。技能允许点选，不代表内部所有节点都应配置成 Point；技能选了单位，也仍可在某个节点提取一次坐标。

投射物的 LaunchLocation / LaunchTargetType 描述发射位置，也应与效果执行目标分开核对。

排查顺序 ​

  1. 检查失败节点的 TargetLocation 与祖先 Effect 引用，确认取的是施法者、默认目标还是其他来源。
  2. 检查该来源是单位还是点，再检查 TargetType 转换后是否保留了后续所需信息。
  3. 对照节点的验证结果，定位 InvalidTarget、MustTargetEntity 或 MustTargetUnit。
  4. 逻辑目标正确但表现位置异常时，再检查 ActorScope、挂点、偏移与跟随设置。
  5. 实际移动目标后观察效果，分别验证固定地面、附着单位、目标死亡/移除时的行为。

相关文档 ​