Friday, May 21, 2010

Creating a food object

Today, we'll be creating a food object, a decorated cake.

You will need:
  • These resources (put the wav file in the C3 or DS Sounds subdirectory, and the c16 file in the Images one.)
  • An open text editor (anything from emacs to notepad is fine, but don't use things like word, they add binary garbage to the file that will confuse the engine.)
  • Some co-ordinates for where you want the object to first appear (the previous tutorial details how to get these.)

The install script injects your object in the world, or an instance thereof, and defines some properties about it. Be careful, when you've set the behaviour, just an install script won't work, you need to have appropriate action scripts for the behaviour. We'll get to behaviour in a minute. First, here's the code in full. Note that all numeric values are positive integers (whole numbers) unless specified otherwise.

new: simp 2 11 29501 "tutorial_cake" 1 0 2000
attr 195
bhvr 48
elas 5
accg 3
aero 10
fric 50
perm 60
mvto 2412 9086

The first line determines this is an install script for a simple object, that it is a food (2 11) with the unique identifier 29501, that its sprite is "tutorial_cake", which has 1 image, and that it is using the first image. The type and unique identifier, or classifier, tell an objects what scripts to use. If two objects use the same classifier, and both have an eat script, there will be a conflict, and errors. The last number on this line determines where the object  sits, depth-wise, in 2.5 dimensional space. It is usally OK to leave this at 2000, if you find your object is hidden, or hiding other objects, you can try experimenting with different values.

The second line determines the attributes of an object (what can carry it, invisibilty etc.) and the third line determines behaviour (what can be done to it by creatures and the hand.) attr 195 means creatures and the hand can carry this object, that it can be affected by collisions, and that it can be affected by other types of physics. bhvr 48 means this object can be picked up and eaten by creatures. This means the object will require an eat script, but there is no need for a pick up script, unless you want something special to happen when a creature picks up the object. Appropriate attr and bhvr numbers can sometimes be difficult to determine by hand, so there is this handy calculator that runs on Windows.

The next few lines determine how physics affects the object. elas is elasticity, and determines how much an object will bounce when hitting a surface. accg is acceleration due to gravity, the only property here which accepts a float or fractional number. There is little reason to change the value. aero is air resistance, and its value should be somewhat proportionate to the size of an object. fric is friction, and determines deceleration when the object is touching a surface. Finally, perm is permeability, and determines which doors or openings an object can pass through, according to that door or opening's own permeability.
 The last line determines where the object will be placed. Change 2412 9086 to your co-ordinates.

Now it's time to write the eat script!

scrp 2 11 29501 12
snde "tuea"
stim writ from 79 1
stim writ from 77 1
stim writ from  0.5
kill ownr

The first line tells this us this is a script for objects of the specifier classifier. 12 is the number for eat scripts.

The second line just plays a sound. Don't forget to enclose the sound name in quotes, and never include the filename.

The third line makes our object do what food is supposed to do, provide nutrients to a creature. What those nutrients are depends on a creature's genome. 79 is the stimulus for eating food, and 1 is the amount. The amount can be an integer, or a decimal value such as 0.75. 77 is the stimulus for eating seeds, and usually provides starch.

The fourth line kills the object after it has been eaten, and the last line just tells the engine that the script is over.

Finally we will write a remove script. These are pretty simple.

enum 2 11 29501 kill targ next
scrx 2 11 29501 12

Any code in between enum classifier and next will perform an action on all objects which have that classifier. scrx removes the specified classifier specific script, especially useful for dealing with clashes.

Save the text file as "tutorial_cake.cos" somewhere that is accessible.

All that's left is to test the object. We won't be compiling an agent in this lesson, so you should think about how to inject the object. A good program to use is the CAOS Tool from the CDN, which also serves as an IDE (development environment) if you wish to abandon standard text editors.

If all has gone well, you will have coded a fully functioning agent, but if you are having problems, don't hesitate to leave a comment!

Monday, May 17, 2010

The Basics

What is CAOS?

CAOS is a programming language used to control objects in Creatures worlds. In Creatures 3 and Docking Station, objects make up everything the player interacts with - Norns, weather, the hand, even the world switcher.

CAOS is interpreted by the Creatures engine. There are several different incarnations of this engine, with slightly different CAOS syntaxes (grammar) and commands. The differences between the Docking Station and Creatures 3 engines are so minute that they can usually be ignored*, and we will not be focusing on any of the DS engine's "special" commands in these tutorials.

Note that the CAOS we produce in these tutorials will largely be incompatible with the Creatures 1 and 2 Engines. However, when you have become adept at CAOS, you may wish to convert some of your agents and scripts for use with previous games!

*Note that Creatures Adventures and Playground use the same engine as Creatures 3. Add-ons are so difficult to produce for these games, however, that they will not be covered in this tutorial.

Hello World

If you have ever taken a programming course, or read a book on the subject, you will probably be familiar with the concept of Hello World Programs. These are short programs created for two purposes, to test that the compiler or interpreter (in this case the engine) is working correctly, and to familiarize oneself with the syntax of the language in question.

Creating a Hello World program is, in this instance, very simple. Press the keys SHIFT+CONTROL+C to open up the command line. (We will be exploring the command line in more depth later, but for now, we will just be using it as a testing tool for simple programs.)

Type the following:

outs "Hello World"

And press the key ENTER. If all goes well, the command line should print "Hello World".

outs is the command used to print a string on the command line, or whatever program you are using to enter CAOS. "Hello World" is the string that will be printed.

In Creatures, there is actually a more interesting way to create a Hello World program! Select your favorite creature, then repeat the above steps with the following code:

targ norn sezz "Hello World"

Your creature should have said "Hello World". It is pretty simple to understand how this works. targ norn makes our code act on the currently selected creature. sezz is a command used to make creatures speak a specified string, and, of course, "Hello World" is the string that is spoken.

Finding Map Locations

Taking a break from syntax, it's time to introduce you to an ingame tool that will become invaluable, the co-ordinate finder. Press the keys SHIFT+CONTROL+X. You should see a couple of numbers next to the hand. Try moving the hand around and seeing how the numbers change. This is the co-ordinate finder. It shows the x (horizontal) and y (vertical) placement of the hand - the two numbers you are seeing. These numbers, or co-ordinates, can be used to place an object at the same position when injecting it or moving it around. We do need to make sure that it is a safe map position for that object according to its size and the type of map area. In the middle of a room at about adult norn head height is usually pretty safe for smaller objects, like toys and food. Don't worry if the placement is in midair, gravity will make most objects fall to the floor.

Try moving an object. Get some safe-looking co-ordinates. Hover the pointer over a piece of cheese or fruit, open the command line, and use this code:

targ hots mvto number1 number2

With number1 being the first co-ordinate you found, and number2 being the second.

This concludes the first lesson. The next lesson will cover how to make an object from scratch, give it some physical properties, and make it possible for creatures to interact with it.


Welcome to the CAOS Tutorials blog. Over the coming weeks I plan to cover, in order, the following subjects:
  • The Basics
  • Creating a food object
  • Creating a toy object
  • Creating a vendor object
  • Working with variables
  • Working with rand (the random number generation function)
  • Compiling an agent
  • Editing existing scripts
  • Mastering the command line
If you want to develop agents, consider whether or not you'll be making your own sprites and sounds. I won't be providing any information on this, but the Creatures Development Network is a good place to start.

Finally, if you don't know what this is all about, the Creatures Wiki should cover everything!

Stay tuned for the first tutorial which will be up soon.