Getting Started with Ogmo Editor

by Matt Thorson
with tiles by FrankieSmileShow

Contents

1. Introduction
2. Starting a New Project File
3. A Very Basic Level
4. Grid Layers
5. Tile Layers and Tilesets
6. Object Layers and Objects
7. Conclusion

1. Introduction

This tutorial will teach you how to use Ogmo Editor. It will teach you how to build a project file in stages, starting with a very simple project and growing into a complex one. As I go, I'll also be teaching you how to use the editor to make levels, and I'll be pointing out how the editor formats the levels it outputs so you can more easily get them into your games.

It will not cover programming specifics on importing the finished stages into your game - this is language/library-dependant, but with an understanding of XML it is very easy to do. There will be more tutorials in the future regarding getting Ogmo Editor levels into games made with various languages/libraries such as Flash (including FlashPunk and Flixel) and XNA.

A quick note before I start: Whenever I refer to using the CTRL key, use the Command key instead if you are on a Mac.

2. Starting a New Project File

Project files are just XML files with the extension changed, and XML files are just text files written in a specific format. The simplest way to write a project file on Windows is in Notepad. If you have it, FlashDevelop also works good for this (select File->New->XML Document). Really, anything that can save simple text files works, but make sure you don't use a text editor that adds any special formatting characters to the file when you save it (for example, WordPad adds formatting characters when it saves .rtf files).

So step 1: open your text editor of choice and start a new file.

Now, the root tag in an Ogmo Editor project file must be the <project> tag. So we start with that:

Now that our project is started, the first thing we'll do is specify a project name. This isn't required, but you'll want to use it to keep different projects distinct in the editor. To specify a name, we just throw a <name> tag into the project and put our desired name inside of it.

This is the beginnings of your first project file! Now let's save it. Ogmo Editor project files must have the extension .oep or the editor won't be able to find them. This also allows you to open them quickly (.oep files are associated with Ogmo Editor). So don't save it as a .txt or .xml file. Select "all files" and save the file as "project.oep".

If you try to open the project file right now, it won't work. But Ogmo Editor will tell you what's wrong (in this case, the project has no <settings> tag).

3. A Very Basic Level

Okay, now we're going to get your project opening and get you making a level. This will be a very basic level though - we're only going to be using the simplest features of Ogmo Editor in this step, so no objects or tilemaps yet, just something called a grid.

First up, we need to define a few things for Ogmo Editor so that it knows how to set up stages for us. We need a <settings> tag in our project.

The <settings> tag holds all the miscellaneous options for a project, such as default stage size, background color, etc. Most of the settings are optional and your project will open even if you don't define them (they'll be set to defaults), but we need to define the default stage size. We do this with two tags: <defaultWidth> and <defaultHeight>.

Now Ogmo Editor knows what size stages should start at. Right now, stages will be stuck at the default size because we haven't defined separate max/min sizes, but for this tutorial we don't need resizable stages (if you want to try anyways, the tags are <minWidth>, <minHeight>, <maxWidth> and <maxHeight>). Next we need to define a layer. All the project's layers belong, predictably, inside a <layers> tag.

Ogmo Editor has three types of layers: the <tiles> layer, the <objects> layer and the <grid> layer. We're just going to start with a grid, because it's the simplest.

We're still not quite ready to load this up yet, though. The <grid> tag has a couple required attributes. Every layer is required to have a name and a gridSize. The name will uniquely identify each layer; this means you aren't allowed to have two layers with the same name. Let's call our grid "floors" for now - grid layers are usually best for defining things like solid blocks. Our layer's gridSize defines the smallest block we can place. You'll see this in action for a second and it'll make more sense - for now just set it to "16". Note that all attributes, whether they're strings or not, must be enclosed in double quotes ("").

Okay, now it's time to load it up! As mentioned before, .oep files are associated with Ogmo Editor, so you could just double-click the file in your file explorer. Alternatively, open Ogmo Editor and select "Open a Project", then find your project file. If the file doesn't open at this point, Ogmo Editor will tell you why if it can. Occasionally however, Ogmo Editor won't be of much help, just giving you an error code (ex: "Error #1090"). If the error is ambiguous like this, it means there's a problem with your XML formatting, or your text editor is adding in formatting characters (line breaks, etc) that are messing with the XML parser.

