| name | sc2data-effects-weapons |
| description | SC2 Data Editor — Effects, Weapons, Upgrades, and the damage chain in XML. Use when creating or modifying CEffect* (damage, search, apply behavior, launch missile, set), CWeapon, CUpgrade, or the full chain from weapon through to damage application. Also covers TargetFind, TargetSort, and Footprints. Always consult the catalogsData.xsd schema for exact fields and structure — do not assume unsupported fields exist. Do not use for actors/visuals (sc2data-actors-visuals) or unit/ability containers (sc2data-units-abilities). |
SC2 Data Editor – Effects & Weapons
Effects and weapons define how game logic executes: what damage is dealt, what behaviors are applied, what searches are performed, and what units are spawned. The full chain from a weapon or ability fires down through effect sets and terminates in atomic effects.
Key References
XML Schema Error Check and Fix Workflow
When editing SC2 data XML, always run this loop until diagnostics are clean:
- Validate with Red Hat XML diagnostics (Problems panel).
- For each error, identify whether it is an invalid element, invalid attribute, invalid enum value, or invalid field path/array index.
- Verify the exact allowed structure in
catalogsData.xsd before changing anything.
- Fix the XML by aligning to schema-supported fields only; remove guessed or unsupported fields.
- Re-validate and repeat until no schema errors remain.
If a user asks to fix XML errors, perform this end-to-end workflow rather than only describing it.
File placement: When creating effects for a new unit or ability, put them in the unit's own self-contained XML file (GameData/Faction/UnitName/UnitName.xml), not in a monolithic EffectData.xml. Register the file via <Catalog path="..."/> in GameData.xml. See the sc2data-units-abilities skill for the full file template.
Effect Chain Architecture
CWeapon
└─ Effect ──► CEffectSet
├─► CEffectDamage (subtract HP)
├─► CEffectApplyBehavior (add buff/debuff)
├─► CEffectCreateUnit (spawn unit)
├─► CEffectSearch / EnumArea (AoE spread)
│ └─► CEffectDamage
└─► CEffectLaunchMissile ──► CEffectDamage
An ability or weapon fires a single root effect. That root is almost always a CEffectSet which chains multiple phases.
Weapons (WeaponData.xml)
File: Base.SC2Data/GameData/WeaponData.xml
<CWeapon id="MyWeapon">
<EditorCategories value="Race:Terran"/>
<DisplayEffect value="MyWeaponDamage"/>
<Effect value="MyWeaponEffect"/>
<Range value="5"/>
<Period value="0.8608"/>
<DamagePoint value="0.0"/>
<BackswingPoint value="0.5"/>
<Arc value="360"/>
<Flags index="AttackTargetMover" value="1"/>
<TargetFilters value="Visible;Self,Ally,Neutral,Dead,Invulnerable"/>
</CWeapon>
Weapon key fields
| Field | Purpose |
|---|
Effect | Root effect fired on attack |
DisplayEffect | Effect used for tooltip damage display (can differ) |
Range | Attack range |
Period | Attack speed — seconds per attack |
DamagePoint | Where in the Period animation the hit lands (0.0–1.0) |
BackswingPoint | Where the unit can move again after attacking |
Arc | Cone arc for directional weapons |
TargetFilters | Which targets can be attacked |
Effect Types
File: Base.SC2Data/GameData/EffectData.xml
CEffectSet — chain multiple effects
<CEffectSet id="MyAbilityEffect">
<EffectArray index="0" value="MyAbilityDamage"/>
<EffectArray index="1" value="MyAbilityApplyBuff"/>
<EffectArray index="2" value="MyAbilitySpawnUnit"/>
</CEffectSet>
CEffectDamage — deal damage
<CEffectDamage id="MyWeaponDamage">
<Amount value="25"/>
<Kind value="Ranged"/>
<DamageModifierSource value="Weapon"/>
<ValidatorArray index="0" value="IsTargetNotInvulnerable"/>
<AttributeBonus index="Armored" value="10"/>
<AttributeBonus index="Light" value="5"/>
</CEffectDamage>
CEffectApplyBehavior — apply a buff/debuff
<CEffectApplyBehavior id="MyStunApply">
<Behavior value="MyStunBehavior"/>
<ValidatorArray index="0" value="IsTargetAlive"/>
</CEffectApplyBehavior>
CEffectRemoveBehavior — strip a buff
<CEffectRemoveBehavior id="MyBuffRemove">
<Behavior value="MyBuff"/>
</CEffectRemoveBehavior>
CEffectSearch — AoE by radius
<CEffectSearch id="MyAoeSearch">
<AreaArray index="0" Radius="2.5" Effect="MyAoeDamage"
TargetFilters="Visible,Alive;Self,Ally,Neutral,Dead"/>
<SearchFlags index="SameCliff" value="1"/>
</CEffectSearch>
CEffectEnumArea — custom-shape AoE
<CEffectEnumArea id="MyLineAoe">
<AreaArray index="0" Effect="MyAoeDamage" Radius="2" Arc="30" Distance="8"/>
</CEffectEnumArea>
CEffectLaunchMissile — spawn a projectile
<CEffectLaunchMissile id="MyMissileLaunch">
<Mover value="MyMissile"/>
<ImpactEffect value="MyMissileImpact"/>
<LaunchMissileFlags index="DeleteOnImpact" value="1"/>
<ImpactLocation><Effect value="TargetPoint"/></ImpactLocation>
</CEffectLaunchMissile>
CEffectCreateUnit — spawn a unit
<CEffectCreateUnit id="SpawnMyUnit">
<UnitType value="MySpawnUnit"/>
<Owner value="Caster"/>
<Count value="1"/>
</CEffectCreateUnit>
CEffectIssueOrder — command a unit
<CEffectIssueOrder id="ForceAttack">
<Ability value="Attack"/>
<AbilityCmd value="Attack"/>
</CEffectIssueOrder>
CEffectModifyPlayer — modify a player resource
<CEffectModifyPlayer id="GrantMinerals">
<Owner value="Caster"/>
<Resource index="Minerals" value="50"/>
</CEffectModifyPlayer>
Effect Subtype Reference
Full list of all CEffect* subtypes for awareness:
| Subtype | Purpose |
|---|
CEffectSet | Sequence multiple effects |
CEffectDamage | Deal HP damage |
CEffectApplyBehavior | Apply a buff/debuff behavior |
CEffectRemoveBehavior | Strip a behavior |
CEffectSearch | AoE by radius — runs sub-effect on all hits |
CEffectEnumArea | Custom-shape AoE (arc, line) |
CEffectLaunchMissile | Spawn a projectile that delivers an impact effect |
CEffectCreateUnit | Spawn a unit |
CEffectIssueOrder | Command a unit to perform an ability |
CEffectModifyPlayer | Modify player resources (minerals, gas, supply) |
CEffectModifyUnit | Modify unit vitals or stats directly |
CEffectCreatePersistent | Create a timed persistent area (for abilities like Psi Storm) |
CEffectDestroyPersistent | End a persistent effect early |
CEffectSwitch | Conditional branch — pick effect by index |
CEffectRandom | Random branch — pick from effect array randomly |
CEffectTeleport | Move a unit to a new location instantly |
CEffectMorph | Transform a unit into a different unit type |
CEffectTransferBehavior | Move a behavior from one unit to another |
CEffectCancelOrder | Cancel a unit's current order |
CEffectUserData | Execute a user-data-driven branch (custom data lookups) |
CEffectLastTarget | Re-use the final target from a previous effect |
CEffectUseCalldown | Trigger a calldown ability |
CEffectLoadContainer | Load a unit into transport |
CEffectRedirectMissile | Change a missile's target mid-flight |
CEffectApplyForce | Push a unit (physics force — used by e.g. Shockwave) |
Effect Common Fields
These fields appear on most or all CEffect* types:
| Field | Purpose |
|---|
ValidatorArray | AND gate — if any validator returns false, effect is skipped and linked actor event is suppressed |
Chance | 0.0–1.0 probability the effect executes (default 1.0 = always) |
DebugTrace | When 1: shows visual debug markers in Test Mode at launch/impact locations |
CasterHistory | Saves the effect in the caster's Effect History Limit (used by some validators) |
CanBeBlocked | If 1, queries the target unit's Block Chance — sends actor sub-event Blocked if blocked |
Markers — prevent re-hitting in AoE
Markers tag a unit as already hit by this effect instance, preventing double-hits in area effects:
<CEffectSearch id="MySplash">
<MarkerArray index="0" MatchFlags="Link" MismatchFlags=""/>
</CEffectSearch>
Use CValidatorUnitCompareMarkerCount to gate effects based on marker state.
Response & AI Notify Flags
| Field | Values | Meaning |
|---|
ResponseFlags | Acquire | Target starts attacking the caster |
ResponseFlags | Flee | Target runs away from caster |
AINotifyFlags | HelpFriend, HurtEnemy, HurtFriend, MajorDanger, MinorDanger | Trigger AI threat/help response |
First-effect targeting rule
The first effect in an ability's effect chain determines the ability's targeting type. If you need a targeted ability (click on unit or point), the root effect must be a type that accepts and uses a target. CEffectIssueOrder as the first effect will make the ability untargetable — place a CEffectSet first or ensure the ordering accounts for this.
Damage Kind & Attribute Bonuses
| Kind | Notes |
|---|
Melee | Affected by armor, melee upgrades |
Ranged | Affected by armor, ranged upgrades |
Spell | Ignores armor by default |
Splash | Can hit multiple units |
Attribute bonuses add extra damage vs units with matching attributes:
<AttributeBonus index="Light" value="10"/>
<AttributeBonus index="Armored" value="5"/>
<AttributeBonus index="Biological" value="15"/>
<AttributeBonus index="Massive" value="20"/>
Upgrades (UpgradeData.xml)
File: Base.SC2Data/GameData/UpgradeData.xml
Upgrades fire an effect chain when researched and can stack in levels:
<CUpgrade id="MyUpgrade">
<EditorCategories value="Race:Terran"/>
<Name value="Upgrade/Name/MyUpgrade"/>
<EffectArray index="0" value="MyUpgradeEffect"/>
<MaxLevel value="3"/>
</CUpgrade>
Upgrades commonly fire CEffectUpgradePlayer (modify unit stats) or CEffectApplyBehavior effects.
Validators in Effects
Attach validators to ValidatorArray on any effect. If any validator returns false, the effect is not applied:
<CEffectDamage id="ConditionalDamage">
<Amount value="50"/>
<ValidatorArray index="0" value="TargetIsExposed"/>
<ValidatorArray index="1" value="CasterNotBurrowed"/>
</CEffectDamage>
See sc2data-behaviors-validators for validator definition patterns.
TargetFind (TargetFindData.xml)
TargetFind types determine where an effect or weapon "finds" its target point/unit:
| Common TargetFind | Meaning |
|---|
TargetPoint | The originally targeted location |
SourcePoint | The caster's location |
BuffTarget | Unit the behavior is applied to |
Footprints (FootprintData.xml / TerrainData.xml)
Footprints define the terrain blocked by a structure:
<CFootprint id="MyStructureFootprint">
<Layers index="0">
<Row index="0" value="PPPPPP"/>
<Row index="1" value="PPPPPP"/>
</Layers>
</CFootprint>
P = passable, X = blocked.
Naming Conventions
| Item | Convention |
|---|
| Weapon id | UnitNameWeapon or descriptive name (e.g. MarineWeapon) |
| Root effect id | Same as weapon or ability id (e.g. MarineWeaponEffect) |
| Damage effect id | Root + Damage (e.g. MarineWeaponDamage) |
| Search effect id | Root + Search (e.g. SiegeSplashSearch) |
| Apply behavior effect | ApplyBehaviorName (e.g. ApplyLockedDown) |
| Upgrade id | PascalCase (e.g. InfantryWeaponLevel1) |
Best Practices
- Always route through a
CEffectSet — even for a single effect — to make future additions trivial.
- Set
DisplayEffect on weapons to the direct CEffectDamage so tooltips show accurate numbers.
- Add
ValidatorArray on CEffectDamage for conditional hits rather than filtering at the weapon level.
- Use
CEffectSearch + CEffectDamage for splash/AoE rather than multiple separate weapons.
- Effects are forward-declared: ability → effect → sub-effect(s). Do not circular-reference.
- Keep each effect id uniquely named; Blizzard's data is dense and naming collisions cause silent overrides.
