KimPlaybit/sc2data-actors-visuals

SC2 Data Editor – Actors & Visuals

Actors are the visual and audio layer of StarCraft II data. They respond to game events and play animations, spawn VFX models, and play sounds. Actors run locally on each client and are not network-synchronized — they have zero effect on gameplay state.

Key References

| Resource | URL | |---|---| | Actors guide | https://s2editor-guides.readthedocs.io/New_Tutorials/04_Data_Editor/060_Actors/ | | Actor Messages Rundown | https://s2editor-guides.readthedocs.io/New_Tutorials/04_Data_Editor/061_Actor_Messages_Rundown/ | | SC2Mapster wiki | https://sc2mapster.wiki.gg/ | | Actors (wiki) | https://sc2mapster.wiki.gg/wiki/Data/Actors | | Actor Events (wiki) | https://sc2mapster.wiki.gg/wiki/Data/Actors/Events | | Actor Terms (wiki) | https://sc2mapster.wiki.gg/wiki/Data/Actors/Terms | | Blizzard Tutorials – Actors.md | https://github.com/SC2Mapster/blizzard-tutorials/blob/master/docs/New_Tutorials/04_Data_Editor/060_Actors.md | | 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 each actor type. 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 actors for a new unit, put them in the unit's own self-contained XML file (GameData/Faction/UnitName/UnitName.xml), not in a monolithic ActorData.xml. Register the file via <Catalog path="..."/> in GameData.xml. See the sc2data-units-abilities skill for the full file template.

Actor File

File: Base.SC2Data/GameData/ActorData.xml

All actor entries are children of <Catalog>:

<?xml version="1.0" encoding="utf-8"?>
<Catalog>
    <CActorUnit id="MyUnitActor" parent="GenericUnitStandard" unitName="MyUnit">
        ...
    </CActorUnit>
</Catalog>

---

Actor Types

| XML Type | Purpose | |---|---| | CActorUnit | Main visual wrapper for a unit — links model, sounds, animations | | CActorModel | A standalone or attached 3D model | | CActorAction | Powers a weapon's attack animation sequence | | CActorSite | Attachment point / positional anchor | | CActorBeam | Laser/beam line between two points | | CActorRange | Range indicator circle drawn under a unit | | CActorSound | Plays a sound as an actor event | | CActorModelMaterial | Modifies material/shader parameters on a model | | CActorTerrain | Applies terrain effects (squibs, burn marks) | | CActorMissile | Visual projectile (no event system) | | CActorDoodad | Environmental object (tree, rock) | | CActorQuad | 2D sprite/quad overlay | | CActorQuery | Actor that queries game state | | CActorRegion | Region-based actor | | CActorSiteOp | Site operation actor | | CActorSplat | Ground decal/splat | | CActorTurret | Turret actor | | CActorVideo | Video playback actor |

Note: This is not an exhaustive list. Always consult the catalogsData.xsd schema for the complete set of actor types and their exact fields/attributes. The schema is the definitive source of truth for what fields each actor type supports.

---

Event System — <On Terms="..." Send="..."/>

Actors are event-driven and reversed: the actor itself declares when it activates, not the thing that triggers it.

<On Terms="EventName.DataId.SubEvent; AnotherTerm; !NegatedTerm" Send="MessageName [Arg1] [Arg2]"/>

Terms syntax

| Syntax | Meaning | |---|---| | ActorCreation | Actor has been created | | ActorOrphan | Actor's host unit died | | UnitBirth.UnitId | Unit of this type was born | | UnitDeath.UnitId | Unit of this type died | | UnitDeathCustomize | Unit death triggered (more flexible) | | WeaponStart.WeaponId.AttackStart | Weapon attack began | | WeaponStop.WeaponId.AttackStop | Weapon attack ended | | Abil.AbilId.SourcePrepStart | Ability cast started | | Abil.AbilId.SourceFinish | Ability finished casting | | Abil.AbilId.SourceStop | Ability interrupted | | AbilMorph.*.Finish | Any morph ability completed | | Upgrade.UpgradeId.Add | Player researched this upgrade | | Upgrade.UpgradeId.Remove | Upgrade removed/lost | | ValidateUnit UpgradeId | Test if upgrade is researched | | IsStatus DeathSuicide 0 | Negate: unit did NOT suicide | | MorphTo UnitId | Unit morphed into this type | | MorphFrom UnitId | Unit morphed away from this type |

