Ember development

From WorldForgeWiki
Jump to: navigation, search

This page is a work in progress,
meaning things are incomplete, unfinished, not fully thought out, might disappear again, and generally are subject to change.
Do not rely on any of this just yet!

This section deals with the development of Ember. It's mainly meant to help those that wish to be involved in the development of Ember.

The quickest way to get involved is to visit the Launchpad and look through the bugs and blueprints.

When working on Ember you should always use the the latest code directly from the GIT repository. Information on how to access it can be found here.


The main philosophy behind the development decision that have been made for Ember is to try to leverage existing FOSS components as much as possible. There's no need to reinvent the wheel for a particular feature when there's already bound to be an already existing solution. In fact, it even seems counter intuitive to develop a FOSS application and not using already existing FOSS components. One of the great benefits of the FOSS world is that code and systems can be reused. And not only reused; they can be refined and updated by the very same people that uses them, since the code is open.

Ember therefore strives to reuse existing FOSS components as much as possible. This shows itself in the very large number of third party components used in the system. There are usually two complaints about this (or really just one).

   * It's hard to compile
   * It makes the executable large

The first complaint is virtually void. It's only applicable for people that wants to compile Ember from CVS, all other people use either the prepackaged Autopackage version, or the precompiled Windows version, or get it from the FreeBSD ports system. Furthermore, all components used by Ember have been carefully selected so that they exists for all of the platforms that we support. There are even instructions on compiling Ember.

The second complaint would perhaps have been true 10 years ago when space and bandwidth were scarce. Today however it's not an issue. Additionally, if you don't have enough bandwidth to download the ~10Mb large Ember package, you probably don't have enough bandwidth to play online games anyway.


Most of Ember is written in C++. Most of the libraries used by Ember are written in C++ also, though there are some are written in C. The GUI is however mainly written in a scripting language, at this moment mostly lua. Ember provides a mechanism which allows for different scripting languages to be supported, as long as there are bindings. Currently however only Lua is supported.


Error creating thumbnail: Unable to save thumbnail to destination
Components in Ember

The components chosen by Ember are all components that are actively developed. They are also all supported on a large variety of platforms. We've tried to commit to components that we feel will be actively developed for a long future term. The goal is to be able to not hesitate to throw out an internal functionality if an external component with similiar functionality develops. By using third party components we don't have be experts in all the different aspects of the client. Instead we can try to focus on making the whole of Ember better. And hopefully the components we've chosen will keep on developing, getting better all the time.

Worldforge libraries

At the core of Ember are of course the Worldforge libraries. These are better described in other parts of the wiki, so they will just be briefly touched here.

  • Atlas is the main protocol for transferring data between the server and the client. Simply put, _everything_ that happens in the world is translated to Atlas. Ember uses some Atlas functionality directly, though most communication happens through Eris.
  • Eris is a client abstraction layer which translates Atlas messages into higher level data structures that makes more sense for the client (such as "Avatar", "Entity" etc.). Ember interacts heavily with this library.
  • WFMath provides math functions. Since all current Worldforge games works with 3d space, there's a need for a mathematical helper library to provide constructs such as points and vectors.
  • Varconf provides functions for loading and saving settings to a configuration file.
  • Mercator provides methods for dealing with generation of nature. It's mainly used for the generation of the terrain.
  • libWfut allows for live updating of media.


Since C++ has no built in mechanism for detached message and event signaling there's a need for a third party solution. While most event situations could be solved by using callbacks instead, signals and slots have a better semantic meaning. They also provide a more decoupled mechanism for events. We've therefore chosen to use the SigC++ library. This provides a mature and very easy to use system for signals and slots. Note that some Worldforge libraries such as Varconf and Eris also uses this library.

Ember subsystems

There's a lot of smaller frameworks in Ember, designed to be pretty configurable and easily extended. These are described in fuller detail here.


Getting media into the Ember client can be a little daunting, but the flexibility of the engine allows for very advanced features. The general guidelines are probably helpful, as well as the Ogre media guidelines.

Portable Binaries

We are currently using the AppImage format for distribution of Linux portable binaries. This allows a single-file download which runs on most Linux systems. It is a great alternative for people who want to run the latest version of the Ember client without compiling it themselves or waiting for it to become available through their distribution's normal package distribution system. Note that running an AppImage of Ember will not interfere with whichever version a user currently has installed through their normal package manager.


Here is the suggested work flow for creating an AppImage of a given Ember release:

  • For maximum compatibility, make sure that you are using a build environment with:
    • gcc >= 4.6
    • glibc <= 2.13
    • As an example, Ubuntu 11.10 matches these criteria
  • Set up the hammer script through the Download and Install section. Make sure that you are not root when you execute the next command. Then, in the "hammer" directory, type either of the following:
    • For a development snapshot image:
    ./hammer.sh release_ember dev
    • For a release image:
    ./hammer.sh release_ember <Ember Release Version>
  • Go get a cup of coffee (or lunch, depending on the speed of your computer) and when you come back you'll have a finished AppImage file in your "hammer/work" directory. This file's name will be in the format "ember-{dev|<Ember Release Version>}-x86_{32|64}. The name will depend on which option you chose above as well as on the architecture of your build system.
  • Just to be safe, you may want to run something along the lines of the following to make sure that the binary is in fact not using a version of glibc higher than 2.13.
objdump -p <AppImage filename>
  • You now have a shiny, new portable Ember binary.


  • If the image does not run, try running the "AppRun" program in the "Ember.AppDir" created by the "hammer.sh" script. If that works normally then there's a problem with the compiled AppImage.
  • If "AppRun" does not run, try starting ember directly by typing in the "hammer" directory:

If that works normally then there's a problem with the "AppRun" program. Troubleshoot the AppImageKit.