Events - what they are and how they happen

When something happens in the world, how does your agent know about it? This CDN_article tells you.

---

An event script is something that gets run when a certain condition is valid - in this way we say that all objects are event driven ... they wait for some kind of signal and respond to it. The type of signal can be a click by a user, an activation from a creature, a periodic timer signal or even a trigger from another agent.

Take a look at some of the example COS files in the tutorial section and you will how event scripts are defined, they start with:

scrp <family> <genus> <species> <event>

and finish with:

endm

And in between these two lines you put all code for what you want to happen when this event is triggered.

The <family> <genus> <species> part defines for which agents this script is relevant ... and this should obviously match the classifier of the agent concerned. This is usually where the damage caused by clashing CDN_Classifiers arises ... if the agent tries to run an event script that wasn't written for it then it's likely to produce errors (such as trying to animate to poses that don't exist for that agent).

The <event> part is a number - and a complete list of event numbers is contained within the CAOS Language Guide.

So how do these events get called? What decides which event happens?

For some of these events the name of the event given will indicate when it is called. For example, the Pickup event (event number 4) is called whenever an agent is picked up! Some of these events are as a response of a creature deciding to perform an action on the object - and the creature itself decides what action it is going to perform (and so what event script will be triggered).

Common Events

There are some of these events that are used much more than others, and some events that are quite specific to a particular type of object. For now we'll concentrate on those events that are used the most.

Activate 1, Activate 2, Deactivate -
These events are all essential defined as activating an object - pushing it, pressing it, making it work.
These events can all be triggered by a creature - and you define which of these actions is possible by using the BHVR command.
To trigger these events with the hand you need to define the CLAC or CLIK of the object.
To trigger these events from other agents you just need to send it a message to trigger, using a command such as MESG WRIT or MESG WRT+

Hit -
This event states what happens when the agent is hit. This action is usually only performed by a creature, and again you must define that this action is possible using BHVR.
It is possible to trigger this event with hand - using CLAC or CLIK.
Other agents can trigger this event using MESG WRIT style commands.

Pickup, Drop -
These events are triggered whenever the object is picked up or dropped.
For a creature to perform this action you need to specify that with the BHVR command.
For the hand to trigger these events it merely has to pick up the object, or drop it.
For another agent to trigger these events it will need to send a message - and it will then pick up or drop the agent concerned.

Timer -
This event is to allow an agent to respond to a time based signal. Whenever an agent's timer is started using the TICK command it will count down until it reaches zero, at which point this timer event will be triggered. In this way a timer event is normally a result of the agents own agenda, rather than being as a result of an action performed on it by another agent. Of course, you can do things like only start the agent's timer once it has been picked up (i.e. setting a value for TICK in the pickup script).
Timers are started by using TICK <value> where <value> is greater that 0, and are stopped by using <value> equal to 0.

Collision -
Collision events are called on agents that have ATTR set such that they suffer collisions - and only when they make a collision with a wall they can not pass through. Useful data can be obtained within this event, such as the impact velocity (using _p1_ and _p2_) or the direction of the wall that was the cause of the collision (using the WALL command)

Eat -
The eat event is (obviously!) called whenever a creature tries to eat an agent. As usual the fact it can be eaten must be specified with BHVR.
This event be triggered from other agents by using MESG WRIT or by the hand, using CLAC or CLIK ... but primarily it is an event that creatures and agents perform on other agents.

CLAC and CLIK

These two commands are the means by which you define what event will be triggered whenever the hand clicks on an agent.
CLAC is used to define the message that will be sent to the object (and so which event will trigger) ... and this can change throughout the lifetime of the agent.
For example, you could create an object and define CLAC such that a click by the hand will trigger an activate 1 event. But then in that activate 1 event you can change CLAC so that the next click will produce an activate 2 ... and so on. Remember though that CLAC makes no difference to the actions that can be taken on this agent by a creature or another agent ... it is only relevant to the event triggered by the hand.
Care should be taken when defining this, because the format is CLAC but for the early event numbers can be misleading. The CAOS Language Guide has a section detailing the message numbers - and how they relate to events - these are the numbers that should be used to CLAC, CLIK and other commands (such as MESG WRIT). For events not listed in this section the message number is the same as the event number.
CLIK allows you to specify a sequence of events that will be triggered by successive clicks with the hand (in the same way that changing CLAC within an event will produce this effect) ... but has the advantage of only having to specify once. Up to 3 events can be sequenced in this way.

BHVR

Behaviour is the only way to specify which actions a creature can perform on this agent ... the values for BHVR are in the CAOS Language Guide.

MESG WRIT and MESG WRT+

These commands allow you to programmatically trigger an event in an agent, and use the message numbers detailed in the CAOS Language Guide.
MESG WRT+ differs only in that you can pass a parameter into the event script launched - which can be read from that event using the _p1_ and _p2_ variables. One use for this, for example, is to have a general event that will produce a different effect based on the value of something ... this something can then be passed in as a parameter and then the event script can produce the desired effect.

Advanced Event Handling

Looking down the event list in the CAOS Language Guide shows a lot of events not mentioned so far ... and for a lot of agent creation they are not necessary. Here is a brief run-down on those events though:
Events 16-30 -
These events are triggered whenever a creature decides to perform an action and generally script how it will deal with this action and if there is an object involved what to do to it (walk towards it, pickup it up - whatever) and in these you will find a line that triggers the relevant agent script.
Events 32-47 -
These events are triggered whenever a creature decides to perform an action on another creature - and deal with things like mating, tickling etc.
Events 64-72 -
These events are triggered as a response to a creatures involuntary action ... defined within the genetics.
Events 73-79 -
These events are triggered on an agent whenever a key is pressed - and it has the relevant IMSK value set
Events 101-117 -
These events are called on the pointer whenever it performs an action
Event 118 -
An event specific to agents with connecting ports
Event 120 -
Triggered whenever the selected creature changes. This is used mainly by the interface components.
Events 121-122 -
Triggered whenever an agent enters of leaves a vehicle
Event 123 -
Triggered whenever the game window is resized. This is used mainly by the interface components.
Events 124-125 -
Triggered on a vehicle whenever it gains/loses a passenger
Event 126 -
Triggered whenever a creature speaks
Event 127 -
Triggered whenever a creature life event occurs - examples of this are birth, pregnancy, death etc.
Event 128 -
Triggered whenever the world loads. For people familiar with C1 or C2 this is the equivalent of the 'enterscope' event
Event 255 -
Triggered whenever an agent has an invalid TARG error. If this event is not defined for an agent then it will prompt a dialogue box on-screen with the nature of problem

Beyond this you can define your own event scripts - simply by creating an event script with the number you desire, and then triggering it. Certain commands require you to enter an event number, creation of a button (PAT: BUTT) for example requires this so that an event is triggered whenever the button is pressed. This event number specification can be either an existing event such as those listed in the CAOS Language Guide, or a new one specific to the object created.

---

Topic Keywords: agent caos creatures3 dockingstation