The Cog Engine Project

Developer's Guide

Have you ever dreamed of creating your own video game?

Introduction

The Imagination Machine

“A computer is an imagination machine. It can take you places where you've never been before, where nobody has ever been.

“A computer is a magic wand. It can make things happen: exciting things, wonderful things.

“If you have ever played games on a computer, you know about these wonderful places and things. The most wonderful thing about the computer, however, is that you can use it to create your own wonderful places, where you and your friends can go. You can create strange worlds, exotic lands. You can even have adventures in these new worlds that you have created.”

--Christopher Lampton, How to Create Adventure Games (1986)

Computers do indeed make it possible for us to explore our imagination, and share pieces of ourselves with others. We can create entire worlds and fill them with our dreams. We can write stories than can be experienced, craft puzzles to be solved, build challenges to be overcome, and conceive enemies to be defeated. The only limits are our own creativity, and our ability to transfer our imagination into something concrete, that can be reproduced and shared.

The Cog Engine Project is about building the tools necessary to take our imaginations, creativity, and ideas and turn them into games, puzzles, and worlds. You shouldn't need to be a computer wizard to be able to write your own video games, and you shouldn't need to spend years of your life learning how to program if that's not the kind of thing that interests you.

The Cog Engine Development Application is a program that was written to take the all of the grunt-work out of writing video games. By following this guide, you can use the program to build your own video game . You don't need any programming experience, but you will need time, hard work, and your imagination. All of the software is free for you to use, modify, and share with others.

Mapping your Imagination

To create your own video game, the first thing you will need to do is use your imagination. This is the one of the most enjoyable parts of the entire process. You should try to be as creative as possible, but ultimately you're going to need to come up with an idea that works. If you want to tell a story with your game, you will need to be able to break that story up into small parts: individual rooms and locations, objects to fill your world with, and a feeling for wh at kinds of actions will be required on the part of the player in order to progress through the game. You can start out with a dream you had, or make a game in the same style as one of your favorites. What sort of game you create will be entirely up to you, so let your mind wander!

After you have an idea of what you want your game to be like, the next step is map out the landscape. This part of the game creation process is very important, as you'll be able to visually see how you are going to space out the different puzzles and objects in your game. Do you want a linear game where the player has to accomplish certain goals in a specific order, or do you want a free-roaming game where there's no “correct” path to the fin ish ?

You may find it helpful to start with a piece of graph paper and a few colored pencils. Draw a box in the center of the paper which represents the room the player will start in. Make sure that the box is large enough so that you'll be able to write inside . Mark the box with a number "1" and write a short description of the room - just a few words that will help you remember which part of your game 's world that box represents (such as “Beach front” or “Staircase leading down”)

Next, you're going to have to make an important decision - how you want to allow the player to be able to move around in your world. If this is your first game, the easiest way is to use compass points, such as “North” and “South,” and perhaps also diagonal directions (“Northwest” and “SouthEast”) and three dimensional directions such as “Up” and “Down.” In this document we will follow the example of the Cycon Odyssey, and use the se 10 types of movements . . Just like the rooms, each direction will eventually get a number too, but you don't have to worry about that right now.

Now you are ready to continue mapping out your video game. Draw one box for every room in your game, and connect the boxes with arrows labelling the direction you need to move from each room to get to the next. You can create one-way arrows (you can only move from the first room into the second, but not back again), or use arrows with dotted lines to indicated that a special action has to occur before the player can move from one room into the other. You can use whatever system of markings is easiest for you to remember, but it's important that you try to stay consistent, so that you'll be able to read your map later.

Something worth keeping in mind as you map out your game is how large you want the final game to be. If you're going to create a game with 100 rooms or more and you want your game to have graphics, you're going to need 100 different graphics or drawings just for the rooms, and that's before you start figuring in all of the objects in your game! For your first attempt at making a game, you may want to start with something simple, say 20 rooms or so, and don't worry about graphics. Once you get the hang of creating a small game from start to finish, you'll find making a larger game is much easier.

When I created the Cycon Odyssey, I created an island where the player would be able to explore beaches, forests, mountains, treetops, and even underground tunnels. I broke the island up into a eastern and wester section, and although the player can wander over almost all of the eastern half of the island from the moment they start playing the game, there's a series of tasks that they'll need to accomplish before they'll be able to reach the western side. The same goes for the treetops and tunnels. By giving the player a large space at the beginning of the game to wander around in, they'll have lots of different puzzles and areas they can explore in any order they choose, so they (hopefully) won't become bored too easily, or think the game is too hard. By leaving some of the more exciting locations and puzzles for later in the game, the player gets rewarded for their time and effort by finding new areas to explore. 

