Ghosthande's Metamorphosing Toy Tutorial
First off, download the Metatoy. Extract the files--there are two included, a .c16 file (which is the sprites) and a .cos file (which is the actual script). Put the .cos file wherever you can easily find it, on your desktop for example, and put the .c16 in your Docking Station/Images folder.

This tutorial rates somewhere in between easy and intermediate. Ideally you will have already read through AquaShee's CAOS Chaos tutorials or Sarako's Mac Agenteering tutorial, which are both really excellent starting points for beginners, and should understand the basics of how to create a simple object. If you don't, that's all right, I'll be explaining the basics here too. Those of you who know more about CAOS can feel free to skip parts you are already familiar with; the actual event script section is marked in bold.

To those who are not so familiar with CAOS, there are several programs that you will need to create a new object. These are the CAOS Tool, SpriteBuilder, the PRAY builder and easyPRAY. The former two are used during the object creation process, and the latter two only come into play when you are finished and want to package your new object for other people to play with.

As you follow this tutorial, you will only really need the CAOS Tool. You will not need SpriteBuilder until you decide to make your own object with custom (or at least a different set of) graphics, and of course you won't need the PRAY tools until you're ready to release your new object to the world.

The CAOS Tool is what you actually write the code in. Although it is possible to write your code in Notepad or a similar simple word processor, the CAOS Tool is by far the best tool for the job. It colors all the text, which makes it easy to read, and it colors unfinished or otherwise problematic commands in red. It also has a 'Refresh Syntax' feature which checks your code to make sure there aren't any errors, and an error output feature, listed under the View menu, which will tell you if there are any errors and give you a clue as to what the problem is and even how to fix it.

Shall we begin?
Let's create an install script first:

inst new: simp 2 21 60674 "a00d" 3 0 5000 attr 199 bhvr 43 accg 3 elas 0 fric 100 perm 100 mvto 400 9200 cmrt 0

inst means the rest of the script is going to run 'instantly'--well, it'll run in one tick, anyway. A tick is about one twentieth of a second in length.

new: simp tells the game that it is now going to create a new object, and that the object it will be creating is a simple object. The alternative is a compound object, for example, a machine that has buttons on it.

2 21 60674 is the new object's classifier number. The number 21 identifies this object as a toy. The last number is the species number. Every object needs its own unique species number, because if two objects have the same species number, it can cause some nasty problems in your game. You will need to reserve a range; Moe is the current keeper of reservations over at Creatures Development.

"a00d" is the name of the sprite file that the object is going to be taking its images from. In this case, I have chosen to use sprites for the baby ChiChi Norn's head.

The number 3 signifies how many sprites the object is going to use altogether, and the number 0 indicates the starting image--the specific sprite that the object will be using at the time it is created. In Creatures, sprites are numbered starting with 0, which means that 0 is actually the first sprite, 1 is the second, etc.

5000 is the plane number, which indicates how close the object is to the foreground. If the number is higher, the object will be in front of most other objects, but if the number is very low, the object will be behind most other objects. A value of 5000 means that this object should appear in front of most Norns.

attr is the object's 'attributes' value. A value of 199 means that the object responds to gravity and walls, and can be picked up.

bhvr is the behavior value. #43 means this object can be picked up, hit, activate 1 (pushed) or activate 2 (pulled). Note that you must define the scripts that the bhvr indicates the object will have; if your object does not include a script that the bhvr has indicated should be there, you will receive an error and the object will autokill--meaning it will delete itself. The only exception to this is the pick-up script, which can be safely left out.

accg is the object's weight. I believe it determines how quickly the object falls. Setting this value to a negative number will make an object float upwards like a balloon.

elas stands for 'elasticity'. It determines how much the object bounces. If the object is given an elasticity of 10, it will retain 10% of its original momentum after hitting a surface. A higher number will make the object bouncier, and a lower number will make the object less bouncy.

fric stands for 'friction'. It determines how much the object will slide if placed on a slope. A lower number will make the object more slippery, and a higher number will make it less slippery.

perm stands for 'permeability'. It determines what kinds of surfaces the object will rest on, and which ones it will fall through. The apples in the Norn Terrarium have their permeability set at random, so that some of them fall through the wooden walkway beneath, but others do not. A value of 100 means the object will rest on any kind of surface.

mvto stands for 'move to'. It determines where the object will appear when it is created. The coordinates, 400 (x) by 9200 (y), is where the toy robot appears, on the Norn Meso's heat pan.

cmrt 0 means we want the camera to move to look at the object we've just made. This is helpful if you happen to be in a different room when the object is created; it takes you to where the object is automatically.



At this point, it's a good idea to start building your removal script. This script should be the very last part of your file, but it can be helpful if you add each object and script as you write them, so that you don't forget to do so later. Remember that you need to remove a script before you inject an updated version of that same script, so for testing purposes this needs to already be in place.

