Data/Actors

## Actors

### High Level Overview

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

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 models, 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.

### Description

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.

### Hints

* 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.

## Events (Actor Events)

Events are the heart of actors, as they link them to everything, manage them, create them, supress them, etc. Actor events are triggers which are embedded into actors.

* For example, we want to create a damage effect that generates some kind of fire grapghic explosion. This means that if that damage effect is created, we can link the creation of the actor at the exact moment the effect is started. Otherwise, effects are mostly invisible effects without actors. Of course, the model of the explosion is chosen in the **Model** field of this actor (depending of what kind of actor we're talking, in this case, it would be a model animation style one shot).

See the special page of Actor Events for further reference.

## Example Usage

### Working with actors

https://www.sc2mapster.com/forums/resources/tutorials/179383-data-working-with-actors-beginner-difficulty

### Attachments

https://www.sc2mapster.com/forums/resources/tutorials/179664-data-working-with-attachments-beginner-difficulty

### 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

#### Overview

* 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

#### Examples

* 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)

## Actor - Sub Types (Classes)

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

* Action
* Actor List
* Arc
* Banker (Unit)
* Batch
* Beam (Simple)
* Beam (Standard)
* Billboard
* Camera
* Camera Model
* Creep
* Curve Set
* Doodad
* Doodad Effect Spawner
* Doodad Preserver
* Editor Camera
* Editor Point
* Event Macro
* Force (Box)
* Force (Cone Rounded End)
* Force (Cylinder)
* Force (Sphere)
* Global Configuration
* Light (Omni Model)
* Light (Omni)
* Light (Spot Model)
* Light (Spot)
* Look At
* Missile
* Model
* Portrait
* Power
* Progress
* Quad
* Queried
* Query Response
* Range
* Region (Arc)
* Region (Circle)
* Region (Combine)
* Region (Game)
* Region (Polygon)
* Region (Rectangle)
* Region (Water)
* Scene
* Selection
* Shadow
* Shield
* Shield Impact
* Simple
* Site
* Site (Mover)
* Site (Rocker)
* Site Operation(2D Rotation)
* Site Operation (Action)
* Site Operation (Attachment Volume)
* Site Operation (Attachment)
* Site Operation (Banker)
* Site Operation (Basic)
* Site Operation (Death Motion)
* Site Operation (Effect)
* Site Operation (Explicit Rotation)
* Site Operation (Forward Vector)
* Site Operation (Height)
* Site Operation (Higher Of Terrain And Water)
* Site Operation (Host Bearings)
* Site Operation (Hosted Offset)
* Site Operation (Incoming)
* Site Operation (Local Offset)
* Site Operation (Patch)
* Site Operation (Physics Impact)
* Site Operation (Random Point in Circle)
* Site Operation (Random Point in Crossbar)
* Site Operation (Random Point in Sphere)
* Site Operation (Random Rotation)
* Site Operation (Rotator)
* Site Operation (Selection Offset)
* Site Operation (Serpent Head)
* Site Operation (Serpent Segment)
* Site Operation (Shadow)
* Site Operation (Smooth Rotation)
* Site Operation (Tipability)
* Site Operation (Up Vector)
* Site Operation (Variance Rotation)
* Site Operation (Z)
* Snapshot
* Sound
* Splat
* Squib
* State Monitor
* Terrain
* Terrain Deformer
* Text
* Tipability
* Turret
* Unit

## (!!!WIP!!!)Actor Hierarchy Tree(!!!WIP!!)

### CActor

