Creatures 2 Agent File Compiler
Copyright 1998+ CyberLife Technology Ltd

Version 1.0 Release 1

D. Silverstone
customer_support@cyberlife.co.uk

Table of Contents
GENERAL INFORMATION
WHAT GOES INTO AN AGENT FILE?
WHAT DO I NEED TO CREATE AN AGENT FILE?
THE PROCESSES OF CREATING AN AGENT FILE
STAGE ONE - DEFINING THE AGENT'S DETAILS
STAGE TWO - ADDING AGENT SCRIPTS
STAGE THREE - CONFIRMING THE RESOURCE DEPENDENCIES
STAGE FOUR - LINKING IN THE NON-STANDARD RESOURCES
STAGE FIVE - SETTING AUTHOR DETAILS
FEATURES OF THE AGENT FILE COMPILER
UCA FILES - UNCOMPILED CREATURES AGENTS	
PRESERVATION OF THE AUTHOR DETAILS


General Information

The Agent file compiler has been written to allow you to create your own agent files for Creatures2. The agent files (also known as COB's) are simplified ways of exchanging agents with others whilst ensuring that all the resources necessary for the agents correct operation are also transferred. The agent files provide a method of transferring all agent-related resources in a single file. This includes the sounds and images, used by the agent, which you could not sensibly expect others to have.

What goes into an Agent file?
Agent files contain a lot of things. The most important of which is the agent data itself. This includes the macro scripts used by the agent (its events) the macro code required to inject an agent into the world, and the code required to remove all trace of the agent afterwards. The agent data also includes how many of the agents are contained within the file, and how long between uses you have to wait. All this information is assembled during the compilation of the agent file.

Agent files also contain resources required by the agent, such as sprite and sound files. The Agent Injector Applet automatically transfers these image and sound files to the correct location. In this way, there are fewer chances of errors occurring due to misplaced sounds and images.

The agent files also have the option of containing details about the agent's author. In this way the author has some method of "signing" agent files.
What do I need to create an Agent file?
In order to create an agent file, you will need a COS file (Creatures Object Source) containing the install, remove and event scripts for your agent. Should your agent use files that are not provided by Creatures2 by default then you will also need these files available (Custom sprites or sounds for example). The Agent file compiler will automatically determine the resource requirements of your agents, and you can link in the resource files very easily indeed.
Finally, you will need to select an image to use as the agent thumbnail.

The processes of creating an Agent File
The following section illustrates the creation of an agent file.
Stage One - Defining the agent's details
When you first open the Agent File Compiler, you are presented with a welcome screen. Clicking on "Next" brings you to the agent details window. Here you enter the agent name (the text which will appear in the agent injector list of agents) a description of the agent (for the agent injector's description box) and settings such as expiry date, number of agents available to inject and the minimum delay between injections.

Stage Two - Adding agent scripts.
In the second stage of the compilation process you enter the scripts into the boxes provided. You are able to do this in one of four ways. Firstly, you can type the scripts into the box directly. Secondly you can cut/paste them into the boxes. Thirdly you can click on the open button and load a COS file into the window, and finally you can locate your COS file in Windows Explorer and drag it onto the window.

Stage Three - Confirming the resource dependencies.
The third stage of the process is to confirm the dependencies calculated by the software. If you need to alter the dependencies presented to you, then please enter them in the memo box. Note that you can only place S16 and WAV files in this box, and the pathnames are not required.

Stage Four - Setting the Thumbnail image for the agent.
On the fourth page of the wizard you give your agent a thumbnail image. This image is displayed in the Agent Injector. Again, you can either "Open" a sprite file, or drag one onto the page.

Stage Five - Linking in the non-standard resources
On the fifth page of the wizard, you will be prompted to link in any resources listed on the previous page, which are not accepted as normal resources. If you fail to link in any non-standard resources which your agent requires, you many find that it will not function on other peoples' systems. To link in files, both click on the open button and select the files to link in, or drag them onto the window from the Windows Explorer program.

Stage Six - Setting Author Details
On the final page of the wizard, you can enter your personal details, in order to provide some form of signing your COB's. If you do not wish to add the information to the COB then do not tick the "Include details" box and the resultant file will be slightly smaller.

Features of the Agent File Compiler
The agent file compiler has certain features designed to save you time and effort in the development of COB files. The main feature is that on many of the pages of the wizard, you can drag files onto the window where you would otherwise have to type data in or cut/paste or use an Open dialog.
UCA files - Uncompiled Creatures Agents
The UCA files that can be saved and loaded via the "OptionalCommands" menu are a way of saving your object files in a format that can be loaded back into the compiler. In this way, if you are developing the agents, you can save yourself a lot of typing and work by simply saving a UCA file, loading it in each time, and dragging onto the script window the new COS file...
Preservation of the Author Details
At your request, the software can save the author details you enter into the author page on the wizard. Then each time you start a new object, those details are loaded into the page by default. Naturally, the author details in a UCA file override the default values. These functions are also on the "OptionalCommands" menu but are only visible when the author page is active.

Multiple Agents in one file
The agent injector supports having more than one agent in an agent file. Thus the agent compiler also supports this. Next to the Agent name entry field on the first stage of the wizard is an arrow which if clicked allows you to select which agent you are working on, and also add and delete agents from the file. It is recommended that you only use this feature when generating an agent file for distribution to others.