By Bryce and Karsten

Acorn has a number of useful technologies which we can (and should) reuse or at least understand really well, before trying to do something in a different manner.


Acorn was initially developed for the purpose of enabling WorldForge to create a playable game. Prior to Acorn, an oft-cited complaint of WorldForge was that there was no program to download and run. Obviously, we needed something - even a simple thing - for people to play with.

However, this was easier said than done. The first few people who accepted this task lacked sufficient game-development know-how, and the project as a whole lacked experience at team oriented game development. The project seemed immense and the starting point unclear. While the pieces were available, by and large they had not been used in a game context, and lacked a number of basic required features.

Finally, we were lucky to find a skillful coordinator and assemble a team dedicated to bringing it about. This endeavor ultimately succeeded greatly in creating a playable game that could be used for demos. And, hopefully, it has succeeded in laying out a foundation on which we can build Mason.

General Game Development

One of the first major efforts completed was the generation of a rulebook for Acorn. It is located here: It describes each of the entities in the game, what sorts of activities they do, and how they react with other entities. This was of key importance for several aspects of game development: It helped identify exactly what animation sequences were required, provided the requirements for the coding of AI and game rules, and allowed easy extraction of the appropriate tasks.

One idea for this was to use it for both the developer guidelines and the player docs, thereby allowing us to kill two birds with one stone. The fewer individual docs, the better!

How it could be improved: The rules left some areas open for interpretation, and so these decisions had to be clarified and worked out during implementation. Also, there were capabilities that Cyphesis and UClient were able to do that did not get incorporated into the rulebook.

RECOMMENDATIONS: This rulebook serves as a good example for the level of detail we need to make the Mason rulebook. We should ensure that the mason rules are sufficiently precise in terms of numbers, complete sets of options, and so forth.

Process and Team Organization

The Acorn team was kept small and focused. It had frequent online IRC meetings to work out what still required implementation. The team stuck to the features dictated by the game rules, and avoided the lure of adding any idea that happened to come by. One of the main reasons this worked was because a sufficient amount of planning, development, and preparation had been done, thereby allowing them to use existing designs, code, and art to a large degree, and only need to "fill in the holes".

Development focused around demo-based milestones at LinuxTag. This gave a clear and pressing delivery schedule to work to. The required features to be implemented by this date was allowed to be flexible, so that even if not everything could be achieved, it could still be viewed as an achievement.

RECOMMENDATIONS: Definitely definitely definitely have a small team of people who are focused on delivering a working game, rather than trying to invent new stuff. These guys must have full decision authority regarding what goes into the final product and what does not, so that they are able to ensure all of their quality objectives can be met. Ongoing development must continue externally to this team, so that the implementers are constantly being supplied with fresh new things to be integrated. The Acorn experience teaches us that creating a releasable version of the game is best done by a small team that works closely together.

Media Development

Much media had been developed prior to the Acorn integration kickoff. By and large, most of the standards had already been specified and merely needed polishing and extending. The largest issue faced by the Acorn team was production of the sprite animations, which was particularly difficult due to the lack of skilled 3D artists. We got a few models from 3D artists for monsters, and then produced the remaining animations using the (non-free) animation tool "Poser". The images created are free, but the 3D model is not. The lack of a free humanoid 3D model to create animations from was a major worry, and one which Mason will need to tackle as well. Using Poser is not recommended as a long term solution; we need something free.

The easiest art to produce was the ground tiles and 2D building tiles, likely due to the excellent skillset we had onhand. Acorn did not require much in the way of buildings or mechanisms, but a number of people did work on 3D models for inanimate things such as a ballista, weapons, etc.

All of the media was created by a small number of people. Most of it was produced by one artist (Uta). This may have been due to a positive-feedback mechanism - the more media one creates, the higher the motivation to help get the rest finished so you can see your work in action. Or it just might have been plain old hard work and dedication. It's expected that with Mason, we're also going to need to find a small number of artists who are willing to dedicate themselves to producing nearly all of the media. We can of course hope that once the game is out and playable, that others will chip in additional media, but shouldn't count on this.

Part way through development we discovered we could make use of media from other open source projects. Unfortunately, this tended to not dovetail with our pre-determined needs and pre-selected file formats, so the amount that could be reused was limited.

