Event

An Event is a key Engine Concept in Unreal. (For details on the 'event' keyword in UnrealScript see Function Syntax.)

An "Event" is a type of message sent during the game by one Actor to other actors. Every event has a name, chosen by the mapper or coder. Certain conditions will make an Actor "call" an event; and some Actors are "listening" for a particular event name to be called, and when it does they will react in some way.

Properties

Every actor has two properties under the Events heading:

Event: The name of the Event that this actor can call
Tag: The name of the Event that will make this actor react – in other words, the name of the event that it listens for

You can think of this like a paging system in a hotel lobby: a groom walks through calling out the event name. Any Actor that is set to listen to this event name will respond.

In the UnrealScript code, this actually works with an iterator that looks at every actor in the game. Any actors whose Tag matches the event being called have their Trigger function executed:

function Trigger( actor Other, pawn EventInstigator )

This system effectively ties two or more actors together. UnrealEd helps you keep track of this by drawing a red line between actors with matching Tag and Event properties. You can also list actors by the value of their Tag or Event in the Actor Search window.

The properties themselves can be set to any string. The important thing is the matching, though it helps to use words relevant to the map, eg "MainDoor" or "Explosion".

Some actors expand on this behaviour, and can call or listen for several events: more on this below.

Triggering an Event

Starting an Event is called "triggering", "calling", "initiating" or "firing" it – every mapper or coder has their way of visualizing the process. When an actor actually calls an event depends on how its class script and its properties. The simplest example is the Trigger actor. This calls its Event whenever a player passes through its Collision Cylinder.

All actors whose Tag matches the Trigger's Event will receive the message – we say that they have been triggered. What these actors then do depends, again, on their own class script and their own properties. Some actors will do nothing, some can react, and some can trigger other actors in turn.

It's possible to create complex chains of events like this: see Trigger Systems for examples.

Chain of "Events"

This is what happens when Actors are triggered:

The Trigger

Player Bob walks into the Trigger's radius:

Touch( actor Other )
- IsRelevant( Other ) checks the actor can actually do stuff

The Trigger runs a ForEach iterator, to find matching actors.

A.Trigger( Other, Other.Instigator )

where:

Other is the actor Bob that touched the Trigger.
Other.Instigator is another script chase for another day.

The Target

function Trigger( actor Other, pawn EventInstigator )

So...

Other is the same Other as in Trigger – Bob
EventInstigator is Other.Instigator from before

Dispatchers

These break the chain:

Target.Trigger( Self, Instigator )

in other words, they pass on themselves as the Other for the triggered actor, not the thing that touched the Trigger that then triggered the dispatcher. This causes problems with, for example the BumpButton state in movers. See Dispatcher for a fix.

Continuous Events

So far, an Event is a discrete occurence. The player walks into the Trigger, something happens. But Events are technically continuous: they don't end until the player walks out of the Trigger radius.

For most setups, the length of the event is irrelevant. For example, most doors are set to start opening when Triggered, wait when fully open, then close: once Triggered there's no way to affect them. From this point of view, an Event is instantaneous.

However, some actors will respond to being UnTriggered. A door whose InitialState is "TriggerControl" will start opening when triggered, but will start closing as soon as the player steps out of the Trigger's radius. A good example of this behavious is the door to the Redeemer in UT's DM-Stalwart-XL.

Just remembered... Triggers can also be set to repeatedly send the trigger message... sort of repeating discrete events.... the plot thickens!

Technical

Functions to cover:

Trigger()
UnTrigger()
Touch()
UnTouch()

In terms of mapping, an event is a combination of certain circumstances which occurs during the game and especially a string which represents the event for Unreal. This could be player touching a Trigger or an opening door.

Mention built-in events too.

Actors that call an event when touched

Trigger: This is the main actor for calling an event. It can be set to react when a player, pawn or indeed any class walks into its collision cylinder or when it suffers a certin amount of damage from being shot.

Actors that process events

These actors are not affected by players passing through their collision cylinder.

Dispatcher : this calls a list of events, with an optional delay between each call.
RoundRobin : each time this is triggered it calls the next event in a list

(note this isn't a complete list, just some of the important ones)

Actors that listen for an event

The Trigger actor itself can be set to wake up or go to sleep when triggered by something else.

(note this isn't a complete list, just some of the important ones)

Troubleshooting

Even simple chains of events can be hard to get right. Only actors that set events and tags in the "Event" section are linked with red lines in the editor, so actors such as Dispatcher are somewhat harder to troubleshoot.

Suggestions:

Use the CAUSEEVENT console command (in PlayerPawn; you must be a server admin). It calls Trigger on all actors with the tag given as a parameter.
Test the chain of command: give the first Trigger that players walk into a message, and test it in game. You should see the message.
If an actor that is being trigerred is capable of sending a player-visible message (eg SpecialEvent), set it up so you can see in game whether it has been triggered.
If triggered movers or pawns don't work, create a SpecialEvent that listens for the same event & set it to broadcast.

Discussion

Unknown: How does Trigger deal with a situation when more than 1 player walks into the radius? Which player makes UnTrigger occur by leaving?

Birelli: Think of it as every player inside the radius is "holding open the event", the event in this case starts when any player enters the Trigger radius and is UnTriggered when there are no players left inside the radius of the trigger.

SuperApe: Edited. Refactored some.

Category Troubleshooting

Category To Do – Answer questions, fill in. Related with Tag.