4. Grid Layers

When you open the project, a new level will be created for you. Because we only have one layer and it happens to be a grid, there isn't much to play around with yet. What you can do is click anywhere on the stage to "paint" a block, or right-click to "erase" it. Hold CTRL and click to flood-fill from the clicked grid cell. Do the same but right-clicking to flood-erase. You can also press CTRL+Z to undo the last action and then CTRL+Y to redo it. Not all that exciting yet, but you could design some floorplans for a platformer or a top-down game with this. Let's add some rectangles of blocks and then save the level to check out how it's being saved.

make a stage something like this, then save it

Save the file as anything (with the .oel extension) and open it in your text editor. Here we'll get a glimpse at how Ogmo Editor formats the levels you save, specifically how it formats grid layer contents. The one in the picture above looks like this:

First off, the editor always uses <level> as the root tag of level files. It then exports the level width and height (though we'll see later a way to disable this), followed by all your layers (of which we currently have only one). As you can see, Ogmo Editor is exporting the grid's contents within a <floors> tag, because we named our grid "floors".

Ogmo Editor, by default, exports grids as a string, with "1" for a painted block and "0" for an empty one. There's a couple ways we can modify this output, though. For example, right now Ogmo Editor is separating each row of the level by starting a new line in the string. If we give the grid a newLine attribute, it will use that instead. Let's see what newLine="-" looks like.

If you add this to the project, save it, and reload it in the editor (close it then open it again) you can see how this affects the level files. In a new level, draw some rectangles and then save the level. Opening it in your text editor, you can see that the whole string is now all on one line but with rows separated by a "-" character. Note that you won't be able to load the old level after changing the newLine attribute - Ogmo Editor will expect "-" characters to mark the ends of rows where there where there are line breaks.

Another useful way to define the output of grid data is with the exportAsObjects attribute. This optional attribute defaults to false, but if set to true tells Ogmo Editor to group blocks into rectangles and output those rectangles. Let's try exportAsObjects="true".

Reload the project again and save another level with a few rectangles of blocks. Here's what the level in the image above looks like with exportAsObjects="true":

Much simpler! Note that the editor grouped the blocks into rectangles and exported their positions and sizes. This method of exporting works great for the level shown, but if the level had lots of single-blocks or diagonal arrangements of blocks it would end up using more characters than the default string mode. Use whichever mode works best for your game!

I haven't covered every attribute of the grid tag. All the attributes are shown in the following reference table. This tutorial won't cover every attribute of every tag, but I will give reference tables for all the layer types and their related tags.

5. Tile Layers and Tilesets

Before we get tilesets working, it's worth talking about project organisation. Now that we're getting into adding graphical resources to the editor, it's best to put your project file where you want it to be in relation to your game's source code. How I like to structure my projects is to have a subfolder named assets in my game's directory, which will hold all non-code content. Then I create assets/gfx for all the game's graphics (possibly further sorted into subfolders like tilesets, enemies, player, etc) and assets/levels for all my level files. I put my project file in assets/levels. This way, as I'm browsing the levels folder, I can quickly open a level to edit it by first double-clicking the project.oep file, and the then double-clicking the level.oel file. For this tutorial, create a folder called "example". Inside it, create folders "gfx" and "levels". Put your project file in the "levels" folder.

Ogmo Editor loads images on project load, so you provide paths to images in the project file and it will load them anew everytime the project is opened. This means that you can edit graphical assets in your assets/gfx folder to have them change their appearance in your game, and the next time you load the project in Ogmo Editor they will have changed there as well. All paths to images in your project file are relative to the location of the project file (making it easy to, for example, sync a project file across different machines over SVN and have it still work).

As we are specifying paths for images in our project, we're going to notice something. All of our paths are going to start with "../gfx/", followed by the filename of the image we are loading. We can go back to our project's <settings>, and add a <workingDirectory> tag to automate this for us.

This <workingDirectory> tag basically says: for every path defined in this project, evaluate it relative to the working directory, rather than relative to the project file's directory. This also has an added bonus - if we later rename or move the "gfx" folder, we only have to change the working directory to get our project working again, not every single path in the project.

Okay, with that out of the way let's step up to the next layer type: the <tiles> layer. When editing tile layers, you place tiles on them. tiles are pieces of tilesets. So to get tile layer editing running, we first have to define at least one <tileset>. Let's throw a couple <tileset> tags into our project file. As can be expected, all of our <tileset> tags will reside within a <tilesets> tag in the project.

The <tileset> tag has a few required attributes: name, tileWidth, tileHeight and image. name uniquely identifies each tileset; no two tilesets are allowed to share a name. tileWidth and tileHeight are the sizes of the tiles within the tileset. image is the path on your filesystem to the image for the tileset. Here's two example tilesets we can use.

some tilesets for us to use

Save the above tileset images to your gfx folder as tiles_bricks.png and tiles_grass.png respectively. Now let's set our tilesets' attributes.

Now we have some tilesets but nowhere to use them. Let's add a <tiles> layer. The <tiles> tag has the same required attributes as the <grid> tag: name and gridSize. Let's go with name="tilesAbove" and gridSize="16".

Also keep in mind that the order you define your layers in matters. In the above example, the "tilesAbove" layer will be above the "floors" layer. If you reversed their order, their depths in the editor would also be reversed. Now let's open up the project in the editor and do some tilemap editing!

Now that we have more than one layer, we're given a "Layers" window in the upper left corner. You can grab it by clicking its title bar and drag around to put it wherever you like. Click the buttons inside to select a layer to edit (the numerical keys are also hotkeys for switching layers, 1 being the top layer, 2 being the second and so on). Switch to the tilesAbove layer. Note that you can still see the layers below and above the currently selected layer, but you cannot edit them unless you switch to them.

Because this is a tile layer, we're shown the "Palette" window and the "Tilesets" window. Click anywhere on the tileset image inside the palette window to select that section as the current tile. Click anywhere on the level to place that tile. Right-click to remove the tile under the mouse cursor. CTRL+click and drag to fill a rectangle with the selected tile, and CTRL+right-click and drag to delete a rectangle of tiles. To speed things up, you can also use the arrow keys or the W/A/S/D keys to move the tile selection in the palette. You can also undo and redo just like with grid layers.

After placing some tiles, try switching tilesets by clicking the "grass" button in the tilesets window. Notice how all your tiles are swapped for their matching tiles in the grass tileset (this can be undone just like placing tiles). Mess around for a while and save a level with some tiles in it. Now open your level file in your text editor and it should look something like this:

The <tilesAbove> tag has an attribute set, showing which tileset it is using. It is also apparent from this file that Ogmo Editor exports tile data as tags, with one <tile> tag representing one tile. The tx and ty values are where the tile's top left corner is positioned on its tileset. The x and y attributes are its position in the level. Like with <grid> layers, we can format this output a bit. First we'll try the exportTileSize attribute. Below I'm adding in the exportTileSize attribute to the "tilesAbove" layer, and then showing you how the level output changes.

The only change here is that our layer now has tileWidth and tileHeight attributes describing the size of the tiles in the tileset it is using. Something else we can do is set the exportTileIDs attribute in the <tiles> tag to true. This will make tiles export a single value ("id") instead of "tx" and "ty". Where "tx" and "ty" are the co-ordinates of the top-left corner of the tile on the tilset, "id" identifies tiles by their order on the tileset. For example, the top-left corner tile is tile number 0, the next to the right is 1, and so on. If our tileset is 4 tiles across, the first tile on the second row would be tile number 4.

There's one other major feature of tile layers: the multipleTilesets attribute. If we set multipleTilesets="true" for a tile layer, you'll be able to add tiles to that layer from several tilesets at once. However, you lose the ability to swap tilesets, and on export the tileset will be exported per-tile, not just once for the whole layer. I'll leave you to experiment with that if you need to use it.

6. Object Layers and Objects

Now it's time to add an Object Layer. What can you do with object layers? Object layers let you place instances of "objects". Object instances can be moved, resized, or deleted. You can set a limit to how many of one type of object can be on a stage (ex: you may want to ensure only one player object can be on a stage).

Objects can be given "values". Values are essentially variables. You define the values and their types, then you can set the values independantly for each isntance of the object. For example a treasure chest object may have an integer value "coins" for how many coins are inside it.

Objects can also be given "nodes". Nodes are a way of planning out the motion of moving objects. For example you can use them to mark where on a level a moving platform will travel. The editor will show you visually how the object would look at each node's position, so you can see how it fits in with the rest of the level.

This tutorial will not cover values or nodes. Those will be saved for a more advanced lesson. Right now I just want to get you placing, moving, deleting and resizing objects. So first we need some images to use for our objects. Here's some, download them and save them in your gfx directory as "ogmo.png" and "spikes.png" respectively.

some object images for us to use

Let's start with Ogmo. We want him to be named "ogmo", we want him to be 16x16, non-resizable and we want each level to have at most one instance of him. Here's how we do all that:

Notice that we didn't have to do anything to make him non-resizable because this is the default. Also, we could just as easily set the cap of Ogmos-per-level to any number, not just 1, by changing the limit attribute. Now we need to actually add an <objects> layer to the project so we can place him. We want the new layer to be above the floors layer but below the tilesAbove layer, so we put the new tag between those two tags in the project file, like so:

There's nothing you haven't seen before with the other layer types here. Let's load the project up and get editing. Now your Layers window will let you select your new layer. Switch to the "actors" layer. Now you're presented with the "Tools" and "Objects" windows. Click on a tool button to see its name in the title bar of the Tools window. Select the "Create" tool (far left) and click anywhere on the stage to place Ogmo. Notice that if you place a second copy of Ogmo, the first disappears because we have a limit of 1 for Ogmo objects. Also note that if you click to create Ogmo but keep the mouse button held, you are automatically switched to the "Select" tool, and able to move Ogmo around until you let go of the button (and then you are also returned to the "Create" tool).

You can switch to the "Select" tool (second from the left) and click and drag to move Ogmo around. You can deselect Ogmo by clicking an empty space on the level. With Ogmo selected, you can press the arrow keys to move him or DELETE to erase him. You can also delete objects by right-clicking them (this also works while using the "Create" tool).

Now let's add a resizable object. We want to add spikes, but we want them to be resizable on the x-axis (and not the y-axis) so we can stretch them to cover platforms.

Our spikes object should now start at 16x16, but be resizable along the x-axis. Reload the project, and let's see this in action. Create a spikes object anywhere on the level. Now switch to the "Resize" tool (third from the left). There's several ways to resize objects, the easiest is just to click the object, using the "Resize" tool, and drag your mouse to the right to make it bigger, to the left to make it smaller. The first thing you'll notice is that our spikes object is very ugly resized, because the image file we have for it is meant to be tiled, not stretched. To remedy that, we use the tile attribute in our <object> tag.

ewww that's ugly

Now reload the project and try resizing a spikes object again, the result should be much better looking. The tile attribute doesn't affect the output of the editor at all, it's just a cosmetic change to make editing a bit easier. Some other cosmetic object attributes are imageWidth and imageHeight, for specifying an area of the image file to use (by default it uses the entire image file). There's also imageOffsetX and imageOffsetY, for specifying where on the image file to get the area defined by imageWidth and imageHeight.

much better

Now, let's pretend our project has lots of objects. So many that we're getting lost looking for them in the Objects window. We can sort objects into folders to help us find them easier. We can have as many folders as we like, and we can even have folders within folders (and folders within folders within folders and so forth). Let's set up a single folder.

If you reload the project and look in the Objects folder, you'll see the spikes object neatly sorted into its own folder.

To finish off the section on the <objects> layer I'll just run through some more useful hotkeys. Q, W, E and R are hotkeys for the four tools, in order from left to right. With the "Select" tool, you can click and drag to rectangle-select multiple objects. Hold CTRL and click an object to select it in addition to other currently selected objects. Hold CTRL and use the arrow keys to resize all the selected objects that are resizable. When moving an object with the "Select" tool, use CTRL to toggle quick-switch back and forth from the "Resize" tool.

7. Conclusion

This basic tutorial will hopefully have taught you how to set up and use all the layer features available in Ogmo Editor. Further tutorials will cover more advanced features, such as object values and nodes. Happy editing!

You can download the finished project file and all its graphics here: Download