---

Read the CAOS Tool instructions:

Welcome to the CAOS Tool for Creatures 3. This professional development tool allows quick error checking and testing of CAOS scripts in the Creatures 3 game.

1. Introduction
CAOS, or Creatures Agent Object Scripting, is the language used to code all the items in the world. It is very powerful within the game environment: it can be used to create entirely new agents for your world, alter existing ones, or even change the world itself. The only real limit is your imagination.

The CAOS Tool allows agents to be created in half the time. It can find the kind of simple coding errors that would otherwise leave you baffled for half a day, and can quickly inject and alter scripts and objects. It can also be used to view the outputs of macro commands, and view and manipulate the scriptorium.

Sadly, the CAOS Tool will not write your agent's code for you! You will still have to learn some CAOS at least. Happily, it's a fairly easy language to learn.

In the meantime, get thinking! We're sure you have some great ideas and now is the time to make your dream agent (or cheat) a reality!

2. Installation
The CAOS Tool is downloaded as a zip file, a compressed file format common to the internet. This files contains the setup program and related files. These files can be extracted from zip files using the programs available from www.winzip.com or www.netzip.com. Extract all files in the zip into the same folder, then run 'setup.exe'. The setup program will guide you through the install process. Remember to have your license key ready, or your newly acquired software will not work. If you find your key does not work, contact [url=mailto:[email protected]]Creatures Labs support.[/url]

3. The COS File Format
Many people moving up from a Creatures 2 third party cobbling program, or people entirely new to agent creation might be unfamiliar with the idea of the COS file. COS files are a text file that contains all your scripts, including event scripting, installation macros and removal code. Here is an example of a very simple COS file:

 

*This is the install script new: simp 2 8 53200 "apple" 15 13 10 attr 195 bhvr 48 elas 30 accg 5 fric 100 mvto 821 769 setv ov61 25 emit 6 0.25 cmra 455 422 0 *A simple eat script scrp 2 8 53200 12 stim writ from 78 1 snde "eat1" kill ownr endm *It goes bang when you drop it scrp 2 8 53200 6 doif wall = down snde "dr10" endi endm *Time to get rid of those apples! rscr enum 2 8 53200 kill targ next scrx 2 8 53200 12 scrx 2 8 53200 6

The install script is first in the file, and then the event scripts are added. The event scripts can be simply placed one after the other in any order after the install script has finished. The scrp command will instruct the computer that the install script has finished, and a new event script is starting. The removal script is specified with the rscr command- this is not a true CAOS command, and is only used in making COS files.

Any lines beginning with an asterisk are ignored on injection, and these comment lines can be used to remember exactly what it was you were trying to do, anyway. Users of C2 COS files will notice a few differences in the format, aside from the big differences in the language. The iscr tag is no longer necessary to specify the install script, although it won't throw up syntax errors if you like using it simply for tidiness. There is also no inst command in the install script, since install scripts are now run instantly by default. Another big difference is the lack of endm commands at the ends of both the install and removal macros. They have been done away with altogether, and including them will cause an error on injecting your agent.

If you want to see more examples of COS scripts, look in the creatures 3/bootstrap/001 World/ folder- there's lots of them. The above example script is fully injectable into the game, and will not clash with any game agents. It's also quite tasty, too.

4. CAOS Tool Colour Coding and Syntax Errors
You will notice that the COS file example above is colour coded. The CAOS Tool colours the various elements of the code according to its function:

 

Blue : Command Magenta: Variable Brown: Value Green: Comment Red: A Naughty Syntax Error

Syntax Errors cause an error message to appear in a pop-up window or in the error window if it has been enabled. The pop-up window will simply inform you that an error has been found, whereas the error window gives full details.

5. Breakdown of Menu Commands

Many of the menu items can also be found as buttons on the toolbar. Hold your mouse pointer over each tool button for a few seconds to see a brief description of its use in the statusbar at the bottom of the CAOS Tool's main window.

File Menu:

• New: Creates a new blank text document in which to enter your CAOS scripting
• Open: Brings up the open file dialogue for opening a previous COS file.
• Close: Closes the currently selected window.
• Close All: Closes all COS files currently open. The CAOS Tool can work with several COS files simultaneously.
• Save: Quickly saves the currently selected COS file using its current filename. If no filename has been specified, it opens the Save As dialogue box.
• Save As: Opens the Save As dialogue box, which allows a new filename to be chosen for your COS file.
• Save All: Saves all open COS files to disk.
• Launch Engine: Starts Creatures 3. Your Creatures 3 CD-ROM must be in the disk drive. No CD cheats here!

Edit Menu:

