The TARG Object

A lot of CAOS commands operate on a targ object - and expect it to exist - so you can imagine targ as a 'focus' point for commands. For example, the command `pose 1` changes the pose of an object to image number 1 - but which object? That is where targ comes in. There can be only one targ at any time but you are free to change targ as often as you like, and there exists certain pointers that allow easy changing of targ (or you can make your own pointers using the variables within the language, but we can come to that later!).

The list of pointers that are available in the language includes (but isn't limited to):

from - the from object is a pointer to the object that caused this event to occur. This event is the one in which the from is used, and an example would be: A ball gets activated by a creature - during the balls activate script the from object will be a pointer to the particular creature who caused this to happen ... the creature who activated the ball.

ownr - the ownr object is a pointer to the object that is currently running this script. This script is the one in which the ownr is referred to and, using the example above, during the execution of the ball's activate script - the ball is the ownr.

norn - this is a pointer to the currently selected creature on the Creatures Menu of the game.

pntr - this is a pointer to the hand object, the in-game representation of the user.

_it_ - this is a pointer to the object that a creature is looking at. This can only be determined from within that particular creatures scripts. For example, from within the ball activate script it is impossible to find out what a particular creature is looking at - but from within one of the creatures scripts it is possible.

carr - a pointer to the object that is carrying the ownr. For example, if the creature picks up the ball - then during any of the balls scripts it will have a value for carr that refers to the creature.

So how do these pointers relate to targ? During the execution of an event script the targ object is by default the ownr of that script (there are certain events where this isn't the case - but as a general rule it works).
So, for example, during the ball's activate script you can use the command `pose 1` and know that the command will operate on the ball. Later in the script you could change to another targ - maybe to find the location of the creature who activated it - but from that point onwards the targ is no longer the ownr. Changing targ in this way is accomplished using `targ` , where refers to some other object.

For example, in the example above we've made the ball change pose and now we want to find the location of the creature that activated it - we can use `targ from` to change targ to the creature, and then we can use other CAOS commands to get information about it.

Other commands that change targ include:

new: - after every new: command the targ object is that object that has just been created - this allows you to alter its characteristics, attributes etc.

enum, esee, etch - these commands will enumerate across all objects that match their specified criteria and change targ to each one that matches in turn. For example, `enum 2 1 10000 pose 1 next` will find the first object matching the criteria family 2 genus 1 species 10000 and make it targ. Once it is targ it will then perform the command `pose 1`, and then perform the `next` command. The `next` command means that if there is another object matching the criteria then control flow will go back to the `enum` with the new object as targ. If there are no more objects matching the criteria, targ will be set to ownr after the next command.

rtar - this will randomly chose an object that matches the criteria given and make it targ. If no such object exists then targ will be set to null

Great care must be taken when changing targ within a script because this is the number 1 reason for a script crashing - a command is trying to operate on an incorrect targ, either because the programmer changed targ away from ownr and forgot to set it back ... or because targ doesn't exist and the programmer tried to perform commands on an object that's not there.

This second case is catered for within the CAOS language, and if you try to change to a targ that doesn't exist you will cause an exception event to occur (#255) and within this you can make provisions for what to do if targ is lost. For example, you have a bird agent (bird1) that chases flies - it has routines for choosing a fly, homing-in on the fly and then eating the fly. But imagine if inbetween choosing and homing-in another bird (bird2) eats that fly. When bird1 starts to look for the fly, to find out where it should move to, it would presumably change targ to the ID of the fly it had chosen and get it's location - but this targ doesn't exist and trying to get the coordinates of it would raise an exception. You would deal with this situation by writing an exception event that said something like 'go back to choosing a fly'.

We'll finish this tutorial by saying that a lot of objects can be made that do not change targ at all ... so if none of this tutorial has made any sense to you DON'T WORRY! You can still make objects and you can file this particular topic away until you have got to grips with how to use the language.