Catalogues are a way of storing data about/for an agent in an easy, accessible manner. They were introduced in Creatures Adventures, and are available and used in all Creatures Evolution Engine games.
A catalogue file is a plain text file with the extension .catalogue in the 'Catalogue' folder of a game. They are made up of data, and comments.
Data is in the form of a tag name, which identifies the data, and then one or more fields of data associated with that tag.
Tags can be made using the TAG syntax, which lets you have as many fields as you wish associated with a tag...
TAG "tagname" "first field" "second field"
... or using the ARRAY syntax, which requires you to manually specify the number of fields associated with the tag:
ARRAY "tagname" 2 "first field" "second field"
If you're replacing an existing tag, such as many of the DS catalogue files do in order to replace C3 data, you need to add OVERRIDE after the TAG or ARRAY command, for example:
TAG OVERRIDE "a tag to replace" "replaced first field" "replaced second field"
Comments are lines which begin with '#' or '*', for example:
## This is a comment.
Or the remains of lines after a '#' or '*', for example:
TAG "tagname" # This is a comment.
Remember that if you want the .catalogue file distributed it with your agent, you have to include it in your PRAY file with the dependency category specified and the inline FILE command linking it into the agent, or easyPRAY can do it for you.
The most common use of Catalogue files is for writing Agent help for agents. Here's how.
TAG "Agent Help <family> <genus> <species>" "Agent name" "Agent description"
You can use the catalogue system for other things, such as multi-lingual agents, or arbitrary text or values the agent should read. You can do this with the READ or WILD command. Beware, when you do this, all catalogue files are searched, so name your tags thoughtfully.
An example tag, from Docking Station's misc.catalogue, is "portal misc", used by Agent Help to construct the text displayed while displaying agent help for a portal. The tag in-file is:
TAG "portal misc" "This warp portal has been identified as: "
And the CAOS code used to access it is:
SETS va01 READ "portal misc" 0
The following CAOS commands are relevant:
- READ and WILD for retrieving strings
- REAQ and REAN for getting meta-information
- REAF to refresh the catalogue
If a catalogue command goes wrong in some way, it will produce a Catalogue Error. Here are some types:
- Index r out of range 0 to N for tag tagname
- Couldn't find Tag tagname
Not being able to find the tag is a common error with the Creatures Exodus recompilation of Creatures 3 and Docking Station for Windows XP. Due to a security feature from Windows Vista not allowing games to create files in the Program Files folder (as in exported creatures), this was solved by creating a split installation, where part of the game was installed in My Documents. This included catalogue files.