• Cut: Standard Windows command- Copies the selected text to the clipboard, and deletes the original.
• Copy: Standard Windows command- Copies the selected text to the clipboard. Only text in the COS window can be copied in this manner- however, pressing Ctrl + C while selecting text in the Error and Output windows performs the same function.
• Paste: Standard Windows command- Pastes the contents of the clipboard to the insertion point in the COS file window.
• Select All: Selects the entire contents of the currently activated window.
• Undo: Undoes the last action. The undo is recursive- if pressed twice, it will undo the last two actions.
• Redo: If an action has been undone by mistake, this command replaces it.
• Find: Opens the find dialogue box. Allows you to find a specific piece of text within the currently selected window.
• Find Next: Once the above 'find' command has been used once, the same search can be repeated by using this menu command.
• Replace: Searches for and replaces a specific word.
• Go To: Takes the cursor to a specific line number within the selected COS file.
• Block Indent: Moves the selected text right one tab stop. The reformat command will undo this command.
• Block Outdent: Moves the selected text left one tab length, if possible. This command is undone by the 'reformat' command.
• Block Comment: Places an asterisk at the beginning of each line of the selected text, transforming it into commented text.
• Block Uncomment: Removes any asterisks at the beginnings of lines within the selected text, turning commented text back into CAOS code.
• Reformat: Formats the text according to nesting within logical statements; for instance, all commands within a doif will be moved one tab right compared to the surrounding code. Commands nested within several doif commands will be moved several tab stops to the right. A syntax check is also performed. The COS file example above has been formatted in this way.

View Menu:

• Toolbar: Toggles the toolbar on and off.
• Statusbar: Toggles the statusbar on and off. The status bar is the bar at the bottom of the CAOS Tool's window that reports simple information on the currently selected window.
• Error Output Window: Toggles the Error Output Window on and off. This window displays more detailed information about any syntax errors within the COS file.
• Script Output Window: Toggles the Script Output Window on and off. This window displays any returning messages from the script injected, and also any error messages from the Creatures Engine on injection.
• Scriptorium Window: Toggles the Scriptorium Window on and off. This window allows you to view any scripts currently in the world within the Creatures game. Creatures 3 must be running for this window to work. When the window is first opened, it can take a little while for all the scripts to be fetched from the game engine. Scripts are organised by family, genus and species.

Scriptorium Menu:

NB: For any of these menu items to work, the scriptorium window must be open.

• Fetch Script(s): Displays the currently selected script in a new text window. If a species is selected, displays all scripts acting upon that species.
• Delete Script(s): Deletes the currently selected script, or all the scripts of the selected species, genus or family (caution!).
• Refresh: Reloads the scripts currently in the creatures world.
• Recursive Expand: Shows all scripts in the selected family genus or species.
• Recursive Collapse: Hides all scripts in the selected family genus or species.
• Write to File: Writes the entire contents of the scriptorium to a text file. Not surprisingly, this can take a while!

Inject Menu:

• Inject Install Script: Injects just the install script of your COS file into the world. If your event scripts have not been injected previously, your newly created agent will obviously not be able to respond to events.
• Inject Event Script: Injects the event scripts only of your COS file into the world. Any agents using these scripts will instantly start using the new versions.
• Inject Install Script and Event Scripts: Installs all your agent scripting in one go.
• Inject Remove Script: Injects your remove script. The CAOS Tool cannot automatically remove your agent from the world- it is up to you to make a removal script.

Window Menu:

This menu allows manipulation of multiple open windows within the CAOS Tool.

• Tile Horizontally: Resizes all windows within the CAOS Tool to fill the available space. Windows are tiled across then down according to time last accessed.
• Tile Vertically: Resizes all windows within the CAOS Tool to fill the available space. Windows are tiled down then across according to time last accessed.
• Cascade: Resizes all windows to the same size, then places them one after another in a diagonal row.
• Arrange Icons: Neatly lines up the icons of all minimised windows along the bottom of the CAOS Tool window.

Help Menu:

• Alphabetical Guide: Accesses an alphabetical guide to all CAOS commands.
• Categorical Guide: Accesses a guide to all CAOS commands arranged according to function.
• About: Tells you who made this tool (as if you didn't know!), plus copyright and legal stuff.

6. Other things to consider when injecting code
It is important to remember that making the COS file is not all there is to making an agent. Unless you are using standard images and sound files from the game, you must make sure all your dependencies are created and in place before you inject your code, or the game will kill your agent. You should place all sound effects, images, genomes etc into the correct place before injecting your CAOS code. This has to be done manually- there is no compiled .agent file at this point putting everything in place for you. Tools are available on the CDN for making the extras for the game, such as the sprite builder kit for making images or the PRAY Builder for creating a .agent file that can be distributed to others as one file.

Obviously, your game needs to be running, otherwise you can't inject code into it. It is possible to inject code on the world switcher screen, but if you wish to add an object to a world, you will need to have loaded a world. It is advisable to have a test world with one or two norns in to test your new creations- that way, you won't muck up your breeding population of creatures.

7. Learning more about the CAOS language and creating your own agents
This guide to the CAOS Tool does not act as a set of tutorials for learning the CAOS language itself. There are many such tutorials available on the web, including an excellent one on the CDN website itself. Learning the language is entirely possible for a beginner, and is a good way to get into the complex world of computer programming. However, a good knowledge of the vagaries of the Windows operating system is always useful.

Once you have made your COS file, your various images and sounds and so forth, you'll probably want to publish them for the whole world to enjoy. The .agent format is ideal for doing this. Agent files contain all data needed to install a new agent into a Creatures 3 world, including all the dependant files. The user can inject your agent into their world using the Creator machine. To compile these agent files, you need to use a subset of the CAOS language called PRAY. Pray basically tells the agent compiler what exactly it is supposed to be compiling, what to stick in the file, and where to place it all when the creator is used. There is a full set of tutorials on using the pray language on the CDN website. So, get coding, and good luck!