Making Agents for Docking Station - by Hausmouse (Hausmouse1@aol.com) 
     - April 25, 2001


Making Agents for Docking Station is about the same as for C3. However, 
there are a few important differences, especially in the PRAY template.

Docking Station, C3, and CAOS compatibility:
_____________________________________

There are a number of new commands in the Docking Station version of CAOS.
These commands won't work in C3. If you have an agent that uses them, you
will not be able to inject it into a C3 standalone game. The best way to 
work around this is to make two similar agents: one without the new 
commands, for C3, and one for DS which does have them.


Moving your agents into the world:
_____________________________________

With the advent of Docking Station, moving an agent into the world becomes
a more complex task. Players may be working with C3 standalone, DS docked 
with C3, or undocked DS worlds. When making your cos file, you have to 
allow for all the possibilities.

In docked Docking Station worlds, you also have two agent injectors: the 
one on the Comms screen, and the one in the C3 engineering section. 
Docking Station stores the location of the injector that was used in two 
game variables, called "CreatorX" and "CreatorY". The following fragment 
of CAOS code can be used to move agents into the world, and will work in 
all cases. It will place them by whichever creator machine was used. Feel 
free to use it in your own agents! :-)

_________________________________________________________________________


*** Check the engine and move it into the world
* Which game engine is it?
doif gnam eq "Docking Station"
*     Which creator did it use?
*     "CreatorX" and "CreatorY" are set when the creator button is pushed.
	setv va00 game "CreatorX"
	setv va01 game "CreatorY"
	doif va00 eq 0 and va01 eq 0
*           DS safe, just in case 
		setv va00 6110
		setv va01 9200
	endi
	doif tmvt va00 va01 eq 1
		mvto va00 va01
	else
		mvsf va00 va01
	endi
elif gnam eq "Creatures 3"
	doif tmvt 5671 3599 eq 1
		mvto 5671 3599
	else
		mvsf 5671 3599
	endi
endi

_________________________________________________________________________

Testing is EASY!:
______________________________________
Testing cos files is much easier in Docking Station than in C3. Docking 
Station CAOS includes the new command "JECT".

Open the CAOS command line with ctrl-shift-c. The syntax for JECT is:

JECT "cos filename with extension" [flags] 

Here are the flags:
 1 - Remove script
 2 - Event scripts
 4 - Install script

You can add these together. For example:
    ject "ds-c3_bread.cos" 7

This will completely remove and then re-install the cos file 
ds-c3_bread.cos. If there's a mistake in the COS it will bring up an error 
message. Go in and fix the error, and try it again. Once your cos file has 
no errors, you are ready to compile it into an agent.



PRAYing agents for C3 and DS:
_____________________________________

Docking Station uses a slightly different PRAY template format than C3. 
It also uses a different 'chunk' type, DSAG. C3 uses AGNT, if you recall. 
To make an agent inject into both C3 and DS, you have to put both a DSAG 
and an AGNT chunk in your PRAY template file. The names of the two chunks 
*must* be different as well. It doesn't have to be a big difference, though.

Example:
    group DSAG "DS Bread Vendor"
    group AGNT "C3 Bread Vendor"

or even:
    group DSAG "Bread Vendor"
    group AGNT "Bread-Vendor"


To compile a DS compatible agent, use PRAYbuilder in DOS, or open Docking 
Station and use the 'pray make' command, just as you would for C3. Don't 
compile the agent in C3, however. C3 doesn't know what to do with a DSAG 
chunk, so it won't work.


The Docking Station PRAY template:
______________________________________

Look at ds-c3_bread.txt to see an example PRAY template with both DSAG 
and AGNT chunks.

It's important to remember that not everyone has both C3 and Docking 
Station, so there might be sounds or images your agent uses that some
people won't have. Include them in the Dependencies and inline FILE
sections, or tell people that they need to buy C3 or whatever.


Copied verbatim from Mark Ashton's post on the CDN:

**************************************************************************

(- This is the template for DS pray files -)

"en-GB"

