This is the first post in the series “Programming Tidbits.” These articles consist of useful bits of information or code that I would like to share, but may not be considered a full article.

The Wrong Thing…

When programming, a lot of times you may find yourself throwing together some code which uses “Magic Numbers.” A magic number is basically just any static number sitting in your code such as:

public function moveMyCharacter() : void
{
	myCharacter.x += 5;
	myCharacter.y += 5;
}
 
public function damageEnemy() : void
{
	someEnemy.health -= 20;
}

Why is it bad?

Now obviously that is just a simple example, but let’s say you have code ALL OVER your project using these “magic numbers.” What happens then, if later you want to change these numbers? You have a long and tedious process of finding all times that they are used. Not only that, but you are prone to missing something which will therefore lead to unpredictable code and bugs.

The right thing…

Instead of being mean to yourself, do the right thing and create constants or variables for all of your magic numbers. The usual place to put them is at the top of your class. Even better would be to externalize the data into some sort of settings file ( if the data is worthy of course ). I’ll be discussing externalizing data in a future article if you aren’t quite sure how to go about that…

So here is the code once again, done properly.

// Top of your Class somewhere...
private const MOVE_SPEED:int = 5;
private const HERO_DAMAGE:int = 20;
 
public function moveMyCharacter() : void
{
	myCharacter.x += MOVE_SPEED;
	myCharacter.y += MOVE_SPEED;
}
 
public function damageEnemy() : void
{
	someEnemy.health -= HERO_DAMAGE;
}

Inspiration

When I first began programming, it seemed like there were a vast amount of tutorials out there which taught you how to do a specific task such as “make a shooting game” or something of that nature. These were great for me at first, as I didn’t know my left toe from my right thumb. Eventually however, I began to get better and I craved more organized and useful information such as how to actually structure games, and how to use proper OOP techniques etc. There simply just isn’t enough of it out there. I found a few articles explaining several ideas and concepts, and I read many different books on OOP and design patterns…then after about a year of working together the different I came up with a great mesh of it all to develop my current game structure.

Purpose

My purpose for this article and those that follow in this series is to teach you piece by piece how to build a reusable game structure for your games as well as explain different game coding techniques and concepts along the way. I’ll be providing code that I’ve written, however for maximum benefit I recommend that you modify or rewrite it to your style and needs. For example, each time I start a new project I simply copy all of my game code over from my latest game and then delete classes which I won’t need, as well as tweak existing code to fit the current project.

Requirements

It is good practice to write down some goals and requirements for what you would like your game engine to incorporate, so let’s consider this now. Our game structure will have consist of the following:

• The ability to save game state, pause, speed up and slow down
• We can set a camera position and size to render what is in the game world.
• The game logic will be separate from the rendering logic.
• Data driven development. IE: Creatures and levels will be built outside of the core code engine itself, usually from XML or on a higher level in an editor of some sorts.
• Object creation is centered in one location
• Control of entities is done through “controller” classes.
• And of course…it will run incredibly fast.

If any of that sounded complicated, fear not. I will be discussing the reasons for each part as well as explaining how it all works. We will create one piece at a time and build upon the structure as we move along, making improvements along the way.

As I complete each section I will update this article to link to each piece. You may visit the google project page to aquire all of the project files and source code as well.

Additional Articles in this series:

• Building a Foundation For Your Games and Handling Screens
• Game Entities and Objects
• Managing Game Objects and Rendering a Game World
  
• The Game Factory – How You Should REALLY be creating objects
• Artificial Intelligence – Boids / Steering Behaviors
• AI – Finite State Machines
• More AI – Pathfinding, etc…
• Particle Effects
• Advanced Collision Detection
• Programming UI
• Data Driven Development
• And more…

Programming Libraries used in the Series:

• Actionscript 3 Math Library
• Input Manager
• Sound Manager
• Animated Bitmap API – Ginger

Conventions that I follow:

• Coding Conventions – Sloppy Code Sucks!
• Organized Trace Commands
• Eliminate Magic Numbers

Recommended Reading:

• Head First – Design Patterns
• Actionscript 3.0 Design Patterns

I want to discuss a technique that I have been using which works very well to get past the initial strain of programming a new part into your game. Yesterday I was trying to figure out how I would program the abilities system for units ( it is a Diablo style game, so there is a possibility for a lot of abilities ).

After staring at the screen for a while, I pulled out the ol’ handy dandy notebook and just began writing things down on paper. Shortly thereafter I had the entire system programmed, and it worked great!

So, the process of programming on paper works like this:

1. Decide your problem. Write it down.
2. List out the steps that need to take place from the player’s view in order for the problem to work. IE:
   • Player chooses class ( Wizard for example )
   • Unit is given abilities.
   • Player presses ability 1 key, ability 1 activates.