* **CActorBase**
	+ **CActorAction**
	+ **CActorActionOverride**
	+ **CActorBearings**
		- **CActorBatch**
		- **CActorCamera**
		- **CActorCutscene**
		- **CActorFoliageFXSpawner**
		- **CActorQuad**
		- **CActorRange**
		- **CActorRegion**
			* **CActorRegionArc**
			* **CActorRegionCircle**
			* **CActorRegionCombine**
			* **CActorRegionGame**
			* **CActorRegionPolygon**
			* **CActorRegionQuad**
			* **CActorRegionWater**
		- **CActorSite**
			* **CActorSiteBillboard**
			* **CActorSiteMover**
			* **CActorSiteRocker**
			* **CActorSiteOrbiter**
		- **CActorSound**
		- **CActorSplat**
			* **CActorSelection**
			* **CActorShadow**
		- **CActorSquib**
		- **CActorTerrainDeformer**
		- **CActorText**
		- **CActorModel**
			* **CActorArc**
			* **CActorBeam**
				+ **CActorBeamSimple**
				+ **CActorBeamStandard**
			* **CActorCameraModel**
			* **CActorDoodad**
			* **CActorDoodadPreserver**
			* **CActorEditorCamera**
			* **CActorEditorPoint**
			* **CActorForce**
				+ **CActorForceBox**
				+ **CActorForceLineSegment**
					- **CActorForceConeRoundedEnd**
					- **CActorForceCylinder**
				+ **CActorForceSphere**
			* **CActorLight**
				+ **CActorLightOmni**
				+ **CActorLightSpot**
			* **CActorLightModel**
				+ **CActorLightOmniModel**
				+ **CActorLightSpotModel**
			* **CActorMinimap**
			* **CActorModelMaterial**
			* **CActorPortrait**
			* **CActorShield**
			* **CActorSnapshot**
			* **CActorUnit**
				+ **CActorMissile**
			* **CActorUnitRing**
	+ **CActorBlob**
	+ **CActorCreep**
	+ **CActorEventMacro**
	+ **CActorEventMacroRunnable**
	+ **CActorGlobalConfig**
	+ **CActorList**
	+ **CActorListPerPlayer**
	+ **CActorLookAt**
	+ **CActorOverrides**
	+ **CActorPower**
	+ **CActorProgress**
	+ **CActorPropertyCurveSet**
	+ **CActorQueryResponse**
	+ **CActorScene**
	+ **CActorSetQueried**
	+ **CActorShieldImpact**
	+ **CActorSimple**
	+ **CActorSiteOp**
		- **CActorSiteOpBase**
			* **CActorSiteOp2DRotation**
			* **CActorSiteOpAction**
			* **CActorSiteOpAttach**
			* **CActorSiteOpAttachVolume**
			* **CActorSiteOpBanker**
			* **CActorSiteOpBankerUnit**
			* **CActorSiteOpBasic**
			* **CActorSiteOpGameCameraFollow**
			* **CActorSiteOpDeathMotion**
			* **CActorSiteOpDeltaSum**
			* **CActorSiteOpEffect**
			* **CActorSiteOpForward**
			* **CActorSiteOpHeight**
			* **CActorSiteOpHigherOfTerrainAndWater**
			* **CActorSiteOpHostBearings**
			* **CActorSiteOpHostedOffset**
			* **CActorSiteOpIncoming**
			* **CActorSiteOpLocalOffset**
			* **CActorSiteOpOrientAttachPointTo**
			* **CActorSiteOpPatch**
			* **CActorSiteOpPersistentOffset**
			* **CActorSiteOpOrbiter**
			* **CActorSiteOpPhysicsImpact**
			* **CActorSiteOpRandomPointInCircle**
			* **CActorSiteOpRandomPointInCrossbar**
			* **CActorSiteOpRandomPointInSphere**
			* **CActorSiteOpRotationExplicit**
			* **CActorSiteOpRotationRandom**
			* **CActorSiteOpRotationSmooth**
			* **CActorSiteOpRotationVariancer**
			* **CActorSiteOpRotator**
			* **CActorSiteOpSelectionOffset**
			* **CActorSiteOpSerpentHead**
			* **CActorSiteOpSerpentSegment**
			* **CActorSiteOpShadow**
			* **CActorSiteOpTether**
			* **CActorSiteOpTipability**
			* **CActorSiteOpTilter**
			* **CActorSiteOpUp**
			* **CActorSiteOpZ**
			* **CActorSiteOpCursor**
			* **CActorSiteOpYawLimiter**
			* **CActorSiteOpPitchLimiter**
	+ **CActorStateMonitor**
	+ **CActorTerrain**
	+ **CActorTurret**