Semicolons ; are AND — all terms must be true.
! prefix negates a term.
* is a wildcard for a single segment.

---

Common Actor Messages (Send)

| Message | Effect | |---|---| | Create | Create this actor (or a referenced actor) | | Destroy | Destroy this actor | | DestroyFinal | Destroy immediately, no death animation | | AnimPlay Attack | Play animation named "Attack" once | | AnimBracketStart Attack Attack | Start looping anim: Opening/Content/Closing tokens | | AnimBracketStop Attack | Stop the bracketed animation | | AnimClear Attack | Clear a running animation | | AnimGroupApply Superior | Apply animation group (variation set) | | SetTintColor {255 128 0 255} | Tint colour (R G B A 0–255) | | SetOpacity 0.5 0 | Set opacity (0.0=opaque, 1.0=transparent); 0=no blend | | ModelSwap NewModelId | Swap the model at runtime | | GlowStart | Start pulsing glow | | GlowStop | Stop pulsing glow | | HaloStart | Start outline halo | | HaloStop | Stop outline halo | | HaloSetColor {R G B} | Set halo colour | | StatusSet Status 1 | Set status flag (e.g. Cloak) | | SetWalkAnimMoveSpeed 3 | Adjust walk animation playback rate | | TerrainSquibActivateGroup MyGroup | Activate a terrain squib group | | SendToRef ::Target Create | Tell the target actor to Create |

---

CActorUnit — Full Example

<CActorUnit id="MyUnitActor" parent="GenericUnitStandard" unitName="MyUnit">
    <!-- Cross-actor messaging alias (e.g. _UnitMedium for medium-sized units) -->
    <Aliases value="_UnitMedium"/>

    <!-- Reusable event macro (defined elsewhere, expands into multiple On entries) -->
    <Macros value="StandardDeathMacro"/>

    <!-- Primary model -->
    <Model value="MyUnitModel"/>
    <AnimBlendTime value="0.300000"/>

    <!-- Construction model shown while building -->
    <BuildModel value="MyUnitBuildModel"/>

    <!-- Portrait model for unit info panel -->
    <PortraitModel value="MyUnitPortrait"/>

    <!-- Placement ghost model -->
    <PlacementModel value="MyUnitPlacement"/>

    <!-- Death variations -->
    <DeathArray index="Normal" ModelLink="MyDeathModel" SoundLink="MyDeathSound" VoiceLink=""/>
    <DeathArray index="Blast" ModelLink="MyBlastDeathModel"/>

    <!-- Unit sounds -->
    <SoundArray index="Ready" value="MyUnit_Ready"/>
    <SoundArray index="What" value="MyUnit_What"/>
    <SoundArray index="Yes" value="MyUnit_Yes"/>
    <SoundArray index="Attack" value="MyUnit_Attack"/>
    <SoundArray index="Pissed" value="MyUnit_Pissed"/>

    <!-- UI icons -->
    <GroupIcon><Image value="Assets\Textures\wireframe-myunit.dds"/></GroupIcon>
    <UnitIcon value="Assets\Textures\btn-unit-myunit.dds"/>
    <HighlightTooltip value="Unit/Tooltip/MyUnit"/>

    <!-- Health bar positioning -->
    <BarOffset value="25"/>
    <BarWidth value="90"/>

    <!-- Actor events -->
    <On Terms="ActorCreation" Send="AnimPlay Birth"/>
    <On Terms="UnitBirth.MyUnit" Send="Create MyBirthEffectActor"/>
    <On Terms="WeaponStart.MyWeapon.AttackStart" Send="AnimBracketStart Attack Attack"/>
    <On Terms="WeaponStop.MyWeapon.AttackStop" Send="AnimBracketStop Attack"/>
    <On Terms="Abil.MyAbility.SourcePrepStart" Send="AnimPlay Spell"/>
    <On Terms="Upgrade.MyUpgrade.Add" Send="AnimGroupApply Superior"/>
    <On Terms="UnitDeathCustomize; IsStatus DeathSuicide 0" Send="Create MyDeathSound"/>
    <On Terms="ActorOrphan" Send="Destroy"/>