I don't have a picture of the original map I created for my game, but here is a picture of summarized version I created that I could carry around in a notebook, so that I could work on my game while on the go:

Filling the World

The next step is to fill your world with all of the objects the player will come in to contact with. This include s the items that the player may pick up along the way, and the obstructions that will block their path forward. You might find it useful to make two lists, one of all of the items, and one of all of the obstructions, and then begin to figure out where on your map the objects should be located. “Items” can be loosely defined as any object the player encounters within a room, and an “obstruction” is any object that exists between rooms, right in the middle of the direction arrow. To help yourself remember, you can color in each of your room boxes with a colored pencil to indicate the location of objects.

In the “Introductory Walkthrough” section of the Cycon Odyssey's Playerguide, there is an example where the player finds a rope tied to a tree branch, unties the rope, and ties it onto an arrow. In order to set up something like this, you'll need to create a separate item for each possible combination. Therefore, in this example you have:

Rope Tied to Tree Branch

Tree Branch

Rope

Arrow

Rope Tied to Arrow

After you have a pretty good idea of what sort of items and obstructions your game will have, you will be ready to start entering your game information into the Cog Development Application.

Putting it all together

You'll need to refer to the Cog Development Application's installation documentation to get the program running on your system. After the program starts, you should see a single window which looks like this:

As you build your game, you will click on each of the buttons, going down the column, and filling out the forms that appear. By the time you've reached the bottom and finished filling out the Events form, you game will be complete! Reme m ber to close each window after you're done filling out the information, b ecause the program doesn't record any changes until the window is closed. Let's click on the Game Information Editor, and begin entering some background information about our game:

Game Editor

Here's a description of what each blank is looking for:

