Making Agents for Creatures 3

How to make a .agent file that will work with Creatures 3
The Creator machine in engineering is capable of taking 3rd party agents files and displaying them in the screen for injecting.
If you use the this method correctly you have the advantages of:
  • - being able to distribute a single file that contains all the dependent files (no need for the user to manually place multiple files in their correct location
  • The Creator can display and animate any image you desire (which makes it easier to tell similar objects apart)
  • The Creator can display a name for the agent.
  • The Creator can remove your agents from the world (no need for the user to be an expert to remove your agents)
  • Agents created can use the bioenergy system (although this isn't compulsory)
  • If an agent created with the Creator (rather than using the bootstrap method) has an error in it the user can start a new world and recover from this. If the bootstrap method is used then any error will exist in all future worlds.

The process of .agent file creation can be summarised as follows:
  • Create a COS file that contains the scripts and installation routine you desire
  • Create a PRAY template text document. This is used by the PRAY Builder to construct an agent file.
  • Place the PRAY Builder, COS and template file in the same folder ... along with any files needed by the agents (sprites, sounds, etc)
  • Run PRAY Builder and after a short time you will have a .agent file that can be placed in the 'My Agents' folder of Creatures 3.

Creating the COS file

Create the COS file as normal, with a part to install the agent(s) and the scripts they need to operate. The only differences are where you position the object. You have two choices and can either make it such that it comes out of the Creator machine (as the objects in-game do) or you can create it such that it moves to a particular position in the world. This later method is particularly suitable for large and/or static agents that live in a particular place in the world.
To make the agent come out of the Creator: Use the following chunk for the placement of the object into the world.
mvto 5440 3580
velo rand 30 40 -5
Note: If your object is particularly heavy or especially light, you may need to alter the values given for velocity! Check to make sure.
To make it appear in the world: This method involves using MVTO as you would normally use it, but a change is needed in the PRAY template file to trigger a camera movement and teleport effect (see next section).

Creating the PRAY template text file

This file can be created with any text editor.
Below is a sample template, containing all the fields that are necessary for the Creator to successfully inject the agent. Text marked means that you need to fill in a value here.

 
Code Explanation
"en-GB" This marks the language to be used. For nearly all cases the best thing to do is just leave it as it is :-)
group AGNT "" Marks the following text as belonging to this particular agent. The tag AGNT is necessary for the Creator to identify this as an agent (rather than an egg for example). The name of the agent should be given in double-quote marks. For example, "SuperClean", and is the text that appears in the info bar above the Creator.
"Agent Type" 0 Marks the file as suitable for injection
"Dependency Count" Specifies how many external dependencies this agent will use. Each sprite file or sound file counts as a separate dependency.
"Dependency " "" This section is for declaring the name for each dependency specified above. Only needed if Dependency Count is not 0.
"Dependency Category " This section is to state where each dependency should reside, with respect to the Creatures 3 directory structure. There needs to be one of these lines for each dependency. Only needed if Dependency Count is not 0.
"Script Count"

Specify how many COS files are needed for this agent not how many event scripts there are! Usually this will be just 1 file, unless you like to keep your events and installations in separate files.
"Script " @ "" For each script specified above there needs to be one of these lines. This gives a name to each script file needed. Only needed if Script Count is not 0.
"Agent Animation File" "" This is where you can specify the name of the sprite file that will be used to display the agent on the Creator screen.
"Agent Animation Gallery" "" This also refers to the image of the agent portrayed on the Creator screen. This section will be used to fill in the NEW: command, and as such the name of the sprite file is entered without the file extension.
"Agent Animation String" "" Specify the animation sequence displayed on the Creator screen. Do not enclose the sequence in square brackets. For example, "1 2 3 255" is ok but "[1 2 3 255]" is wrong.
"Agent Bioenergy Value" This is the amount of bioenergy it takes to create the agent. This can be 0 to allow the agent to be made for free. This is not the same as the amount of bioenergy gained by recycling the agent, which is controlled by OV61 within the agent itself.
"Remove script" "" Allows you to specify a chunk of code that will allow the agent to be removed from the game, simply by clicking the remove button on the Creator machine.
   
"Camera X" These lines are only needed if you do not want the agent to appear out of the Creator machine. If these are included then the Creator screen will move to the location specified and a teleport effect will be seen around the agent injected.
"Camera Y"
   
inline FILE "" "" This command is essential if you are using files that do not ship with the game. This command will package up any files you need into the .agent file, and they will be unpacked on the users system if they don't exist there. Usually the destination and source names are the same. One of these lines is needed for each file you require for the object.

 

Running PRAY Builder

PRAY Builder is a command line program, which means you need to produce a DOS prompt to operate it. Note: One of the Power Toys available for Windows is called 'Command Prompt Here' and is very useful for opening up a DOS prompt with a path set to the folder you are in at that time.
Make sure all the files specified with inline, the COS file, the PRAY text file and the PRAY Builder are in the same folder. Then at the command prompt type: praybuilder and hit enter - the build process has started.
After a short while you will have a new file called Agent in the same folder, and this file can now be distributed to anyone you like. (Although it's probably best to make sure it works first!)

How to make sure it works

Remove all dependent files from your C3 folders (i.e. remove the images/sounds needed by your new agent), and try to inject the agent with the Creator. If an error comes up then you probably haven't successfully packaged the files into the agent file. If everything works as it should then you should find that the files needed have now been created in the relevant folders for you.

Hopefully it's common sense to test your work before making it available to others!

Example 1

The following is an example of a new Agent file, consisting of files not found by default in C3. The ZIP file here contains the COS, the image and the PRAY template. The Agent actually has 2 agents specified in it - the Bacterial Spotter and the SuperClean Bacterial Spray.

NOTE: Although functional this Agent is purely to demonstrate the PRAY system. These objects are copyright CyberLife Technology Ltd and are a work in progress of some objects that will be released free of charge onto the creatures.co.uk site shortly. The artwork is temporary, the CDN_Classifiers chosen are arbitrary, there are no sound effects and the object has not been through a formal test procedure - you will not be doing a non-CDN member a favour by distributing this object!

This project consists of two separate COS files, one for each agent, and 1 shared sprite file. The PRAY template shows the specification of the relevant fields, and the inlining of the sprite file. This example does not include a catalogue file for the agent help.

Simply take the contents of the ZIP file and run through the process detailed above to create a .agent file with PRAY Builder.

STOP PRESS This item was released as a part of the 1999 Yule Pack, under the guise of a Millennium Bug Kit. The classification and graphics (but not the sprite filename) are different between the two versions.

 

Example 2

This ZIP file contains the PRAY template file and COS for the Yule Fireworks that were released as part of the 1999 Yule Pack. This template packs 3 sound files, a catalogue and an image into the agent file and should provide a useful pointer if you are having problems.



Topic Keywords: agent creatures3 pray tutorials