Thursday 30 April 2015

A C3/DS Agent PRAY File

PRAY files are used to compile agents and make them appear in the C3 or DS Creator, by explaining to the game how they should appear in the creator and what files are included in the agent file.  We're going to go through this example PRAY file line by line, explaining what each part does.   PRAY files can be saved as .txt files, or .ps (PRAY Source) files and can be used with a variety of tools (PrayBuilder, easyPRAY, Monk, etc.) to create agent files.

Typically, the commentary is below the code.

"en-GB"
This lets the game know that this section of the PRAY code is for the English engine. 

group AGNT "My Awesome Agent (C3)"
The name in the C3 Creator - this must be different from the DS name.  The tag AGNT is necessary for the Creator to identify this as an object kind of agent, instead of, say, a breed's egg agent.

"Agent Type" 0

This marks the file as suitable for injection.

"Agent Animation File" "myawesomeagentimage.c16"

This is where you specify the name of the sprite file that will be used to display the agent on the C3 Creator's screen.

"Agent Animation Gallery" "myawesomeagentimage"
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" "0"
This can be used to specify the animation sequence displayed on the Creator screen, but 0 is fine for non-animating display pictures.  If you're animating a string, do not enclose the sequence in square brackets. "1 2 3 255" is ok.

"Agent Bioenergy Value" 0
This is used to specify the amount of bioenergy it costs you to create this agent in Creatures 3.  A value of 0 here makes this a free agent.  The amount of bioenergy yielded by recycling the agent is determined by an object variable in the cos file for the agent.

"Remove script" "enum X X XXXX kill targ next scrx X X XXXX 1 scrx X X XXXX 2"
This 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.  Replace the XXes with your classifers and don't forget to use scrx to remove the scripts as well!

"Script Count" 1
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 1" @ "myawesomeagentscript.cos"
For each script specified above there needs to be one of these lines. This gives a name to each script file needed.

This following section is where you tell your agent what files it needs to run.  It does not include them in the file.

"Dependency Count" 3
Specifies how many external dependencies this agent will use. Each sprite file, catalogue file or sound file counts as a separate dependency.

"Dependency 1" "myawesomeagentimage.c16"
This section is for declaring the name for each dependency specified above.

"Dependency Category 1" 2
This section is to state where each dependency should reside, with respect to the Creatures 3 directory structure. It tells the game where to unpack that file to.  There needs to be one of these lines for each dependency.

0 is for the main C3 directory.
1 is for the Sounds folder.
2 is for the Images folder.
3 is for the Genetics directory.  (Used in breeds.)
4 is for the Body Data directory. (Used in breeds.)
5 is for the Overlay Data directory.  (Used in clothes!)
6 is for the Backgrounds directory. (Used for metarooms.)
7 is for the Catalogue directory.
10 is for the My Creatures directory. 

"Dependency 2" "chwp.wav"
"Dependency Category 2" 1
"Dependency 3" "myawesomeagent.catalogue"
"Dependency Category 3" 7

And now we're done with the C3 portion of the code.

group DSAG "My Awesome Agent (DS)"
This lets the game know that this name is for the DS creator.  It needs to be different from the C3 name.

"Agent Type" 0
This marks the file as suitable for injection.

"Agent Description" "My Awesome Agent is awesome and makes a noise."
This appears in the DS creator when the player looks through their list as a description of the agent.

"Agent Description-fr" "Ma Awesome Agent est impressionnant et fait un bruit."
"Agent Description-de" "Mein Awesome Agent ist genial und macht ein Gerausch."

You can also add French, German, Italian (it), Spanish (es) and Dutch (nl) descriptions.

"Web Label" "Creatures Caves"
"Web URL" "www.creaturescaves.com"
This causes part of the Creator machine to store your website's address and can be used to launch your site in their web browser from their game.  The game already does the http:// and the last / automatically. 

"Agent Animation File" "myawesomeagentimage.c16"

This is where you specify the name of the sprite file that will be used to display the agent on the DS Creator's screen.

"Agent Animation Gallery" "myawesomeagentimage"

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" "0"

This can be used to specify the animation sequence displayed on the DS Creator's screen, but 0 is fine for non-animating display pictures. If you're animating a string, do not enclose the sequence in square brackets. "1 2 3 255" is ok.

"Agent Sprite First Image" 0
Used by the agent injector to display your agent to the player.

"Remove script" "enum XX XX XXXXX kill targ next scrx XX XX XXXXX 1 scrx XX XX XXXXX 2"
This 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. Replace the XXes with your classifers and don't forget to use scrx to remove the scripts as well!

