Overview
All transitions between States are triggered by Events.
There are 2 main types of Events:
- System Events: Sent automatically by Unity/PlayMaker; cannot be edited or deleted.
- User Events: Custom events that you can use however you want.
Use the Event Manager to add/edit/view Events.
System Events
System events are sent automatically by Unity/PlayMaker. Many of them map to standard MonoBehaviour events. Others map to newer Unity systems (e.g. the UI System).
By convention, system events are capitalized.
Core Events
NOTE: "game object" refers to the game object that owns the FSM.
Event | Description | Unity Docs |
---|---|---|
START | Sent when the state machine is enabled. | N.A. |
FINISHED | Sent when all actions on the active state have finished. See Actions. | N.A. |
LEVEL LOADED | Sent after a new level is loaded. | OnLevelWasLoaded |
BECAME VISIBLE | Sent when the game object becomes visible by any camera. | OnBecameVisible |
BECAME INVISIBLE | Sent when the game object is no longer visible by any camera. | OnBecameInvisible |
Physics Events
NOTE: After a COLLISION or TRIGGER event you can use GetCollisionInfo, GetTriggerInfo, or GetControllerHitInfo to get more info on the collision/trigger event.
COLLISION ENTER | Sent when the game object first collides with another object. | OnCollisionEnter |
COLLISION EXIT | Sent when the game object stops colliding with another object. | OnCollisionExit |
COLLISION STAY | Sent while the game object is colliding with another object. | OnCollisionStay |
TRIGGER ENTER | Sent when the game object enters a trigger volume. | OnTriggerEnter |
TRIGGER EXIT | Sent when the game object exits a trigger volume. | OnTriggerExit |
TRIGGER STAY | Sent while the game object stays inside a trigger volume. | OnTriggerStay |
CONTROLLER COLLIDER HIT | Sent when the character controller on the game object collides with an object. | OnControllerColliderHit |
COLLISION ENTER 2D | Sent when the game object first collides with a 2D Collider. | OnCollisionEnter2D |
COLLISION EXIT 2D | Sent when the game object stops colliding with a 2D Collider. | OnCollisionExit2D |
COLLISION STAY 2D | Sent while the game object is colliding with a 2D Collider. | OnCollisionStay2D |
TRIGGER ENTER 2D | Sent when the game object enters a 2D Trigger. | OnTriggerEnter |
TRIGGER EXIT 2D | Sent when the game object exits a 2D Trigger. | OnTriggerExit |
TRIGGER STAY 2D | Sent while the game object stays inside a 2D Trigger. | OnTriggerStay |
PARTICLE COLLISION | Sent when a particle hits a Collider. See unity docs for more info. | OnParticleCollision |
JOINT BREAK | Sent when a Joint attached to the same game object breaks. | OnJointBreak |
JOINT BREAK 2D | Sent when a Joint2D attached to the same game object breaks. | OnJointBreak2D |
Mouse Events
TIP: Mouse Events are mainly used to interact with GameObjects with colliders. To use the new Unity UI system see UI Events below.
MOUSE DOWN | Sent when the mouse clicks on the game object. | OnMouseDown |
MOUSE DRAG | Sent while the mouse button is down and over the game object. | OnMouseDrag |
MOUSE ENTER | Sent when the mouse rolls over the game object. | OnMouseEnter |
MOUSE EXIT | Sent when the mouse rolls off the game object. | OnMouseExit |
MOUSE OVER | Sent while the mouse is over the game object. | OnMouseOver |
MOUSE UP | Sent when the mouse button is released over the game object. | OnMouseUp |
MOUSE UP AS BUTTON | Sent when the mouse button is released over the same GUI Element or Collider it was pressed on. | OnMouseUpAsButton |
NOTE: If you're using the new Input System, Unity will not send these Mouse Events. Instead, make sure you have an EventSystem with an InputSystemUIInputModule in the scene and a PhysicsRaycaster or Physics2DRaycaster on your Camera, and then use the UI Events below. E.g., Use UI POINTER DOWN instead of MOUSE DOWN.
Application Events
APPLICATION FOCUS | Sent when the Application gets focus. |
APPLICATION PAUSE | Sent when the Application is paused. |
APPLICATION QUIT | Sent right before the Application quits. |
UI Events
NOTE: The owner GameObject needs the appropriate UI Components for the FSM to get these UI Events. If you want to get UI events from other GameObjects use UI Actions.
UI CLICK | Sent when a Button is pressed. Game object needs a Button component. |
UI BEGIN DRAG | Sent before a drag is started. |
UI DRAG | Sent every time the pointer is moved during dragging. |
UI END DRAG | Sent when a drag is ended. |
UI DROP | Sent when an object accepts a drop. |
UI POINTER UP | Sent when a mouse click is released. |
UI POINTER CLICK | Sent when a click is detected. |
UI POINTER DOWN | Sent during ongoing mouse clicks until release of the mouse button |
UI POINTER ENTER | Sent when the mouse begins to hover over the GameObject. |
UI POINTER EXIT | Sent when the mouse stops hovering over the GameObject. |
UI BOOL VALUE CHANGED | Sent when a Toggle value changes. Game object needs a Toggle component. Use Get Event Bool Data to get the value. |
UI FLOAT VALUE CHANGED | Sent when a Slider or Scrollbar value changes. Game object needs a Slider or Scrollbar component. Use Get Event Float Data to get the value. |
UI INT VALUE CHANGED | Sent when a Dropdown selection changes. Game object needs a Dropdown component. Use Get Event Int Data to get the value. |
UI VECTOR2 VALUE CHANGED | Sent when a ScrollRect value changes. Game object needs a ScrollRect component. Use Get Event Vector2 Data to get the value. |
UI END EDIT | Sent when when editing of an InputField has ended. Owner needs an InputField component. |
User Events
User events are usually named for clarity: Open Door, Turn On, Turn Off etc.
You can make and edit these events in the Event Manager.
Sending Events
There are a few ways to send events to an FSM:
- Using Actions
- Using Animation Events
- Sending event from scripts.
Sending Events From Actions
The most basic Actions to send an event:
Other Actions send events based on conditions:
Events are essential to the flow of an FSM, so many actions send them.
Global Events
Events can be marked as Global in the Event Manager. Global events can be sent between FSMs.
Do not confuse Global Events with Global Transitions.
Event Data
You can associate data with an event using Set Event Data. For example, you could set the amount of damage to inflict with a Do Damage event.
You can get information and data associated with an event using Get Event Info. For example, you could read the amount of damage associated with a Do Damage event.
Infinite Loops
PlayMaker lets you chain together multiple states in a single frame. E.g., An event can trigger a state transition; the new state can run some actions and send another event and so on... all in one update.
This is useful for doing a lot of work in a single frame, but sometimes you can accidentally create infinite loops that would crash Unity!
As a precaution, if a loop exceeds 1000 iterations PlayMaker will stop looping and log an error.
If it's your intention to loop more than 1000 times you can override this limit in the FSM Inspector.
However, if the loop is unintentional, you can use a Next Frame Event to break out of the infinite loop. This tells PlayMaker that you've finished work for this frame, and should continue in the next frame.
Example:
These states create an infinite loop:
After Add Force we transition back to MousePickEvent, but the mouse button is still down, so we go back to Add Force, but the mouse button is still down... an infinite loop!
You can break out of the infinite loop with a Next Frame Event:
The Next Frame Event waits until the next frame to send the FINISHED event.
In the next frame, if the mouse button is still down we return to Add Force, if it was released we stay in the MousePickEvent state.
Animation Events
You can use Unity's Animation window to send events to PlayMaker FSMs.