Event Scripts

Now we're ready to start writing the scripts for this agent, so let's start thinking about event numbers.

Like I said previously, event scripts start with a SCRP line. The SCRP line lists the agent's classifier, which tells the game which agent the script belongs to, and the event number, which identifies what kind of event the script is used for. There are tons of event numbers used by the game, and these are listed in the CAOS Documentation, but most developers only ever use a small handful of these numbers.

Here are some of the most commonly used event numbers:

#	Nickname	Used when?
1	Activate 1 / Push	When the agent is pushed by a Creature or other agent, or the pointer clicks on it.
2	Activate 2 / Pull	When the agent is pulled by a Creature or other agent, or (in certain conditions, if the agent is coded that way) when the pointer clicks on it.
3	Hit	When the agent is hit by a Creature or other agent.
4	Pick Up	When the agent is picked up, eg. by a Creature or the pointer.
5	Drop	When the agent, having already been picked up, is dropped.
6	Collision	When the agent collides with a hard surface, eg. after falling to the ground.
9	Timer	How the agent acts in response to the passage of time.
10	Constructor	A special script that is automatically called when the agent is created. Some developers use this script to store code that would otherwise go in the install script. DS only; this script doesn't run in C3.
12	Eat	When a Creature, or other agent, attempts to eat this agent.

When we set the Banshee dolly's BHVR, we told it that it could be pushed, pulled, hit and picked up by Creatures, that it could be clicked and picked up by the pointer, and that it would Suffer Collisions. For now, though, we'll focus on just the activate and hit scripts.

Activate and Hit Scripts

A few lines under our install script, but still above our remove script, we'll start to write out the Banshee dolly's Activate 1 script.

There are two actions called "activate" in the game: Activate 1 and Activate 2. Creatures refer to these actions as "push" and "pull" respectively. The Activate 1 script controls what happens when a Creature pushes the agent, and the Activate 2 script is what happens if the Creature pulls it instead.

Remember how an event script begins with SCRP, and ends with ENDM? That's the part we write next. SCRP is, interestingly, not listed in the CAOS Documentation. If it was, its entry would probably look something like this:

SCRP (command) FAMILY (integer) GENUS (integer) SPECIES (integer) EVENT (integer)

The SCRP command it takes the family, genus and species of the agent (its classifier), and then the number of the event script. So our Activate 1 script will begin and end with the following lines:

scrp 2 21 60659 1
endm

What an agent does when it is activated depends largely on what you want it to do. I'm going to show you how to make the Banshee dolly do the following:

• Tell the Creature to reduce boredom because it's played with a toy
• Make a noise
• Play an animation

Played With Toy

Older creatures games injected chemicals and adjusted drives in the Creature's body, but we don't do it that way in C3/DS. Instead we use something called stimuli. A stimulus is essentially a "package" that adjusts multiple chemicals and drives a certain way. Creatures in C3/DS can't learn to associate direct chemical or drive changes with an object—it only works for stimuli. Because of this, and because Creatures can't distinguish agents within the same category, we try to be careful to use appropriate stimuli in a predictable way.

We send a Creature a stimulus using the STIM WRIT command. This command takes three parameters: a reference to the Creature we're going to send the stimulus to, which stimulus we want to use, and how strong the stimulus should be.

You can see a list of Stimulus Numbers in your CAOS Documentation. The stimulus 97, nicknamed "played with toy", tells Creatures "you have just had fun!" and reduces their boredom somewhat.

We can go ahead and give the Creature a stimulus strength of 1, which is typical for playing with toys. But how to we target the Creature?

We can't use TARG in this case, because an event script automatically targets the agent it's running for. So we would be stimming the Banshee dolly itself. In order to get the thing that prompted the script to run—the agent that pushed the toy—we use the variable FROM. So our stimulus line should look like this:

stim writ from 97 1

Make a noise

If stimuli seem complicated, don't worry: making an agent play a sound effect is super easy!

The sound effect I used for the Norndolls is called "bdrp.wav". If you don't have it in your game's Sounds folder already, you can download it here. I like use it for plush toys because it is a soft, fabric-y kind of sound.

The way to make an agent play a sound effect is with the SNDC command, which only needs one parameter: the name of the file to play. Just like with the name of the sprite file, we put quotes around it, and the file extension (.wav) is left off, like so:

sndc "bdrp"

Play an animation

The last thing we want the Banshee dolly to do is play an animation. As far as I'm aware, Creatures can't actually perceive sprite animations. They just add some visual interest for the player.

In Creatures, the order of frames in an animation isn't determined by how they are ordered in the sprite file. Instead the animation is triggered and controlled by the ANIM command. This command uses square brackets to list the sprites that are going to play in the animation. So a basic animation line might look like this:

anim [1 2 3 4 5]

Just like in SpriteBuilder, sprite numbers are counted upward from zero, so the first sprite used by the agent is considered sprite 0, the second is sprite 1, and so on. The animation above plays five frames, skipping the first one.

The Banshee dolly has fifteen sprites, but these sprites represent three different animations. Only the first five sprites form the "I've been played with" animation. Knowing that the first sprite counts as zero, can you guess which numbers we use for the ANIM line?

We could do something like this:

anim [0 1 2 3 4]

Sprite 0 is the default "resting" sprite, and sprite 4 is the end of the play animation, where the dolly's arms are up in the air. If we use the animation just like that, the dolly will stay that way after it is played with. It looks a bit funky... like he's saying "gimme a hug!"

To make the dolly return to its normal resting position, all we have to do is add the same numbers to the end, but in the reverse order. Like this:

