Level Architect Owner’s Manual

For the Citrus Engine

By Eric Smith

http://citrusengine.com

Don’t understand something? Let us know so that we can make it more clear!

What is the Level Architect

The Level Architect is a 2D grid-free level editor built specifically for the Citrus Engine (however, as will be explained in detail later, it could be used for any appropriate engine).

The Level Architect essentially creates an XML file that tells the engine which game objects to create (Platforms, Coins, Enemies, etc) and what properties to set (X, Y, Speed, Health, etc). The engine itself is responsible for actually creating the objects and setting their properties. The Level Architect’s responsibility is to make it easy to define the layout of the level, and the engine’s responsibility is to accurately create objects from that definition.

The Level Architect also makes your life easier in a couple of other ways. Besides helping you design pixel-perfect levels, it will also do the following things:

Why Use the Level Architect

The Level Architect, like any level editor, is a critical tool for creatively designing engaging levels. Without a level editor, the only way to build levels is to manually create and position each object with code. For medium to large levels, this process becomes unwieldy and ultimately restricts creativity.

The Level Architect itself was created specifically for the Citrus Engine, so while you can use any appropriate level editor that you’d like with the Citrus Engine, you’ll find that the Level Architect provides a superior work flow.

Since the Level Architect was created for the Citrus Engine, it can automatically create and set up your Citrus Engine for you, by downloading the latest files from the internet and installing them in your project folder. It can also automatically upgrade your Citrus Engine code for you at any time.

Another large advantage of the Level Architect is its code monitoring feature. By reading your ActionScript, it automatically knows which game assets are available for your level, and what properties that you can change on those assets. Other level editors don’t know which properties are available for your game objects, so you have to manually create your properties and assign values to them. This means that you must be responsible for memorizing the names and appropriate values for every property on every game object. This becomes a barrier to the level design process. Since the Level Architect quietly reads your code files’ meta tags, it can find the Hero’s “Jump Height” property and expose it to you (among all the others).

Finally, the Level Architect streamlines your work flow by automating project setup. The Level Architect will set up a brand new Citrus Engine project for you in seconds. Imagine that you’re sitting on your couch eating a huge head of cabbage when you suddenly think of a great level design idea. Rather than spending the next 20 minutes downloading the code, setting up your project, and coding out your project’s shell, you can just open up the Level Architect and create a new project.

Note: The Level Architect does not automatically create your IDE’s project files. If you are coding in Flash Professional, you must create your FLA manually. Likewise, if you are coding in FlashDevelop, Flash Builder, or FDT, you must manually create those project files manually. The Level Architect cannot anticipate which IDE(s) you will be using, and thus leaves that decision up to you. Please see “Setting Up Your Project in an IDE” for instructions about how to set up your project in each IDE.

Setting Up Your First Project

Let’s get started with setting up your first Citrus Engine project using the Level Architect.

If this is your first time opening the application, you will see a welcome message that will ask you to choose a location to create your first project. After closing the welcome message, an operating system window will come up that will let you choose a location for your .ce project file. I would recommend that you create an empty folder first, then save your project file inside that folder (as opposed to creating the project file directly on your desktop).

After you’ve named and saved your project file, the Level Architect will ask you if you would like to download the project files. If this is your first time setting up a project, I recommend that you click Yes. If you are an advanced Citrus Engine user and want to set up your project structure manually, or use a version of the Citrus Engine other than the latest version, you can click No. You will need an internet connection to download the latest project files. If you are not connected to the internet, the download/install will fail.

Note: You will also want to click No if you are using the Level Architect with a different engine.

At this point, the Level Architect will begin downloading and installing your project files. The Level Architect does this by downloading a couple of ZIP files from the internet, and extracting them into the same directory as your project file.

When the project files are finished installing, the Level Architect automatically opens an example level that has already been made.

Note: If you are interested in looking at the Level Architect's level XML structure, you can find the example level in your project’s “/bin” folder.

New Project Contents

When you allow the Level Architect to auto-create a new project, it installs several files into your project folder. Here is a summary of the files that it installs:

Play Testing a Level

Feel free to play around with this example level by browsing through the menus and sidebar. You can test/play your level by going to Project > Launch SWF. This launches a game SWF that has already been created for you. Later, as you get deeper into your project, you will compile your own SWF and link it to the Level Architect.

