Expansion Pack Syntax

From Lazy 8 Studios Wiki

Let's start by looking at the example expansion pack included with Cogs. To make this expansion pack visible to Cogs, change the extension of ExpansionPackExample.hidden to ExpansionPackExample.txt. If you open this file, here's what you'll find.

#cogs-levels v1.0
1
 
200 0  110 195 340  180 315 550  "data/puzzles/three-gears.puzzle"   "Three Gears"
"Piece together the
three interlocking cogs."

The first line is the header and should appear exactly as seen here. As of June 9, 2009, this header is missing from the example expansion pack included with the Steam version of Cogs, so you may need to add it yourself.

The next number, 1, tells us how many puzzles are included in this expansion pack. This is followed by a matching number of puzzle descriptions with the following format:

<id> <unlock> <timeGold> <timeSilver> <timeBronze> <movesGold> <movesSilver> <movesBronze> <file> <name> <description>

<id> is the unique ID of the puzzle and one of the trickier parts of sharing expansion packs. ID values 0-49 are used for the original 50 levels and values 50-199 are reserved for official expansion packs, leaving moders with 200-999. When you're creating your own puzzles, it's important that you pick and ID that is not yet used by any of your loaded expansion packs. If two puzzles share an ID, they'll both load, but they'll also share user data. For instance, if you complete one level, the award will show up for the other level with the shared ID.

<unlock> tells us how many stars we need to unlock the level. For expansion packs, you'll probably want this value to be 0.

The next six values, <timeGold>, <timeSilver>, <timeBronze>, <movesGold>, <movesSilver> and <movesBronze> give the time and move award thresholds for the gold silver and bronze awards. The time thresholds are expressed in seconds.

<file> is the name of the file that contains the puzzle, relative to the cogs directory.

<name> should be a quoted string with the brief level name that shows up in the selection list.

<description> is a multi-line quoted string that gives the description of the level that will show up in the overview widget when a puzzle is clicked in the selection list. This text won't automatically wrap to fit in the overview text box, so you need to use line breaks wisely.