Cogs mod tutorial

From Lazy 8 Studios Wiki

Welcome the Cogs mod tutorial. In this document, I'll walk you through all the steps for making your own Cogs puzzles. There isn't a visual editor for Cogs, so you're going to have to get your hands a bit dirty. But the good news is that you can look at the source code of every puzzle that comes with the game, so you have lots of examples to get you started.

Original Creations

For starters, I need to get some legal details out of the way. You are invited (and, in fact, encouraged) to create your own puzzles and give them away for free. We even have a page at ModDB.com to make it easy to share your creations. However, you are not permitted to sell your original puzzles for profit. If you have a great design that you think is worth something, get in touch with us at Lazy 8 Studios and we'll consider purchasing your puzzle for use in an official expansion pack.

Resources

In addition to this document, there are several places you can go for help with designing your own puzzles.

The Cogs page at ModDB.com - A community of modders who can help if you get stuck.
Lazy 8 Studios Discussion Forum - General questions can go here.
Expansion Pack Syntax - A wiki doc that outlines the syntax of an expansion pack.
Puzzle File Syntax - Another wiki doc with details about every part of the .puzzle file.
Contact Lazy 8 Studios - If all else fails, contact the guys who made Cogs and wrote all these docs in the first place.

Now, on to the tutorial.

Definitions

To make sure we're using a consistent language, I want to define some of the terms that I'll be using in this tutorial.

Expansion pack: A text document in the data directory that lists one or more puzzles. You can try out an example by renaming ExpansionPackExample.hidden to ExpansionPackExample.txt. You can read more about this in Step 1 below.
Puzzle: A text file with a .puzzle extension that describes one level. The example expansion pack lists one puzzle file, data/puzzles/three-gears.puzzle
Board: The spatial relationship of tiles in a puzzle. This is defined at the beginning of a puzzle file and identifies the position, rotation and adjacency relationships between puzzle tiles.
Tile: A piece of the puzzle that slides as a single unit. A tile may contain one or more gadgets.
Gadget: A mechanical part such as a gear, pipe, chime, hammer, or block with a predefined behavior.

Step 1: Create an expansion pack

To make it easy to get started, we've included an example expansion pack with Cogs. To activate it, just change the extension of ExpansionPackExample.hidden to ExpansionPackExample.txt. If you purchased Cogs on Steam, then you'll probably find this file at C:\Program Files\Steam\steamapps\common\cogs\data. If you purchased Cogs elsewhere, then you'll probably find it at C:\Program Files\Cogs\data.

You may also need to add this line to the top of the file.

#cogs-levels v1.0

The next time you start Cogs, you'll see a new puzzle at the end of the list. Cogs recognizes any file with a name ExpansionPack*.txt as a valid expansion pack. To create your own expansion pack rather than using the example version, just create a file named ExpansionPack<packName>.txt, where <packName> is any name you choose to help distinguish your expansion pack from those of other modders.

It's easy to add additional puzzles to your expansion pack. For the full documentation on how to do this, check out the wiki document for the Expansion Pack Syntax.

Step 2: Choose a board layout

Eventually, you may want to design your own board layouts, but for your first puzzle mod, it will be a lot easier if you start with a puzzle shape that has already been designed. Once you pick a puzzle to start with, you'll need to figure out the file name for that puzzle. You can do that by opening data/loc/English/levelInfo.txt, which you'll notice has exactly the same syntax as an expansion pack. Find the name of the puzzle that you want to mod and you'll see the corresponding filename. Copy this file and give it a new name with a .puzzle extension (e.g., myFirstMod.puzzle). Then make sure that this puzzle is listed in the expansion pack that you created in Step 1.

Open the .puzzle file you just created and take a look through it. At the top, you'll probably see a comment section, where each line starts with the # character. This shows the flattened layout for your puzzle board, which will be useful to reference when you start laying out your gadgets in Step 5.

Step 3: Design your puzzle

An example of an unfolded puzzle schematic

Even though puzzles can be 3D, they must be designed in a flattened form. For instance, you can design a cylinder puzzle by unrolling the cylinder -- you just need to remember that the board spaces on the far left side of your diagram are neighbors of the board spaces on the right side of your diagram.

