sc2data-effects-weapons

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

Resource	URL
Data Editor Introduction	https://s2editor-guides.readthedocs.io/New_Tutorials/04_Data_Editor/058_Data_Editor_Introduction/
SC2Mapster wiki	https://sc2mapster.wiki.gg/
Effects (wiki)	https://sc2mapster.wiki.gg/wiki/Data/Effects
Targets for Effects (wiki)	https://sc2mapster.wiki.gg/wiki/Targets_for_Effects
Weapons (wiki)	https://sc2mapster.wiki.gg/wiki/Data/Weapons
SC2Mapster mkdocs reference	https://sc2mapster.github.io/mkdocs/galaxy/
ShadowDragon Base.SC2Data (real GameData XML reference)	https://github.com/ShadowDragonSC2/Base.SC2Data/tree/main/GameData
Source of Truth: CatalogsData XSD Schema	https://github.com/ShadowDragonSC2/Base.SC2Data/raw/refs/heads/main/.vscode/schemas/catalogsData.xsd — Always consult this for exact fields, attributes, and structure of effects, weapons, and upgrades. Do not assume fields exist; verify against the schema.
Recommended VS Code Extension	Red Hat XML (redhat.vscode-xml) — Install this extension for XML validation, auto-completion, and error detection using the catalogsData.xsd schema. Configure it in .vscode/settings.json for automatic validation.

XML Schema Error Check and Fix Workflow

When editing SC2 data XML, always run this loop until diagnostics are clean:

1. Validate with Red Hat XML diagnostics (Problems panel).
2. For each error, identify whether it is an invalid element, invalid attribute, invalid enum value, or invalid field path/array index.
3. Verify the exact allowed structure in catalogsData.xsd before changing anything.
4. Fix the XML by aligning to schema-supported fields only; remove guessed or unsupported fields.
5. 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 shown in tooltip for damage display -->
    <Effect value="MyWeaponEffect"/>            <!-- root effect to fire on attack -->
    <Range value="5"/>                          <!-- attack range -->
    <Period value="0.8608"/>                    <!-- attack period (seconds between attacks) -->
    <DamagePoint value="0.0"/>                  <!-- % of Period before damage applies (0–1) -->
    <BackswingPoint value="0.5"/>              <!-- % of Period before unit can move/turn -->
    <Arc value="360"/>                          <!-- attack arc in degrees -->
    <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"/>              <!-- Melee, Ranged, Spell, Splash -->
    <DamageModifierSource value="Weapon"/>
    <ValidatorArray index="0" value="IsTargetNotInvulnerable"/>
    <AttributeBonus index="Armored" value="10"/>  <!-- bonus vs Armored: 25+10=35 -->
    <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"/>   <!-- ignore units on different cliff levels -->
</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"/>              <!-- Caster, Neutral, etc. -->
    <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"/>   <!-- add 50 minerals to caster's player -->
</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=""/>
    <!-- Units already tagged with "Link" are skipped; new hits get tagged -->
</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"/>   <!-- 0 = no limit, 1 = single-level, 3 = tri-level -->
</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.