Unfortunately, since games commonly have multiple levels, the game cannot anticipate which level you want to play, so you must tell it. After the game’s SWF has launched, you can load your level file by following these steps:

  1. Press Tab to open the Citrus Engine console.
  2. Type “play example” and press the Enter key on the keyboard.

Note: You don’t have to re-type this command every time you want to test your level. You can quickly access your command history when the console is open by pressing the up arrow key on your keyboard. Pressing up multiple times will keep travelling backwards through the commands that you’ve previously executed. Likewise, you can press the down arrow key to go forward in your history. If you are at the front of your command history, the command line will go blank so that you can type a new command.

This tells the Citrus Engine to load a level called “example.lev”. You can leave the .lev part off, as the Citrus Engine’s “play” command assumes it is a .lev file. The level name that you specify must be a relative path from the SWF file. For instance, if you have a level named “cavern” in inside a “/levels” folder (inside the “/bin” folder), your “play” command would look like this: “play levels/cavern”.

Obviously, this system is not what you want your players to do when they play your completed game. As your game progresses and becomes more mature, you will be modifying your project’s code to include menus and ordered levels. However, even then, you will want a way to be able to play any level at any time (so that you don’t have to play through your entire game in order to test a level). For that reason, it is good to leave the “play” command in-tact and simply disable the Citrus Engine console before launching your game.

Creating a New Level From Scratch

After you’ve played around with the example level, you’ll probably want to create your own level from scratch. To create a new, empty level, go to Project > New Level. This will clear the blueprints and provide a fresh state for your new level.

Creating Game Objects

To create a new game object, notice the sidebar on the right side of the screen. Click the “Creation” tab at the top of the sidebar (if it is not already active). Within this tab is a list of the game objects that the Level Architect has recognized in your project’s code. This is not a static, hard-coded list. Later you will add (or remove) more objects on this list.

Drag the “Hero” list item from the list onto the blueprint paper. When you release the mouse button, you will see a small square white box. This box represents the collision rectangle for your hero. Right now, your hero doesn’t have a graphic (because you haven’t made one), but we will fix that later.

Now that you have made a hero, remember to save your level. Go to Project > Save Level. If you haven’t already saved your level once, the Level Architect will ask you to choose a location to save your level to. Choose your project’s “bin” folder and give it a name, like “level1”. The Citrus Engine console requires that your level be one word (no spaces) in order to execute the “play” console command.

Let’s add a platform for the hero to stand on. Drag the “Platform” list item from the sidebar to the blueprints so that your mouse is underneath the hero. Once again, this white box only represents the collision area for your platform. Within the game, your platform is invisible (along with your hero) because there is no graphic.

Transforming Game Objects

When you first create your platform, you’re probably thinking that it’s too small and you’d like for it to be longer. To make your platform longer, click on the white box. A common Photoshop-style “transform box” will appear around the white box. You can drag the little anchor boxes to resize the platform. Dragging the center of the platform will move it.

To rotate your game object, position your cursor just outside of one of the corner anchors. When the cursor arrow turns into a curved double-sided arrow, click and drag  to rotate the box.

Deleting Objects

If you don’t want an object any more, you can delete it. To delete a game object, click on it, then press the “backspace” key (or “delete” on an Apple keyboard).

Changing Object Properties