Right now, our removal script should be written like this:

rscr enum 2 21 60674 kill targ next

You can remember the rscr command because it sounds like 'eraser', which is exactly what this script does.

enum tells the game that you want it to look at an object belonging to a certain classifier number; the numbers that come after this command are the classifier numbers for our object.

kill targ instructs the game to kill--meaning delete--that object.

next tells it to check to see if there are any more of that kind of object, and repeat the actions specified above. The game will keep checking for and deleting this kind of object until no objects of this type exist in the world.



So now we have an object that looks like a Norn head, and does absolutely nothing. Exciting, isn't it? Well, it will be soon, once we put the event scripts in.

In-between the install script and the removal script, type this:

scrp 2 21 60674 1 endm scrp 2 21 60674 2 endm scrp 2 21 60674 3 endm

These are our three event scripts. scrp stands for 'script'; the first three numbers are our object's classifier, and the number at the very end is the number of the script itself.

1 means that the script is an 'activate1' script, which determines what happens when a Creature "pushes" the object or the hand clicks on it.

2 means that the script is an 'activate2' script, which determines what happens when a Creature "pulls" the object; under normal circumstances the hand can't perform this action.

3 means that the script is a 'hit' script, which determines what happens when a Creature "hits" the object; the hand can't do this either.

endm is the closing command for the script, and indicates that the script has come to an end.

Right now all three scripts are empty, so they don't do anything at all.



Now go back to your removal script, and on the line after the "next" command, type in scrx 2 21 60674 1. On the line after that, type in scrx 2 21 60674 2, and on the line after that, scrx 2 21 60674 3. Each line looks a lot like the beginning of an event script, but with "scrx" instead of "scrp". scrx tells the game to remove the specified script, instead of running it. You don't need to have a "next" after a script removal command, because the game only keeps one copy of each script, so after it's been deleted once, it's gone.

Our object's script should look like this now:

inst new: simp 2 21 60674 "metatoy" 3 0 5000 attr 199 bhvr 43 accg 3 elas 0 fric 100 perm 100 mvto 400 9200 cmrt 0 scrp 2 21 60674 1 endm scrp 2 21 60674 2 endm scrp 2 21 60674 3 endm rscr enum 2 21 60674 kill targ next scrx 2 21 60674 1 scrx 2 21 60674 2 scrx 2 21 60674 3

We can inject the script into the game, if we want. The CAOS Tool has another useful feature, which is the ability to start the game by clicking 'Launch Engine' under the 'File' menu. Or by typing Ctrl+L. I recommend that you create a world specifically for testing objects, so that if something ever does crash your game, you don't lose your favorite Creatures.

There is an option under the 'Inject' menu that says 'Inject Install Script and Event Scripts'. This will create our object in the game, and inject the event scripts into the game so that the object can use it. Another option right above it, 'Inject Install Script', injects the object but none of the event scripts; it's a nifty way of making a second object of the same type, or a third, or a fourth, or...

Go ahead and inject it. Next to the robot toy will appear our object, a toy which looks like a baby Norn's head. You can pick it up or click on it, although nothing will happen; you can try throwing it around to get a feel for how the different settings in the install script affect the object. Once you're finished playing around with it, go back to the 'Inject' menu on the CAOS Tool and click the option that says 'Inject Remove Script'. This will remove our object and its event scripts from the world.





Now comes the fun part of the script, which coincidentally is also the part that makes this tutorial lean toward an 'intermediate' skill ranking. Now we are going to program the event scripts, and make this object a metamorphosing toy like I promised we would.

First let's go back and look at our install script. On the very last line of our install script, type in setv ov10 1.

The command setv tells the game that we are setting a variable; the rest of the code establishes that the variable ov10 has a value of 1. Note that ov-class variables don't have a set meaning. They're just floating out there, waiting for you to use them for whatever you want.

Our next step is to tell the game what to do with the variable we've just set. So let's go to our 'activate1' script. This is the "push" command for a Creature. What we're about to put in it will actually be going into the 'activate2' script, but since the hand can't perform the 'activate2' action, we're going to use the 'activate1' script for now. That way we can test the object without having to use a Creature for a guinea pig.

In your 'activate1' script, type this:

scrp 2 21 60674 1          doif ov10 eq 1                   anim [0 1 2]                   sndc "cp_2"                   setv ov10 2          else                   anim [2 1 0]                   sndc "cp_2"                   setv ov10 1          endi endm

Note that I've indented the text here, because it makes "if" statements like this a lot easier to read.

doif means 'do the following if', ov10 is the same variable we set as 1 in our install script, eq means 'equal to', and of course there is the number 1.

When you read it like a sentence, it means, "do the following (starting at the next line) if ov10 is equal to 1." Because we stated in our install script that ov10 is equal to 1, the code after this line will be run when the hand clicks on the object.

