In WebManager, as described in my previous post, a WCB is made out of several Components, such as a form, an element, etcetera. Each component (although ‘each’ isn’t a fact, fyi) has, next to a basic set of settings, also an optional setting for permissions. With permissions, I refer to access control lists (of sorts) for the five (or so) basic usergroups that exist in WebManager, usergroups such as authors, users, developers, etcetera. Each usergroup can have a set of permssions assigned to them, which indicate what that user can do. These permissions can then, in the controller or in a .JSP file, be checked again using WebManager’s AuthorizationService, a service object with some permission checking methods.

A permission is defined as follows. First, you create a Category, basically a parent for each permission. The Category is defined as a Category instance, which gets passed a ‘category’ string, an unique identifier for that category. Usually, at least in the default archetypes, this identifier is equal to the component’s bundle ID, which in turn is a combination of the WCB’s ID and an appendage (such as ‘element’ or whatnot). This results in a category string similar to, for example, “info.greatjustice.wcb.somewcb.element”.

Next, one creates a set of Permission objects, which are objects created according to a permission string (a should-be unique string) and the category defined before. The permission string is usually the category string, with the permission itself appended to it (such as ‘.update’, ‘.delete’, etc). This leads to a permission string of ‘info.greatjustice.wcb.somewcb.element.update’, for example.

Now that there’s a set of permissions (we’ll use the base set of CRUD permissions as an example here - create, read, update, delete), we can assign them to the usergroups that have these permissions. When no permissions are defined, all users have full access to the WCB component. When just one permission is set in one usergroup, that usergroup can only perform that action, nothing else. Anyways, to assign a permission to a permission group, the ComponentDefinition object, which is used to configure and (by WebManager itself) initialize a WCB’s component, has a method, setPermissionsForPermissionGroup(), that allows the setting of a permission. The method takes two arguments, the usergroup (which is a constant string defined in WebManager’s WCBConstants class) and an array of Permission objects to assign to that usergroup.

Next to that, the Element component type has a few extra methods (setCreatePermission and setDeletePermission) that, I assume, sets a global permission that indicates that component can be created and deleted, or in this case, can be inserted or removed from a page - regardless of user rank, i.e. ‘global’.

Now, back to the topic at hand and my own work on this, I figured that this system wasn’t ideal, for a number of reasons.

First, there’s an enormous amount of freedom associated with setting a permission. Because you can pass strings, there’s no way of knowing whether it’ll ‘work’ until you try it out. There’s no set specification about what input is allowed, and nor is there any checking for proper values. This leads me to believe that the whole permission system in WebManager is little more than a string comparison system (as in, if the usergroup identified by this string has the permission defined by that string, return true, else return false), which is fine in itself, but then, why’s there the complexity in the assigning of the permissions? Why bother creating a long permission string when you could just fill in “Slartibartfast” as a permission, and check if a user has the “Slartibartfast” permission all the time?

I can understand that, of course, since I’m sure the system would allow checking for a permission set in component A in component B, with this relatively low-level approach. Still though, I believed that this system could be improved. The lowest step, the assigning of the permission category is pretty much the starting point. I don’t believe that that could be abstracted any more, at least not without completely automating the system of assigning permissions, so that’ll largely stay the same.

The permissions themselves though could be largely automated. There’s a few facts we know about the permissions:

• The permission string is always (or, 99.9% of the time) based on the category’s string.
• The permission is in most cases one of Create, Read, Update, or Delete, and in exceptional cases it’s a similar system with other permissions such as ‘UpdateSomePart’.
• The permission is never used in a dynamic sense - once a permission has been created, it doesn’t turn into something else.
• The usergroups are a pre-defined set of 5 groups, currently defined as plain strings.

Now, with these above facts in mind, there’s a number of things we could do to improve on the permission system.

• Add typesafe constraints to the permissions and usergroups
• Auto-generate permissions based on sensible defaults
• Auto-generate permissions based on what a user wants

Note that there’s one or two additional points to the above list, but they apply to the entire library in a wider sense of the word - i.e. an alternative / easier method of creating ComponentPermissions. I’ll do a full article on that once it’s finished.

We’ll want to improve on the permission system for a number of reasons. First, we’ll want to make it more typesafe - if you know there’s a limited set of usergroups (5, in this case), why would you want to have the users set it as a string? If you know a permission is always a fixed value, why set it as a string value that allows everyone to freely fill things in?

Second, we’ll want to automate - in several layers of meaning - the process of creating and assigning permissions. If you know the category and know the set of permission types, it’s easy to auto-generate the Permission objects and assign them to the ComponentDefinition automatically. Automating in ’several layers’ mean, in this case, that there’s the possiblity to have all permissions auto-generate (the base CRUD permissions, for example), but at the same time not restrict the users in defining their permissions.

After a few days of development (or something, I don’t really keep track of time - I don’t seem to have any deadline or other important tasks where I work), The end-product consisted of a set of components that allow for easy and typesafe definition of permissions, with several layers of automation and customization.

One of the first things I did was to put the permission groups into an enum, a language feature I’ve never used until about 9 months ago, but which I already love. Using an enum instead of the constant string values defined in WebManager’s WCBConsts has the main advantage of being typesafe - when you have a method that expects a usergroup, you can only accept usergroups, instead of having to do a manual check to examine the string value passed to it. The setPermissionsForPermissionGroup could, if WebManager used the enum approach, accept a permission group and an array of Permission objects instead of ’some’ string and an array. This guarantees that there is no way that a user could ever enter the wrong value, simply because the software wouldn’t compile if there’s an incorrect value set there.

The second thing I did was to make my own subclass of the PermissionCategory object, which, at first, just defined a constructor that forced each mandatory value to be set at object create-time - a PermissionCategory requires two or three values in order to function properly, but those values could only be set using setter methods. The custom permsision category defined a single constructor that forces the user to define all two or three values in one go, so it becomes impossible to ‘forget’ a value. This approach is also used in the ComponentDefinition replacement code in the same library, but as said, more on that in a later article.

Later, the custom PermissionCategory got a few additional methods that created Permission objects. A Permission always has a Category as its parent, so why not invert it and have a Category spawn its Permissions?

As said earlier, a Permission’s permission string is usually the same as the Category’s permission string, so why not base a Permission’s string on the Category’s string with just a small appendage (’.create’, for example)?

In this approach, I once again returned to the enum. Defined a Permissions enum that defined four permissions: Create, Update, Read, and Delete. Each had a string representation as well defined inside the enum, string representations in the form of  ’.create’, ‘.update’, ‘.read’, etcetera.

The permissions enum, in combination with the custom PermissionCategory, resulted in a ‘createPermission’ method in the PermissionCategory that took just one parameter, an entry from the Permission enum. The result was a concatenation of the category’s string and the Permission’s toString() method result, which was then inserted into a new Permission object, along with the category assigned to it that created it.

Next to a Permission enum, I also created a PermissionGroup enum, which acted a simple wrapper around the string values from WebManager itself - only then typesafe. With it came some extra methods that allow a developer to get the groups ‘above’ a current group, so they could, for example, allow everything for the Editor usergroup and all those above it.

So, with an abstraction of the Permissions, the PermissionGroup, and the PermissionCategory in place, we’ve already come a long way. We can now create a set of permissions for a permission group and, using another abstraction for the creation of ComponentDefinitions, assign them all in one go. However, we can go one step further, by auto-generating the permissions.

In most cases, there’s just a single set of permissions that you’d always apply - CRUD. Create, Read, Update, and Delete, and this often in relation to an object of sorts - in this case, an Element component, or the object that you can insert into a page, can only be created (for example) by an Editor, but can only be deleted again by the Main Editor usergroup, which is one level up in the hierarchy.

WebManager’s permission system allows for more fine-grained permissions, but in most cases, this default set of permissions would work good enough. So, I also added an abstraction for storing and auto-generating CRUD permissions. This was done in two stages, actually. First up was a ‘generic’ CRUDPermissionsContainer, an interface that defines four methods for getting the four permissions. I wanted to allow people to define their ‘own’ CRUD permissions quartet instead of forcing them to either use the auto-generated ones or have to manually define all permissions, hence the abstraction. Underneath that are two default implementations: A CRUDPermissionsContainer implementation that works only with the earlier defined CRUDPermissions enum, which took just a PermissionCategory as constructor argument and created the permissions from there automatically, and a more generic container with a constructor with five arguments, the PermissionCategory object itself, and four Permission objects - one for each of the four CRUD permissions.

As the title suggests, this is a bit over-engineered, but it’s good practice material - I’m still cheap for my employer, so I can spend some more time on over-engineering. I know that there’s plenty of people that wish they had some excess time to spend on refactoring, =D.