</CActorUnit>

---

CActorAction — Weapon Attack Sequence

Used with the GenericAttack parent. The three tokens are Attack, Launch, and Impact:

<CActorAction id="MyWeaponAction" parent="GenericAttack">
    <!-- Attack: play windup animation on the unit actor -->
    <On Terms="ActionStart" Send="AnimPlay Attack ::Creator"/>

    <!-- Launch: spawn projectile model at weapon launch point -->
    <On Terms="ActionLaunch" Send="Create MyProjectileModel ::Creator"/>

    <!-- Impact: spawn explosion model at target -->
    <On Terms="ActionImpact" Send="Create MyImpactModel ::Target"/>
</CActorAction>

---

Actor Parents Reference

| Parent | What it provides | |---|---| | GenericUnitStandard | Default unit actor — selection circle, health bar, standard events | | GenericAttack | Weapon action actor — Attack/Launch/Impact event tokens | | ModelAddition | Attaches a model to another actor (buff visuals, attachments) | | ModelAnimationStyleContinuous | Looping model (persistent AoE like Psi Storm) | | ModelAnimationStyleOneShot | One-shot model (explosions, birth effects) | | BehaviorGlaze | Applies glaze (overlay) while a behavior is active; uses buff token | | SoundOneShot | Plays sound once then auto-destroys | | SoundContinuous | Plays sound until destroyed | | Range Abil | Range indicator for an ability | | Range Behavior | Range indicator for a behavior/aura | | Range Weapon | Range indicator for a weapon | | Cursor Splat | AoE targeting cursor shown during ability targeting |

Warning: When using Range * or Cursor Splat parents via the editor UI, the editor generates default <On events. After creation, Reset To Parent Value on the Events field, or manually delete the generated <On lines in XML view to avoid duplicate/broken event wiring.

---

Aliases

Aliases let other actors address this actor by a shorthand type name:

<Aliases value="_UnitMedium"/>

Common system aliases used in Terms:

• ::Creator — the actor that created this actor
• ::Host — the unit this actor is attached to
• ::Target — the target of an action
• ::Main — the main actor of the host unit
• _Unit — any unit actor (generic)
• _Structure — any structure actor
• _UnitSmall / _UnitMedium / _UnitLarge — by size class

---

Macros

Macros expand into a set of <On> entries at runtime. Defined in a CActorMacro entry, referenced by name:

<Macros value="ZergBurrowStandardAnimMacro"/>

Blizzard provides many reusable macros for common patterns (burrow/unburrow, death, cloak, etc.). Check existing units of the same race/type for applicable macros before writing manual <On> events.

---

CActorModel — Standalone or Attached Model

<!-- Birth VFX: one-shot model, auto-destroys after animation plays -->
<CActorModel id="MyBirthEffectActor" parent="ModelAnimationStyleOneShot">
    <Model value="MyBirthModel"/>
    <On Terms="ActorCreation" Send="AnimPlay Birth"/>
    <On Terms="AnimDone" Send="Destroy"/>
</CActorModel>

<!-- Persistent looping area model -->
<CActorModel id="MyAuraModel" parent="ModelAnimationStyleContinuous">
    <Model value="MyAuraModel"/>
</CActorModel>

---

CActorSound

<CActorSound id="MyReadySound" parent="SoundOneShot">
    <Sound value="MyUnit_Ready"/>
    <On Terms="ActorCreation" Send="AnimPlay"/>
    <On Terms="ActorOrphan" Send="Destroy"/>
</CActorSound>

---

CActorBeam — Laser Beam

<CActorBeam id="MyLaserBeam">
    <Model value="MyBeamModel"/>
    <!-- Beam connects ::Creator (source) to ::Target -->