"Script Count" 1

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 1" @ "myawesomeagentscript.cos"

For each script specified above there needs to be one of these lines. This gives a name to each script file needed.

Note that this cos file is the same as the one in the C3 section - this assumes that the cos file itself checks if you're running C3, C3 docked with DS, or DS standalone.

Another way of doing it is to include a "myawesomeagent C3.cos" in the C3 section, and a "myawesomeagent DS.cos" in the DS section.  If you do so, the script count for each section remains 1. 

"Dependency Count" 3

Specifies how many external dependencies this agent will use. Each sprite file, catalogue file or sound file counts as a separate dependency.

"Dependency 1" "myawesomeagentimage.c16"

This section is for declaring the name for each dependency specified above.

"Dependency Category 1" 2

This section is to state where each dependency should reside, with respect to the Docking Station directory structure. It tells the game where to unpack that file to. There needs to be one of these lines for each dependency.

0 is for the main DS directory.
1 is for the Sounds folder.
2 is for the Images folder.
3 is for the Genetics directory. (Used in breeds.)
4 is for the Body Data directory. (Used in breeds.)
5 is for the Overlay Data directory. (Used in clothes!)
6 is for the Backgrounds directory. (Used for metarooms.)
7 is for the Catalogue directory.
10 is for the My Creatures directory.

"Dependency 2" "chwp.wav"
"Dependency Category 2" 1
"Dependency 3" "myawesomeagent.catalogue"
"Dependency Category 3" 7

And now we're done with making sure our agent displays properly in the creators and will unpack to the right places.  But we still need to include the files in our agent!!!

It is important to make sure that all the files that you expect your user to not have (the new images, new catalogues, and new sounds) are listed here, or they will not be included in the agent.  This will create a "dependency error" for the user.  They are listed twice because they are stating the destination and source names, which are usually the same. One of these lines is needed for each file you require for the object.


inline FILE "myawesomeagentimage.c16" "myawesomeagentimage.c16"
inline FILE "chwp.wav" "chwp.wav"
inline FILE "myawesomeagent.catalogue" "myawesomeagent.catalogue"

Now to look at it all together:
"en-GB"

group AGNT "My Awesome Agent (C3)"

"Agent Type" 0
"Agent Animation File" "myawesomeagentimage.c16"
"Agent Animation Gallery" "myawesomeagentimage"
"Agent Animation String" "0"
"Agent Bioenergy Value" 0
"Remove script" "enum X X XXXX kill targ next scrx X X XXXX 1 scrx X X XXXX 2"
"Script Count" 1
"Script 1" @ "myawesomeagentscript.cos"
"Dependency Count" 3
"Dependency 1" "myawesomeagentimage.c16"
"Dependency Category 1" 2
"Dependency 2" "chwp.wav"
"Dependency Category 2" 1
"Dependency 3" "myawesomeagent.catalogue"
"Dependency Category 3" 7

group DSAG "My Awesome Agent (DS)"

"Agent Type" 0
"Agent Description" "My Awesome Agent is awesome and makes a noise."
"Agent Description-fr" "Ma Awesome Agent est impressionnant et fait un bruit."
"Agent Description-de" "Mein Awesome Agent ist genial und macht ein Gerausch."
"Web Label" "Creatures Caves"
"Web URL" "www.creaturescaves.com"
"Agent Animation File" "myawesomeagentimage.c16"
"Agent Animation Gallery" "myawesomeagentimage"
"Agent Animation String" "0"
"Agent Sprite First Image" 0
"Remove script" "enum X X XXXX kill targ next scrx X X XXXX 1 scrx X X XXXX 2"
"Script Count" 1
"Script 1" @ "myawesomeagentscript.cos"
"Dependency Count" 3
"Dependency 1" "myawesomeagentimage.c16"
"Dependency Category 1" 2
"Dependency 2" "chwp.wav"
"Dependency Category 2" 1
"Dependency 3" "myawesomeagent.catalogue"
"Dependency Category 3" 7

inline FILE "myawesomeagentimage.c16" "myawesomeagentimage.c16"

inline FILE "chwp.wav" "chwp.wav"
inline FILE "myawesomeagent.catalogue" "myawesomeagent.catalogue"



Further reading

 Making Agents for Creatures 3 - CDN
 How to create .agent files for Docking Station and Creatures 3 - CDN
 DSAG PRAY Template - CDN
PRAY Mistakes - CDN

2 comments:

  1. Oh neat, you started a blog! I'll have to add it to my list.

    ReplyDelete