anim [0 1 2 3 4 3 2 1 0]

Now the dolly starts out in the normal resting pose (0), lifts its arms like it is being played with (4), and then goes back to the resting pose (0).

The finished Activate 1 script should look something like this:

scrp 2 21 60659 1
stim writ from 97 1
sndc "bdrp"
anim [0 1 2 3 4 3 2 1 0]
endm

Now that we've added our first event script, we should add the following line to our remove script at the end of the file. To do this, just add a line that says "SCRX", then lists the agent's classifier, and lastly the script's event number. Like so:

scrx 2 21 60659 1

You can inject the agent into the game if you would like to see your work in action. Creatures still can't play with it at this point, but you can click on it to see what happens.

The Activate 2 Script

There are two ways to go about making the "pull" and "hit" scripts. The easiest way is to just copy-paste the Activate 1 script and change the Event Number. But if pushing and pulling an agent do the exact same thing, and the scripts are longer than just three lines, there are alternatives.

For instance, this is how I might write out an Activate 2 script, if I didn't want to write out the same thing twice:

scrp 2 21 60659 2
stim writ from 97 1
mesg writ ownr 0
endm

It's a bit silly when the original script was only three lines long, but it can be very useful for an agent with more complicated interactions.

MESG WRIT is a command that tells an agent to run a certain script. We're sending the message to the OWNR, which is the agent using the script. In other words, the Banshee dolly is talking to itself. The zero is a Message Number—you can find a list of those in the CAOS Documentation. 0 is the number for the Activate 1 script.

Notice that I've left the STIM WRIT line there. This is because we still need to let the Creature know it's played with a toy. The STIM WRIT line in the Activate 1 script can't stim him if it has been called this way: since the Banshee dolly called its own Activate 1 script, the "FROM" will be listed as the Banshee dolly. We don't care that it will end up stimming itself—that can't hurt anything—we just want to make sure the Creature gets the right feedback if it pulled the toy, and this does the trick.

The Hit Script

For the hit script, we do want it to do something a little different. So we'll start by copying and pasting the Activate 1 script. We'll change the Event Number to 3 for "hit".

There is no stimulus for "hit toy", but we could use 44 ("I hit someone"), 87 ("hit critter") or 92 ("hit machine"). According to the Creatures Stimuli Notes, "hit machine" only gives Grendels boredom and doesn't affect normal Norns at all, so it's probably less useful.

Since this isn't just some friendly playing, we can also reflect that by changing the sound effect from "bdrp" to "spnk", which is the slapping noise Norns, Ettins and the pointer make when they hit something.

You can see the new hit script with the changes I've made highlighted.

scrp 2 21 60659 3
stim writ from 87 1
sndc "spnk"
anim [0 1 2 3 4 3 2 1 0]
endm

At this point the agent has all the Event Scripts it needs for Creatures to interact with it, so you can go ahead and remove the apostrophe (*) from the BHVR line. It's ready for some Grendel glomping.

Our remove script should also be pretty well populated by now. Don't forget to add lines whenever you write a new script, or it won't remove old code versions, and attempts to preview and test the agent won't work out so well.

Pickup, Drop and Collision Scripts

The pickup, drop and collision scripts can be thought of as a sequence of events: a Creature or the pointer picks up the Banshee dolly, then drops the dolly, and the dolly collides with the ground.

Creatures 3 and Docking Station have default scripts to allow Creatures to pick up and drop agents, at least assuming those agents have the correct BHVR to allow it. The same is true for collision scripts. You don't actually need to write these scripts yourself. We're only writing them because we want to be able to have our own animations and sound effects play.

For our pickup script, we need to stim the Creature with "Get" to tell them that they've picked something up, and animate the dolly. The five frames after the "activated" animation form the "I'm being picked up" animation. I'm also going to make it play the "bdrp" sound effect, just because.

Think you can write the "pickup" script on your own? You probably can— you've already used all the commands you need. But if you're not certain, I won't begrudge it if you want to check your answer.

As far as our drop script is concerned: we aren't making the Banshee dolly do anything specific right when it's dropped, so there's no reason to write one. If we were, though, we would just want to make sure it stimmed the Creature with stimulus 19 ("I dropped it").

The last script we need to write for the agent is the collision script. This script doesn't need to stim anybody, since the Creature that may have dropped it isn't directly involved with the agent anymore. Typically, an agent plays a sound effect when it hits the ground, and for the Banshee dolly we might want to animate it so that it goes back into the sitting position. To do the latter, we can use the exact same animation , but use those numbers in the reverse order.

I'm certain you can do this on your own by now, but you are still welcome to click here if you'd like to see an example.

Using Conditions

You may have noticed already that the Banshee dolly sprite file contains 15 frames, but we've only used ten of them so far.

If you test the Banshee dolly with a Creature assistant (or assistants), you'll see that when someone pushes or pulls the dolly while it is being held, it jumps back to the "sitting" pose when it animates. It looks kind of strange! That's what the last five frames in the sprite file are for: they represent an alternate animation that we can use when the agent is pushed or pulled, if it is being held at the time.

Remember what our Activate 1 script looks like?

scrp 2 21 60659 1
stim writ from 97 1
sndc "bdrp"
anim [0 1 2 3 4 3 2 1 0]
endm

We're going to use something called a condition—also known as an "if statement"—to give the Banshee dolly different options in how it can behave. A condition is just a block of code that says "if this happens, do X... otherwise do Y".

A condition has three basic components: a DOIF line that means "if this condition is true, then...", an ELSE line which shows what the alternative is if the condition wasn't met, and an ENDI line to tell the game that our condition is finished.