An Atlas Tutorial


Atlas is a key component in the WorldForge architecture. It is an object-oriented protocol for communications between processes. These processes may be on the same machine, or machines hundreds of miles apart. The protocol can use all manner of media to transmit information, including files, streams and possibly even shared memory in the future. This tutorial will help you understand the kind of data that can be transmitted with Atlas, and hopefully encourage you to use it in your applications.

Atlas and its Implementations

Atlas is often confused with the libraries that implement it, like Atlas-C++ and Atlas-Python. These are two libraries that implement Atlas, written in different programming languages, but to confuse the issue even more, they don't always transmit the same thing for the same data. The XML implementation of atlas looks quite different to a 'packed ascii' version, and a computer expecting one format will not understand another format. It is up to the library programmer to allow computers to negotiate which version of the protocol they are to use.

Data Types

Atlas data is constructed using five primitive types: There is no limit on the sizes of these data types, though practical circumstances will place limitations on the protocol. One would expect a limit of 32 bits for an integer, 64 for a floating point number, and a whopping 2GB for character strings, lists and maps. Strings are binary transparent, and thus can contain characters like \0 without having them interpreted as commands by the computer.

A common way of describing the data types is as follows:


A list is an ordered collection of data objects, of any type. You can have lists of integers, lists of floats, lists of strings, mixed lists, and even lists containing other lists and maps. This allows for aggreggation or clumping together of data. Complex structures can be created this way. For instance:

[1, 2, 3, [4.0, 5.0], ["six", "seven", "eight"], 9, 10]

"Ordered" means that the elements of the list will maintain their order, not that they will be sorted.


A map is an unordered collection of data objects, of any type. It is not a description of geographical landscape in this context, though one application of Atlas may be to transmit and store geographical information. Data objects are named for retrieval. A map may contain any kind and mix of data objects. Note that implementations of atlas may reorder the contents of maps, so you should never rely on the ordering of objects in a map. A sample map example:
{name:"Mary", kids:0, pets:3, husband:"Geoff"}


An object is a specialized kind of map. It has two required key:value elements - id and parents. id is a string, parents is a list. The id field must be unique. For instance:

{id:"F98", parents:["human"], name:"Joe"}


An atlas class is a kind of object, with the value objtype:"class" to express its nature. All classes inherit from root_entity in the atlas class hierarchy. The class is really no different from an object except that it is expected to be static - nothing should manipulate its attributes. For instance:

{id:"human", objtype:"class", parents:["living"], description:"This creature walks"}

So the object with id 'F98' ('Joe') inherits the description field from the class object with the id 'human'.


An atlas operation is an object that inherits from root_operation. They are something like remote method calls, in other words a request to execute a command at the other end of the connection. However, they do not return values, as they are really only messages to the object, the response (if any) is up to the object itself. In operation objects, objtype is set to "op". The operation may include the to, from, and args fields.

The to field specifies the object to send the operation to, the from field specifies the object sending the operation, and the args field is a list of parameters for the call. For instance:

{objtype:"op", parents:["get"], from:"account_id_3423", args[ {id:"root_operation"} ] }

This operation requests the id of object "root_operation" by the object account_id_3423.


There needs to be some means of determining what operations can be performed on an object. These can be defined in an object by an attribute object called an interface. Interface objects inherit from root_interface. (You'll notice there are a number of these 'root' objects. In fact, they all inherit from the atlas 'root' class. Atlas has a standard class hierarchy that is similar to an API. This has been extended in WorldForge to create the atlas_game hierarchy of classes.)


The Atlas protocol is a powerful medium for software communications. It is highly extensible, allowing new Class hierarchies to be developed for specific purposes. We expect the protocol to find uses in a wide range of fields outside the gaming development community. Designed to convey object-oriented semantics within a computer system, it is a useful tool in this paradigm of programming. It provides a conceptually simple way of developing a distributed system.

We can expect many extensions to both Atlas and its implementations, we have a lot to thank its creators.