But anyways, to wrap things up. My total permission system setup now allows users to set up the complete permission set for all users in a single line of code, and allows full customization in far less lines of code than the old one (where the old one involved at least two or three dozen lines - creating five string values,  create a couple of Permission objects, put those in arrays, call the same method a couple of times in the ComponentDefinition object to assign them, etcetera. Having to do that every time for each component / WCB that requires permissions gets tedious, and not to mention it increases the code and, as such, the complexity of a class / method, and reduces its readability.

I’ll post a bit of code later on (maybe) to further illustrate this post, one line of code can say more than a thousand words and whatnot.

I’m currently doing a 20-week internship at Oberon Interactive, a largely web-oriented company that does webdesign, online campaigns, that kinda stuff, all from their HQ in Amsterdam. It’s got about 12 or so employees (including myself), but I’m not sure yet because there’s almost always someone missing. On there, I’ve been assigned with the task of making development of WCB’s easier.

Before I throw in more TLA’s though, I’ll explain what I’m working with. I’m working with a pretty extensive enterprise content management system called WebManager, made by Dutch company GX. Since WebManager is the only piece of software GX seems to be developing, I’ll probably often confuse WebManager with GX and vice-versa, so if I use GX in reference to an item, I mean WebManager.

Anyways, since version 9 (I believe) of WebManager, GX has added the ability for developers to add functionality to WebManager through a plug-in-like system. This functionality is packaged in bundles called WebManager Content Bundles, aka WCB’s. These WCB’s are basically OSGi modules, built on top of Apache Felix, an implementation of OSGi’s service platform.

Now, Oberon has received at least one assignment from a large Dutch football site (i.e. the football type with the round ball, not the oblong one) that, at least for now, involves creating two of these WCB’s to be included into their site. The visible bit of a WCB can easily be inserted into existing WebManager pages through WebManager’s Edit Environment, a back-end that looks an awful lot like Microsoft Word.

Anyways, I’m working with that currently, and my primary internship assignment is to make WCB development a lot easier, reliable, and faster. There’s several aspects of WCB development that have to be improved, as I’ve discovered / determined for myself so far, and this article is about one of them: Dependency management. I’m sure I’ll be writing more posts during my internship on a range of (WCB development) related subjects, so be sure to hang around.

For this first installment, I’ve taken a closer look on how the WCB API’s handle dependency management, also comparing it with other, more formalized approaches. I’ve put the report into a neat, 10-page Word document, which I’ll link to below. Here’s a summary though, and you’re going to have to visit the internets to figure the terms I use out or read the .doc itself in order to find out what is what.

A WCB is built out of separate Components, like a Form, an Element, a Servlet, etc. Each Component has one central class of sorts that is initialized by some obscure part of WebManager, i.e. out of the programmer’s control. In order to be able to use, for example, the Authorization Service, with which you can check access permissions for users for a certain access, you have to pass a string value containing the class name of said Authorization Service to a new instance of a ServiceDependency object, then pass that to a ComponentDefinition object which is passed back to WebManager when your WCB is installed / initialized.

There’s loads of problems with this approach:

* No typesafe checking, so you’ll only see if you’ve entered the wrong classname at runtime (whilst one could pass a Class object, much more typesafe).

* It’s hard to get to the central object to get the service(s), you either have to call a getComponent() method from the controller class and cast that into the specific class, or implement the class as a singleton.

* No control over the dependencies’ lifecycle - you can only pass the class you’d like to initialize to WebManager, can’t pass any parameters or whatever.

* You can only inject services into that one Component object.

* Injection is (usually) done using reflection on a class’s private fields, obliterating the meaning of the ‘private’ keyword, and preventing the usage of setter methods (and additional behaviour one could associate with that).

All in all, they do use the term ‘dependency injection’ a few times in their official documentation, but in practice all you do is pass the names of the classes you’d like to have created, have WebManager inject those into an object that acts as a hard-to-access Service Locator, and be done with it. The Service Locator isn’t a bad choice per sé, but since the dependencies contained in the SL are injected somewhere at runtime, after all the objects (Controller, for example) are created, you’d only be able to access the dependencies at runtime of an object, through accessor methods. I’d much prefer if an object’s dependencies were injected at construction-time, through constructor injection, etc.

But all that, and then some, is all described in the document. Read it and let me know what you think - I’d love a second opinion on the matter, or alternative solutions to solving this problem.

http://greatjustice.info/files/dependency-management.doc

Edit: Small update, if this topic interests you, make sure to read Fowler’s article on the subject - it helped me formalize the different techniques used. Also, I should seriously buy / read his book(s), fgj.

Each usergroup has a set of permissions in each group - so basically, you have to be able to store a usergroup’s permissions on a per-group basis. In this article, I’ll explain how I’ve used bitmasks and the associated operators as explained in the previous article to store those permissions, as well as the usergroup(s) a particular user belongs to in a specifc group. The bottom line is that by storing the permission a usergroup has in a bitmask, you end up with a lot less database usage. But that’ll be explained in this article.

First though, a case study. This is actually a good idea for pretty much every software application, both as a whole and its parts - analyze what you’re trying to do. In this case, I wanted to create a social network site of sorts (using the Zend Framework) with, next to the obvious user profiles and user-to-user communication, a ‘groups’ system, where users can create groups, clubs, or whatnot, each with its own discussions (or ‘threads’, you could basically also see it as a forum where users can create their own sections). More specifically, the owner / Administrator of a Group should be able to determine the access people have to their own groups - for example, a private group, an invite-only group, a read-only group, etcetera.

To implement this, a permission system would have to be setup. I was already pretty sure I’d use a default set of usergroups (Creators, Administrators, Moderators, Members and groupless, Guests), also called Roles, which more properly describes the per-group Role a User has - in group A, a User may just be a visiting Guest, whilst in group B the user would be a Moderator, and in C a Member, etc.

Next to that, I also figured that one User may fulfill more than one Role - in first instance the Creator / Administrator combination, where a Creator in its own doesn’t have any particular rights or duties, but when combined with the Administrator role, a Creator rises above the ‘regular’ Administrator rank, in that he cannot be removed from the group by other Administrators. In retrospect, allowing every user to have more than one Role at a time might’ve been a little overkill, but it’s quite manageable in terms of the database storage required to associate a User with a Group.

In the database, there’s a link table, GroupUsers, that contains the group ID, the user ID, and the Role, the latter being a regular integer value. Just one column to indicate the user’s Role, no matter how many Roles the user has.

Next to assigning Roles to Users on a per-group basis, a Role would also need to have a set of Permissions, also on a per-group basis. In other words, in one group a Member could, for example, create new threads, whilst in another a Member could only reply to threads, all based on the choice of the Administrator(s) of that particular group.

So another requirement was that per Group, the permissions of a Role would have to be stored.

The Permissions are basically a list of sorts, containing items such as

(users with this Role can:)

• View the group
• View threads
• Edit threads
• Create new threads
• Reply to threads
• Edit own posts
• Edit other people’s posts
• etc

The permissions each Role has can be determined and set with the above list of permissions. Next to that, it’s relatively easy to extend these permissions.

The problem however is storage. In a regular system, one might say that the Role has a list of boolean permission values in that Group - canViewGroup, canViewThreads, canEditThreads, etcetera. Translating that to a database schema is also easy - just add boolean columns canViewGroup, canViewThreads, etcetera, with values 0 or 1 in them.

However, this makes the Groups table, in which we can store the permissions for each group, needlessly long - for each role + permission, a column is needed, so with just the above 7 permissions, 28 columns would be needed to store these. One of the base rules of database design is to make your database tables as narrow as possible - as few columns as possible. The narrower the table, the less data has to be processed and searched through, the faster access is.

In order to solve this particular problem, bitmasks were used. Instead of storing each permission as its own boolean value, each permission has its own unique mask - as described in the previous article. The permissions itself is stored in a numerical value, both in the program’s code itself (the Group object) and in the database. Instead of having the amount of roles times the amount of permissions in database columns for each Group, you can now do with just one column per usergroup. Here’s how it’s done. We keep everything in the Group object, since that’s where the Roles’  Permissions are stored. You could opt to put the storage of Roles in a separate object, but it makes no functional or logical difference (there’s a 1-to-1 relationship between a Group and its permissions).

In the Group object, we put the numerical values that store the permissions for each usergroup, and we define a list of constants that represent the bitmasks (or ‘flags’) for each permission. Note again that all permissions are powers of 2, as explained in the other article. Note also the usage of class-level constants, introduced in PHP 5 (I believe).

class Group
{
	const PERM_VIEW_GROUP = 1;
	const PERM_VIEW_THREADS = 2;
	const PERM_EDIT_THREADS = 4;
	const PERM_CREATE_THREADS = 8;
	const PERM_REPLY_THREADS = 16;
	const PERM_EDIT_OWN_POSTS = 32;
	const PERM_EDIT_OTHER_POSTS = 64;

	private $administratorPermissions = 0;
	private $moderatorPermissions = 0;
	private $memberPermissions = 0;
	private $guestPermissions = 0;

}

For each Role, methods can be defined that set, unset, add or remove permissions to a certain usergroup. 

	public function setAdministratorPermissions($perms)
	{
		$this->administratorPermissions = $perms;
	}

	// returns the Administrator role's permissions
	public function getAdministratorPermissions()
	{
		return $this->administratorPermissions;
	}

	// Adds a permission to the Administrator role.
	public function addAdministratorPermission($perm)
	{
		// we use the |= operator, which is equal to $value = $value | $perm
		$this->administratorPermissions |= $perm;
	}

	// Removes / unsets the given permission from the Administrator role's permissions.
	public function removeAdministratorPermission($perm)
	{
		$this->administratorPermissions &= ~$perm
	}

	// checks if the Administrator role has the given permission
	public function getAdministratorPermission($perm)
	{
		return (($this->administratorPermissions & $perm) != 0);
	}

Rinse and repeat for the other usergroups. Of course, all this could be condensed into even smaller chunks. You could also, to further redue the storage used for permission, create additional permission masks, the full set for each usergroup - i.e. MODERATOR_PERM_CAN_VIEW_THREAD, etc. However, you'll probably run up against the limitations of the system - i.e. that a number can only contain so much bits before it overflows. If you have only a few permissions, you could chuck it all into a single value, but if you have more (more than 8), use separate variables.

I’m fairly sure that every beginning programmer will read through the introductionary text of a new programming language and encounter several operators whose function remains unknown - I’m referring to the &, |, << and >> operators, which are present in pretty much every programming language. These operators are the binary AND, binary OR, and the left and right bitshift operators. Some will research further and, if they’re familiar with binary numbers (i.e. how numbers are represented in a processor, on the lowest level, with ones and zeroes), might also discover what it is they do exactly on a value.

However, a practical application for those doesn’t always make itself apparent. For me personally, it took three years (or four, dunno exactly) before I finally encountered an application for it. This was whilst I was working on Clan Arena / the C4 engine, whose code contains a relatively large amount of binary operators and functionality.

In C4, the application of these operators is numerous, but it often boils down to one thing - setting and reading properties of an object, for example a renderable 3D model. One property of a model was how it was rendered - render its wireframe, textures, shadow, specific shadow mode, and I dunno what else. Those are just examples btw, I’m not actually sure how they were really used.

The point with that particular application was that you could assign several settings to a model, whilst internally, each setting was stored in just a single, numerical variable. This means that you could set a number of ‘flags’, as they’re also referred to, to a single object.

The easiest comparison is with booleans. Pretty much everyone knows the boolean true / false logic, so that shouldn’t need any more explanation. Let’s say you’re writing a 3D engine and you’re at the part where to decide which part of a model to render - wireframe, texture, shadow, etc. A model, in this case, can indicate what it wants the engine to render, i.e. the model has a set of properties - let’s call em renderWireframe, renderTexture, and renderShadow, all boolean variables.

For each rendering pass, the engine will check these three variables and render accordingly. Simple enough.

Now, with bitmasks and binary operators, you could store these three (and many more, up to 32 or 64) variables into just one single variable, an integer. This is a prime example of data encapsulation in OOP environments - from the outside, the renderable object has a few methods, say, getRenderShadow(), getRenderWireframe(), and getRenderTexture(), but on the inside, these three booleans are all stored into a single variable.

The easiest way to picture this is to rotate the three booleans to a horizontal orientation. Let’s say the number 1 is the boolean true, and 0 is the boolean false (which, btw, is perfectly applicable to C/C++ and other languages in that order). You’d get some vars like:

bool renderWireframe = 0;
bool renderTexture = 1;
bool renderShadow = 1;

In this example, we want to render the model’s texture and shadow, but not the wireframe. When you take the values, rotate them horizontally, you’d get the following value:

011

A binary number which, if you happen to know binary, can also be interpreted as the number 3, thus reducing the amount of variables used to store the rendering information from 3 to 1. You may think that this isn’t a major improvement, but imagine you have to send the rendering variables through a Message, as I’ve described in an earlier post: Next to the Model object’s three variables, you’d also get a Message object with the same three variables.

In the default C4 implementation, this’ll take a few minutes to create. When you reduce the amount of variables in the Model to 1, you also get a Message with just 1 variable to send - which takes less time to write , and reduces the overhead of packing / unpacking the message by a factor 3 at most (probably a lot less, seeing that the original booleans took up just 3 bits in memory, compared to the 32 or 64 bits an integer would take up). Multiply this saving by the amount of times the message is sent back and forth, and you’ll notice a major improvement (logically speaking, that is, it’ll probably save amounts that can only be measured in nanoseconds, something you’ll hardly notice)

This particular example is probably easy to imagine, but can easily be converted to the inner workings of a program itself - Objects send each other messages all the time, in the form of method invocations and the passing of other Objects. Reduce the amount of variables, and you get less method invocations, less memory access overhead, etcetera.

In a follow-up article, I’ll explain how I’ve used this technique for an access control system for a PHP-based website / application. For now though, I’ll try to explain how to use the system described above.

Usage

There’s basically three operations you’ll need to know in order to work with binary variables / bitmasks: Reading, writing, and deleting / unsetting. Reading involves checking a variable if it’s got a certain value - in the above example, for example, you’ll want to check whether to render textures or not, and in a later stage, whether to render shadows or not. Writing is also important, since you’ll have to set the value at some point. Finally, unsetting involves removing a value from the variable.

We’ll start by setting a flag / bitmask in a variable.

First, you’ll have to declare a variable that contains the information. In this case, we’ll use C/C++ datatypes, but this technique applies to pretty much every programming language. We’ll initialize it to 0.

int var = 0;

Note that the binary representation of this number is 00000000 in an 8-bit system (we’ll use just 4 bits for this example purpose, in a modern-day system this’ll probably be 16, 32, 64 or even 128 bits).

Second, we’ll have to have a base value for all possible settings that can be set. As in, we’ll want to declare a few constant values that represent the settings. These constants, and this is important, have to be a power of 2, like 1, 2, 4, 8, 16, 32, 64, 128, etcetera. If you translate those to binary, you get sequences like 0001, 0010, 0100 and 1000 - note that each binary number has just one 1 set, the rest is 0. We’ll define the constants as such:

const int renderWireframe = 1;
const int renderTexture = 2;
const int renderShadow = 4;

In C/C++ and most other languages, you can simplify this action by using the bitshift operator (<<). This will basically move all 1’s in a binary number one space to the left, so that 0001 << 1 (bitshift 0001 with 1 space) will result in 0010, as shown in the example below. This however doesn’t work in all languages - PHP, for example, has problems with assigning the outcome of an operator to a constant. You can just use the notation above, the result is the same.

const int renderWireframe = 1 << 0; // 1
const int renderTexture = 1 << 1;   // 2
const int renderShadow = 1 << 2;// 4

In this case, you won’t have to manually calculate the power of 2 yourself, which, at least for higher numbers, is convenient - and you don’t want to risk miscalculations, not even with one number, since it’ll cause unexpected results.

I’ll explain the reasoning behind this in a bit, if you don’t get it by then. First though, we’ll write a value into our integer variable we declared earlier.

Assignment

To assign a value to a binary variable, you’ll need to use the binary OR operator - the single | character, like so:

var = var | renderTexture;

(note that some languages also have the |= operator, which can also be used instead.) The OR operator basically says something like: ‘For each number in the binary representation of the resulting variable, set to 1 if either var or renderTexture also has a 1 at that position’. A calculus notation will clarify (I hope):

0000
0010
---- |
0010

0 OR 0 = 0
0 OR 0 = 0
0 OR 1 = 1
0 OR 0 = 0

(feel free to replace 0 and 1 with false and true, and the | operator with the || operator, which compares the variables on a true/false level, a step higher than the binary level)

We’ve added renderTexture to the var, indicating we’ll want to render the texture. Let’s also add the renderShadow one:

var = var | renderShadow;

Which looks like

0010
0100
---- |
0110

0 OR 0 = 0
0 OR 1 = 1
1 OR 0 = 1
0 OR 0 = 0

Hopefully, the reasoning behind assigning only powers of 2 to the constants become clear now - assign anything but a power of 2, and you could get multiple flags set in the variable, which isn’t what you intend. Unless you do, of course.

Now, our variable called var has a value of 0110, which, translated back to the decimal system, is 6. Note that 6 is neither the value of the renderTexture constant, nor the value of the renderShadow constant - it’s a combination of the two. It also isn’t a power of 2. Because of this, you can’t compare the value with one of the constants using the == operator directly - you’ll have to extract the value from the variable, or, to be more precise, check if the value you’re checking for is contained in the variable.

Querying

To do this, we use the binary AND operator, &, on both the var and the constant, and check if the result is anything but 0. Let’s check if our variable has the renderShadow flag set. Note that AND works the same as OR, with the exception that the resulting binary number is only set to 1 if both the first AND the second binary number at the position is 1.

0110
0100
---- &
0100

0100 is not 0, so we can safely say that the renderShadow flag is set inside the variable. I said earlier to see if the variable is simply ‘anything but 0′, but the above example indicates that the result is actually equal to the renderShadow constant - why not compare it with that? There’s a number of reasons for that, actually, the primary one being that it’s a lot simpler. What’s easier to type:

if ((var & renderShadow) != 0)

or

if ((var & renderShadow) != renderShadow)

?

The result is in both cases the same - true in this particular example - but the former is a lot easier to write. In fact, in a lot of languages that are either typeless or semi-loosely typed, in which a regular int can, for example, also be interpreted as a boolean, such as C/C++, you could also just do

if (var & renderShadow)

and leave out the comparison entirely - in C/C++ and PHP (haven’t tried this in other languages yet), anything but 0 is interpreted as a boolean true, when used in an if-statement.

However, it’s considered bad practice to use it in this way, since it may cause confusion and doesn’t work this way in all languages. Not only that, but it confuses one type with another - whilst an integer can be interpreted and used as a boolean, they’re logically speaking two entirely different things. I made a mistake when I tried to put the result of one of these operations into a variable - instead of the result (a boolean true or false), the variable was set to the numerical value of the result (4 in the above example), producing odd, unexpected results.

Querying multiple masks

You should note however that you can only check for one value at a time using this method (using the comparison to 0), even though you’ve learned how to combine two binary values with each other earlier using the OR operator. The reason is that, when comparing a variable AND-ed with a combination of two values, the resulting value will be a non-0 value even when just one of the two flags is set. This can be prevented by comparing the resulting variable with the combination value instead of checking if it’s not 0 . An example:

var = 0;
var = var | renderTexture; // set var to 0010

// check if var is set to both renderTexture and renderShadow
if ((var & (renderTexture | renderShadow) != 0)

First we combine the two constants:

0010 // renderTexture
0100 // renderShadow
---- |
0110

Then we do the comparison:

0110 // renderTexture | renderShadow
0010 // var
---- &
0010

0010 is 2, is not 0, so the comparison would return true - even though renderShadow wasn’t set. Compare it with the combination of the two instead of ‘higher than 0′, and you’ll get the right result:

if ((0010 & 0110) == (renderTexture | renderShadow))

0010 & 0110 = 0010
0010 & 0100 = 0110

Or, in full

if ((var & (renderTexture | renderShadow)) == (renderTexture | renderShadow))

0010 is not equal to 0110, so the above comparison returns false, which is what we expected. You’ll have to do some more typing to get this to work though, and do the or-ing of the two constants twice (unless you place the or-ed version in a local variable or, if you do the combined comparison a lot, a constant on its own).

int cmp = (renderTexture | renderShadow);
if ((var & cmp) == cmp) {}

Unsetting

The third and final operation we’ll want to be able to perform, is to unset a flag from the variable. To do this, we AND the variable with the inverse of the mask. Previously, we did the AND-operator, that turned 0100 and 0110 into 0100, since only the second 1 was set and both numbers have to be 1 in order to have a 1 in the same position in the result. To unset a variable however, we’ll want the inverse to happen - set the value to 0 if both numbers are 1, i.e. the position in the variable has to be set to 0 at the position where the flag is 1.

If we have a value 0110, and a mask 0100, and we want to unset the mask from the value (i.e. remove the second 1 in the value), we use the inverse of the mask and AND that with the value.

We take the mask 0100 and we inverse it, which can be done with the ~ operator in most languages (bitwise NOT). The inverse of 0100, ~0100, is 1011. ANDing that with the value 0110, and we get:

0110
1011
---- &
0010

or the value minus the flag value.

(another use of the binary NOT operator is to get the maximum value an integer can have - simply echo ~0, the binary NOT of 0, and you get a binary value of all 1’s, or the maximum integer value)

That’s about all there is to binary operators. As I said in the beginning, I’ll attempt to describe an application of this technique with a real-world example, by using the bitmask technique to define roles for users, and permissions belonging to those roles. The major advantage of using bitmasks in such a manner is that of database storage - you only need one database column to describe everything a user having a role can do. But more on that in the follow-up.

In this post (and following posts), I will dive into Zend Framework, describe its various loosely-coupled components, and make an attempt at judging the framework.

For this summer vacation, I had decided to start my own website project, just to keep up-to-date and whatnot. Since PHP is the most supported scripting language (and currently supported by my relatively cheap host), I decided to do it in that - much less hassle trying to get it online. Although PHP isn’t my favorite language, I decided to give it another serious try, with everything I’ve learned of OO programming and design during the last few years.

Earlier, I’ve played around with Ruby on Rails, the web application framework that sparked an enormous flood in MVC frameworks in various programming languages - amongst which PHP. I even made a simple site with that, got some hosting for it (which was quite more expensive than my current host), and attempted to put it online… but that failed.

Later, I played around with CakePHP, a very popular PHP framework that, as other frameworks do as well, offers an MVC structure, an object-relational mapper, AJAX support, and all that and then some. I didn’t finish the website I started to built with it (due to uncertainties with the people that were going to use / run / operate it and my own lack of interest), so I am not able to properly judge CakePHP. I was annoyed by how you insert variables in templates though - when I attempted it, you had to echo an array index from an object field:

$something->post['Post'];

or something like that - I can’t remember. Looking at the current quickstart,  they’ve changed it to echo-ing a structure like

$post['Post']['id'];

but that still isn’t to my liking - it’s an array in an array in an equally-named variable. If there are multiple posts, which is the only reason I can think of why you’d use a two-dimensional array, at least call your variable $posts (plural), and run through all the posts with a foreach loop or something.

Anyways, that was probably more than a year ago. So this summer, I finally decided to start working on my own website and, following some rumours on the internets about Zend Framework, I decided to give it a try.

The Zend Framework is in a lot of respects the same as all those other PHP frameworks out there, having a database abstraction layer, MVC support, AJAX support, and all that. The main thing that ZF stands out for however is that it’s all loosely-coupled - using one component of Zend Framework, for example the database layer, does not mean you also have to use their MVC component, and vice-versa. There’s a list of components of the Zend Framework in the programmer’s documentation, and for the biggest part, they all work independently of each other. For example, if you want to configure your database connection (using Zend_Db), you can do that by passing an array of the configuration parameters, or you can use an instance of Zend_Config, which can also be initialized in multiple ways (by using an ini or XML file, or by passing a PHP array). These decouplings and lack of dependencies between Zend Framework components is one of the major points in the entire framework. It doesn’t force you to use one or the other. Want to use your own controller structure? No problem. Want to use a third-party database abstraction layer? No problem either.

Zend doesn’t force you to use anything, it leaves you with the choice. And I believe that is a very good philosophy.

So far, I’ve spent a good week or so on the framework, progressing through the development by reading the documentation on one component, then building part of my application using that, followed by reading up on another component, and intergrating that into my application. It’s relatively easy to remodel an existing application to use Zend Framework components, or to add additional functionality to your program. Which I find a nice way of working, since you can take learning the framework one step at a time, whenever you’re ready for it.

So far, I’ve only used a small part of the Zend Framework - Zend_Controller, Zend_Db, Zend_Form, Zend_Filter,  and Zend_Validator conciously. Some more components are used unconciously, such as Zend_View and whatnot, but it’s possible to replace those as well. As such, I’m nowhere near providing an accurate description or review of the framework. However, in the week or so I have noticed several things, both positive and negative.

First, there’s quite a lot and thorough description of each component in the Zend_Framework, which explain the biggest parts of each component. There’s also a complete API available, although the documentation on that isn’t very extensive - three-worded method descriptions and such, for example. With that, the documentation is just ‘good’, not perfect. But since the framework is still in development, with the 1.6 version being released as a release candidate not too long ago, I’m sure that’ll come along soon.

Next, there are serious demands for new framework components. They have to have an 80% test coverage, proper documentation, adhere to the coding standards, and so forth. The test coverage requirement is, in my perspective, especially valueable, since it gives some degree of guarantee that the framework is good in terms of quality. I haven’t actually seen the tests (or even executed them) yet, but I do plan on writing tests for my own application, once I have a basic version done.

However, not everything is fine and dandy with the Zend Framework. While it does offer a large set of components, it isn’t really intended to be a full website framework. For example, it isn’t shipped with an object-relational mapper (yet), or with scaffolding purposes, which, for other frameworks, are often used for advertising purposes (as in: lookie me! I can make a blog in 5 minutes!). This means that some components, such as object / relational communications have to be written by the developer himself. The Zend Framework makes the development of a website a lot easier, but doesn’t take all the work from the developer. This can be seen as both a good and a bad thing. It’s good because it allows a lot of freedom and control for developers, allowing them to control pretty much every aspect of their website, without relying on auto-generated code or underlying functionality. It’s bad however because it’s not very easy to learn for new users. The latter part can probably be solved by both extensive documentation (a full tutorial isn’t yet available) and frameworks built on top of the Zend Framework, that do add features such as scaffolding to the framework. Such features might be added to the framework itself in a future date.

All in all, I like Zend Framework. It doesn’t seem to be aimed entirely at new developers, isn’t pretentious or promising instant websites, but offers a professional framework for serious developers that know what they’re doing, without forcing their hand into using components that may not be applicable for their particular situation. I’m also unable to judge whether the Zend Framework is suitable for (relatively) new programmers either. I’m not having any serious learning problems with it, since I like to tell myself I know proper object-oriented programming, but I can imagine that new programmers will have problems with it, due to it giving a lot of freedom, requiring a lot of design knowledge, and the absence of step-by-step guides for building a full website.

In the near future, I’ll (probably) be writing some more articles concerning the Zend Framework and/or components therein.

EDIT: My bad, the Zend Framework does have some sort of object/relational mapper, in the form of the Zend_Db_Table and Zend_Db_Table_Row classes, which represent a database table and/or table row. The latter one in specific is the OR-mapper, and allows you to call methods like save() to store a row into the database. I’ll try and write an article on it once I figure it out properly for myself and I cba.

So far, most refactorings I’ve done involve moving functionality from one central Game class to different smaller classes - resource and game management so far. One refactoring however is one I’m pretty proud of (in all decency), and is described in the refactoring proposal as the Composite Message System.

In this article, I’ll (attemt to) explain the process of this particular refactoring: explain the old situation, what the problem was with that situation, how it was analyzed and how, eventually (and with the help of my trusty Design Patterns book) I came up with a replacement system of that situation, one that was a lot more flexible and reusable, and one that would accellerate the speed at which programmers could produce results.

For those that are interested, I’ll be discussing the Composite, Visitor, Factory Method and (to a lesser degree) Builder design patterns in this article.

Ye Olde slash Current Situation

While I’m not officially allowed to post any real code from the C4 engine or demo game, I’m pretty sure there’s no restrictions to discussing said code / design.

In the current situation, you can send messages to other clients through C4’s MessageMgr class, accessible through a global (shudder) variable, TheMessageMgr. The MessageMgr has a SendMessage method, which takes an address (in the form of the key of the recipient, managed by said MessageMgr) and a Message. This Message is a subclass of C4’s Message class, a class that contains some management functions (message ID number and such), but mainly defines the behavior of subclasses.

In a C4-made game, a subclass of Message has to be created for each message type. For example, say you want to send a chat message to a certain player. In C4, you’ll have to create a new class ChatMessage, which extends Message. ChatMessage would contain two variables: Sender, a long value referring to the player who sent the message, and Message, a String (or character array) containing the actual message.

C4’s Message interface defines that any Message should also implement a Compress() and a Decompress() method, two methods that basically pass a Compressor and/or a Decompressor object to the Message object, on which methods can be called so that the Message can add and extract its own data from a byte stream (or whatever, I don’t know / don’t need to know how the data is actually represented inside the Compressor / Decompressor objects). So you’ll have the following methods:

void ChatMessage::Compress(Compressor& data)
{
	data << sender;
	data << message;
}

bool ChatMessage::Decompress(Decompressor& data)
{
	data >> sender;
	data >> message;
}

Basically, the Compressor and Decompressor implement the << and >> operators, which add and extract the data from their internal representation. This actually adheres to the Visitor design pattern already, where a client sends an object to another object, where this other object (a Message subclass in this case) calls methods on the visiting object to, in this case, add data to it.

So, in total, to create a new Message type, you have to create a new class (in a header file) containing the class itself, the fields, two constructors, accessors for the fields, and a Compress and Decompress method. Next, implement the methods defined in the header file in a .cpp file (as well as message sending and receiving functionality, but that’s something for another day.) Sounds straightforward enough, and to be honest, it is.

However.

Say you want to create another message that sends an announcement to all players, say, a server message that appears in the middle of each player’s screen. Simple enough, create a new Message class that contains a string and done. Rinse and repeat the above operations of new files, new class, constructors, compress / decompress, accessors, and implementation. Next, you want to send a notification that playey X has left the game. Again, simple enough, just create a new message type PlayerLeftMessage, which contains just one long value (the player key), constructors, accessors, compress/decompress, implement… wait a minute, didn’t we do that earlier?

The observant reader will notice that in the above example, three full-on message types were created, each about 50 lines in total (no comments, with whitespace), and each containing roughly the same methods and functionality. The only actual difference between the three is the data they contain / send, and an internal key to uniquely identify the message type on reception. Not very much. And yet, you have to create a full class for it.

Let’s break it down a bit more. The types of data that can be sent over a network is limited by what the Compressor and Decompressor classes can handle in their << and >> operators. These types include:

• Booleans
• Floating point numbers
• Chars / Unsigned chars
• Character arrays (Strings)
• Shorts / Unsigned shorts
• Longs / Unsigned longs
• Long64 / Ulong64 (64 bits integers)

All messages, one way or the other, send these and only these values. More advanced data types, such as for example the Vector3D type, are broken down into components and sent. The Vector3D is broken down into 3 floating point numbers (floats), for example.

What does this mean? It means that, one way or the other, every message is composed of the above data types. Every message type converts the data they have to send to these types. They all do, no exceptions.

Solution

As I came to realize this, I figured there had to be a better, more flexibe way to define new message types, using the components described above. I read the chapter in the Design Patterns book on the Composite design pattern (since all message types were ‘composed’ of the above types), and attempted to work out a solution, as described in the refactoring proposal document.

The solution involved defining a class structure that allows a client to dynamically assemble (’compose’) a message type from both simple and complex ‘modules’, building blocks so to speak. There’s basically two types of building blocks: ‘Leaf’-blocks and ‘Composed’ blocks. Leaf blocks are the lowest point in the imaginary Composite Message tree, and contain one type of data - corresponding to the above list of Compressor-supported data types. It contains just one field, and implements both the Compress and Decompress methods defined by C4’s Message class.

The Composed block is a bit more advanced. It contains an internal list of other blocks (which can be either other Composed objects or leaves), and methods for traversing that list. It also implements the Compress and Decompress method, but instead of calling the Compressor / Decompressor’s << and >> operators, it passes the Compressor / Decompressor objects on to its subnodes’ own Compress / Decompress methods, so they can perform whatever action they need to do on it. If one of the subnodes is a leaf node, it’ll add or extract its own locally stored data to the Compressor / Decompressor object. If it’s another Composed node, it’ll pass the Compressor / Decompressor on to its children.

The figure below illustrates.

In this diagram, SomeMessage and Vector3DMessage are Composed Messages, while StringMessage, LongMessage and FloatMessage are leaf messages. All message nodes can be treated equally - they all, directly or indirectly, inherit from C4’s Message class. They all implement a Compress / Decompress method. They’re also all subclasses of a custom CompositeMessage type, which defines methods for traversing the tree.

To construct a CompositeMessage, which now is a means of defining a new Message type as described earlier, all a programmer has to do now is a handful of code statements:

CompositeMessage * message = new ComposedMessage();
message->AddSubnode(new StringMessage("some string here"));
message->AddSubnode(new LongMessage(10));

TheMessageMgr->SendMessage(message);

Three lines to create a new message type that would otherwise take 50. Quite an improvement, if I say so myself. Of course, there’s more to this than the above, as I realized after I had thought out this design.

You now have a tree of CompositeMessage objects, which are either ComposedMessage or LeafMessage types. Which one? No clue - as it should be. Proper OO programming involves not knowing or needing to know what specific implementation of a class you’re working with. So in the above example, you could see the entire tree as a tree of CompositeMessage objects.

Extracting data

However. How are you supposed to get the data stored in that from it now? This was the problem I had as well, and which I discussed with some people on the internets. From those, I gathered the Visitor design pattern is usually the means of traversing a tree and getting data from it.

Earlier in this article, we briefly passed this Visitor design pattern - the Compress and Decompress methods in the Message subclasses are both Visitor methods. The Compressor and Decompressor objects passed to those are Visitor objects. Such an approach could also be used in the Composite Message type.

In order to extract the data from a Composed message, I thought up a Visitor object that contained a list of sorts for each supported data type, as well as accessors for those. For each data type, there’s an AddXValue() and an GetXValue() method, that in turn adds a value of type X to the Visitor and get a value of type X from the Visitor. GetXValue will return the first X value when it’s called the first time, the second when called the second time, etcetera - according to a first in, first out pattern.

In the CompositeMessage type, a Visit method was added for each subclass to implement, which passes a Visitor object to the object. A Leaf subclass would implement it by calling Visitor->AddXValue(), passing its locally stored value to the Visitor. A Composed subclass would implement it by passing the Visitor to each of its subnodes.

Once the Visitor has traversed all the nodes of the Composite message, it’s filled with data, which can be extracted by the client again using the GetXValue() methods. An example:

CompositeMessage * message = new ComposedMessage();
message->AddSubnode(new StringMessage("some string here"));
message->AddSubnode(new LongMessage(10));

Visitor * visitor = new Visitor();
message->Visit(visitor);
String * someString = message->GetStringValue();
long someLong = message->GetLongValue();

Looks straightforward enough. The only thing to keep in mind is that the data should be extracted in the order the composite message was assembled. This method can also be used to fill the CompositeMessage with data, by defining a FillVisit method for each CompositeMessage subclass. Instead of calling Visitor->SetXValue() however, the GetXValue() method is called and its resulting value is set as the object’s local data.

Speaking of assembling, it’s best if a CompositeMessage type is assembled from only one point in the program, so that the exact same structure is maintained each time the CompositeMessage is composed (or ‘built’). To accomplish this, we’ll use the Factory Method design pattern. For each Composite message type, we define a construction method that takes the initial values of the various components of the Composite Message. Here’s an example:

CompositeMessage * CreateSomeMessage(Vector3D someVector, long someLong, float someFloat)
{
	CompositeMessage * message = new CompositeMessage();
	message->addSubnode(new Vector3DMessage(someVector));
	message->addSubnode(new LongMessage(someLong));
	message->addSubnode(new FloatMessage(someFloat));

	return message;
}

Simple and straightforward enough.

Consequences

This structure has both up- and downsides.

Using this structure makes it a lot easier to quickly create new message types. The process of new files, new class, fields, constructors, accessors, compress/decompress methods and all that is no longer needed, instead a programmer now assembles a message in three lines that earlier took 50, not counting documentation. Chucking it into a Factory Method as defined above adds some lines, but still nowhere near 50. This leads to increased production speed, and allows the programmer to concentrate on his task of solving problems, instead of the tedious business of writing the same class over and over again, with only slight differences.

Dynamic. With this structure, it’s possible to define message types at runtime, based on various factors. As such, the complexity of a message can be adjusted to the requirements. You could create a large, complex composite message for a player’s initial data, then adjust it to a much smaller / simpler one that only contains the data that has been updated.

Compatible with existing Message system. There’s no need whatsoever to change anything in the engine’s network code, since as far as the engine’s concerned, the CompositeMessage is just yet another Message. So this system can easily be used alongside existing messages, so that a transferrence from or to this system can be executed gradually, one message type at at time, without breaking the rest of the application.

There are however also some disadvantages to this system:

For one, it’s not as straightforward anymore. In the old system, all you had to do was call message->GetSender() (or something) to get the sender of a chat message. Now, you first have to create a Visitor object, pass it to the composite message, and call GetLongValue() from the Visitor. It’s a few extra steps, and it’s a lot more ambiguous - who says the long value received from the Visitor is really a player’s key? It’s uncertain, which means that in order to use this system, you have to keep track of the message type, and the order of data.

Also, it’s slower than the existing. The existing method was just a class with some message. Sending a new message involved creating a new instance of this class, and done. Creating a new CompositeMessage instance involves creating an X-amount of new objects, depending on the amount of data to be sent, and calling several methods on said objects before it can be sent. And that’s not all, for when it’s received again, the entire tree has to be traversed twice - once by the Decompressor object to fill it with data, and once again by the Visitor object to extract the data. How much slower this is, I don’t know - if in fact it is measureable - but it requires more instructions than the existing system. I’m guessing the performance decrease is negligible though, considering that at the same time messages are received and such, C4’s engine calculates loads of matrix transforms and whatnot.

Finally, this system can be used alongside the existing message system. Didn’t I already say that before? I did, since this point can be seen as both an advantage and a disadvantage. It’s in this case disadvantageous because the two message systems can become confused with each other - when one message is a class and another is a CompositeMessage, you’ll end up with maintaining two different systems. It’s best to do either one or the other, not both. But I guess that’s also personal.

Code

Anyway, for points I went and implemented the system (or a version thereof) explained in the refactoring proposal document. I’ll post the code below, but first, a warning: I haven’t properly tested this code. I did translate a few messages to the system, but nothing really complex, and nowhere enough to say this code is safe. If you’re planning on using this code, don’t assume it’ll work. I won’t give any guarantees.

Here’s the code. Hope you don’t mind the massive amount of code (relatively), and that Wordpress messed up the indentation.

CompositeMessage.h

#ifndef CompositeMessage_h
#define CompositeMessage_h

#include "C4Messages.h"
#include "C4Engine.h"

namespace C4
{

/*
The Visitor class is a class representing an object that is able to traverse a
Complex Message structure to gather data.
*/
class Visitor
{
private:

// For each data types, two fields have to be defined:
// * The array (or whatever) used to store the data
// * A counter keeping track of the last data returned.

// Long values
Array longValues;
long currentLongValue;

Array unsignedLongValues;
long currentUnsignedLongValue;

// Boolean values
Array boolValues;
long currentBoolValue;

// Float values
Array floatValues;
long currentFloatValue;

// String values
Array stringValues;
long currentStringValue;

// Char values
Array charValues;
long currentCharValue;

Array unsignedCharValues;
long currentUnsignedCharValue;

// Short values
Array shortValues;
long currentShortValue;

Array unsignedShortValues;
long currentUnsignedShortValue;

// long64 values
Array long64Values;
long currentLong64Value;

Array
unsignedLong64Values;
long currentUnsignedLong64Value;

public:
Visitor();
~Visitor();

// Long values
void AddLongValue(long value);
long GetLongValue(void);

void AddUnsignedLongValue(unsigned long value);
unsigned long GetUnsignedLongValue(void);

// Bool values
void AddBoolValue(bool value);
bool GetBoolValue(void);

// Float values
void AddFloatValue(float value);
float GetFloatValue(void);

// String values
void AddStringValue(const char * value);
const char * GetStringValue(void);

// Char values
void AddCharValue(char value);
char GetCharValue(void);

void AddUnsignedCharValue(unsigned char value);
unsigned char GetUnsignedCharValue(void);

// Short values
void AddShortValue(short value);
short GetShortValue(void);

void AddUnsignedShortValue(unsigned short value);
unsigned short GetUnsignedShortValue(void);

// Long64 values
void AddLong64Value(long64 value);
long64 GetLong64Value(void);

void AddUnsignedLong64Value(ulong64 value);
ulong64 GetUnsignedLong64Value(void);
};

/*
The CompositeMessage class acts as the interface to all CompositeMessage subclasses,
and defines the basic behavior of all subclasses. The main two subclasses to this class
are LeafMessage and ComposedMessage - see those for more information.

*/
class CompositeMessage : public Message
{
public:
// Constructor, used to set an identifier for the Message.
// Passes type to the Message constructor.
CompositeMessage(MessageType type);
~CompositeMessage(void);

// The Compress method is called right before a Message is sent.
virtual void Compress(Compressor& data) const;

// The Decompress method is called after the type of a Message has
// been determined.
virtual bool Decompress(Decompressor& data);

// The Add method adds a subnode to a CompositeMessage.
virtual void Add(CompositeMessage * subnode);

// The Visit method should, when implemented by a leaf class,
// pass its data to the Visitor object. When implemented by a Composed
// class, it should pass the Visitor to its subnodes and, when appropriate,
// extract the data from the visitor, assemble its complex object, and
// pass that to the Visitor again.
virtual void Visit(Visitor * visitor) const;

// The FillVisit method works the same as the Visit method, except should
// be used to extract data from the Visitor and assign that data to the local
// fields. Once again, Composed message types should pass the Visitor on to
// subclasses.
virtual void FillVisit(Visitor * visitor);

// The GetData method is implemented by the CompositeMessage itself,
// and will create a Visitor object, send it through its own structure
// (regardless of whether it's a tree or just a single node), and return
// the filled Visitor to the calling client.
virtual Visitor * GetData(void) const;
};

/*
The LeafMessage class is the parent class to all Composite Message nodes
that do not have any subnodes of themselves. Therefore, the Add method
will remain unimplemented (i.e. will do nothing) for Leaf nodes.

Subclasses usually contain one basic type value, so you get
BoolMessage, LongMessage etc subclasses to this class.

Note that LeafMessage is an abstract class, and does not implement
any functions itself.
*/
class LeafMessage : public CompositeMessage
{
public:
LeafMessage(MessageType type);
~LeafMessage(void);

// Compresses the local data into a Compressor.
virtual void Compress(Compressor& data) const;

// Extracts data from the Decompressor and stores it in a local value
virtual bool Decompress(Decompressor& data);

// Stores locally stored data into the given Visitor object.
virtual void Visit(Visitor * visitor) const;

// Extracts data from the Visitor object and stores it locally.
virtual void FillVisit(Visitor * visitor);
};

/*
The ComposedMessage class is a class that can be used
to compose more comples messages. It implements the Add,
Compress, Decompress, Visit and FillVisit methods,
each of which will traverse the array of subnodes
also defined in this class.

Subclasses that implement these four classes should all,
at one point, call this class's implementations. This can
be done either before or after doing their own thing.
*/
class ComposedMessage : public CompositeMessage
{
private:
Array subnodes;
public:
ComposedMessage(MessageType type);
~ComposedMessage(void);

// Adds the passed CompositeMessage, which can either be a leaf or another ComposedMessage,
// to the list of subnodes.
void Add(CompositeMessage * subnode);

// Will iterate through all subnodes and pass the Compressor object to each
// subnode's Compress method.
void Compress(Compressor& data) const;

// Will iterate through all subnodes and pass the Decompressor object to each
// subnode's Deompress method.
bool Decompress(Decompressor& data);

// Will iterate through all subnodes and pass the Visitor object to each
// subnode's Visit method.
void Visit(Visitor * visitor) const;

// Will iterate through all subnodes and pass the Visitor object to each
// subnode's FillVisit method.
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a boolean value.
*/
class BoolMessage : public LeafMessage
{
private:
bool value;
public:
BoolMessage(MessageType type, bool val = false);
BoolMessage(bool val = false);
~BoolMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor* visitor);
};

/*
Leaf Message type used to store a long value.
*/
class LongMessage : public LeafMessage
{
private:
long value;
public:
LongMessage(long val = 0L);
LongMessage(MessageType type, long val = 0L);
~LongMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store an unsigned long value.
*/
class UnsignedLongMessage : public LeafMessage
{
private:
unsigned long value;
public:
UnsignedLongMessage(unsigned long val = 0L);
UnsignedLongMessage(MessageType type, unsigned long val);
~UnsignedLongMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a long64 value. (see C4Types.h for long64 info)
*/
class Long64Message : public LeafMessage
{
private:
long64 value;
public:
Long64Message(long64 val = 0L);
Long64Message(MessageType type, long64 val = 0L);
~Long64Message(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store an ulong64 (unsigned long64) value. (see C4Types.h for ulong64 info)
*/
class UnsignedLong64Message : public LeafMessage
{
private:
ulong64 value;
public:
UnsignedLong64Message(ulong64 val = 0L);
UnsignedLong64Message(MessageType type, ulong64 val = 0L);
~UnsignedLong64Message(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a char value.
*/
class CharMessage : public LeafMessage
{
private:
char value;
public:
CharMessage(char val = ' ');
CharMessage(MessageType type, char val);
~CharMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store an unsigned char value.
*/
class UnsignedCharMessage : public LeafMessage
{
private:
unsigned char value;
public:
UnsignedCharMessage(unsigned char val = ' ');
UnsignedCharMessage(MessageType type, unsigned char val = ' ');
~UnsignedCharMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a string (or char pointer / array) value.
See also C4String.h.
*/
class StringMessage : public LeafMessage
{
private:
String value;
public:
StringMessage(const char * val = "");
StringMessage(MessageType type, const char * val = "");
~StringMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a short value.
*/
class ShortMessage : public LeafMessage
{
private:
short value;
public:
ShortMessage(short val = 0);
ShortMessage(MessageType type, short val = 0);
~ShortMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store an unsigned short value.
*/
class UnsignedShortMessage : public LeafMessage
{
private:
unsigned short value;
public:
UnsignedShortMessage(unsigned short val = 0);
UnsignedShortMessage(MessageType type, unsigned short val = 0);
~UnsignedShortMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
Leaf Message type used to store a float value.
*/
class FloatMessage : public LeafMessage
{
private:
float value;
public:
FloatMessage(float val = 0.0F);
FloatMessage(MessageType type, float val = 0.0F);
~FloatMessage(void);
void Compress(Compressor& data) const;
bool Decompress(Decompressor& data);
void Visit(Visitor * visitor) const;
void FillVisit(Visitor * visitor);
};

/*
The MessageTypeManager class is a supportive class for the Composite Message system,
and defines / can define a list of factory methods that assemble a Composite Message.

Optionally, parameters can be passed to the factory method of each message type,
which contain the data to be assigned to the nodes of the composed message.
However, keep in mind that empty composed messages should also be created,
for when a Message is received but not decompressed yet.

I've only put a few examples in this class, cba to do all current message types.
There's a description of each message type in their implementations, see the .cpp file
for information and usage etc.

In the examples put into those comments, pay particular attention to the lack of casts
to a specific message type. All messages, when received, are cast into a CompositeMessage
type - none of the underlying classes are ever directly used by a client.

In a system where all Messages have been replaced by CompositeMessages, a ReceiveMessage
method would only have to do a single cast at the top of the method, from C4's Message
to this CompositeMessage type. A massive reduction in casts is a result, and a result from
that is more reliable and type-safe code.
*/
class MessageTypeManager
{
public:
static CompositeMessage * GetServerInfoMessage(long playerCount = 0L, long maxPlayerCount = 0L, String gameName = "", ResourceName worldName = "");
static CompositeMessage * GetGameInfoMessage(unsigned long flags = 0L, ResourceName world = "");
static CompositeMessage * GetUpdateScoreMessage(long playerScore = 0L);
static CompositeMessage * GetUpdateHealthMessage(long playerHealth = 0L);
static CompositeMessage * GetClientOrientationMessage(float azimuth = 0.0F, float altitude = 0.0F);
};

}

#endif

CompositeMessage.cpp
#include "CompositeMessage.h"

#include "MGMultiplayer.h" // message types

using namespace C4;

Visitor::Visitor()
{
// set all 'current X value' indicator to 0.
currentLongValue = 0L;
currentUnsignedLongValue = 0L;
currentBoolValue = 0L;
currentFloatValue = 0L;
currentStringValue = 0L;
currentCharValue = 0L;
currentUnsignedCharValue = 0L;
currentShortValue = 0L;
currentUnsignedShortValue = 0L;
currentLong64Value = 0L;
currentUnsignedLong64Value = 0L;
}

Visitor::~Visitor()
{
}

// Adds a long value to the array.
void Visitor::AddLongValue(long value)
{
longValues.AddElement(value);
}

// Gets a long value from the array, or 0 if the array will exceed its bounds.
long Visitor::GetLongValue(void)
{
if (currentLongValue >= longValues.GetElementCount())
return 0;
else
return (longValues[currentLongValue++]);
}

// Adds an unsigned long value to the array.
void Visitor::AddUnsignedLongValue(unsigned long value){
unsignedLongValues.AddElement(value);
}

// Gets an unsigned long value from the array, or 0 if the array will exceed its bounds.
unsigned long Visitor::GetUnsignedLongValue(void){
if (currentUnsignedLongValue >= unsignedLongValues.GetElementCount())
return 0;
else
return (unsignedLongValues[currentUnsignedLongValue++]);
}

void Visitor::AddBoolValue(bool value){
boolValues.AddElement(value);
}

bool Visitor::GetBoolValue(void){
if (currentBoolValue >= boolValues.GetElementCount())
return false;
else
return (boolValues[currentBoolValue++]);
}

void Visitor::AddFloatValue(float value){
floatValues.AddElement(value);
}

float Visitor::GetFloatValue(void){
if (currentFloatValue >= floatValues.GetElementCount())
return false;
else
return (floatValues[currentFloatValue++]);
}

void Visitor::AddStringValue(const char * value){
stringValues.AddElement(value);
}

const char * Visitor::GetStringValue(void){
if (currentStringValue >= stringValues.GetElementCount())
return "";
else
return (stringValues[currentStringValue++]);
}

void Visitor::AddCharValue(char value){
charValues.AddElement(value);
}

char Visitor::GetCharValue(void){
if (currentCharValue >= charValues.GetElementCount())
return ' ';
else
return (charValues[currentCharValue++]);
}

void Visitor::AddUnsignedCharValue(unsigned char value){
unsignedCharValues.AddElement(value);
}

unsigned char Visitor::GetUnsignedCharValue(void){
if (currentUnsignedCharValue >= charValues.GetElementCount())
return ' ';
else
return (unsignedCharValues[currentUnsignedCharValue++]);
}

void Visitor::AddShortValue(short value){
shortValues.AddElement(value);
}

short Visitor::GetShortValue(void){
if (currentShortValue >= shortValues.GetElementCount())
return 0;
else
return (shortValues[currentShortValue++]);
}

void Visitor::AddUnsignedShortValue(unsigned short value){
unsignedShortValues.AddElement(value);
}

unsigned short Visitor::GetUnsignedShortValue(void){
if (currentUnsignedShortValue >= unsignedShortValues.GetElementCount())
return 0;
else
return (unsignedShortValues[currentUnsignedShortValue++]);
}

void Visitor::AddLong64Value(long64 value){
long64Values.AddElement(value);
}

long64 Visitor::GetLong64Value(void)
{
if (currentLong64Value >= long64Values.GetElementCount())
return 0;
else
return (long64Values[currentLong64Value++]);
}

void Visitor::AddUnsignedLong64Value(ulong64 value){
unsignedLong64Values.AddElement(value);
}

ulong64 Visitor::GetUnsignedLong64Value(void){
if (currentUnsignedLong64Value >= unsignedLong64Values.GetElementCount())
return 0;
else
return (unsignedLong64Values[currentUnsignedLong64Value++]);
}

// Compsite Message implementation.

// Constructor calls the parent constructor, passing the type parameter.
CompositeMessage::CompositeMessage(MessageType type) : Message(type){}

CompositeMessage::~CompositeMessage(void){}

void CompositeMessage::Compress(Compressor &data) const{}

bool CompositeMessage::Decompress(Decompressor &data) {return true;}

void CompositeMessage::Add(CompositeMessage * subnode) {}

void CompositeMessage::Visit(C4::Visitor * visitor) const {}

void CompositeMessage::FillVisit(C4::Visitor * visitor){}

/*
Creates a Visitor object and passes it to the Visit method, which
is implemented differently depending on what subclass of CompositeMessage
is currently used. When passed, the Visitor is returned.
*/
Visitor * CompositeMessage::GetData(void) const {
Visitor * visitor = new Visitor();
Visit(visitor);
return visitor;
}

// LeafMessage constructor, calls the parent CompositeMessage constructor
// passing the type parameter to it.
LeafMessage::LeafMessage(MessageType type) : CompositeMessage(type){}

LeafMessage::~LeafMessage(void){}

void LeafMessage::Compress(Compressor& data) const {}

bool LeafMessage::Decompress(Decompressor& data) {return true;}

void LeafMessage::Visit(Visitor * visitor) const {}

void LeafMessage::FillVisit(Visitor * visitor) {}

/*
ComposedMessage implementation.
*/
ComposedMessage::ComposedMessage(MessageType type) : CompositeMessage(type) {}

// deletes all the subnodes (if any) recursively.
ComposedMessage::~ComposedMessage(void)
{
long count = subnodes.GetElementCount();
for (natural a = 0; a < count; a++)
{
if (subnodes[a]) delete subnodes[a];
}
}

// Adds the given element to the subnode array.
void ComposedMessage::Add(CompositeMessage * subnode)
{
subnodes.AddElement(subnode);
}

// Passes the Compressor to all subnodes' Compress methods.
void ComposedMessage::Compress(Compressor& data) const
{
long count = subnodes.GetElementCount();
for (natural a = 0; a < count; a++)
{
if (subnodes[a]) subnodes[a]->Compress(data);
}
}

// Passes the Decompressor to all subnodes' Decompress methods.
bool ComposedMessage::Decompress(Decompressor &data)
{
long count = subnodes.GetElementCount();
for (natural a = 0; a < count; a++)
{
if (subnodes[a])
{
if (!(subnodes[a]->Decompress(data)))
return false;
}
}
return true;
}

// Passes the Visitor object to all subnodes' Visit methods.
void ComposedMessage::Visit(Visitor * visitor) const
{
long count = subnodes.GetElementCount();
for (natural a = 0; a < count; a++)
{
if (subnodes[a])
subnodes[a]->Visit(visitor);
}
}

// Passes the Visitor object to all subnodes' FillVisit methods.
void ComposedMessage::FillVisit(Visitor *visitor)
{
long count = subnodes.GetElementCount();
for (natural a = 0; a < count; a++)
{
if (subnodes[a])
subnodes[a]->FillVisit(visitor);
}
}

/*
BoolMessage implementation
*/
BoolMessage::BoolMessage(bool val) : LeafMessage(kMessageBool)
{
value = val;
}

BoolMessage::BoolMessage(MessageType type, bool val) : LeafMessage(type)
{
value = val;
}

BoolMessage::~BoolMessage(void) {}

void BoolMessage::Compress(Compressor& data) const
{
data << value;
}

bool BoolMessage::Decompress(Decompressor& data)
{
data >> value;
return (true);
}

void BoolMessage::Visit(Visitor * visitor) const
{
visitor->AddBoolValue(value);
}

void BoolMessage::FillVisit(Visitor *visitor)
{
value = visitor->GetBoolValue();
}

/*
LongMessage implementation
*/
LongMessage::LongMessage(long val) : LeafMessage(kMessageLong)
{
value = val;
}

LongMessage::LongMessage(MessageType type, long val) : LeafMessage(type)
{
value = val;
}

LongMessage::~LongMessage(void) {}

void LongMessage::Compress(Compressor &data) const
{
data << value;
}

bool LongMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void LongMessage::Visit(Visitor * visitor) const
{
visitor->AddLongValue(value);
}

void LongMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetLongValue();
}

/*
UnsignedLongMessage implementation
*/
UnsignedLongMessage::UnsignedLongMessage(unsigned long val) : LeafMessage(kMessageUnsignedLong)
{
value = val;
}

UnsignedLongMessage::UnsignedLongMessage(unsigned long val, MessageType type) : LeafMessage(type)
{
value = val;
}

UnsignedLongMessage::~UnsignedLongMessage(void) {}

void UnsignedLongMessage::Compress(Compressor &data) const
{
data << value;
}

bool UnsignedLongMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void UnsignedLongMessage::Visit(Visitor * visitor) const
{
visitor->AddUnsignedLongValue(value);
}

void UnsignedLongMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetUnsignedLongValue();
}

/*
Long64Message implementation
*/
Long64Message::Long64Message(long64 val) : LeafMessage(kMessageLong64)
{
value = val;
}

Long64Message::Long64Message(MessageType type, long64 val) : LeafMessage(type)
{
value = val;
}

Long64Message::~Long64Message(void) {}

void Long64Message::Compress(Compressor &data) const
{
data << value;
}

bool Long64Message::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void Long64Message::Visit(Visitor * visitor) const
{
visitor->AddLong64Value(value);
}

void Long64Message::FillVisit(Visitor * visitor)
{
value = visitor->GetLong64Value();
}

/*
UnsignedLong64Message implementation
*/
UnsignedLong64Message::UnsignedLong64Message(ulong64 val) : LeafMessage(kMessageUnsignedLong64)
{
value = val;
}

UnsignedLong64Message::UnsignedLong64Message(MessageType type, ulong64 val) : LeafMessage(type)
{
value = val;
}

UnsignedLong64Message::~UnsignedLong64Message(void) {}

void UnsignedLong64Message::Compress(Compressor &data) const
{
data << value;
}

bool UnsignedLong64Message::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void UnsignedLong64Message::Visit(Visitor * visitor) const
{
visitor->AddUnsignedLong64Value(value);
}

void UnsignedLong64Message::FillVisit(Visitor * visitor)
{
value = visitor->GetUnsignedLong64Value();
}

/*
CharMessage implementation
*/

CharMessage::CharMessage(char val) : LeafMessage(kMessageChar)
{
value = val;
}

CharMessage::CharMessage(MessageType type, char val) : LeafMessage(type)
{
value = val;
}

CharMessage::~CharMessage(void) {}

void CharMessage::Compress(Compressor &data) const
{
data << value;
}

bool CharMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void CharMessage::Visit(Visitor * visitor) const
{
visitor->AddCharValue(value);
}

void CharMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetCharValue();
}

/*
UnsignedCharMessage implementation
*/
UnsignedCharMessage::UnsignedCharMessage(unsigned char val) : LeafMessage(kMessageUnsignedChar)
{
value = val;
}

UnsignedCharMessage::UnsignedCharMessage(MessageType type, unsigned char val) : LeafMessage(type)
{
value = val;
}

UnsignedCharMessage::~UnsignedCharMessage(void) {}

void UnsignedCharMessage::Compress(Compressor &data) const
{
data << value;
}

bool UnsignedCharMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void UnsignedCharMessage::Visit(Visitor * visitor) const
{
visitor->AddUnsignedCharValue(value);
}

void UnsignedCharMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetUnsignedCharValue();
}

/*
StringMessage implementation
*/
StringMessage::StringMessage(const char *val) : LeafMessage(kMessageString)
{
value = val;
}

StringMessage::StringMessage(MessageType type, const char *val) : LeafMessage(type)
{
value = val;
}

StringMessage::~StringMessage(void) {}

void StringMessage::Compress(Compressor &data) const
{
data << value;
}

bool StringMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void StringMessage::Visit(Visitor * visitor) const
{
visitor->AddStringValue(value);
}

void StringMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetStringValue();
}

/*
ShortMessage implementation
*/
ShortMessage::ShortMessage(short val) : LeafMessage(kMessageShort)
{
value = val;
}

ShortMessage::ShortMessage(MessageType type, short val) : LeafMessage(type)
{
value = val;
}

ShortMessage::~ShortMessage(void) {}

void ShortMessage::Compress(Compressor &data) const
{
data << value;
}

bool ShortMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void ShortMessage::Visit(Visitor * visitor) const
{
visitor->AddShortValue(value);
}

void ShortMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetShortValue();
}

/*
UnsignedShortMessage implementation
*/
UnsignedShortMessage::UnsignedShortMessage(unsigned short val) : LeafMessage(kMessageUnsignedShort)
{
value = val;
}

UnsignedShortMessage::UnsignedShortMessage(MessageType type, unsigned short val) : LeafMessage(type)
{
value = val;
}

UnsignedShortMessage::~UnsignedShortMessage(void) {}

void UnsignedShortMessage::Compress(Compressor &data) const
{
data << value;
}

bool UnsignedShortMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void UnsignedShortMessage::Visit(Visitor * visitor) const
{
visitor->AddUnsignedShortValue(value);
}

void UnsignedShortMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetUnsignedShortValue();
}

/*
FloatMessage implementation
*/
FloatMessage::FloatMessage(float val) : LeafMessage(kMessageFloat)
{
value = val;
}

FloatMessage::FloatMessage(MessageType type, float val) : LeafMessage(type)
{
value = val;
}

FloatMessage::~FloatMessage(void) {}

void FloatMessage::Compress(Compressor &data) const
{
data << value;
}

bool FloatMessage::Decompress(C4::Decompressor &data)
{
data >> value;
return (true);
}

void FloatMessage::Visit(Visitor * visitor) const
{
visitor->AddFloatValue(value);
}

void FloatMessage::FillVisit(Visitor * visitor)
{
value = visitor->GetFloatValue();
}

/*
Creates and returns a CompositeMessage containing two long values and two string values.
Usage:

Creating new filled ServerInfoMessage composite message:

// parameters are all the params you want to send.
CompositeMessage * message = MessageTypeManager::GetServerInfoMessage(playerCount, maxPlayerCount, gameName, worldName);
TheMessageMgr->SendMessage(addressee, *message);
// (note that there should be a star in front of the 'message' param in the sendmessage method, since the
// GetServerInfoMessage method returns a pointer to the message, whereas the SendMessage method expects
// a reference instead.

// Also, the message should probably be deleted after this, but I dunno if the message is sent right
// away or stored in a cache for a while, which could lead to unexpected results if the message is deleted.

Receiving incoming ServerInfoMessage composite message type:

CompositeMessage * msg = static_cast(message);
Visitor * v = msg->GetData();

long playerCount = v->GetLongValue();
long maxPlayerCount = v->GetLongValue();
String gameName = v->GetStringValue();
ResourceName worldName = v->GetStringValue();

// note that the order of inserting and extracting data of the same type should be the same on both
// the sending and receiving side.
*/
CompositeMessage * MessageTypeManager::GetServerInfoMessage(long playerCount, long maxPlayerCount, String gameName, ResourceName worldName)
{
CompositeMessage * message = new ComposedMessage(kMessageServerInfo);
message->Add(new LongMessage(playerCount));
message->Add(new LongMessage(maxPlayerCount));
message->Add(new StringMessage(gameName));
message->Add(new StringMessage(worldName));
return message;
}

/*
Creates and returns a GameInfoMessage composite message type, containing an unsigned long and a string value.

Usage:

CompositeMessage * message = MessageTypeManager::GetGameInfoMessage(multiplayerFlags, worldName);
TheMessageMgr->SendMessage(addressee, *message);

// extracting

CompositeMessage * msg = static_cast(message);
Visitor * v = msg->GetData();

unsigned long flags = v->GetUnsignedLongValue();
ResourceName world = v->GetStringValue();
*/
CompositeMessage * MessageTypeManager::GetGameInfoMessage(unsigned long flags, ResourceName world)
{
CompositeMessage * message = new ComposedMessage(kMessageGameInfo);
message->Add(new UnsignedLongMessage(flags));
message->Add(new StringMessage(world));
return message;
}

/*
Creates and returns an UpdateScoreMessage, which contains a single Long value.
Notice that in this case, a LongMessage is returned directly without first having
to put it into a ComposedMessage - the advantage of using a proper abstract class.
Receiving parties will just treat it like any other CompositeMessage, as in,
they won't be able nor will they have to see the difference between the two.

Usage:

// send
TheMessageMgr->SendMessage(addressee, *MessageTypeManager::GetUpdateScoreMessage(playerScore));

// receive

long score = static_cast(message)->GetData()->GetLongValue();
*/
CompositeMessage * MessageTypeManager::GetUpdateScoreMessage(long playerScore)
{
return (new LongMessage(kMessageUpdateScore, playerScore));
}

/*
Creates and returns a new UpdateHealthMessage, which has the same structure of
GetUpdateScoreMessage. The only difference between the two is the message identification
number. We could make the two even simpler, by defining and implementing a
CreateLongMessage method, which takes a message identifier and an initial value,
and returns a LongMessage with that value. GetUpdateHealthMessage and GetUpdateScoreMessage
could then both call and return the return value of that GetLongMessage method, passing
their own message type identifier to the method. We won't do that in here though,
to keep things straightforward for now.

Usage:

// send
TheMessageMgr->SendMessage(addressee, *MessageTypeManager::GetUpdateHealthMessage(playerHealth));

// receive

long playerHealth = static_cast(message)->GetData()->GetLongValue();

*/
CompositeMessage * MessageTypeManager::GetUpdateHealthMessage(long playerHealth)
{
return new LongMessage(kMessageUpdateHealth, playerHealth);
}

/*
Creates and returns a ClientOrientation CompositeMessage, which contains two float values.

Usage:

Send:
TheMessageMgr->SendMessage(addressee, MessageTypeManager::GetClientOrientationMessage(azimuth, altitude));

Receive:

Visitor * v = static_cast(message)->GetData();
float azimuth = v->GetFloatValue();
float altitude = v->GetFloatValue();

*/
CompositeMessage * MessageTypeManager::GetClientOrientationMessage(float azimuth, float altitude)
{
CompositeMessage * message = new ComposedMessage(kMessageClientOrientation);
message->Add(new FloatMessage(azimuth));
message->Add(new FloatMessage(altitude));
return message;
}

The game itself is a sci-fi tactical first person shooter (well, it’s supposed to be in a distant future, olz), which was basically in a half-assed concept stage for about a year or two, during which some very nice concept art drawings were made, but nothing concrete was made, such as actual game design (i.e. functional design) or background story.

The project was eventually put forward to our university as a project for the Game Design minor, and since then, we’ve been working on it for the last 20 weeks. In this post, I won’t go into detail about the project itself, but more into the 3D engine that was used: The C4 engine.

About

The C4 Engine is written and maintained by Eric Lengyel, a mathematician slash application developer, who’s worked on the technologies behind several games, including several PS3 titles (although no actual names are given). He’s also written some or contributed to some books, including Mathematics for 3D Game Programming And Computer Graphics, so he bascially knows what he’s talking about.

C4’s got a load of features, including all the basic graphics capabilities one would want for a game, as well as a built-in world editor, graphical script editor, etc. The next version, 149, which is out now for licensed users, has a greatly improved graphical script editor, with conditionals and variables and whatnot (it didn’t have those earlier). Version 1.5, to be released late August if everything’s right, will come with a terrain editor and large outdoor terrain support (as in, the current version is mainly suitable for indoor or ‘roomed’ environments, which can be divided into so-called zones, which are used to determine what has to be rendered etc).

For more info on C4’s features, look here.

The C4 engine is aimed at both professional users and ‘indie’ game developers (independent, hobbyists, students etc). For both types, a license can be aquired. The indie category, such as we are, can get a license for as low as $200.-, which gives the licensee a lifetime license (= free updates to later versions), and allows 5 people to work on the engine and the engine’s code. However, this license type will be updated when version 1.5 (150) is released, and will be upped to $350,- accoring to the C4 website.  The engine is supplied as both the executables, plugins and, something unique, the full source code to both the engine and the demo game. That means that programmers can edit or add features to the engine itself, and get a deeper insight into the workings of the engine by reading its code. According to the C4 engine’s website, some large corporations (such as Lockheed Martin) and universities have taken licenses for the C4 engine.

Screenshots

Let’s goan see some screenshots from the current demo game which, by the way, doesn’t show off the full potential of the demo game. The full-sized screenshots can be viewed here.

This first image shows a basic piece of a level with a so-called cube light, a light that basically projects a texture 360 degrees around it. In this case, it projects the insides of a lantern.

This next image displays a scene from the Cemetery level, a relatively new demo level. This particular screenshot displays an imported terrain (not using the terrain editor yet btw, just the height map import option), with a fog layer on top of it. The fog’s fully configureable, so you can set the height at which it starts, the color, the density, etc.

A feature not shown in this screenshot is the lightning effect, which lights up the entire level and plays thunder sounds and such. Once again, this isn’t a level that’s graphically the most impressive, just a limited feature showcase - see some of the screenshots for other games made with C4 for better examples.

The Ravensword game screenshots shows how good proper normal maps can look (normal map is a texture that contains height information, which is used to calculate shadows on the object itself, which translates to a perception of depth and detail). The screenshots for World of Subways (yes, a subway simulator game) look in roughly the same style as Half-Life 2, only more realistic (and with less zombies).

The above screenshot is taken from the primary demo level, and shows imported terrain for the overall layout of the land, a waterfall effect (made with C4’s particle system), water itself (which uses animated textures and portals for reflection / refraction, see also this tutorial on C4’s wiki on how the water effect was made.) , etcetera.

This next screenshot is of C4’s built-in world editor, which allows people to make their own worlds. On the left side is a menu bar, which contains all the tools a world editor can use. The pane next to that is the Scene Graph, a graphical representation of the internal structure of a world editor. A root node, the Infinite Zone, contains a handful of subnodes, such as geometries, light sources, etcetera, which in turn can contain several subnodes as well.

The above is a screenshot of C4’s graphical script editor, I’m fairly sure this is the old (or current) version. Version 149 of the engine, to be released soon, contains additional features that could, once fully developed, allow non-programmers to program the behavior of an NPC, for example.

Experiences

Anyways, this was supposed to be more of a review and experiences with the C4 engine, but eh, it’ll need a good intro in order for people to sorta know what we’re talking about.

We’ve spent a good 20 weeks on our project, half of which was spent designing our game and exploring the C4 engine. We played around and made some basic worlds with the world editor, dived into the demo game’s code and edited some stuff, added a weapon by following a tutorial, etcetera.

It was pretty daunting to begin with for several reasons:

• A new language. Up until this project, all 3 of us (we had 3 programmers in our group) had little to no experience programming in C++ - I myself had done a fractal generator largely copied from the internets during a 2-week period. So with the C4 engine (which is written in C++, in case you didn’t realize that by now), we encountered new, unexplored problems like pointers and such. Scary.
• A new environment. The C4 engine’s quite different from the Java libraries and such I’ve used before this, with a lot of tricks and such. For example, a lot of binary flags are used - basically a means of storing a large amount of boolean data into a single variable. But that was all learnable.
• Poorly designed demo game. The engine itself is designed properly, but the demo game’s code looks as if it was programmed in some free saturday afternoons. There’s 500-lined functions containing large switch-statements which contain logic for pretty much all components for the demo game, to name an example. More on that later.
• Lack of commenting / documentation. The C4 engine’s code itself is reasonably documented (it’s not entirely complete and in a format that basically forces you to view the online version),  but the demo game itself isn’t. There are some scarce one or two-lined comments in particular bits of code, but not by far complete. So in order to understand the inner workings of the demo game, we had to dive into the code itself and work according to some of the tutorials on the C4 wiki. But after some time, we got the hang of it and knew enough of both the engine and the demo game’s code to add most of the features we wanted.

We added our own weapons (a handgun and an assault rifle), some of our own models (not all, which is why we didn’t get all the points for the end-product), animations (and animation control), sounds, and our own special features - distraction grenades, one that generated a ‘hologram’, one that played a sound, and one that displayed a flashing light pattern (which is supposed to look like gunfire). All three configureable by the player (by using an in-game selection menu), etc. They were all fired by the C4 demo game’s grenade launcher, but it’s the idea that counts.

We also added teams to the players (a multiplayer mode was already available), 3 game modes, and did some refactorings by splitting up some of the classes into their own files (a habit from Java, counteracted by the habit of whoever wrote the demo game to put loads of similar classes into a single file). The end result was a game that displayed most of the features we had planned, but didn’t look as good and looked basically only half-finished, due to the lack of models and the levels being only half-finished. But I myself got most points, mainly due to programming.

Anyways, the C4 engine left a very good overall impression on me. I haven’t had any experience with other game engines (that is, unless you count ZZT as being a game engine), but those that do think that C4’s the most awesome and well thought-out engines they’ve encountered so far. The engine itself is very rich in features without looking cluttered or bloated, and is still in full development, a new version with new features being released every month or so. We started when the engine was at version 147, and when we were done, version 149 beta 2 was out. A few days ago, the final version of 149 was released, along with a new demo including new demo levels and everything.

Criticisms

The majority of criticisms we as programmers had on the engine was all in its demo game and the documentation. The code-level documentation is allright (see above), but in terms of ‘how do you do so-and-so’, it’s still lacking. For example, halfway our project I wanted to find out how the C4 networking system worked. At that time, the only documentation avaiable was an article on the C4 wiki, highlighting the basic assumptions and workings of the network and messaging system, and the API documentation itself on the messages and message manager, which sends and handles messages, as well as the network manager, which operates on a lower level.

So because of that, we were bascially forced to figure it all our on ourselves, mainly trying to get as much information as possible from the API documentation and the code found in the demo game. Because we didn’t want others to have the same problem (and spend as much time on solving it), we (read: I) wrote a two-part tutorial on C4’s messaging system, in which a basic chat application is made. You can find that tutorial right here, and part two here.

But yeah, not everything is as of yet documented and explained. There’s enough to get you going, but it’s just not all there yet.

The second major problem was the lack of design in the demo game. There’s at least a dozen examples to think of, but it’s kinda bollox to have to repeat them all here. I can do one example though, the weapon system in the demo game. According to the tutorial on the C4 wiki on adding a weapon to the demo game,  a programmer has to add two files to the project, and edit 12 (!) files to add it to the game. These files handle firing, selecting, picking up, ammo etc of the weapon. But the problem is that it’s so divided, it’s difficult to figure all that out on your own without the use of a tutorial. Not only that, but the weapon system is decentralized, or, to put it more bluntly, all over the place. There are .h and .cpp files for each type of weapon, but they don’t contain anything related to t