From SC2Mapster Wiki
Jump to: navigation, search


High Level Overview

Actors are based on the Actor computing paradigm, described here on wikipedia: Actor Modal

The key takeaways are as follows:

An actor is an abstract entity. In Starcraft 2, there are many unique Actors responsible for handling various functions (some deal with data that is viewable or presented to the user, such as modals, or sounds, whereas others are to facilitate action between actors, like Lists and Regions).

Each Actor can create other Actors. This is handled via the Create message. Note that any actor can create any other actor, including itself. When you do not specify the actor to be created, the game itself creates the actor. You can view the game engine itself as the master actor that is always present.

Actors can send messages to each other. Most usage is actors being sent messages from the game engine (such as Unit Birth, or Effect Used), but many messages come from the same actor (Actor Creation often is the case here, when an actor is created, it automatically sends an actor creation message to itself, allowing you to catch it and use it). The Target field found in all Actor Messages allow one to specify the message be sent to another actor, identified by ID, by Alias or by Reference. These messages can both be notifications (Actor Creation, Actor Destruction, Actor Orphan) or messages that directly modify the actor in question (Set Scale, Set Tint Scale).

Actors can react to messages received. These are the Actor Events. It tells the Actor that when it receives a certain message (along with limiting it to a certain source), that the actor should send a message. The message often is aimed at the same actor, but it does not have to be sent to the receiving actor, it can be sent to yet another actor. For example, I can configure a unit actor such that when it receives a Set Tint message, it should create a sound actor, which will lead to a sound being played.


Actors are the the nerve-cells of the StarCraft II engine. They can operate alone or be attached to each other. When you open the Actors tab in the data editor you will see a list of all the objects (visuals, sounds, etc.) that can be displayed on the map.

The StarCraft II engine is component based, as opposed to class based. Actors are one of the most basic components in this system. As a result they are a bit abstract. An example of a class based engine is Unreal Engine, while Unity is an example of a component based engine. Most modern game engines are component based.


  • Actors are used to attach models to each other.
  • Actors regulate how entities move around, rotates and flies.
  • Actors recieve and send death messages.
  • Actors can be made to listen to surrounding events in the game.
  • Actors can be ignorant about what is going on in the rest of the game.
  • Actors decide which animation the models should be playing.
  • Actors can be very simple or very complex.
  • Actors can destroy themselves.
  • Actors decide how the units attached to it should respond to physics.
  • Actors decide how large the footprint of the doodad should be.
  • Doodads, units, missiles, decals and beams are all actors with different properties and models attached to them.
  • Actors have similar capabilities as triggers, since they have events that trigger actions in responses to the event.

Example Usage

Working with actors


Understanding Site Operators (SOps)

The game world has a xyz reference system. Every actor has a xyz reference system. Site Operators defines how these reference systems should relate to each other. It is possible to create chains of actors attached to each other, where these reference systems have been given limitations of movement and adjustments. The end result is - as an example - that you can attach a turret to any other unit, rotate it, flip it and limit its rotational capacities. The middle-men actors that regulates positioning, tilt and movement are called site operators. Some site operators enable the dynamic adjustment of position and rotation in response to terrain or water height and angle or even the relative positions of attachment points on other connected actors.

Understanding Tokens


  • A Token is a special data field added to some types of actors, displayed beneath the main data list unless using XML view mode. The scrollbar doesn't affect it.
  • Tokens cannot be added within the normal data editor, but one can copy actors with existing token links
  • Tokens are always directed at a specific data type, for example Unit actor tokens always refer to the Units data type. This is important as data entities can (and often do) share names if they are of a different type
  • By themselves Token fields are completely worthless, their value has no effect whatsoever. The effect comes from changing the value in a Token field
  • When a Token field is changed the editor scans through all fields on the host actor and replaces all field values that match the old token value with the new value
  • This is the core use of Tokens: you can easily change one value to edit many fields at once, similar to the "find and replace" option in any decent text editing program


  • Unit actors have a token of the Units data type, meant to assign the actor to the unit it is meant to represent
  • Action actors have up to 3, all of Effects data type:
    • Attack Effect: is used by "simple" weapons like the Marine's, it triggers both Launch and Impact actions
    • Hit Effect: is used by supporting actors such as "shield hitters" for AoE attacks, it is rarely assigned properly
    • Impact Effect: is intended for Missile-based or otherwise delayed attacks and controls only the Impact action
    • Launch Effect: is the second component for delayed attacks and controls the Launch action and actor creation
  • Missile actors usually have a Units data type token as they're also meant to represent units
  • Splat actors have varying types, Burrow and Building type splats have Units tokens while Cursor Splats have Abilities tokens.

Technical Details and Shortcomings

  • Not all token-capable actors actually have the link set up properly, making the field useless in those cases
  • Copying an actor directly preserves the original token value, which may or may not be helpful
  • When using the "duplicate" option (Ctrl+U) and if the target of the token is also duplicated the token value will be changed to the duplicated target. This does not trigger a token update on the host actor, which usually is beneficial
  • The greatest problem with tokens: A token update scans all fields on the host actor and acts like the aforementioned "find string and replace" function; even fields that don't correspond to the same data type as the token but happen to contain the same string will be replaced (example: change the token on the Marine actor, the Art: Model field will also change despite referring to the Models data type and not Units)
  • Since changing an empty or disconnected token doesn't have any effect, this can be used to restore or even create links: First change the token value to the name of an existing field value, then change it again to change said field (and all others sharing the same string for their value, see above)

Understanding Actor Events

  • Actor events are triggers which are embedded into actors. See the special page of Actor Events for further reference.

Actor - Sub Types (Classes)

Actor types are categories which defined in the properties of an actor when you create it.

Fields Names