• Game Title - Enter the title of your video game here
• Game Designer - Put your name here, so that you'll get credit for creating the game
• Game Designer's Email Address - It's a good idea to leave some sort of contact information so that players can get in touch with you to give you feedback on your game
• Last Update - Enter the date you la st made a change to the game here. It's helpful to be able to know when you last made a change, especially if you keep backup copies of old game files around.
• Version Number - Give your game a version number that indicates how far along it has come
• Game URL - This is the address of your video game on the World Wide Web. If you're not going to host your game online, you don't need to fill this out, but it will be useful to keep this updated later
• Database URL - You won't need to fill this blank out either if you're not going to place your game online.
• Image Directory - This entry is important if your game will have graphics, because it tells the Cog Engine where to look for your graphic files. A good place to keep your files is in a subdirectory of where you place the Cog Engine. If you don't have any graphics yet, just leave this entry blank.
• Image Loading Graphic - Enter the filename of a graphic to be displayed while your game graphics are being downloaded. A simple picture which says something like “Graphics Downloading” should suffice. (It's ok ay to leave this blank for now)
• Introduction Graphic - Enter the filename of a graphic that should be displayed when the game is first loaded up. (It's ok ay to leave this blank for now too)
• Introduction Text - This is where you enter a few sentences or paragraphs that get displayed when the game is played for the first time. You should have a small introductory storyline, with perhaps a little indication as to what the player is supposed to accomplish.
• Debug Mode: Debug mode will print out some extra information about the game while the player is playing it (such as displaying the number of the current room the player is in). It's very helpful to have this turned on (set to “true”) while you are working on your game, but you'll probably want to turn it off when you are finished.
• Game Settings - These are miscellaneous settings that change how the interface looks to the player. You may want to experiment with the various settings to get the look of your game just right. It's safe to leave these on for now.
• Notes - This is just a useful section for you to jot down your thoughts as you put your game together. You may want to use this space to keep track of what you have left to do, or where there are problems you need to fix.

Here's how the Cycon Odyssey's game editor looks, after it has been all filled out:

Player Editor

The next editor to fill out is the Player Editor. This editor configures the player's character at the start of a new game. This includes what the player's name should be, which room they start out in, and what items are in their inventory at the beginning of the game (if any):

Since you haven't created any rooms or items yet, it's probably best to just leave this editor alone for now. When you are ready to fill out these entries, all you need to know is that a "-1" in any form means that the corresponding player statistic isn't used in your game. All of these statistics are off by default. Here's what the the Cycon Odyssey's player editor looks like:

Direction Editor

Next in our list is the Direction Editor. This is where you will enter each direction the player can move in, along with a unique number for each direction. In the case of the Cycon Odyssey, these numbers are:

1 - NorthWest

2 - North

3 - NorthEast

4 - West

5 - Center (this direction isn't actually used in the game, but we keep it for the sake of the graphical compass - more on this later)

6 - East

7 - SouthWest

8 - South

9 - North

10 - Up

11 - Down

In the abbreviations blank, you can enter a shortcut the player can type into the command line (if you are using a command line in your game) to represent the direction they want to move in. The next three blanks are for the graphics the graphical compass should display, depending on the status of that direction in each room. For instance, if the player can move west from the room they're currently in, but not east, you can have the compass show a color in the western direction (such as orange) to indicate that they can move, but a different color in the east (such as grey) to indicate that they can't. An “obstructed” compass image means that they player would be able to move in that direction, but there's an obstruction in their way.

After you fill out the information for the first direction, click the “New” button to add another, and so on, until you've entered the information for each direction. You can then use the arrow buttons to cycle between entries. If you want to skip to a specific direction number, just type that number in the blank and hit enter. If you want to delete a direction entire ly, just remove the name and either close the editor or switch to a different entry. A dialog box will appear that warns you that the direction has no name and will be deleted.

If you're not certain on how to set up you r compass graphics, you can just use the default graphics from the Cycon Odyssey, and set up your directions according to the Cycon Odyssey's example:

Room Editor

Now that the groundwork for the game has been laid down, it's time to starting telling the computer what your map looks like. After opening up the Room Editor, you'll be presented with a window that looks like this:

The Room Editor is one of the largest and most complex in the program, so we'll take this step by step. Don't be intimidated by all of those entry fields, here is what they all mean:

• Room # - Just like it says, each room in your game and on your map has a number.
• Room Name - Enter the name you gave your room on the map here. This will make it easier to find on paper later, should you need to reference where you are .
• Graphic Image - This is the graphic that should be displayed whenever a player enters the room.
• Text Description (Long) - The first time a player enters a room, you're going to want to give as detailed a description of their surroundings as possible. The more creative and well-written your descriptions are, the better the player's experience will be. Don't worry about describing the directions a player can travel however, we'll come to that in a moment .
• Text Description (Short) - Each time a player revisits a room, they shouldn't need to have to read through an entire paragraph of text to recognize where they are. Enter a shor t , one or two sentence long summarized description of the room here .
• Direction Description - This is where you describe each of the directions the player can travel . You may want to capitalize the name of the direction they are able to travel, in order for the word to stand out .
• Player Has Visited This Room - This is a marker that tells the program whether to display the full or short description when the player enters the room. You should leave this set to “false” by default .
• Items and Available Items - This is where you tell the computer where to place each item when the game is played for the first time. The Available Items drop-down widget contains the full list of all of the items in your game, and will be empty when you are first creating your world. After you have added items, if you want to place one in the current room, simply select it from the list, and click the Add Item button. The Item will be appended to the list in the Items window. To remove an item from the current room, just delete the entire line from the Items window.
• Directions - This menu contains a list of each of the possible directions the player can travel in. By default this list is empty, and until you have filled out the Directions Editor and added a few rooms, you won't be able to change any of the direction settings. When you are ready to connect all of the rooms together, select “Add New Direction” from the directions menu, and select which room that direction leads to from the “Leads To Room” drop-down list. If you select “Nowhere” from the list, the current direction will be removed.
• Player Has Moved This Way - Just like the Player Has Visited This Room entry, this entry is more for the computer's benefit than the game developers. You can safely leave it set to false.
• Obstructions and Available Obstructions - This menu set works in exactly the same way as the Items and Available Items menus described above. There is one important difference however; when you are dealing with Obstructions, their location is in a room's direction (the one showing in the Directions menu) and not in the room itself. Also, when adding an obstruction, if th e path is blocked between the current room and the adjacent room, you'll need to add the obstruction to both room s ' directions. This may be a little confusing, but in other words, if room A is east of room B, and there's a boulder in between both rooms, you'll need to add the obstruction to room A's east direction, as well as room B's west direction in order to properly simulate a boulder blocking the path.
• First Transition Text - This is optional text that gets printed out the first time the player moves in this direction from the current room.
• Transition Text - This is optional text that gets printed out each time the player moves in this direction from the current room.
• First Transition Graphic - This is a graphic which gets shown in the same manner as the First Transition Text
• Transition Graphic - This is a graphic which gets shown in the same manner as the Transition Text.

The “New” and arrow buttons at the top of the screen work in the same way as in the Direction Editor. Here is what the first room of the Cycon Odyssey looks like:

By the time you've finished entering all of your rooms and their direction connections into the Cog Development Application, you will be able to actually load up your game and explore a little. You won't be able to interact with the environment very much however, until you've finished  entering all of the items and obstructions, and told the computer what sort of actions the player can take.

Item Editor

The item editor is where you enter all of the information about the various objects in your game's rooms. After you open the editor for the first time, it will look like this:

The various entries here are pretty easy to understand, but deserve explanation:

• Item # - The current item's number. Just as with Directions and Room, each item in the game requires its own unique number .
• Name - The item's name. This is what will get displayed by the Cog Engine when it lists each of the items in the room .
• Aliases - If there's more than one word that you want the player to be able to use when describing the current item, enter each word or phase, separated by commas, here. An example would be allowing a player to call a “dagger” a “knife” and have the computer understand that the player is referring to the same object. Another way to use this feature is to give the player a shorter name to work with, such as giving the “Rope Tied to Arrow” the aliases “rope” and “arrow.”
• Environmental Graphic Image - This is the graphic that should be displayed by the Cog Engine whenever the item is in the current room, but not in the player's inventory
• Environment Graphic Coordinates - The X and Y coordinates, relati ve to the upper-left corner of the current room's graphic. The Environmental Graphic Image will get displayed at th ese coordinates, on top of the current room's graphic
• Closeup Graphic Image - If a player “Examine"s or “Look"s at a particular item, this graphic will be displayed.
• Icon Graphic Image - Not currently used by the Cog Engine, this feature will allow an icon to appear in the player's inventory window if this item is in their inventory .
• Equipped Graphic Image - Also not currently used by the Cog Engine, this feature will allow a different icon to appear in the player's inventory window if the item is in an “equipped” state ( For e xample, consider a flashlight . If the flashlight is “off” then the Icon Graphic will be displayed. If the flashlight is “on” then the equipped graphic image will be displayed) .
• Text Description - This text is displayed whenever a player Looks at or Examines an item .
• Current Locations - This window shows you which rooms currently contain this item. ( You can't edit this information directly, you'll need to open up the Room Editor to the corresponding room if you want to add or remove an item from that location )
• Equipped - This indicates whether the item is in a “used” state or not (such as whether a flashlight is currently turned on or off)
• Weight - If this is set to “-1" then the player cannot pick up the object. This is important if you want to place a large object in a room that the player can examine, but can't move. You can also limit how much weight a Player can carry by entering a number in the Player Editor's Weight blank. You can give each item a numeric weight, and if the combined total of all of the weights of all of the items in the players inventory meets or would be above   the player's maximum weight limit, then the play can't pick up any more items .
• Bulk - This works similar to the weight restriction described above, except that you can use this to describe how many objects can fit into a particular container, regardless of their weight. For instance, if all a player has to carry their items around in is a knapsack, then even if they player can lift up 255 arrows, you can set the “bulk” to be too large for the knapsack.

Here's an example Item Editor entry from the Cycon Odyssey:

Obstruction Editor

The Obstruction Editor is practically identical to the Item Editor, with only one major difference : the “Visible” setting. This setting determines whether or not a player can see what is obstructing their path in a particular direction. If you game has a “flashlight” item, which the player must use in order to move from room X to room Y, then you can place an obstruction between the two called “Darkness,” but which will not be listed when the player enters either room . You can set up the “Darkness” obstruction to be removed from between room X and Y whenever the player turns “on” the flashlight, and it can be put back into place whenever the player turns “off” the flashlight, or drops it from their inventory. You'll learn how to control details like this in the Event Editor section .

Here's an example Obstruction Editor entry from the Cycon Odyssey:

Verbs and Events

By the time you have finished filling out all of the above editors, your game world will be completely set up. The next phase of development will instruct the computer what sort of actions the player can take in your game, and what effects those actions will produce. Whereas most video games would use complex programming code to accomplish this, the Cog Engine works upon a much simpler principle. You can point and click to build rules for each of the player's actions. Anything that you don't create a rule for, the player can't do. It's as simple as that.

Verb Editor

Each pair of actions and effects are called "Events." Each event is grou p ed according to the verb used in the action. A few examples of verbs would be " Use , " "Get," "Drop , " "Combine , " etc. When you fi rst load up the Verb Editor, the window will look like this:

Just as wi th the previous editors, each very will b e given a number, and that's the first entry you see. The "Name" entry is where you enter each verb, and the "Aliases" entry allows you to use the same verb when describing different actions (using commas to separate indivi dual aliases). For instance, i f a player finds a magic al potion in your game, and you want to allow the player to "Drink" the potion, you can make "Drink" an alias of the verb "U se ," and also add aliases such as "Quaff ," " S wallow," "Sip,"  and so on. Using aliases for verb names make the game a little eas ier for the player if they are using the command line to play your game, since they won't get stuck playing "word guessing games" if they want to perform a particular action , but aren't thinking of the same verb as you were when you designed the puz zle.

A sample completed verb entry from the Cycon Odyssey looks like this:

Event Editor

The Event Editor is where everything gets tied together. There are two important components of this editor, the Event Build er and the Event Editor itself. A third comp onent, the "Event Gramm ar Reference" is provided for the benefit of serious programmers, who want to know the nitty-gritty behind the game engine. If you don't know what an EBNF grammar is, or how to read one , th en you can safely ignore this component.  Let's take a look at the default event builder screen:

You'll notice a lot of blank selection boxes in this screenshot, because the event builder uses all of the game 's current data to produce its menus , and this screenshot was taken with an empty game. Here's a look at a n event in the process of being built from the Cycon Odyssey:

This eve nt is taken from the C og Engine player's guide walkthrough. E ach event is co mposed of at least three categories: an action, an object, and an effect. You may only have one action per event, but each even t can have up to two objects, and an unlimited number of effect s. This example event has one action ("Use"), two objects (the " Dagger" item and the "Savage" obstruction), and a series of effects which we go into the de tails of shortly.

T he list of available actions is built based on each of the verb names in the verb editor ( Aliases for ve r bs are not listed ). Simply click on the menu, and select which verb you want to use for the particular event.

The next two items you see are the "<Object>" and "<Reference>" widgets . Select whether your want to refer to an item or an ob struction, and then pick which one you want  from the drop down list . If you want to add a second o bject (usually the recipient of the action), click the "Add Object" button at the top of the window , and select the object. "Remove O bject" will remove the object if you change your mind.

You can set up further "Requirements" for an action to be considered a match , such as the player having to have a certain i tem in their inventory, or a certain condition existing (such as a flashlight being turned on /equipped).

Last, we have the event's effect list. You can specify a wide variety of effects for any particular action, so it would be a good idea to experiment for a bit with some of the different combinations you can create. In this example from the Cycon Odyssey, we want to desc ribe to the comp uter what should happen if the player attacks someone they find on the island with a dagger. We want the person , who was previously obstruction the player from moving west from room 5 to room 7 (and vice versa to the ea st) , to run away, and leave behind a bow and arrow. We also want to print out a short message that tell s the player what happened , and gives them a sudd le clue that there might have been a better way to remove this particular "ob struction" from their path, be side an aggressive assault.

After selecting our action and objects, we can be gin to build up the ef fects list. First we want to remove the ob struction from the players path. It is important to reme mber to remove the ob struction in both directions , or else the player could get stuck and not be able to return. Next, we want to add the "Bow " and "Arrow" items to the room the player is currently in. We could also specify that items are arbitrarily added to or removed from a ny room in the game, if we so desired. Finally we set up a TextMessage to be displayed to the Cog Engine's output window.

Once our even t is build, we click the "Append Event" button to add our event to the game's list of events. This list is stored inside of the Event Editor component. Clic king on the Event Editor component in the Cycon Odyssey will produce a list of all of different events in the game. Since it is usually easier to read t his list if we display object and room references by name, that option was clicked on for this screenshot:

The event editor will group events together according to the ver b sel ected in the action box of the event builder. When a player in the game attempts to perform an action, the Cog Engine will search through the event list , looking for a possible match. If it finds one, it will immediately execute that event's effect list, and will stop searching. Therefore, if you have two different events with the same action block, the first one with all of its requirements met will take pre c edence.

Each event listed is specially formatted according to the EBNF grammer described in the

Event Grammer Reference tab. If you want to tweak events by hand, you can edit them directly in the Event Editor by keeping the formatting the same, or you can always delete an event and rebuilt it with the Event Builder.

Finishing Touches

Creating a video game can be a very time-consuming process. All too frequently, the part of the development process that requires the most amount of time is putting on the "finishing touches" to make sure that a game works the way you (the developer ) int ended. You will need to play through your game many times to make certain that everything works co rrectly. You may want to ask a friend to try your game while you watch , so that you can get an idea of how someone else might p erceive a certain puzzle or situation. If you are going to place your gam e online, you might want to create a website centered around the game, to get others in terested in playing it. What's most important is that you have a good time being creative and b uilding a new world for yourself and other to explore and e njoy!