G System Developers Handbook

The G System is a C++/Qt based framework for simulation of virtual realities. The core library defines the structure of world content, so called elements, and defines the interface for so called agents which implement the behaviour of elements.

A world engine (GWE) is used for storage (DB), communication between elements and network transparency. The goal for the GWE is to build a hierarchical network distributed system that allows for huge worlds to be simulated. The structure represents the structure of the world itself like solar systems - planets - continents - areas - cities/lands - ...

We also build such a virtual reality with the system, it is called G Universe.

The main website of the G System project is http://www.g-system.at.

BSD style license (that means it's free and open source software) for all the source code except external libraries that are used, they have their own license (usually LGPL or BSD).

The documentation is available under the GNU Free Documentation License.

The GCS (library) defines the element structure. Elements are the basic building blocks for world content.

The GBE (library) is a library of basic element parts (agents, influences, forms,...) that can be used to faster build new worlds.

The GWE (library) provides the execution environment for elements. This also includes the network layer as well as the DB interface. It makes interaction between elements possible in a network transparent way. Note that the interaction itself is handled by agents (part of the GCS).

The GCE (library) is responsible for user interaction. It represents the world content in a 3D environment and allows for user input.

All parts have full API documentation (for further reading).

The demo application shows the basic usage and features of the system and can also serve as a quick testing framework.

GOD serves as an easy to use graphical configuration utility for the GWE. You can create/modify configuration files and integrate a GWE Server into an existing server network infrastructure.

A simple startup application is guniverse. It can load existing configurations, written by hand or created with GOD, into the GWE and initialize it. guniverse is also meant to be usable as system startup application to initialize a GWE Server on system startup (rc script).

guniverseclient is the "user client" for the G Universe. It builds on top of the G System components (libraries) and provides an user interface to interact with user elements.

In order to understand the G System and its way of development it is helpful to understand some of the basic ideas that drives this project forward.

The G System (or G for short) was designed primarily for one purpose: the simulation of evolution. But what does this mean? This is a good question to ask and happily it is not too difficult to answer. Before we start, we want to say that the system is in no way limited to this kind of simulation but this is what we have in mind while creating the G System. If you intend to use it for something completely different you will probably find out that it is quite useful for many purposes - because everything actually is part of evolution...

Many scientific or mathematical simulation frameworks and applications are highly specialized in their domain, which is mostly of a technical nature like electronics, mechanics or any combination. The G System does not attempt to bring a complete framework in such domains but tries to fill the gap of a more social, life and evolution framework. Still, it provides the means to construct many highly technical simulations and in fact such implementations could bring even more completeness to the virtual universe that the G System brings forth. The main aspects of the G System do not in any way contradict to technical simulations. In fact, life itself is a wonderfully scientific system. This system can model life, evolution and social aspects of our day to day experiences without taking away the fascination passionate philosophers intuitively feel about the subject.

It is important to remember that the word simulation in the context of the G System is not strictly used according to the technical meaning of the word in todays science. Instead, the term is rather extended and applied to a much wider range of phenomas we all encounter in daily life. This means that the G System is a simulation in a broader view of things, trying to provide a simulation and a framework for life, society and evolution besides being a general purpose simulation framework.

The second term that is heavily used and needs to be clarified is evolution. In general evolution is understood as evolution of form, meaning genetic changes in bodies of a species through successive generations. But that is truly just a minor part in the larger scheme of things. We define evolution as evolution of life, meaning the change of consciousness of the life that is expressed through the forms. Life never dies or goes away. It's always the same life that, through time, uses different forms to express itself.

Every software project has some origin, a reason why it exists and why developers actually are willing to spend their time on. Thoughts, ideas and a lot of other things are written down in the Philocorner document of the G System. To understand the G System, one should understand the philosophy that backs up this project. In some ways these philosophical considerations opens the project to a group of people normally not involved in software projects at all. Such people are of course highly welcome to join.

The G System Framework, as such, is not an application in itself, it is rather a set of tools and libraries that can be used to make a simulation. They work by providing a kind of virtual reality whose constituent elements can evolve over time in a realistic way. Users can interact with this reality and thus influence the environment. By being able to interact with others in the environment users themselves are part of the process of evolution.

On the other hand, the G Universe is the virtual reality built with the G System in order to implement the desired evolution simulation. This universe is open to anyone who wants to take part in it. Participation of human entities results in a highly dynamic and interesting behaviour of the overall virtual universe. This also leads to a worldwide virtual community that builds up a complete society in this virtual world. The G Universe can in fact be used to experiement with complex social settings as the working of the virtual world just represents real life - since real life is evolution. The difference is that the G System offers more possibilities, as it is virtual; and, being virtual, it allows for better analysation and thus understanding of the processes involved.

Take a quick look at our world, what is there? People, animals, plants ... but also cities, nations, the planet as a whole, many natural areas like forests, continents, rivers, the air, ... . On a different level we can consider that our environment is filled with certain ideas, concepts, feelings, etc., whatever makes up the atmosphere we feel or sense around us when we go to work, interact with other people, or just sit in a quiet place. The point is that all things around us are changing in one way or another, and we ourself change in time. We can call this "evolution". How is this accomplished? All systems follow certain laws, physicists know this well. But there are not only physical laws which accurately describe the behaviour of physical matter, there are also laws that apply to the latter categories (emotions, thoughts, ideas, the perceived ambiance of the place we are right now,...). Under such laws changes take place inside the system according to how the individual parts influence each other. Now, this is a very rational approach but I think it shows the basic concept.

Now let's take a look at the universe. Even this enormous system is changing/evolving in some way. Solar systems come into existence and fade away. And inside such solar systems are planets. On some such planets we may find evolution to be quite active...

I think the most interesting way of looking at evolution is to think about human beings, which is probably a very good subject for these studies. For now, this is left to the reader as an exercise...

Summing things up we can say that everything is evolving and evolution is possible through influences between parts of a system. Designing the influences themselves and the reactions are two major steps in creating a simulation with the G System.

This was a basic overview of what the G System aims at. It tries to give you a context for the rest of the documentation.

If you intend to join the G System team, you are very welcome to do so. We are very happy for every contribution made to the project.

In this section you will find some guidelines and information on how to best procede to get involved.

An important aspect to consider is that the G System is fully an open source project, meaning it is completely free to be used by everyone for any purpose without restrictions. So it is a project for everyone, for common good. Whatever you invest enriches all that are related to this project. Likewise everything that other people invest comes to your good - which is basically the whole idea behind open source: you give a tiny bit and you get all the contribution that other people give.

There is also a more general section about contributing at the end of the G System Developers Handbook. In particular, if you don't intend to join the team, but want to support the G System you can donate to the project, thus allowing the team of developers to spend more time on the project.

The first thing to do is to choose what you want to work on. There are really many options for helping the project:

Even if you have no suitable abilities or simply no time to spend, then at least you can help us to be able to spend more time on the project by donating money.

After deciding what you want to work on you should sign up for the appropriate mailing lists, which can be found on the G System homepage. Please discuss what you want to do on these mailing lists.

In any case you should read the section on the fundamental technologies that the G System utilizes and get familiar with what you need.

And please fully read this G System Developers Handbook, there is lots of valuable information to be found in it.

This section gives you some advice on how to work with this project: what tools to use, how to prepare patches and so on. Most of these guidelines are not obligatory, but usually provide the best way to work with the project. If you have other or better ways to get things done, in particular if you use different tools, then you should just carry on using them as long as the results are usable.

All these operating systems come with a large number of libraries and application that can be installed right away. If one of the required libraries or tools are not included with the installation CDs of the operating system, you might need to download and install them yourself.

You should make sure that you have the following libraries installed:

You should make sure that you have the following tools and applications installed:

Here you will find an example setup that can be used for G System development. It is by no means the one and only possible setup, but you may find the instructions helpful to set up your own environment. The final setup will be useful for both working on the source code as well as documentation. You will also be able to run a local XMPP server to use for the G Universe Server and the G Universe Client and have a database set up. This makes it possible to perform all development related activities on a single host that does not even need to be connected to the internet.

Please note that not every step is discussed in detail. You should have some basic knowledge to be able to deal with your operating system. This is intentional, you should have to think yourself to get aquainted with the system, which will help you a lot for the actual development work itself that you will do. If you think something important is missing from these instructions or something is simply wrong, please contact the G System team.

The overall setup that is presented uses NetBSD together with pkgsrc. With this it is rather easy to install all required packages, you basically only need to know what you need. The advantage of pkgsrc is that it works on many different unix-like operating systems, not just NetBSD, so you could use pkgsrc for whatever operating system you're using. You can find details on supported platforms on the pkgsrc website - http://www.pkgsrc.org.

After installing all required packages we will take a look at tweaking the environment to suit your needs - environment variables, database configurations, importing the project into KDevelop and other things.

If possible you should have a spare computer to do the actual installation on. If that is not possible for you, partitioning the hard disk might serve your needs.

All system related configurations must be performed as super user (root) of course.

At the time of writing the available versions were in general NetBSD 3.0, xorg 6.9.0, PostgreSQL 8.0 and 8.1, Qt 4.1, Jabberd 2.0s10 and G System pre-0.6 (svn trunk).

The first thing to install is the operating system, NetBSD in this case. I'm not going to duplicate any documentation, so just take a look at the NetBSD documentation to get yourself a working installation: http://www.netbsd.org/guide/en/.

After you have successfully installed NetBSD (wasn't that easy after all? Just putting in the CD and walking through the multilinugal setup...), you should install pkgsrc. Have a look at the documentation on how to do this: http://www.netbsd.org/Documentation/pkgsrc/.

Currently it is recommended to use the latest CVS version of pkgsrc, only this includes the required Qt 4. As an alternative, you can manually install the latest Qt version yourself. Please note that at the time of writing, pkgsrc does not yet provide the PostgreSQL database plugin for Qt 4. You can also use the SQLite plugin, which is available. You could also download and install Qt yourself, this way you can install all database plugins you want, including PostgreSQL.

After installing pkgsrc, you should edit /etc/mk.conf to set some options, I have found the following useful:

ACCEPTABLE_LICENSES+=lame-license
PKG_OPTIONS.jabberd2=pam pgsql
PGSQL_THREAD_SAFETY=yes
X11_TYPE=xorg

Please note that this uses xorg as the X11 server, you might have other preferences. The lame-license is required for the lame mp3 encoder, which in turn is required for kdemultimedia, in case you want a full K Desktop Environment. Also note that we use the pgsql option for jabberd2, which is different from the default, which is mysql. But we will use pgsql for all our database needs (three databases in total).

With pkgsrc you can install a package just by typing make install in the directory of the desired package. This list is hopefully somewhat complete, please tell us if you think something is missing.

Some of these packages require you to install rc scripts. The install procedure will tell you to do so. Make sure you don't miss to do this. In particular this applies for the PostgreSQL and the Jabberd2 packages.

You will find all the required rc scripts in /usr/pkg/share/examples/rc.d/. The ones you need to copy to /etc/rc.d/ are:

After installing all the packages, there are a few things you should do with your fresh installation to make NetBSD suit your needs.

rm -rf /usr/X11R6
ln -s /usr/pkg/xorg /usr/X11R6

mkdir -p -m 1777 /tmp/.ICE-unix
mkdir -p -m 1777 /tmp/.X11-unix

echo "Starting the K Display Manager (kdm)"
/usr/pkg/bin/kdm

I found it useful to put various environment variables into my $HOME/.profile file.

A very useful variable is LD_LIBRARY_PATH. To avoid the need of installing the G System, this variable can be used to point to the location of the compiled libraries. Thus it is possible to start the compiled G System binaries without the need to install the libraries into the system. So everything can stay in the development tree.

Other variables include variables used for Qt and path settings.

I found the following content in $HOME/.profile useful:

PATH=$HOME/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11R6/bin:/usr/pkg/bin
PATH=${PATH}:/usr/pkg/sbin:/usr/games:/usr/local/bin:/usr/local/sbin

QTDIR=/usr/pkg/qt4
QMAKESPEC=netbsd-g++

PATH=$QTDIR/bin:$PATH

LD_LIBRARY_PATH=/home/raphael/devel/G/trunk/lib:/usr/X11R6/lib

export PATH QTDIR QMAKESPEC LD_LIBRARY_PATH

EDITOR=vi
export EDITOR

Please note that these settings are only useful for shells that evaluate $HOME/.profile. I would recommend you to use bash. You can find it in pkgsrc as well, if it's not already installed. Note, you can use vipw to set the login shell.

Additionally, the LD_LIBRARY_PATH variable expects the G System development sources to be in $HOME/devel/G.

PostgreSQL is a fully featured, robust ORDBMS (Object Relational Database Management System). It is the most advanced free DBMS available. Look at http://www.postgresql.org for details and documentation.

# su pgsql
$ createuser jabberd2
$ createdb -O jabberd2 jabberd2
$ exit
# cd /usr/pkgsrc/chat/jabberd2
# make extract
# cd work/jabberd*/tools
# su pgsql
$ psql -U jabberd2 jabberd2
jabberd2=> \i db-setup.pgsql
jabberd2=> \q
$ exit
# cd /usr/pkgsrc/chat/jabberd2
# make clean

# su pgsql
$ createuser <username>
$ createdb -O <username> gserver
$ createdb -O <username> gclient
$ exit
#

jabberd2 is an XMPP server. XMPP is the protocol used by the G World Engine for network communication. Look at http://www.xmpp.org and http://www.jabber.org for details.

Please note that there are probably better XMPP servers out there, especially fully XMPP compliant servers like ejabberd are preferred. So using jabberd2 is just one possibility - jabberd2 is also integrated in pkgsrc, so it's easier to set up.

#!/bin/sh
#
# $NetBSD: c2s.sh,v 1.2 2004/06/26 11:21:46 abs Exp $
#
# PROVIDE: c2s
# REQUIRE: DAEMON pgsql

jabberd=YES
c2s=YES
sm=YES
s2s=YES
router=YES
resolver=YES

Before you proceed it is probably a good idea at this point to reboot your machine and see if the whole startup procedure works fine, especially with regards to the PostgreSQL database and Jabberd2. Another reason is to make sure that the environment variables are all set when you log in as user. If you know your system well enough you'll certainly be able to achieve all this faster without rebooting, of course.

Getting the sources and compiling is explained in detail in the chapter Source Management. It is recommended to check out the sources into the $HOME/devel/G/trunk directory.

Please also make sure that you are able to compile all of the G System source code. You should be able to perform this step with ./scripts/compile from within the trunk directory of the sources. Please note that the 3.4 version of gcc will not work correctly, use a different version. NetBSD 3 uses gcc 3.3, so that works just fine.

And make sure that you do not install the G System into the system. That is, do not call ./scripts/makeinstall.

We are now ready to run the G Universe Server and the G Universe Client on localhost, connected to the local PostgreSQL database and communicate through the local jabber/XMPP server.

First start the server: ./bin/guniverse and then the client: ./bin/guniverseclient.

If you have the docbook packages and libxslt installed, you can also build the documentation. To do so, run ./scripts/makedocs from the base directory of the G System sources. You can set various parametres for the script, depending on what you actually want to build, the output of running the script without parametres will tell you what options you have.

If you want to use KDevelop you can simply do so by running KDevelop and choosing Import Project... from the Project menu. Then select the $HOME/devel/G/trunk directory, set GSystem as project name and choose Qt C++ Application (QMake based) as project type.

You can make your life easier if you enable code completion, also for the Qt library. Go to Project settings and add Qt to code completion in the C++ settings. Note that KDevelop won't provide you with code completion for the x3dtoolkit, the qglviewer and the xmpp libraries, as these are included in the project files - KDevelop does not detect this.

When using KDevelop you should be aware of the following guidelines:

This feature list describes the desired functionality for the G System that should be implemented for the 1.0 release. The G System is made up of various parts, each part will be documented independently. Only source code related features will be discussed. Nevertheless documentation is just as important as source code so we work hard to provide good documentation for the whole system. Documentation and other aspects are included in the raodmap.

Please note that many already implemented features are still subject to further improvements.

State: stable

State: Element management done, XML based data management including network already usable.

State: usable, improvements still to be done in user-element interaction

State: World generation and a few basic agents done.

State: since version 0.5 of the G System it's possible to run a multi-user virtual universe.

This section includes a summary of the things that need to be done in the near future, if you would like to work on something, please discuss it on the g-devel mailing list. Look at the homepage for joining the mailing list.

The 0.6.x release series focuses on making the G System usable for real-world applications.

These jobs are not necessarily fast todo, but should be doable without solid knowledge of the system. If you want to work on one of these jobs, you can discuss this on the mailing list.

All project data, including the website, is kept in a subversion repository. Subversion is a revision control system, which is an essential tool for any software project, or even any kind of data. If you are unfamiliar with subversion, or even with revision control systems in general you should take a look at http://subversion.tigris.org. You can also get subversion from this site for any platform. All required information can be found in the subversion book, which can be found at http://svnbook.red-bean.com.

The actual place where subversion stores all the data is called a repository.

When reading about the architecture of the G System, you will probably find many uncommon and new aspects of software development. This is mostly because of the quite uncommon purpose this project works on. Nevertheless, we feel that the G System fills a gap in both social and scientific areas that require some attention. So the purpose of the technical implementation is to model life (or evolution, both are the same), and is thus not a means by itself. This can result in a somewhat uncommon but highly fascinating software design. Note that this is the purpose of the G Universe, you are free to model any kind of simulation with the G System Framework.

First, we should take a look at what parts constitute the whole system. The G System is modularised to allow for easy and flexible application development. Here is a brief overview.

There are also some individual applications that build on the G System framework and are part of the project:

The G System was designed to represent evolution. As such it has to retain incredible flexibility to represent almost everything in a consistent way. The high level of abstraction which is reached in the G Core System provides this flexibility and still allows for consistent rule systems. Energy represents matter, form represents form, agents represent the interactions that occur between the elements of the system. The hierarchical structure ultimately leads to the conclusion that every element is after all part of the universe and is thus in some way one with and/or connected to all existing elements. This is only a very basic interpretation of the Core System but is valid in general.

It is a long way from a view of life/evolution to creating software from it. The G System tries to provide an as perfect as possible framework for this modelling work. It does not dictate how the modelling of evolution should be done on a detailed level. Nor does it dictate how any particular simulation should be implemented. Implementation is thus left to the philosophical thinking and scientific modelling capabilities of the involved people. If you feel the need to take part in such an effort to find/create a simulation of an issue so fundamental to humankind, you probably should get involved in this project.

The central library is the GCS (G Core System). It defines the basic structure of world content. Every such piece of world content is called an "element", represented by the class GCS::GElement. This class uses other classes like GCS::GObject to store information about the element.

Basically an element consists of three things:

Energy gives an element a certain characteristic and is fully defined in the core system as GCS::GEnergy. Energy can take an important role for agent behaviour as some agents behave differently for different energies.

Form defines the element's geometry, the basic form attributes are defined in the GCS as GCS::GForm. The GCS::GElementData object optionally contains a setting for a 3D datafile, usually a 3D modell in the X3D file format.

The GCS::GObject class holds all data of an element. This includes the energy, the form, the ID of the element, the IDs of children and the parent ID as well as the ID of the element this element is connected to. There is also a generic data container which can hold any desired additional data of the element. This data is stored in an XML structure. All agents have access to this data and should use it to store ALL persistent data. This data gets also automatically transported by the GWE through the network and into the database.

Agents perform all of the behaviours of elements, which includes all laws that the element is affected by. No agents are defined in the GCS itself, it only provides the framework in GCS::GAgent to allow easy creation of new agents. Have a look at the basic elements library for some examples.

What the agent exactly does is completely up to the agent designer. Every agent is executed as a separate thread. Additionally the agent has read and write access to all data of its own element and read only access to other elements for which the IDs are known. When working with element data the agent designer has to keep in mind that there can be more active agents in the element which are also working with element data. For proper synchronisation most element data can be locked. It is highly recommended to use this locking mechanism when developing agents. To avoid deadlocks the order of locking is always:

Please keep in mind that all data that should be persistent must be stored stored in the GCS::GElementData object that is contained in the element's GCS::GObject. The GCS::GElementData class already provides methods to work with element data. These methods have the prefix xml.

Agents basically have two responsibilities:

The response mechanism is implemented by reimplementing a virtual receive method of the GCS::GAgent class. The parameter of this method is the influence itself.

GCS::GAgent inherits QThread which means that the agent itself is a thread. In its execution the agent can work with and process element data and can radiate influences or send influences to specific destinations (often the connected element). This is where most of the actual logic of the agent is usually defined.

An element can globally be started or parked, which means that all agent threads of that element get started or parked.

See the documentation of the GCS::GAgent class for more details.

An influence is represented by the GCS::GElementInfluence class. Agents can send out influences, either by radiation of influence or by influencing a definite destination element (this is where the ID of the "connected" element comes in). As soon as the agent has created such an influence, the agent can send it out and the GWE is then responsible for bringing the influence to the destination(s). When an influence is sent out, some other element will receive an influence. A virtual method of every agent of every receiver element is called and the influence is the parameter. Using this method the agent can define the reactions to the influence. The reaction can either be a simple modification of element attributes - or even just internal agent attributes - or more complex things that are handled in the agent's thread (instead of handling the reaction directly in this influence receiving method).

The GCS::GElementInfluence class is independent of an GCS::GElement instance, but is used by elements for interaction. By limiting interaction to one general way, it is possible to create general rule systems that apply to all kinds of interaction.

The only attribute that is transported with an influence itself is energy. In early versions of the G System it was common to subclass GCS::GElementInfluence to provide additional information to the receiving agent. But this brings a close dependency between sender and receiver of the influence. Starting with version 0.5 agents are able to access data of remote elements (for reading only) and thus it is not necessary to transport any additional information with the influence itself. If for example an receiving element needs to react to the sender's position then the agent would simply fetch the additional information through the GCS::GWorldData interface.

Influences always carry energy from the source element with them. This means that an element that sends out an influence puts a certain amount of its own energy into that influence, which can be thought of as the strength of the influence. If more than one element receive the influence, the GWE automatically distributes the energy among all receivers. Every receiving element absorbs the received energy amount.

The kind of energy that is received with an influence also determines whether the influence is at all recognised. Only if the energies are somewhat alike the influence is received at all. Further improvements on the GWE could result in the GWE making decisions about how much energy is received by what element.

The element data of IDs proposes a hierarchical world structure, and in fact this is what is used. Every element is in itself a complete unit to the outside and can have a very complex subhierarchy - solar systems are good examples. First, we have the whole solar system that can be seen as a complete unit ("one element") to the rest of the galaxy. This element has some child elements, which are included in itself (in terms of position). These children are the planets, asteroids, large space stations and space ships and so on. Every such element again holds a complex subhierarchy - continents - oceans. Continents hold landscapes and cities. They hold either houses, individual beings or whatever. Individual beings are again a very complex entity - which is probably a topic for our Philosophical Corner (philocorner).

Please note that an element does not have any direct reference (or pointer) to other elements, only their ID. Thus it is not necessary to have the other elements in the same system process - they can even be on a remote machine connected through the network. Large applications probably even should be distributed hierarchically among a network. Reflecting the element hierarchy of the virtual world in the hierarchy of the computer systems used is often a good idea. See the chapter about GWE for further details.

The G System is designed to simulate huge virtual realities. This can include many solar systems and planets, down to small details such as houses, environments, and even individual plants. All these things are not static. This means everything can change, humans (often controlled by real human users) move around, interact with other elements in their environment, ...

To allow for such a large scale simulation, some infrastructure needs to provide the computer processing power, the storage, and the communication. This infrastructure is provided by the GWE - the G World Engine, it is the container framework for all elements.

Elements simply operate. To them, the complete simulated universe is just a huge (hierarchical) collection of elements. They are not concerned with the physical location of other elements when communicating. Providing this seamless network transparency of a distributed server infrastructure is the purpose of the GWE.

As hinted in the previous section, the GWE is a distributed server infrastructure, or in other words, an element container and thus the framework the elements rely on for their operation.

The following UML diagram should give an idea of the GWE structure.

Currently there is one Network implementation available, the GXmppNetwork. This implementation builds on the standardised XMPP protocol. XMPP is essentially a real-time XML router, as Justin K. has put it in an email. And this is exactly what we need. We have XML data that needs to be routed through the network to some destination (another GWE Server).

Speaking in XMPP language a GWE Server is an XMPP client and uses an XMPP server to communicate with other GWE Servers which are also XMPP clients (possibly from other XMPP servers). Thus we do not even have hardwired peer-to-peer connections but rather a transportation framework that takes care of message routing and delivering.

The network structure basically looks like the following:

A client is a GWE Server with an user interface. To the network a client is thus nothing special. In general a GWE Server that acts as a client has few elements it is responsible for and has a lot of secondary (predicted) elements.

The GCS, which defines the elements, works almost by itself. Still, it requires the GWE to provide some services, in particular the communication infrastructure between elements.

The GWE and the GCS implementation must work together and be of a compatible implementation. If you plan to implement a GWE according to this specification, you must also provide a GCS that is compliant to the GCS specification.

The network protocol builds directly on the XMPP Core protocol. You can find additional information for this on http://www.xmpp.org. The protocol is thus completely XML based. Here, all valid XML messages are defined as well as the roles of the various parts of the G System.

Other protocols might be implemented. In such cases GWE Servers capable of both the XMPP based protocol and the other protocol must act as gateway. It is highly recommended to contact the G System team to discuss the integration of new protocols. The rest of this section only describes the official XMPP based protocol.

This section describes all known XML constructs that the GWE server must be able to understand. A short description of the expected behaviour is also given.

We refer to each such XML construct as message. Be careful not to confuse it with the message stanza kind of XMPP. Still, it is true that the messages described here can only be contained in message stanzas, so there is some connection at least.

Remember that particularly this section is subject to changes, especially extensions. The G System developers are not bound to ensure compatibility between different versions of development releases. Only with the release of version 1.0 can this protocol specification be considered stable and compatibility will be ensured at least through all 1.x releases.

World creation is an interesting topic, some of the required functionality is already implemented. The class GBE::GDynamicGeneratorAgent class provides functionality to generate a randomised universe based on a deterministic random generator. As this allows for a huge universe to be created, the generator can create just as much as the current active elements (whether they are intelligent computer driven beings or human users) require. As these active elements start to explore other parts of the universe the generator brings these parts into existence - and by the time passed, these parts can determine in what state they have evolved (age of solar systems or planets,...). Parts of the universe that are not inhabited by active elements are just put to "sleep" to save computing power. This is sadly a limitation we have, but it will have only a minimal (if at all) effect on the overall simulation if handled correctly.

Now, if the G System is about evolution, how does this get along with a randomised universe? This is rather a philosophical question but as it must occur to some readers we will answer (part of it) it here. First we need to distuingish between form representation and physiological aspects of the universe. The deterministic random world generation is in the first sense a means to determine where to place what kind of elements. It is a completely different topic how these elements behave after their creation, which is not in any way determined by the generator. Also, if for example the generator determines that on a certain location in a solar system a planet should be placed then the planet is not necessarily just there but the created element can just be a divine energy in the area of the planet that slowly evolves into a planet - for example by attracting asteroids, fragments of dead planets, ... So the determination that on a certain location a planet should be, does not clash with the way how this planet comes into existance and evolves.

Another agent, GBE::GReparentAgent, handles the hierarchical structure of elements. As discussed earlier, the universe is represented in a highly hierarchical structure - which is indeed necessary to allow for huge universes to be functional. Thus a human being may be part of a house while being inside. But if the human being walks out, it will be part of the city or the surrounding landscape. In order to handle the hierarchy changes properly, the reparent agent observes positional changes and notifies all affected elements when a change occurs. Details can be found in the API documentation.

Attention: This concept is not yet fully implemented. It is also considered to provide scriptable agents that can load scripts that define their actual behaviour. Various scripting languages are possible, like Ruby or SPL. It is still considered which is best suitable. A possibility would also be to provide more than one scripting language, like GBE::GRubyAgent and GBE::GSplAgent. Thus, more scripting languages are usable.

Agents are the parts of an element that define their behaviour. The behaviour of elements ultimately defines the physiology or the behaviour of the overall simulation created with the G System.

This makes agents a very important part of the G System. In particular agents are exactly what is used to customize the simulation to the needs of the particular usage. This also means that agents need to be created by people not directly developing the G System itself. To allow everyone to develop custom agents, a plugin architecture is used.

Agents can thus be developed independently of the G System Framework distribution. The plugin architecture takes care of dynamically loading agents into the simulation. It is even possible to update agents during runtime by unloading and reloading a particular plugin.

The GWE actually takes care of loading and creating GCS::GAgent objects from libraries. The responsible class is the GWE::GAgentPluginManager which implements dynamic library loading and plugin instantiation. Any kind of agents can be loaded this way.

The GWE::GAgentPluginManager class is also used by the GWE::GCoreXmlSerializer class to actually create agents specified by the XML document.

TO BE WRITTEN

This tutorial is based on version 0.3 of the G System. As such it is very much outdated and needs to be updated for the current version.

This tutorial will guide you through the process of agent design and implementation. Agents are used to provide behaviour or functionality for elements. The agent interface and the element structure in general are provided by the GCS library. All required information will be provided in this tutorial, but you still might want to take a look at the API documentation while working through the tuorial.

When we have created the agents we will also write the application that puts it all together, but we will see that this is a simple step.

By subclassing the GCS::GAgent class, we already have a compilable agent. Of course it does not do much out of itself, but we only need to implement what we really need.

There are two important methods, that the agent interface offers: GAgent::run() and GAgent::receiveInfluence().

The run() method is executed as an independent thread. GAgent inherits QThread to make this possible. The receiveInfluence() method is called whenever an influence is received by the element.

GAgent::run() should hold all the code that the agent should do out of itself. It is possible to create any level of complexity here. The agent could even access information from the internet and act accordingly, there is no restriction. Also it is perfectly fine to create more threads, but then starting and parking the agent must be implemented carefully. See the API documentation for details.

Our first agent will be called InfluenceSender and inherits GAgent. It should periodically radiate an influence, we can achieve this with a simple reimplementation of GAgent::run().

void InfluenceSender::run()
{
  while(!shutdown)
  {
    GEnergy* e = this->requestEnergy();
    
    GElementInfluence influence( this->getElementID(), e->take(0.01));
    emit radiateInfluence( influence );
    
    sleep(2);
  }
}

Let's walk this through line by line.

while(!shutdown)

shutdown is a protected attribute of GAgent. By default it is FALSE as long as the agent should execute, if the element should stop to execute then this variable is set to TRUE. With this while loop we make sure the thread stops, that means the run() method returns, when it is supposed to do so. Basically every agent that runs as a thread has this while loop. More complex agents might have to implement their own way of shutting down though.

GEnergy* e = this->requestEnergy();

Every element has energy that gives the element a certain characteristic. When we want to influence something, this "personal" characteristic of the element is always included in the influence we generate.

GElementInfluence influence( this->getElementID(), e->take(0.01));

The GCS::GElementInfluence class is used as a base class for all influences. It even implements a complete influence in itself without having to create a subclass. The required parameters are the source ID, which is represented by a GCS::GElementID object. This ID of the element can be obtained by GAgent::getElementID(). The second parameter of an influence is the energy that we load the influence with. We already obtained a pointer to the element's energy and GEnergy::take() creates a GEnergy object with the given fraction of the original energy. This means, we take 1% (0.01) of our own energy and load the influence with it. Normally the more energy we put into an influence the stronger is the effect. But we need to consider that every element only has a certain amount of energy so we need to be careful about how much we really use for an influence. As we will see later, by receiving influence the energy amount of the element can increase.

emit radiateInfluence( influence );

As soon as we have created the influence object we are ready to send it out. The GAgent class defines two signals for influence sending: GAgent::radiateInfluence() and GAgent::sendInfluence(). The first is used to radiate the influence into the surrounding environment and the second is used to send the influence to a specific destination element. We simply want to radiate the influence into our surrounding. What elements are affected by radiating influences depends on the implementation of the G World Engine (GWE). The implementation we will use in our application is the GWEInterfaceSimple. In this class radiation of influences affects the element's parent, all children of the source element and all elements that are touching the source element (forms overlap).

sleep(2);

This method is provided by QThread and puts the agent to sleep for given number of seconds. After that execution starts just after this call, which means that we are at the beginning of the while loop.

#ifndef INFLUENCESENDERH
#define INFLUENCESENDERH

#include <GAgent.h>

class InfluenceSender : public GCS::GAgent
{
  Q_OBJECT
  public:
    InfluenceSender(QObject* parent = 0, const char* name = 0);
    virtual ~InfluenceSender();
    
  protected:
    virtual void run();
};

#endif

using namespace XXX;

Now that we have seen how to send an influence in the run() method we can take a look at how we handle influence receiving in the receiveInfluence() slot. This slot gets called whenever the element receives an influence, just like the one we have created in the previous section.

We will stick to a very simple implementation so it is easy to follow. The agent we use for receiving will be called InfluenceReceiver, and all we want to do is to print information about the received influence. So this is how the implementation looks:

void InfluenceReceiver::receiveInfluence(GElementInfluence& influence)
{
  const GElementID& source_id = influence.source();
  qDebug("influence received from " + QString::number(source_id.getID())
  + " by " + QString::number(getElementID().getID()) + "...");
  
  GEnergy& inf_energy = influence.Energy;
  qDebug(" energy (level,amount,sigma): "
  + QString::number(inf_energy.level()) + " "
  + QString::number(inf_energy.amount()) + " "
  + QString::number(inf_energy.sigma()));
  
  GEnergy* own_energy = this->requestEnergy();
  own_energy->put(inf_energy);
}

This implementation shows how to access the data of an received influence. We will also write this data to the console so we can see what our elements are doing when we run the application.

qDebug() is used for output and simply accepts a string which it writes to the standard output of the application which in turn is our console. QString::number() converts a given number to a string.

const GElementID& source_id = influence.source();

GElementInfluence::source() returns a constant GElementID reference to the source element. With it we can identify from where the influence came. In complexer environments the receiving agent could create a child (subelement) with a connection ID of the source element's GElementID. A connection ID of an element can be seen as the element this element is concerned with. In particular it could send (in contrast to radiate!) influences of certain specialised types to it to achieve some desired result. See the API documentation of GCS::GObject::Connection for additional information. This attribute will play an important role in complex settings with intelligent agents.

GEnergy& inf_energy = influence.Energy;

The energy of an influence is a publicly accessible attribute. This essentially means that we can even modify it. Here we store a reference to it in a local variable.

GEnergy* own_energy = this->requestEnergy();
own_energy->put(inf_energy);

And this is exactly what we do here. We "put" the energy from the influence into the element's own energy. This is a process of mixing two energies of different level, amount and sigma into one energy. This is perfectly comparable to mixing two bottles of water with different colours (the colour being the energy level).

So we see that the GCS::GElementInfluence class offers two pieces of information:

After writing our two agents, we will put it all together in a small application. For this we will create two elements, a parent and its child. Radiated influences always influence the source's parent and children, so in this setting the elements will influence each other.

The main() function could look like this:

#include <qapplication.h>

#include "InfluenceSender.h"
#include "InfluenceReceiver.h"
#include <GWEInterfaceSimple.h>
#include <GElement.h>
#include <GObject.h>
#include <GEnergy.h>
#include <GElementID.h>

using namespace GCS;
using namespace GWE;

int main(int argc, char** argv)
{
  QApplication a(argc,argv);
  GWEInterfaceSimple* gwe = new GWEInterfaceSimple();
  
  GObject* object_parent = new GObject(
                            new GEnergy(5,10,3), //level,amount,sigma
                            NULL, //no form
                            GElementID(1), //the element is it's own parent
                            GElementID(1), //ID is 1
                            GElementID(1)); //connection ID is 1 - itself
  
  GElement* element_parent = new GElement(object_parent);
  element_parent->addAgent(new InfluenceSender());
  element_parent->addAgent(new InfluenceReceiver());
    
  gwe->add(element_parent);
  
  GElement* child = new GElement(
                        new GObject(
                            new GEnergy(3,1,2), //level,amount,sigma
                            NULL, //no form
                            GElementID(1), //parent
                            GElementID(2), //ID is 2
                            GElementID(1))); //connection ID is 1 - the parent
                                
  child->addAgent(new InfluenceSender());
  child->addAgent(new InfluenceReceiver());
  object_parent->addChild(child->getElementID());
  
  gwe->add(child);
  
  element_parent->executeElement();
  child->executeElement();
  
  return a.exec();
}

The main() function is in general very flexible in design. It is important that a QApplication object is present before any G related classes are instantiated, because many of these classes are derived from QObject. To be able to create a QApplication instance we need to include qapplication.h. Additionally we include the two header files from our self-made agents. Also it is important to include every used class of the G libraries. And in implementation files,

using namespace XXX;

should be used so we can use these classes without namespaces.

After creating the QApplication, we can create a GWE instance. This is used to handle all elements and manage influence sending and radiating between elements. Without a GWE influences wouldn't work.

The next step is to create the GObject of the parent element. The object holds all the data of an element, so we have to give an energy, a form and IDs for the parent, for itself and for the connected element. We store the created object in a pointer as we need it later to add the child.

Creating the element itself is then very simple, we only need to pass it the object.

In order to set agents for an element we can use GElement::addAgent(). The element takes care of initialisation of the agent, which means setting the GAgent::Object and GAgent::Agents attributes and starting the agent thread when the element is executed.

After the element itself is created and the agents are added, we add the element to the GWE. Note that when an agent creates a child element it only needs to emit a GAgent::childElementCreated() signal and the GWE recognises the child automatically, as long as the parent itself was added to the GWE. This means that only the top-most element needs to be added to the GWE manually and if this top-most element creates it's own children they will be automatically registered with the GWE through this signal. In our tutorial we don't create the child with an agent in the parent, so we will also have to do the parenting and the registration with the GWE ourselves.

It is important that every element has a parent. The top-most element is essentially its own parent. This is currently the convention used by the GWE, but it might change in the future. The API Reference is your friend in this case.

Then we create the child element with a slightly different energy level. After adding the agents we also add this element as a child to the parent's object. Then we add to the GWE.

As soon as all initialisation is done we can execute the elements and start the Qt event loop. Our application is running now. When an element is executed, it also starts all agent threads, just as it parks all agents when the element is parked. So no direct communication to the agents is necessary.

You could now try to complete the source code yourself with missing header files and implementations and compile it. It is highly recommended you go for it yourself. If you do encounter problems you cannot solve, you are welcome to use the forums on our website or the mailing list for your questions. You could also download the source files for this tutorial, which includes a qmake project file and short installation instructions, but this is only recommended when you don't manage to create the application yourself.

The complete source code for the tutorial can be found at ftp://ftp.g-system.at/data/tutorials/.