Home Sweet Albia presents

A Guide to Mac Agenteering

IV. Time to PRAY

1. Clean Up

Move your finished script, sprite, and sound files to your agent folder. You can keep the Testing folder around if you want, for the next agent you work on. If you're using a sound or sprite file that came with the game (like the "pop_.wav" I used in the bubble blower), you don't need to touch it -- you only need to distribute new files with your agent. Now rename "test.cos" to something more identifiable, like "bubble blower.cos", and you're on the home stretch.

2. Create Agent Help

Agent Help works by reading special text files with a ".catalogue" extension. Create a new text file in your agent folder, naming it something like "bubble blower.catalogue". Its contents will be a series of short text blocks like this:

TAG "Agent Help 2 21 999"
"Bubble Blower"
"This simple toy creates bubbles when held by a creature or the Hand."

You'll want one TAG block for each species number used in your agent.

3. Write PRAY Source

The PRAY compiler will take all your scripts, sprites, etc. and create a single handy ".agents" file. It does this by reading a PRAY source file, a simple text file listing all details and dependencies of your agent. Here's a simple template to follow:

"en-GB"

group AGNT "[agent name} "
"Agent Type" 0
"Agent Description" "[agent description]"

"Agent Animation File" "[sprite file with .c16 extension]"
"Agent Animation Gallery" "[sprite file without .c16 extension]"
"Agent Animation String" "0"

"Remove script" "enum [classifier] kill targ next"

"Script Count" 1
"Script 1" @ "[script file with .cos extension]"

"Dependency Count" [total number of dependency files]
"Dependency 1" "[filename with extension]"
"Dependency Category 1" [file category number]
"Dependency 2" "[another filename with extension]"
"Dependency Category 2" [another file category number]
[etc.]

group DSAG "[agent name] "
"Agent Type" 0
"Agent Description" "[agent description]"

"Web Label" "[website name]"
"Web URL" "[website address]"

"Agent Animation File" "[sprite file with .c16 extension]"
"Agent Animation Gallery" "[sprite file without .c16 extension]"
"Agent Animation String" "0"
"Agent Sprite First Image" 0

"Remove script" "enum [classifier] kill targ next"

"Script Count" 1
"Script 1" @ "[script file with .cos extension]"

"Dependency Count" [total number of dependency files]
"Dependency 1" "[filename with extension]"
"Dependency Category 1" [file category number]
"Dependency 2" "[another filename with extension]"
"Dependency Category 2" [another file category number]
[etc.]

inline FILE "[filename]" "[filename]"
[etc.]

There are three main sections: information for Creatures 3, information for Docking Station, and a list of files to include in the compiled agent file. The inline files only need to be listed once at the end, but each information section has its own dependency list. A dependency is a C16, WAV, or catalogue file. The category number identifies what kind of file it is: 2 for images, 1 for sounds, and 7 for catalogue files.

... A sample PRAY source file for the bubble blower can be found in the bubble blower kit.

4. Compile the Agent

It's finally time to compile your agent. Make sure all your files are in the same folder, otherwise they won't get included in the finished product. Load up Monk ("PRAY chunk" should be selected), drag your PRAY source file onto the blue box, and with any luck you'll have a shiny new agent file waiting in your folder! Kind of anticlimactic, isn't it?

5. One Last Test

It's a good idea to test the final agent file before you distribute it. Delete any files that are supposed to be included from the Creatures data folders, then place the ".agents" file in the [Creatures Data]/My Agents directory. Start (or restart) Docking Station and load any world you like. Go to the Creator and find your agent, then inject it. Does it work? Good!

The Agent Help, however, will not work automatically on a Mac. For whatever reason, catalogue files are put in the [Home]/Library/Preferences/Creature Labs/Docking Station/data/Catalogue directory instead of the [Creatures Data]/Catalogue directory. Just copy your catalogue file from one to the other, and reload your world.

6. Zip and Share

Congratulations! Your agent is ready to share with the world! Drag your ".agents" file into YemuZip, and save the ZIP file with the rest of your agent stuff. If you don't have your own website on which to post your agent, Creatures Caves will let you upload it to theirs. Don't worry that you made it on a Mac -- no one will ever know! It will work just fine on Windows and Linux, too.

Moving On

So now that you're an agenteer, what will you do next? You can find more agent engineering articles, including several tutorials, on the CDN. AquaShee also has the wonderful CAOS Chaos tutorial. If you feel particularly brave, you can delve into the various Bootstap folders that contain the scripts for the original games. You can even decompile other people's agents to see what they're made of -- open Monk, select "PRAY source", and drag the ".agents" file into the blue box.

There are plenty of resources out there, and not nearly enough cool agents: so go forth, agenteer, and show the world your stuff!

Thanks to Moe, Spook, RProgrammer, and Malkin!

>> BACK TO SWEET HOME ALBIA