</CActorBeam>

---

CActorMissile — Projectile Actor

Important: CActorMissile does NOT have an <On> array for event wiring. It is purely a visual projectile with no event system. Use CActorAction or other actors for event handling around missile launches/impacts.

<CActorMissile id="MyMissileActor">
    <Model value="MyMissileModel"/>
    <!-- Missile follows its mover/physics, no events -->
</CActorMissile>

---

Advanced Event Patterns

Timer Pattern — per-actor delays and loops

A timer lives entirely on the actor. Set it on creation and respond to its expiry:

<!-- Start a 3-second timer (with up to 1 second random variance) on creation -->
<On Terms="ActorCreation" Send="TimerSet MyTimer 3 1"/>

<!-- Respond when that timer fires, identified by the TimerName term -->
<On Terms="TimerExpired; TimerName MyTimer" Send="AnimPlay Attack"/>

TimerSet <Name> <BaseDuration> <RandomRange> — adds a random 0–RandomRange seconds on top. Use TimerStop MyTimer to cancel before expiry.

Signal Pattern — cross-actor events

Signals send an artificial event from one actor to another via a reference alias:

<!-- From a buff actor: tell the host unit actor to play a flash -->
<On Terms="ActorCreation" Send="Signal AbilityFlash ::Host"/>

<!-- In the main unit CActorUnit: listen for that signal -->
<On Terms="Signal AbilityFlash" Send="AnimPlay Flash"/>

Signals bypass the normal game event system and go directly from sender to receiver.

Status Set — actor state machine

Use StatusSet + IsStatus to track internal actor state without needing external data:

<!-- Track burrow state -->
<On Terms="Abil.BurrowDown.SourceFinish" Send="StatusSet Burrowed 1"/>
<On Terms="Abil.BurrowUp.SourceFinish"   Send="StatusSet Burrowed 0"/>

<!-- Conditionally act only when burrowed -->
<On Terms="WeaponStart.MyWeapon.AttackStart; IsStatus Burrowed 1" Send="AnimPlay BurrowedAttack"/>

Cap — limit event to fire N times per actor lifetime

The Cap N term prevents an event from triggering more than N times over the actor's life:

<!-- Play birth anim only once even if creation somehow fires again -->
<On Terms="ActorCreation; Cap 1" Send="AnimPlay Birth"/>

From Effect Tree Descendant — isolate per-effect-instance actors

When multiple instances of the same effect run simultaneously (e.g. multiple persistent effects), use FromEffectTreeDescendant to restrict each actor's response to its own effect tree only:

<On Terms="Effect.TentacleHit; FromEffectTreeDescendant TentacleEffect" Send="AnimPlay Hit"/>

Without this term, every active instance of that actor type would respond to every matching event.

Upgrade Event — Affected Unit Array requirement

The Upgrade.UpgradeId.Add actor event only fires if the unit type is in the upgrade's Affected Unit Array in the Data Editor. If the event never fires in playtesting, add the unit to that array:

<CUpgrade id="MyUpgrade">
    <AffectedUnitArray value="MyUnit"/>   <!-- required for Upgrade actor event to fire on MyUnit -->
</CUpgrade>

Ability Charge/Cooldown Actor Events

Charge and cooldown actor events only fire if the corresponding flags are set on the ability:

| Ability flag (Shared Flags) | Enables actor events | |---|---| | Register Charge Event | Abil.MyAbility.ChargeStart, .ChargeUse, .ChargeExpire | | Register Cooldown Event | Abil.MyAbility.CooldownStart, .CooldownExpire |

---

Best Practices

• Actors do not affect gameplay — never use actors to track game state.
• Prefer macros over manual <On> events when the unit race/type has matching macros.
• Keep actor ids consistent with unit ids: unit MyUnit → actor MyUnitActor.
• Use parent="ModelAnimationStyleOneShot" for all one-time VFX (explosions, birth effects).
• Always add <On Terms="ActorOrphan" Send="Destroy"/> to orphan non-unit actors that should clean up.
• Test animations in the editor with the Actor Viewer (F7 in the editor).