(- TYPE
This specifies what type of PRAY resource this is.
DSAG marks this as a Docking Station agent, and it will not be detected by
Creatures 3
-)

group DSAG "<put the name of the agent here>"

"Agent Type" 0

"Agent Description" "<any text at all! You can include contact details,
credits, support URL etc. This is a limited size text field though so test
before release to make sure it all appears!>"

(- DEPENDENCIES
Dependencies are all the external files that are packaged into this agent 
to make it work. This includes images, sounds, attachments etc.
-)

"Dependency Count" <how many files need installing, don't count the COS
file>

"Dependency 1" "<name of first dependency INCLUDING the file extension>"

(- Repeat the 'Dependency X' field for each dependency counted -)

"Dependency Category 1" <category of dependency, states which folder to
install to>

(- Repeat 'Dependency Category X' field for each dependency counted

  Useful information:
        Dependency information is required to contain the category for
        each dependency listed. Failure to comply will result in failed
        injection of the agent.

  Categories are as follows:
        0 = Main directory
        1 = Sounds directory
        2 = Images directory
        3 = Genetics Directory
        4 = Body Data Directory (ATT files)
        5 = Overlay Directory
        6 = Backgrounds Directory
        7 = Catalogue Directory
        8 = Bootstrap Directory (Denied)
        9 = Worlds Directory (Denied)
       10 = Creatures Directory
       11 = Pray Files Directory (Denied)
-)


(- SCRIPTS
Script count should always be 1. If you want to inject multiple agents you
can do this within one COS file.
-)

"Script Count" 1

"Script 1" @ "<specify the COS file to be packaged, include the .cos
extension>"



(- DISPLAYING THE AGENT ON THE CREATOR or AGENT INJECTOR
The following fields are used by the agent injector to display your agent to
the player.
-)

"Agent Animation File" "<specify the image file used on the creator display,
include the extension because this field is used to test whether it exists
on your machine>"

"Agent Animation Gallery" "<specify the image used on the creator display.
Don't include the extension as this field is used by the NEW: command to
create the object>"

"Agent Sprite First Image" <specify the first image in the sprite file used
for displaying on the creator screens. This is used in the NEW: commands as
the first_image value>

"Agent Animation String" "<give the animation you want to see in the creator
for example 1 2 3 255 cycles between images 1, 2, 3 and repeats forever>"



"Web URL" "<put your website address here - without the http:// part. For
example. www.creatures.co.uk>"
(- the following fields are not needed to have your web URL work. A default
image is used for all websites, but the fields below allow you to create
your own icon and have it displayed -)
"Web Icon" "<not compulsory - a 16x16 icon to be used with your URL. DON'T
include the file extension>"
"Web Icon Base" "<first image in file specified above to use for web icon>"
"Web Icon Animation String" "<animation string to use for this icon>"

"Web Label" "<a small description for the URL i.e. Come to the official home
of Creatures">

"Remove script" "<write the whole removal chunk in CAOS that will remove
this agent and its scripts from the world>"



(- POSITIONING
The creator machines in Docking Station (and C3 when Docked) use game
variables called "CreatorX" and "CreatorY" to define the position to inject
to for an object to appear near the creator.
You should have code in your install script that uses this, if available, or
a definite position in the world. Be aware though, that injection will fail
if the definite position doesn't exist.
-)

(- CAMERA
You can make the camera on the creator screen pan to your newly injected
agent, this can help the player locate an agent that appears in an area they
are not looking at. Alternatively you could make the whole game camera point
at the agent injected by adding CMRT 0 to the install script for the agent.
-)

"Camera X" <You can specify camera X co-ordinate here>
"Camera Y" <You can specify camera Y co-ordinate here>



(- FILES
All files that you list in the dependency section above should be packaged
into the agent file. You do this by specifying them here.
Note that the source and destination names can be the same, and usually will
be.
-)


inline FILE "<name of source file>" "<name of destination file>"
inline FILE "<name of source file>" "<name of destination file>"


*************************************************************************