3. Now that you see what is required to complete your problem it is much easier to program it. Decide on which classes will be needed, and then write out how it will all work using pseudo code…so for me it was something like this:
   • Ability Class, abilities will extend this…for example: HealAbility, ProjectileAbility, etc.
   • onKeyPress( “A” ) : Unit.useAbility( 1 );
   • Unit.useAbility(): ability1.execute();
   • ability1.execute(): unit.addHealth( 20 ); //or spawnProjectile( “Fireball” ); //or unit.addBuff( … )
4. Once you have all of it written down in pseudo code like that it really makes it super simple to code everything because you are just basically putting it in Actionscript.

Originally I had thought it would be difficult and take quite some time to design and program all of the things I did yesterday (it was a lot) however since I used this technique I believe it relieved the pressure of creating code that doesn’t work and just let me focus on the concept of HOW it should work. Hopefully you can find a style or programming on paper that works best for you as well.

I am writing this article in the hopes that you will learn from mistakes that I have made. Let me just tell you…sloppy code SUCKS! Once you start getting into bigger projects (or even not such a big project) and even worse when you start to work with others and share code things can become a mess. So I am hoping some of you with no coding standard or no idea of how to “properly” structure your code will get something out of this and decide to do the same or at the least come up with your own standard and stick with it.

Occasionally I do tweak or add to my standards but for the most part I really do keep everything the same.

Currently I’ve been improving some habits of mine (mainly things like spacing and brackets etc) a bit so my older code is a little sloppier than my newer stuff which is okay. I also want to first point out this article by GamePoetry which links to the “UrbanSquall” coding standards. Those are basically what I stick to except for the few additions / changes mentioned below.

So let’s get started.

Class properties / Members

Public
The idea here is to always avoid using getter/setter functions whenever possible. Well, atleast for anything that would be called once or more each frame. If it’s an obscure variable that is rarely called or used for something that isn’t speed related you can use them…otherwise NO. Anything that is both gettable/settable will be simply written as it is:

//it probably wouldn't matter too much if you externally modified this variable
public var maxSpeed:Number;

Read-Only
EDIT ( 12/26/2008 ) : I no longer use different naming convention for read alone variables, I simply either use a getter or I keep them public with a code comment that warns against changing the variable externally.

The speed difference of NOT using getters/setters can be very apparent with something like a “Vector” class where the ‘x/y’ variables are public. This adds probably 20-30 FPS to a demo with about 2-3000 sprites all doing world bounds wrap checks etc. Just imagine the speed difference when ALL of your code complies with this.

Sometimes we may want to reduce the “m_bulletsLeft” safely so in that case create a function such as “shootGun()” inside the class that holds “m_bulletsLeft” rather than making it a public variable and implementing some external code to reduce the “m_bulletsLeft” variable. (This is more of a proper Object Oriented design practice: ‘Encapsulate Change’)

Private / Protected
For all properties usable only by the class that created them we will use: m_variableName
For any protected property which can be used only by classes when extend it we will use: _variableName

//this helps avoid naming conflicts...which is good!
private var m_beanCounter:int;
protected static var _nextID:int = 0;

Naming Conventions

Booleans
Any boolean properties and functions will always be structured in question format. They are followed by the words: “is, has, can, does”:

