     PRAY AGENT TUTORIAL FOR C3 by Hausmouse (Hausmouse1@aol.com)
     - April 27, 2001

INTRODUCTION:

This collection of files is a tutorial on the PRAY function of Creatures 3.
Included are instructions for using the PRAYBuilder program provided by
Creatures Labs, as well as the PRAY caos command within the game itself.

This tutorial is designed to teach you how to package your agents for
easy injection and distribution. This isn't a tutorial on CAOS or how
to make agents, although the included cos file has lots of comments that
should help you learn how it's done.

PRAY and DOCKING STATION:
This tutorial focuses on Creatures 3, but most of the information will be
accurate for Docking Station as well. There are also some files that will 
help describe the differences between making agents in Docking Station
and making them in Creatures 3. 


GETTING STARTED:
_____________________________________________________
PRAY is the method by which Creatures 3 takes the source code of an agent
and compiles it into a neat little archive with a .agent extension, which
can then be placed into your My Agents folder and injected into C3 via
the Creator Machine.

You can compile an agent in one of two ways: 
  1)Use a stand-alone DOS program called PRAYBuilder.exe, available from 
    the CDN (which is down as of November, 2000, but should return in a 
    few weeks)

  2)Use the CAOS command PRAY from within the Creatures 3 engine itself. 
    This is, in my opinion, the easier choice.

____________________________________________________
Explanation of files in the zipped archive:

PRAYforDOS.txt
     - Instructions for using PRAYBuilder.exe from the MS-DOS prompt.

PRAYforC3.txt
     - Instructions for using the caos command line in Creatures 3 (or
       Docking Station) to compile agents with the PRAY MAKE command.

DockingStation.txt
     - Describes the differences in the DS and C3 PRAY template, as well
       as other agent-making issues.


Example files:
bread_vendor.c16     -  Sprite file (Image) the image the agent uses
bread_tut.catalogue  -  Catalogue file (Agent Help)
bread_tut.cos        -  Example COS file with comments.
bread_vendor.txt     -  Example PRAY template file with comments.
ds-c3_bread.cos      -  Example COS file that's Docking Station compatible.
ds-c3_bread.txt      -  Example PRAY template with DS and C3 sections. 
hm_logo.c16          -  Sprite used as a Web Icon in Docking Station

_____________________________________________________
The typical files you need to PRAY a complete agent:

COS file - extension: *.cos

           This is your CAOS code. It should be in plain text format, 
           with no special characters. Creatures Labs has a CAOS tool 
           for C3. Notepad and the MS-DOS Editor work great as well.

CATALOGUE file - extension: *.catalogue

           If you want C3's Agent Help function to work with
           your agent, you must include a catalogue file.

IMAGE file - extension: *.c16, *.s16

             Many agents use the sprites included with C3. If your
             agent uses custom-made sprites, you *must* include
             them, or your agent will not work on other people's
             systems.

SOUND file - extension: *.wav

             If your agent uses custom sound files, they must be
             included, just like the images.

PRAY TEMPLATE file - extension: *.ps, *.txt, or other.

             This is the file that instructs PRAYBuilder on how
             to package your agent. The extension can be anything,
             so far as I know, but you have to remember what it is,
             so *.ps or *.txt is good.

_____________________________________________________
CREATING YOUR PRAY TEMPLATE

Look at the included file "bread_vendor.txt". This is a PRAY template
for a food dispenser. Lines of text enclosed in (- these symbols -) 
are comments. They are meant for the reader, and will not be compiled.
You can delete any commented line and the PRAY template will work the
same.

When writing a PRAY template, be extra careful with spelling errors
or other typos. PRAY is unforgiving of such mistakes. :-)


Dependencies:

These are the files required by your agent in order to work. The
"Dependency Count" is the total number of files, *not* including your
COS file. Each individual sound or image file counts as a dependency.

Example:
    "Dependency Count" 4

Each file your agent uses should be listed as a separate dependency.
The format is:

"Dependency [number]" "filename.extension"

Examples:
   "Dependency 1" "bread_vendor.c16"
   "Dependency 2" "bread_tut.catalogue"
   "Dependency 3" "_eem.wav"
   "Dependency 4" "bibl.wav"

   ...and so on.



Once you have listed a Dependency, you must specify a Category for it.
This tells the agent which folder to extract your included files to.
The format is:

"Dependency Category [number]" [folder number]

Examples:
    "Dependency Category 1" 2
    "Dependency Category 2" 7
    "Dependency Category 3" 1
    "Dependency Category 4" 1

    ...and so on.

The [number] for a Dependecy Category corresponds to the same number as 
the Dependecy list. This is why I make template files that put the Category
right after the Dependency listing, so I don't get confused.

Example:
   "Dependency 1" "bread_vendor.c16"
   "Dependency Category 1" 2

   "Dependency 2" "bread_tut.catalogue"
   "Dependency Category 2" 7

The folder numbers specify different folders in your C3 directory:
             _______________________________________
              FOLDER NUMBER         C3 FOLDER
                  0           Main C3 Directory
                  1           Sounds Directory
                  2           Images Directory
                  3           Genetics Directory
                  4           Body Data Directory
                  5           Overlay Data Directory
                  6           Backgrounds Directory
                  7           Catalogue Directory
                  10          My Creatures Directory
             _______________________________________

!!!!IMPORTANT NOTE!!!!

  Listing an image or other file as a dependency will not 
  automatically include it in the final .agent. For the file to be 
  packaged with the agent it must be listed as an 'inline FILE' at
  the bottom of the PRAY template.



_____________________________________________________

TESTING AGENTS:

It's a good idea to test your agents before you make them
available for download. A little bit of testing beforehand
can save you a lot of grief later.

First, test your COS file. Place any required images, sounds, etc, 
into the correct folders. If you have the C3 CAOS Tool, you can use
it to inject your cos file into a world.

If you don't have the C3 CAOS Tool, create a new folder in the 
Bootstrap folder, and place your COS file there.

Start C3, and start a new world. Your agent should appear where you 
chose to place it with the mvto statement in the COS, often by the 
Creator Machine.

Make sure Autokill is off. Type ctrl-shift-w to bring up the Wolf
Control screen. ctrl-shift-a toggles autokill on and off. Test your 
agent. Play with it. Have some creatures play with it. If you get 
errors, go back and fix your COS, then start a new world and keep 
testing.

Once your COS file works properly, you are ready to compile it into
an agent.

PRAY TEMPLATE:

Make your PRAY template according to the example template. In the
Dependency Count, you only need to count the number of new 3rd-party
files used by the agent. If your agent uses sounds or images that 
came with Creatures 3, those files do not need to be listed. 

Once you have your PRAY template file, you can compile your agent.
Follow the directions in either PRAYforDOS.txt or PRAYforC3.txt

If you get errors at this point, it is probably your PRAY template. 
Make sure there are no spelling mistakes. Make sure the line with 
"en-GB" is present. Make sure there is a carriage return (enter) at 
the end of the last line.

The mistake I make most often is forgetting to change a filename
somewhere, so PRAYBuilder can't find a file it thinks it needs.


Do a final test of your agent by placing it in your My Agents folder,
and injecting it into a C3 world. Make sure Autokill is off, or you
could lose your Creator Machine! 

Also remember to remove the required images, sounds, etc. from the 
correct folders. This forces your agent to extract these files 
itself, just as it would on someone else's computer.

If something goes wrong, it's probably the PRAY template, since you 
already tested the COS file, and it works. Go back and check for 
mistakes.

If everything works, then you're ready to distribute your agent! :-)


Hausmouse1@aol.com