anim means 'animation', and the numbers in the brackets are the numbers of the sprites that are used for the animation, listed in chronological order.

sndc is a command that means we are going to play a sound file; "cp_2" is the sound used by the Commedia when it transforms into something, but you can substitute it for a different sound file if you want to; look through your Docking Station/Sounds folder and pick whichever one you like.

setv ov10 2 is just like the command we used in the install script, except we are defining the variable ov10 as the number 2, when it was equal to 1 before.

else refers back to our "doif' statement; it means, "if the doif command is not true". The doif command states "if ov10 is equal to 1", so logically "else" means "if ov10 is not equal to 1".

When would ov10 not be equal to 1? It is defined as 1 at the very beginning, so the first time we click on it, that doif statement is true. When the code following it is carried out, one of the things that happens is that ov10 is set to 2. So in other words, "else" indicates what will happen the second time the object is activated.

Like the "doif" statement, our "else" is followed by an animation, a sound effect, and a setv statement. This time it reads setv ov10 1, just like in the install script; it sets ov10 back to its original value of 1. This means that the next time the object is activated, the "doif" statement will be true again. We have just created an event that changes every other time it occurs!

Our next step is to test the object in-game, to make sure this part of the code works. Testing an object a little at a time is a great strategy, because it allows you to detect and solve problems as they arise, rather than at the end when you've already written all the scripting and must try to determine where the problem lies. Click 'Inject Install and Event Scripts' from the 'Inject' menu. Click on the object; the expression goes from normal to angry, and when you click a second time, it returns to normal. Then go ahead and remove it again.

Copy the code we just wrote in the 'activate1' script, and paste it in the 'activate2' script; we know it works, so now we're going to make the second major part of our object: the 'activate1' code.

In your 'activate1' script, type this:

scrp 2 21 60674 1          doif ov10 eq 1                   stim writ from 97 1                   anim [0 1 2 1 0]                   sndc "cp_2"          else                   stim writ from 97 1                   anim [2 1 0 1 2]                   sndc "cp_2"          endi endm

Like before, the "doif" statement relies on the variable ov10, but the command that would change the value at the end is not included; it could be, and other variables could be incorporated within the "doif" and "else" to make all kinds of different things happen, but for this tutorial I decided to keep things simple.

Most of the code is the same as that used above, except for the line stim writ from 97 1. What is this? It is actually the part of the code that rewards a Creature for playing with the toy. stim writ from is the standard command for "give Creature a stimulus", while 97 is the number of the stimulus in question (in this case, the stimulus is "played with toy") and 1 is its intensity.

In this example, the only thing that's different between the actions for the two modes we've established is the animation, but you can also use different sound effects, or give the object completely different behaviors.



Up until now, I've chosen to leave the 'hit' script empty. Setting bhvr to 43 happens to require you to include a 'hit' script, but by leaving it empty you can still ensure that nothing happens if a Creature tries to hit the option. This won't prevent Creatures from trying, however; if you want to discourage Creatures from wasting their time by trying to hit your object, you can put stim writ from 0 1 inside the 'hit' script. This gives Creatures the stimulus 0, which is "disappointment".



By now, the object's script should look like this:

inst new: simp 2 21 60674 "metatoy" 3 0 5000 attr 199 bhvr 43 accg 3 elas 0 fric 100 perm 100 mvto 400 9200 cmrt 0 scrp 2 21 60674 1          doif ov10 eq 1                   stim writ from 97 1                   anim [0 1 2 1 0]                   sndc "cp_2"          else                   stim writ from 97 1                   anim [2 1 0 1 2]                   sndc "cp_2"          endi endm scrp 2 21 60674 2          doif ov10 eq 1                   anim [0 1 2]                   sndc "cp_2"                   setv ov10 2          else                   anim [2 1 0]                   sndc "cp_2"                   setv ov10 1          endi endm scrp 2 21 60674 3          stim writ from 0 1 endm rscr enum 2 21 60674          kill targ next scrx 2 21 60674 1 scrx 2 21 60674 2 scrx 2 21 60674 3

We are now finished with the creation process!
You may now inject the object into your world for your Creatures to play with.

If at some point you choose to redistribute it for others to use in their worlds, just make a note of all the custom-made files that your object uses, the stuff that other people won't already have in their games. Download PRAY Builder and easyPRAY, and use easyPRAY to make the files you listed into an agent; I won't go through how to do so here because it's fairly easy and the program comes with its own instructions.



Where to go from here?

A possible next step would be to make an object with three or more options that are cycled through. Perhaps you could make a food that changes from a seed to a fruit to a food and back--three foods in one, to satisfy all your Creatures' cravings. You could also make an object that cycles to a random action each time, instead of going through them in a set order.

Whatever you choose to do, happy coding!

Back to BBW