The first thing you need to know, before you begin coding an agent, is how to identify it in CAOS.
Every agent type in the game is identified by a classifier, a series of numbers that distinguishes it from any other kind of agent. So what we might call a "beach ball", and Brux calls a "toy", the game recognizes by its classifier, "2 21 60661".
Anything that has scripts, or a physical presence in the world, has a classifier. Not just regular items like food, critters and machinery, but also the cursor, the favorite place icons, and the game's inventory window. Yes, even Brux: male Grendels have the classifier "4 2 1".
Classifier parts
The first number in a classifier is referred to as the family, and the second is the genus. Together, these two numbers indicate what category the object belongs to. Creatures can only distinguish objects based on their category: for example, all agents whose classifiers start with "2 21" will be referred to as "toys" by Creatures, regardless of whether they are balls that bounce, tops that spin, electric guitars that play music, or any other kind of toy. You can find a full list of agent categories here.
The third number in an agent's classifier is called the species. This is how the game distinguishes agents from one another even when they belong to same category (such as an electric guitar from a beach ball). The blue and yellow ball from Creatures 3 has a species of 6, the Fun In The Sun beach ball has a species of 60661, and so on.
Classifier clashes
Agents are linked to their scripts based on their classifier. If a Norn hits the Creatures 3 ball, the game knows to use the "I've been hit" script for the agent with the classifier "2 21 6". If two different kinds of agent have the same classifier, the game will think they are the same kind of agent and try to use the same scripts for both of them. This is called a classifier clash.
Note that the whole classifier is what needs to be unique, not just the species number. If I made a new toy and gave it the classifier "2 21 60661", it would clash with the Fun In The Sun beach ball, which already has the classifier "2 21 60661". But I can use the classifier "2 8 60661" for a slice of watermelon, and that's just fine because the beach ball is a toy (2 21) and the watermelon slice is fruit (2 8). Because they belong to different categories, they don't conflict with each other.
To make sure developers don't use the same classifiers by accident and cause conflicts with each other's agents, we reserve species numbers for ourselves (called "script ranges") and only use those numbers.
If you are a new developer then you probably haven't reserved a range yet, but that's okay. For this tutorial you won't need to. I'm giving the Banshee dolly a classifier of 2 21 60659. Feel free to use that same classifier as you follow along with the tutorial. You can reserve a script range of your own once you're ready to start making your own original agents.
At this point you should understand the basics of classifiers, so we're going to look at some of the specifics about the different kinds of scripts that agents use.
Now that we know what we'll be writing, let's get our programs set up.
There are a few things we want to do to help us get ready before we start using the CAOS Tool.
I recommend keeping the CAOS Categorical handy when you code. It is a reference to all the CAOS commands in the game, so it is invaluable for any developer. It's a bit technical so it probably won't make much sense the first few times you look at it, but we will look at some of the entries as we go along to explain what they mean.
When you're ready to start coding, start up your game and get situated. I recommend starting in a new world that doesn't have any Creatures you're attached to, so that you won't have any distractions. And if you do mess something up somehow, you won't have any qualms about deleting that world and starting over.
Useful note: if you're running Windows 7, Vista, or any other version of Windows that has User Account Control, remember to run both Creatures 3 or Docking Station (whichever you're using) and the CAOS Tool in administrator mode while you are developing. Otherwise they may have problems "talking" to each other.
The most important thing you need to do once your game is running is to disable Autokill.
What is Autokill?If you look at the very top of the window, you will probably see that it says something like "Autokill enabled". Autokill is a feature that automatically removes (kills) any agent that experiences an error. Autokill is used during regular gameplay to prevent the game from being interrupted.
Autokill must be disabled when you are coding, because you need to be able to see any errors your agent makes in order to troubleshoot them. Even the best coders will not be able to tell you what's wrong with an agent just from the fact that Autokill removed it. Error messages are the key to solving any kind of problem you might encounter.
To disable Autokill, you need to bring up the Wolf Controls. You can make the Wolf Control window appear using the keystroke Ctrl + Shift + W. It will look like this:
As you can see from the window above, the keystroke that turns Autokill off is Ctrl + Shift + A. From what I've heard, some versions of the game allow you to toggle Autokill without having to open the Wolf Control window. Others, like mine, require the Wolf Control window to be open first. Be aware that Autokill will not stay off permanently: it turns itself back on whenever you start up the game.
With your game running, the CAOS Documentation open (hopefully), and Autokill disabled, you are ready to begin coding.
The CAOS Tool can interact with your game if both programs are running simultaneously. By default, the CAOS Tool expects that you will be using it with Creatures 3. If you plan on developing for Docking Station, make sure that Docking Station is already running the first time you run the CAOS Tool. The CAOS Tool will check to see if either game is running, so it will recognize that you want to develop for Docking Station and change its settings accordingly. You will know that this has happened because the CAOS Tool's title bar will say something like "CAOS 1.002 - Docking Station". In the future it will remember which game you use.
You'll notice that in addition to the menu, the CAOS Tool comes with a whole lot of buttons. Hovering your mouse over one of the buttons will bring up some text explaining what the button does; a longer explanation will appear at the bottom of the window, where it says "Ready" in the screenshot.
The first ten buttons are features common to most text editors, such as New, Save, Cut, Paste, and so on. The last button, with the yellow question mark, simply brings up some information about the program. The five buttons before it are the most important functions of the program, the ones that give it a huge advantage over plain text editors like Notepad.
On the menu go to View -> Error Output Window, which will make a smaller window appear inside the CAOS Tool. Now let's start coding!