To change the properties of an object that you created, follow these steps.

  1. Select the object on the blueprints by clicking on it.
  2. Click the “Properties” tab on the sidebar.
  3. Find the property you want to change, and click the value on the right side. Delete the existing value and type your new value in.
  4. Click off of the property field. (If you press escape key before clicking off of the property value, the value will revert back to whatever it was when you first clicked into it.

Note: You can undo property changes by going to Edit > Undo.

Scrolling Around on the Blueprints

As the size of your level grows, you’ll need to move the visible area of your blueprint to create more objects. You can scroll around your blueprints by right-click dragging. You can also hold down the left-click drag while holding the spacebar (like in Photoshop).

There is no limit to the size of your level.

You can orient yourself in the level by looking at the numbers in the lower-left corner of the window. The first number is the position of your cursor in the level on the x-axis, and the second number is the mouse’s y-axis position.

There is a small white notch at (0, 0). This is to orient yourself as well; however, your level doesn’t have to start at this position. You can place your hero anywhere.

Diving into the Menus

If you’re curious what one of the menu items does, this is the place to look. We’ll go over the functionality of each of the menu items, spending more time on some of the less-obvious ones.

Most menu items also have a shortcut key associated with them. For menu items that you use very often (like Undo/Redo) it is good to memorize the shortcut key.

The Sidebar: Ins and Outs

The sidebar has two important tabs on it: “Creation” and “Properties”. We will go over each of them in detail, including how each tab list is generated.

You can quickly expand and collapse the sidebar by pressing the “s” key on the keyboard, or by clicking the arrow at the top of the sidebar.

The Creation Sidebar Tab

The Creation tab contains a list of game object “assets”. You use these assets to create individual “instances” of game objects. You can drag a list item onto the blueprint to create an instance of that asset. Once you’ve created an instance, you can modify the individual properties of that instance.

Each asset is actually just an ActionScript class. The Level Architect searches through your project, looking at each ActionScript class to see if it is a valid asset that can be used to create a game object. See “Creating Your Own Assets With Meta Tags” for more information about how to create your own assets using ActionScript. We will go over it briefly here.

The Level Architect looks at each ActionScript class in your project. If it finds one with a a special meta tag, then it knows that this class is supposed to be a creatable game object in the Level Architect. The Level Architect will then parse the code and put that asset in this list, along with all that class’s settable properties.

If you’ve created a new asset, it should automatically appear in the list. If it does not, de-focus and re-focus that Level Architect window. Focusing the window is what triggers the Level Architect to troll through the code in search of new assets and properties.

If this still does not cause your asset to appear in the list, it is likely that the meta tags are improperly typed. Go back and double-check your meta tag syntax.

Note: It is best not to have a large number of extraneous files in your project folder. This may slow down the Level Architect’s ability to search for assets as it has to look at each file in your project to determine if it is an appropriate asset.

The Properties Sidebar Tab

The Properties tab allows you to change the behavior, functionality, and look of your game object. Whenever you have a game object selected, all of its editable properties and values are listed. These values can be changed by clicking on the value and typing a new value.

Visual Properties

Some properties change the functionality of the game object when you play your game. Other properties change the visual appearance of your game object. When you change visual properties, you will see the blueprint graphic update to reflect these changes. Similarly, if you modify the game object from the blueprint, you will see the value update in the properties sidebar.

All assets in the Level Architect are expected to have certain visual properties so that they can be reflected in the blueprints. If you create a custom game object, it should extend a class (or implement an interface) that has the following properties: x, y, rotation, group, view, offsetX, offsetY, registration, width, height.

Width/Height Properties

The width and height properties represent (you guessed it...) the width and height of your game object. These properties must be called out though, as there may be some confusion about what you expect them to do.

Many of your game’s objects will be “physics objects” and will require a collision area. The width and height properties (along with X and Y) represent the collision bounding box of your game object. These properties are not representative of the width and height of your object’s graphic. There is no way to resize your graphic in the Level Architect. Graphics should be sized in an image editing program like Photoshop.

Some objects, such as backgrounds, do not have collision areas. Even so, the Level Architect does not differentiate between physics objects and non-physics objects, so all objects are assumed to have a collision area. For backgrounds, the width/height properties become more-less useless except as positional anchors for moving the background around.

View Property

The “view” property is a special property that defines the graphic that your game should use to represent your game object visually. This is a different graphic from the white box that represents the collision area of your game object. The view property is a simple string that can either represent an external graphic that is loaded at runtime (such as a PNG, SWF, or JPG), or as a class that represents your graphic (such as a MovieClip from your Flash library).

The Level Architect can only show your graphic if it is a runtime-loaded graphic file. If you want your graphics to be embedded, the Level Architect cannot show you a preview of your graphic since it cannot compile the class.

There are two ways to specify a runtime-loaded graphic for your object’s view. The easiest way is to click the magnifying glass button to the right of the list item. This will open a file browser that allows you to choose a supported image file. Your game’s graphics assets should be located in the same directory as your game’s SWF file, or in a sub-directory of that directory. The path that the “view” property uses is relative to your game’s SWF. If your project’s SWF file has not been chosen, the magnifying glass will not appear, and your graphics will not be previewed in the blueprints.

The second way to specify a runtime-loaded graphic is to manually type the path to the graphic into the property’s value field. Again, the path should be relative to your game’s SWF. Example:

art/characters/cat.swf

Finally, if you would like to specify an embedded graphic for your game object, your “view” property value should be a fully-qualified class name. This means that you need to include the package that your class is in:

com.mygame.objects.Cat

The type of class that this object needs to be depends on which Citrus Engine rendering method that you are using. The default (and most common) rendering method is the Sprite rendering method, in which case the class that you specify should extend DisplayObject (including Sprite, MovieClip, etc). If you are not sure what kind of rendering method that you are using, you’re probably using the default “Sprite” method.

Group Property

The group property represents which layer that your game object is on. Higher group numbers will be in front of lower group numbers. Objects that have the same group number will be depth-sorted according to their creation-time.

The Code Side

The Level Architect is only one aspect of your game. You will arguably spend most of your time writing code. If you make your game right, you will be able to separate your programming workflow from your design workflow, something that is especially important when working in teams of two or more.

The following section is for the developer who will be making your game objects, game shell, etc.

Setting Up Your Project in an IDE

When the Level Architect auto-creates your project, it does not create your IDE project file(s). Depending on which IDE (or, application) you code in, you will have a separate method of setting up your IDE to publish the project that the Level Architect created.

These tutorials are assuming that you automatically downloaded the Level Architect project files when you created your Level Architect project (see “Setting Up your First Project”).

Setting Up FlashDevelop

FlashDevelop is my favorite IDE. If you have a Windows machine, I recommend that you download and use it (it is the only one of the major IDEs that is free). If you are familiar with setting up FlashDevelop projects, you may be able to figure this part out on your own. However, there are a few things that I will mention that may save you some headaches.

  1. Create a new Project by going to Project > New Project.
  2. Under the ActionScript 3 Templates section, choose Empty Project, not AS3 Project. If you choose any project template except Empty Project, Flash Develop will overwrite the Main.as file that the Level Architect creates (this is not necessarily bad if you plan on writing your own document class immediately).
  3. Click the browse button, and save your FlashDevelop file in the same folder as your Level Architect project file.
  4. Make sure “Create directory for project” is not checked, then click OK.
  5. Click OK when you get a warning dialog that asks if you are sure that you want to copy template files into a non-empty directory. An empty project does not have any template files (that’s why we chose it!).
  6. Go to Project > Properties and Click the Browse... button to select your “Output File”.
  7. Choose the game SWF in your project’s bin folder (it will have the same name as your Level Architect project).
  8. Click the Classpaths tab.
  9. Click Add Classpath and select the “engine” folder. Do this again for the “src” folder.
  10. Click the Compiler Options tab. Look for the “Use Network Services” option and change it to “false”. This ensures that the Flash Player won’t complain when trying to load your level XML file.
  11. Click OK to close the Properties window.
  12. In the project sidebar, right-click on the Main.as file and select “Always Compile”. The file icon will gain a green down arrow which means that it is the “document class”.
  13. In the project sidebar, expand the “engine” folder and right-click on the Box2D.swc file. Select Add To Library.
  14. In the icon bar along the top, make sure that the project is set to “Debug” and not “Release”. This will allow you to trace and debug your project.
  15. Compile and run your project by pressing the “Play” button in the icon bar.

Setting Up Flash Professional

This tutorial was written for Flash Pro CS4. The process is very similar in CS5, but very different in CS5.5. You will need to perform the equivalent task in CS5.5 even though the Publish Settings window is laid out differently.

  1. Create a new ActionScript 3 Flash File.
  2. Go to File > Save as... and name/save your FLA into the same folder as your Level Architect project file.
  3. Go to File > Publish Settings.
  4. In the “Flash” field where you specify your output SWF, type “bin/MyGame.swf”, except type the name of your project’s SWF file instead of “MyGame”. If you don’t know what the name of your project’s SWF is, browse to your project’s “/bin” folder and find the Flash file.
  5. Click the Flash tab. Then click the “Settings...” button. The “Advanced ActionScript 3.0 Settings” window will pop up. You will need to do a few things in this window.
  6. Under the “Source Path” tab, click the little “+” button. Then type “./engine” (Make sure to include the dot and slash before the word “engine”).
  7. Click the “+” button again, and type “./src”.
  8. Under the “Library Path” tab, click the little “+” button once again, and then type “./engine/Box2D.swc”.
  9. At the top of the window is a Document Class field. In it, type “Main”. (Note: There is a bug in some versions of Flash that causes a warning dialog to appear. The dialog will say that it can’t find the document class, so it will create one automatically for you. This is a bug, because it CAN find the document class. Ignore it.)
  10. Click OK to close the Advanced ActionScript 3.0 settings. Back in the “Publish Settings” window under the Flash tab, check “Export SWC”. Box2D requires you to do this, probably because it uses Alchemy or meta tags.
  11. Click the OK button to close the Publish Settings window.
  12. You should now be able to compile the game.

Setting Up Flash Builder

  1. Go to File > New > ActionScript Project.
  2. Give your project a name, then under the Project Contents section, browse to the location of your project’s root folder, and select that folder. Click Next.
  3. Click on the “Source path” tab and then click the “Add Folder...” button. When the Add Folder window pops up, type “engine” in the field, then press OK.
  4. Select the “Library path” tab, then click the “Add SWC...” button. When the Add SWC window pops up, type “engine/Box2D.swc” (or browse there). Press OK.
  5. In the “Main Application File” field, type “Main.as”.
  6. In the “Output Folder” field, type “bin”.
  7. Click “Finish”. You should see your project tree in the package explorer.
  8. Make sure your project is selected in the package explorer, then go to File > Properties. Click the ActionScript Compiler section in the sidebar.
  9. In the Compiler Options section, in the “Additional compiler arguments” field, add the following text to the end of whatever is already in there: “ -use-network=false”. Feel free to set any other settings that you prefer while you’re in here. You must add this compiler argument so that Flash doesn’t throw a “security sandbox violation” error when it tries to load your level file. If you’d like, you can remove this argument before you deploy your game onto the internet.
  10. Click OK. When a warning dialog appears, click OK there too.
  11. You can now build and run/debug your game.
  12. Finally, Flash Builder will name your published game “Main.swf” which is not the same name as the SWF that came with your Level Architect project. You will have to tell the Level Architect about this new SWF file because it thinks you are still using the other SWF. To do that, in the Level Architect, go to Project > Choose SWF. Then choose the “Main.swf” file from the “/bin” folder. You can now delete the other SWF with the same name as your project.

Creating Your Own Assets with Meta Tags

By now, you may be wondering how you can create your own game objects and have them show up in the Level Architect. This section explains how use meta tags to do this.

The Level Architect dynamically reads the ActionScript files in your project, and looks for specific meta tags. When it finds a [Property] meta tag inside of an ActionScript file, the Level Architect knows that this is an asset, and adds this class to the asset list in the Creation sidebar tab. When you create an instance of that asset in your level, any settable property that has the [Property] meta tag will show up in the Properties sidebar.

This section is mainly about how to add [Property] tags to your Citrus Engine objects. For more information about how to write custom Citrus Engine objects, please consult the Citrus Engine code and documentation. However, here is a brief summary of Citrus Engine objects.

Custom Citrus Engine Game Object Overview

All game objects in the Citrus Engine extend from one of two classes: either CitrusSprite or PhysicsObject.

Both CitrusSprite and PhysicsObject implement the ISpriteView interface, which contains the definition for common visual properties such as x, y, width, height, and rotation (among others). When you create your own custom object, you should extend CitrusSprite or PhysicsObject.

Exposing Properties to the Level Architect

The Level Architect recognizes your new game object class when you properly place a [Property] tag inside of it. Your game object class must have one or more [[Property] tags in order for the Level Architect to make it show up in the Creation sidebar tab. To expose your game object and its properties to the Level Architect, place the following code above your public properties and setter functions:

[Property(value=”defaultValueHere”)]

The word “Property” tells the Level Architect that you want this property to appear in the Level Architect’s Properties panel. The “value” parameter, along with a String inside quotes, tells the Level Architect what the default value should be for this property. Here is an example of a property called “speed” that will be exposed to the Level Architect:

[Property(value=”4”)]

public var speed:Number = 4;

Notice a couple of things: First of all, even though the default value is a Number, you still must place it inside of quotes. Also, even though you’ve immediately assigned a value to the actual “speed” property, you still must put a value inside the meta tag.

You can also put a property tag in front of a setter function:

[Property(value=”100”)]

public function set startingHealth(value:Number):void

{

return _startingHealth;

}

You must put the [Property] meta tag over the setter, not the getter. Creating a getter function does not guarantee that the property is writable, and it must be writable for the Citrus Engine to set it.

If you do not want a property or setter to appear in the Level Architect, you do not have to put a meta tag above it.

Loading Level Files Into Your Game

Section in progress...

Note: You can see how to load level files into your game and create levels from them by reading through the Main.as and GameState.as classes that are included with a Level Architect project.

The Level Architect level files are just XML files. They are given a .lev extension just for distinction and cuteness. Thus, you can load them just like you would load any other file or URL in Flash:

Once the XML file is loaded, you can parse the XML object and turn it into a bunch of game objects like this:

...