Understanding Classifiers

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.

How Scripts Work

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.

• The Install script is what we call any code that appears at the beginning of a .COS file. The install script is the script that runs when the user clicks the 'inject' button. That usually means installing the agent itself, but in reality you can put just about any kind of code at the beginning of your .COS file and it will run when the agent is injected—even if it does something completely different, like deleting an agent, making the cursor invisible to Creatures, or moving all Norns to the incubator area.
• The Remove script appears at the very end of the .COS file, and it begins with the command RSCR, which tells the game "the remove script starts from here and ends at the end of the file". Most agents have very straightforward remove scripts that delete the agent and remove their event scripts from the game. But you can also perform some other actions, like moving agents or Creatures, making the cursor visible again, etc.
• Event scripts determine any kind of event that might befall the agent, such as being interacted with by a Creature, impacting a solid surface, or even just experiencing the passage of time. If you are familiar with other programming languages, think of an event script as a function or method.
  
  An event script begins with an opening that says "SCRP", followed by the agent's classifier, and then the script number (which determines what type of event it handles). For example, "scrp 2 21 60661 1" governs how the beach ball acts when pushed.
  
  The end of the event script is marked with a line that says "ENDM", which is necessary to tell the game where the script stops.
  
  Install scripts and remove scripts exist only in the agent file, and they run immediately when the player pushes the "inject" or "remove" button on the creator machine. But event scripts work a little differently. Each world created in the game has a library of scripts called the scriptorium, where it stores all the scripts for all the agents in the world. When you inject an agent's event scripts into the game, they are stored in the scriptorium for future use.

Now that we know what we'll be writing, let's get our programs set up.

Getting Ready to Code

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.

An Introduction to the CAOS Tool

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.

• Reformat / Refresh syntax
  Clicking the "Reformat" button will make the CAOS Tool proofread your work. It will check your code for errors, changing the color of any problematic commands to red, and ensure that the indentation is correct. I recommend using this feature every time you make a major change: it makes it much easier to ensure that you have not forgotten any closing commands, placed code outside of the script or condition it belongs to, and so on.
• Inject Install Script
  Runs the install script, but doesn't inject the event scripts.
• Inject Event Scripts
  Injects the scripts that govern an agent's behavior, but doesn't run the install script.
• Inject Install Script & Event Scripts
  Runs the install script and its scripts into the game.
• Inject Remove Script
  Runs the agent's remove script.

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!

Onward to Part 3!