public var isCollidable:Boolean;
public function doesRayIntersectCircle( a_rayOrigin:Vector, a_rayHeading:Vector, a_circleCenter:Vector, a_circleRadius:Number ):Boolean{ //code }
private var m_hasGun:Boolean;
protected var _canComeToTheParty:Boolean; // lol

Constants
All constants will be in caps with phrases separated by underscores:

public static const HEAVY_ARMOR:int = 0x000001;
public static const WOODEN_SHIELD:int = 0x000010;
public static const SLARGH_FIGHTER:String = "slargh_fighter";
private static const ENEMIES_PER_WAVE:int = 15;

Public Functions / Private Functions
Usually I stick to the “Urbansquall” convention on this which is to use a “verbNoun() format. Sometimes my functions will stray slightly from the “verbNoun” format when parameters are available and instead I will try to complete a sentence with the parameters. In other words I use “verbPreposition(noun)” format:

public function addTo( a_vector:Vector ):void;
public function wrapAround( a_topLeft:Vector, a_bottomRight:Vector):void;
public function dotOf( a_vector:Vector ):Number;

Event Handler Functions
I will treat event handlers slightly different when naming them. I always name them as if they are happening because of an event (hmm…) Which means basically all of them have “on” preceding them.

onScriptLoad(e:Event):void{}
onEntityCollision(e:CollisionEvent):void{}

Variable / Function Positioning

The order I use to place variables and functions ( except for specific circumstances ) are as follows:

1. Static Constants
2. Getters / Setters
3. Public variables
4. Constructor
5. Public Class Functions
6. Overriden Public Functions
7. Protected Functions
8. Private Functions
9. Protected Variables
10. Private Variables

As far as I can think of those + the urbanSquall link from above are the conventions I stick with. Hopefully you decide to do the same! Also be sure to read: Better Debug Tracing for some tracing conventions that should be followed as well.

As I have been teaching myself game programming, one of the harder parts has been the math involved. It can be quite complex depending on what you are trying to do. While building various parts for my game engine I’ve needed several math functions. I’ve read through a couple of game and math books and have also created quite a few extras just based on what I had learned. I have created a pretty good library of useful functions and so after showing a friend of mine and him remarking that it was quite helpful I decided I would go ahead and release the code for everyone else to use!

I currently don’t really have any demos or anything showing how to use the code, however go ahead and take a browse through the functions and there may be some stuff you will use eventually. It’s pretty self explanatory anyways and it is all documented. I will definitely be referring to a lot of the code from these classes in some upcoming posts as well so if you are waiting for a more detailed explanation of when and how to use some of it don’t worry it’s on the way!

You can download everything as a package or just get the classes you need in the repository from my google project page here: http://code.google.com/p/cheezeworld/

As of writing this I currently have:

Vector - Perfect alternative to using the built in “Point” class and has basically ALL of the Vector operations you would need to perform plus a few more.

AABBox - A very lightweight object to simply store “rect” data for whatever purpose.

Matrix2D - Handles any Matrix math needed. Use in conjunction with the Vector class.

Transformations - Some static functions for performing transformations to Vectors easily (such as local to global etc…)

Geometry - A very powerful bunch of static functions for doing a wide range of math such as line intersection tests between rays, segments, polygons, circles, etc etc… This is great for most hit test operations and ray casting + other stuff…just check it out.

Math Utils - This is pretty much just a small number of things that I actually just usually copy directly into the code I am working on or as a private function into a class that needs it but wanted to have a reference to it since they are useful so it’s all bundled up in this class.

While programming my game’s “Entity Framework” as I like to call it, I had the need for a better way to initialize all of my entities. Here are the properties for just the base “Entity” class:

public class Entity extends EventDispatcher{
 
	public static const DISPOSE:String = "dispose_event";
 
	public var pos:Vector;
	public var rotation:Number;
	public var scale:Number;
	public var radius:Number;
	public var isCollidable:Boolean;
	public var team:String;
 
	public var _id:String;
	public var _type:String;
	public var _pos:Vector;
	public var _oldPos:Vector;
	public var _world:GameWorld;
	public var _timePassed:int;
	//...the rest of the code
}

Also I wanted to have default values as well as the ability to load the defaults from some sort of “Settings” file for pretty much all of these values so normally you would have to do your constructor like:

public function Entity(position:Vector, rotation:Number=360, scale:Number=1, radius:Number=1, isCollidable:Boolean=true, team:String="neutral", id:String=null, type:String=null, world:GameWorld=null){
 
	if(pos != null) { pos = position; } else { pos = new Vector(); }
	if(rotation != 360) { rotation = rotation } else { rotation = Settings.EntityRotation; }
	//etc...
 
}

So as you can see that would get pretty messy ESPECIALLY when you decided to extend it since you’d have to put all of those properties in the constructure PLUS any new properties…so you can just imagine the headache there.

Anyways lets just cut to the chase. Here is the wonderful solution I came up with to handle any type of constructor nightmare like that: Read the rest of this entry »

I’ve done some collab coding work as well as plenty of my own projects and if you have done the same you would probably agree that debugging can be one of the biggest tasks that we as programmers have to face in our projects.

Usually proper debugging consists of many many trace statements until we are able to pinpoint areas that aren’t doing exactly what it is that we want our code to be doing. Well, one problem that I have run along many times within my own code and more so when working with other people’s code is the problem of not being able to find trace statements and / or not knowing where a particular trace statement came from!

Take for example Read the rest of this entry »

It took me a bit longer than I thought, but it is done! I have created a custom “BitmapClip” class for you guys! This class can do it all:

1. Import MovieClip, Sprite, and even Tile sheets!
2. Animate each clip at it’s own frame rate.
3. Control it just like you would a MovieClip.
4. It even creates pre-rotated frames for you! Now you can have super fast animated clips AND support rotation! WOOT.
5. You can also support scaling by simply adding the clip to a sprite without losing *much* speed.

If you want to see a demo where I am using the BitmapClip with thousands of clips on screen moving / scaling and rotating then go here: Game Framework Test

You can download the package containing all of the code and demos or simply grab the file off of the repository on my Google project page.

The following are instructions on how to use it (which are included in the download as well):
Read the rest of this entry »