CAOS2PRAY: An Easier Way

Sometime last fall, while I was preparing for CCSF, I discovered a little thing known as CAOS2PRAY. It would not be too much of a stretch to claim that, were it not for CAOS2PRAY, I may not have gotten around to releasing as many agents as I did, because I hate, hate hate hate writing prayfiles, and even easyPRAY was giving me problems.

CAOS2PRAY is basically a method of embedding your PRAY info in your .cos file so you don't have to deal with a separate file (or if you're using easyPRAY, a separate program as well). I really feel that it is a wonderfully simple way to compile agents, but is not very well known or understood; hence this little guide.

All I learned about CAOS2PRAY, I learned from the official documentation here. This tutorial attempts to simplify that manual, but you should refer to it for further information.

CAOS2PRAY was actually developed by RProgrammer as part of Jagent. As such, you need to use Monk to compile your agents for it to be effective. Malkin has already written a simple guide to Monk, so I'll skip those details and jump right into the unknown. Note that this tutorial also assumes you've written a PRAY file before and understand what information is generally required.

Again, CAOS2PRAY is not a program or anything of the sort. It's basically just a syntax you follow to, instead of writing the prayinfo in a separate file, write in the cosfile itself, in a much more simplified fashion.

If you were to decompile my Advanced Muco (or any of my more recent agents), you would notice the top of the cosfile contains text like this:

**CAOS2PRAY
*# Pray-File "advmuco.agents"
*# DS-Name "Advanced Muco"
*# Depend blnk.c16
*# attach advmucoo.c16 advmucohelp.catalogue
*# desc = "A display next to Muco the Egg Layer that allows you to choose breeds from a list."
*# Agent Animation File = "advmucoo.c16"
*# Agent Animation String = "0 1 255"
*# Agent Sprite First Image = 0
*# Agent Animation Gallery = "advmucoo"
*# Web URL = "naturingnurturing.blogspot.com"
*# Web Label = "Naturing :: Nurturing"

This is all I needed to write. Then I just made sure all the inline files were in the same folder, dragged and dropped the cosfile onto monk, and it spit out a complete and packaged agentfile, no prayfile required! It's incredibly easy to write up a "template" like the one above and just copy/paste it at the beginning of your cosfiles, changing the info as needed.

• To make use of CAOS2PRAY, you need to understand a few things:
• Since you're putting this text directly in the cosfile, you have to start each line with an asterisk [*] to comment it out so it doesn't throw errors when C3/DS tries to read it.
• When compiling with CAOS2PRAY, Monk searches for the hash/pound sign [#]. Thus, you have to start each line that you want Monk to recognize with the asterisk followed by the hash sign [*#]. The only exception is the remove script, which Monk finds on its own.
• It's best to put your CAOS2PRAY info at the top of your cosfile, or at the very least, not at the bottom. Once Monk hits your remove script, it will stop reading further commands, so if your info is at the bottom, under your remove script, Monk won't see it. 

Now, if you're a careful observer, you may have noticed that some lines in the example contain equal signs [=] while others do not. That is because there are two different sorts of lines that Monk understands, commands and tags.
Tags are very simple, so we'll start with them. They're the ones with the equal signs, and they translate directly to the prayfile.

Let's say you write the following lines in CAOS2PRAY:

*# Agent Animation Gallery = "advmucoo"
*# Agent Sprite First Image = 0
*# Banana Cream Pie = "in your face"
*# Number of Pies = 42

This is the same thing as writing the following in a typical prayfile:

"Agent Animation Gallery" "advmucoo"
"Agent Sprite First Image" 0
"Banana Cream Pie" "in your face"
"Number of Pies" 42


Not that you would actually need to define the latter two unless you had a modified agent injector that read those values, but you get the point.

At first glance, it may appear that CAOS2PRAY is more writing than a typical prayfile. But there are shortcuts available, too. You may have noticed in the example, a tag simple labeled "desc"

*# desc = "A display next to Muco the Egg Layer that allows you to choose breeds from a list."

Monk translates this to the following in the prayfile:

"Agent Description" "A display next to Muco the Egg Layer that allows you to choose breeds from a list."

It doesn't matter if you use "desc" or "Agent Description" -- it will be read the same way. Here are the shortcuts that Monk supports:

"anim" -- "Agent Animation String"
"anim file" -- "Agent Animation File"
"desc" -- "Agent Description"
"anim start" OR "anim img" OR "anim image" OR "first image" -- "Agent Sprite First Image"
"bioenergy" "Agent Bioenergy Value"

As you can see, there are shortcuts for a lot of values in the example that I chose to write out instead of using the shortcut. I'm not really sure why I did that. Obviously if you're typing it all out by hand, it would be quicker to use the shortcuts, but in the end it doesn't matter which you use, especially if you're just copy-pasting a template.

Now, the commands. This is where CAOS2PRAY really shines.
Command lines do not contain equal signs, they are simply written as {command} {something}.
The commands are as follows:

Pray-File: This is what the output file will be named. Be sure to include the .agent extension. This is required!
DS-Name: The name of the agent as displayed in the DS agent injector.
C3-Name: The name of the agent as displayed in the C3 agent injector. Only required if your agent is C3-standalone compatible. Remember that your C3 agent name cannot be the same as your DS agent name!
Depend: This specifies dependencies (images, sounds, etc that the agent needs to function) but does not compile them into the agent. These must be separated by spaces and include the file extension. The nice thing about this is that you don't have to define a category like you would when writing a PRAYfile by hand; Monk does this for you. As you can see in my example, I got lazy and didn't include all the dependencies my agent needed. You should probably not follow my example, and instead try to list all the images, sounds, etc that the agent needs, even if they are included with C3/DS, because you never know when someone might accidentally delete half their sounds folder and then spam you with angry messages when they inject your agent and it gets autokilled instead of just throwing a dependency error.
Attach: This specifies dependencies and compiles them into the agent. Monk will throw an error if you don't have these files included in the folder with the cosfile while compiling the agent. Same rules apply as with Depend (must be separated by spaces and include the file extension). You use this for sprites, sounds, catalogue files, etc that are not native to C3/DS. If you list a file in Attach, you do not have to list it in Depend.
Inline: This compiles files into the agent, but will not specify them as a dependencies (unless you also list them in Depend). I'm not really sure why you would use this when you can just use Attach, but it's there, just in case.
Link: Supposedly this allows you to link to other cosfiles you want to include in the agent. I've never used it, though.

As I mentioned earlier, Monk finds your agent's remove script on its own-- you don't need to specify it manually like you would when writing up a prayfile by hand.

Hopefully this guide will help some of you get a grasp on CAOS2PRAY and have an easier time compiling C3/DS agents. If you have any trouble, get confused, or notice any errors in this guide, do let me know. I aim to keep this as understandable and accurate as possible.