RECOMMENDATIONS: From the get-go, seek to maximize use of existing media. Do thorough research regarding what is available already both within WorldForge and through other open source projects (and be sure to verify the licensing is compatible). Focus intently early on, at acquiring or creating at least one Free humanoid model, that can be used to produce animations in a free tool. If this cannot be done, it's going to really hamper post-Mason efforts. The Mason game design should focus on diversity of "things" rather than of "critters", since the former will be easier to develop media for (even a novice 3D modeller can make spheres, boxes, and rods, but creating a monster would be tough.) Limit monster choice to things we already have 3D models for, but be able to incorporate new monsters into the game design as the media becomes available.


Atlas is the communications protocol used to connect the client (UClient) and server (Cyphesis). It is implemented in library form via libAtlas-C++ and libAtlas-Python.

A frequently voiced complaint was that Atlas was insufficiently documented. In fact, it had a fairly sizable amount of documentation, but it was code docs, and usually people were looking for a tutorial, or overview, or implementation guide. Over time some of this documentation was created, but even today there are still some gaps.

A complete description of a dynamic system consists of the following:

1) A description of structure, describing the active components and the
2) A description of the the exchanged datatypes and their meaning
3) A description of possible events 
   (an event is a change of values observable at one of the interfaces)
4) A description of the operations
   (an operation is a sequence of events; it usually implies
   computations and the exchange of data between two active componets)
The existing Acorn documentation covers 1, 2, and 3 sufficiently, but we need better docs for the operations. Class diagrams illustrating the inheritance hierarchy would be very helpful.

The possible operations (e.g. login, move forward, etc..) are only vaguely described in the AcornInternal paper written by Alistair. There are no specifications, though. A client coder would need to look at example code to figure out how these operations are meant to work. The Eris library is a practical solution, as it removes this burden of implementing the Atlas protocol from the client developer, but not an ideal situation.

RECOMMENDATIONS: We badly need a specification for the Atlas operations. Either petri nets or UML sequence diagrams would be a good way of illustrating what is actually happening between server and client. Alistair and Karsten at several times had to look at each other's code in order to understand the client-server protocol.


When Acorn was kicked off, it was wondered whether to use Cyphesis or the in-development (pre-STAGE) server. We chose to use Cyphesis because it was further along in terms of usability, even though its performance was not so good, due to being scripted entirely in Python. Cyphesis was also missing some of the key features required by a game server, such as being able to log in. However, because the server was functional and already had Atlas implemented in it, we were able to start using it and augmenting it as we went.

Ultimately, the performance issue with the Python implementation became too great, and large sections of it needed to be rewritten in C++. This porting to C++ was done largely by Alistair. It's suspected that having prototyped the server in Python made the reimplementation in C++ much easier than if it was rewritten and redesigned from scratch.

RECOMMENDATIONS: The work done to get Cyphesis-C++ up and usable as a game server should definitely be taken advantage of for Mason, but longer term development should move towards STAGE for performance and added sophistication of features. Use Cyphesis-C++ to prototype as much as possible; the reimplementation of these things into STAGE will go much swifter.


Karsten began work on this client from the beginning of WorldForge and is perhaps the last of the first generation clients still in use here. At the time Acorn kicked off, it was the only client mature enough to be used in a game, and so was adopted for that purpose. Because Uta had done a huge amount of art specifically tailored to UClient, this gave us a major headstart on implementing the game.

Features needed for Acorn were:


 Browsing server list received from Metaserver
 Create account
 Login to account
 Select one of the server-side-stored characters
* Create new character


 Hitting items (the pigs, the oaks, the skeletons)
* An inventory which allows:
  - Taking items from the ground and putting them into the inventory
  - Transferring items from the inventory to the ground or to other game objects  - Trading items
  - "Piling" of items (e.g. put all coins on one pile)
  - Selecting single items of a pile (select one of the pigs) - NOT YET IMPLEMENTED -

Some design issues in UClient surfaced during this work, which would have prompted a redesign, but this was not done out of interest in keeping the client stable so that Acorn could be reliably developed. Also, during this development period, other libraries, techniques and technologies were discovered or brought into being at WorldForge, and other clients were able to take the time to redevelop themselves to meet these needs. UClient has evolved for more than two years and maintaining it becomes harder with every change. UClient1 very strongly depends on libuta and libAtlas-C++ - for example, it uses Atlas::Message::Object objects for all internal messages, which has the consequence that any change of the API of one of those libraries means immense code changes in the UClient sources.