In general, it's easiest to design your puzzle in the solution form and worry about scrambling it later. This diagram shows my design schematic for the Trike puzzle. Note that I've unfolded the cube so that it can be represented in a 2D diagram.

When I design puzzles, I use different colors to represent different layers of pipes and gears. In this case, the small blue circles represent eight-tooth gears and the large blue circles represent the wheels. Don't forget to put an 'X' on each face of the puzzle to remind you that one space should be left blank.

Step 4: A clean slate

As you start to edit your .puzzle file, you may want to frequently refer to the Puzzle File Syntax wiki document, which gives a detailed description of each section of the file. To create a blank slate for your puzzle, you'll probably find it easiest to clear a lot of the data that you imported from the puzzle template. To do this, I recommend that you leave the camera, board layout, mesh, texture and material sections as they are. However, for the finish conditions, finish actions, sounds and animations, set each count to 0 and delete the other contents of that section. Completely delete the last few lines of your puzzle template -- the scrambles and checksum.

Next, remove all of the gadgets from your puzzle tiles. To do this, go through the list of tiles and replace each one with an empty tile. Note that you should not modify the POSITION values, but you should reset the LAYERCOUNT to 1 for each tile.

POSITION    <index>
LAYERCOUNT  1
GADGET geometry {  
  LAYER       0
  LIBMESH     meshTile
  LIBMATERIAL wood01 
}

When you're done with this step, try loading up your new puzzle file in Cogs. You should have all blank tiles. If there are any errors, a console window will open and they will be reported there.

Step 5: Add your gadgets

It's now time to add the gadgets to your puzzle. The good news is that there are lots of example puzzles to choose from, so in many cases, you can just cut and paste gadgets from them. For instance, if you want a straight pipe with openings in the left and right directions, open a puzzle file that you know has the part you're looking for and search for a pipe gadget with both OPENING_L and OPENING_R. As you add your gadgets, you'll probably want to frequently reference the Tiles section of the Puzzle File Syntax wiki doc.

As you add gadgets to your puzzle, remember that the LAYERCOUNT must always match the number of gadgets and the LAYER ids must be listed in increasing order. It's a good practice to frequently test your puzzle in Cogs to make sure that you haven't introduced any errors. There's no need to quit Cogs each time you test your puzzle -- just press Pause and Retry.

Step 6: Detect a solution

Once all your gadgets are in place, the next step is adding FinishConditions and FinishActions so that you can properly detect a solution and perform an animation when the puzzle has been solved. As with the gadgets that you added in Step 5, it's often easiest to cut and paste FinishConditions and FinishActions from other files and then modify the parameters as needed. Don't forget to increment the counter every time you add a FinishCondition or FinishAction.

Step 7: Scramble

Time to scramble your puzzle. Slide your tiles around in the Cogs engine to get them to a sufficiently scrambled state. When you're happy with how it looks, type the showscramble cheat code to get a printout of the current tile configuration. You can then copy and paste this at the very end of your .puzzle file. You'll need to create three different scramble configurations, SCRAMBLE, SCRAMBLETIME, and SCRAMBLEMOVES to set the starting layouts in Inventor mode, Time Challenge mode and Move Challenge mode respectively.

Common Mistakes

Cogs is particular that the number of items in a list exactly matches number of items actually provided. The most common error is adding or removing an item from a list without updating the total. If this happens, you'll probably see an error that looks something like this:

Error loading puzzle file.  Expected 'FINISHCONDITIONS'

If you see this, look for the section that comes immediately prior to the given keyword and make sure that the given list length matches the actual list length.

Advanced Material Editing

Screenshot of the realtime material editor in use

If you get to the point where you are creating your own models and materials for Cogs, you may find it helpful to use the built in material editor to tweak your material parameters. To use the editor, first add the EDIT keyword to a material description. Then load your puzzle file and type the MatEditor cheat code. This will open a console window where you will see the material parameters. With the Cogs window in the foreground, press up and down to select different parameters. You can use the Q, W, E and R keys to increment parameter values and the A, S, D and F keys to decrement values. Note that your changes are not automatically saved to your .puzzle file. You'll need to copy the changes to your puzzle manually.