Thus, while UClient would be a good starting point for Mason, the second generation clients now in development are probably better targets to shoot for. Karsten will be retiring UClient1 later when Acorn 1.0 is released, and is already working on UClient2, which will be named Morgate, because from his point of view, designing and implementing Morgate from scratch would be less work than cleaning up the UClient design.

One of the technologies brought into being for Acorn was Janus, a protocol for sharing User Interface descriptions between the server and client, in a generic way. This allows the same client to be dynamically and automatically 'reconfigured' for a particular game simply by downloading new UI definitions from the server, and doing it generically enough that any client would be able to translate and map these instructions to fit whatever widget set it happens to be using. Currently, there is no documentation on libjanus, though maybe comparing the gtk-binding to the libuta-binding illustrates the idea. libjanus does not yet specify a minimal functionality which a binding must provide. Thus a specification is needed for when other developers start to implement their own (client-specific) bindings. Karsten will work on compiling a draft for such a specification and encourages questions regarding libJanus to be shipped his way.

The sprite compression (especially the raw-format), scripting of the user interface (via LUA and Janus), and the terrain engine are features which Karsten plans for Morgate as well. Karsten feels these to be extremely valuable and may be worth exploration by other client developers.

Karsten also implemented a dynamically loadable binary module system in UClient. One of the ideas here was that it would allow others to develop pluggable modules for UClient. In reality, he feels that the binary modules added no benefit at all, and does not plan to include this capability in Morgate.

RECOMMENDATIONS: Go to second generation of clients and retire UClient as early as possible. Once clients have been selected, seek to avoid massive redesigns even if it means the client might start growing obsolete, as this can screw up being able to deliver the game in a timely fashion. Use Janus in all clients, tho we need to come up with a detailed spec for it before it will be very easy for client developers to integrate it.


The handling of the maps was perhaps the greatest achievement of Acorn: Uta created the maps using the old isoedit, those are read by uclient. But in addition to the isomap file, which just contains a list of tiles and object graphics, UClient reads the file types.xml which maps some of the graphic names to game-object types and defines additional attributes for the game objects: geometrically size, weight.

UClient can be used to read these two files and to compile a new mapfile (Atlas-XML-formatted).

These compiled mapfiles are part of the server distribution, while the isomap and types.xml are part of the uclient distribution.

In a normal setup, cyphesis will read its mapfiles and uclient its iso maps - as a result from the above desribed procedure, both - client and server - have the same map in memory without having transferred any data over the net!

Each item on this distributed map has an unique ID and a timestamp, only the server is allowed to change the map items.

When the player character walks around, the client receives sight operations for all the items which enter the sight radius of the player character. These sights ops only contain the ID and the timestamp. The client will now compare the received timestamp of each item with the timestamp in its database. If the timestamp is newer, the client will request the server for detailed information about this item in order to receive the changed attributes (the client will actually send a loop operation on this item's id).

With these techniques we were able to load maps with quite a high density of items, while keeping the needed net-bandwidth low.

RECOMMENDATIONS: Isoedit really has not been maintained at all over the years, but for Mason something akin to it that implements all of the same features and capabilities will be required. Being able to distribute the map as part of the client package and to transfer only changed items via the server was very helpful; it would probably be worthwhile to continue this approach unless a better technique is proven.

Installation & Support

Finding people interested in testing out Acorn was not too difficult, however there was a real obstacle course set before them in order to get it up and running. The most frequently cited issues were media installation troubles and finding a server to play on. With the introduction of the metaserver, the latter issue was reduced and eventually resolved. The media troubles were resolved via careful packaging and documentation, though still occur from time to time.

While many people were able to install and use the Linux version of the client, having to locate a server was an issue, until the metaserver was created. This was a major boon for locating available servers.

RECOMMENDATIONS: Attend to the installation process early and often. This will make or break the game almost as much as anything else. Maintain a listing of available servers, and ensure this is automatically updated, with problematical servers marked. This helps ensure player trust in the system.