All information about required GWE behaviour in terms of service for the G Core System as well as network protocol can be found in this section. It should provide enough information to build your own compatible G World Engine. You are still advised to know about the general GWE design discussed in earlier sections.
This specification is work in progress. Information will be added while the specifications are being discussed and implemented by the developers. You can of course join the development team to add valuable considerations for this important part of the G System.
Although it is a very important aspect to fully document the functionality requirements, the current focus is to provide an implementation on the basis of C++ and the Qt toolkit.
This specification is definitely not as normative as it could or should be. If you have suggestions on improving the style of the specification you are very welcome to contact us on the mailinglists and discuss your ideas. Productive criticism is certainly welcome.
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.
The G World Engine Servers represent an XMPP client as defined by the XMPP protocol. XMPP Servers are used to establish a communication between the GWE Servers, the XMPP Servers are out of scope for this project, they are only used as a transport mechanism.
Although the GWE basically adhers to the XMPP-Core (RFC 3920) specification some elements of the XMPP-IM (RFC 3921) specifications are implemented to allow presence handling and basic message exchange with so called Jabber instant messaging clients. This allows for interesting interaction between the GWE and pure instant messaging applications.
GWE communication is totally accomplished through message stanzas. Each message stanza uses the appropriate to attribute for destination identification. In every such stanza additional xml data can be transported which is specified by the actual protocol.
Network communication is initialized according to the rules specified in the XMPP-Core protocol. Additionally, after authentication a presence stanza is transmitted with an empty show element. This changes the state of the GWE Server to online in the sense of XMPP and actually enables message forwarding to the GWE Server from the XMPP Server.
After XMPP initialization the master server of the established GWE Server infrastructure is contacted to register the GWE Server and integrate it into the hierarchy. The master server usually stores the registered GWE Server as a child server.
After server registration basic element data is exchanged. When element information is exchanged for the first time normal communication is taken up.
Normal GWE communication is taken up after successfull initialization and registration. In this state only relevant element data is exchanged between servers.
Further cases to be described in the future:
Server hierarchy restructuring
Element responsibility exchange
Proper shutdown
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.
See the GCS XML Schema for the structure of a valid GElement XML message.
Additional to the given structure in the XML Schema, the following attribute is allowed in the <GElement> tag:
Additional attributes in <GElement> tag:
owner (string, XMPP JID), defines the GWE Server that manages this element as primary element.
A GElement message is used to exchange information about elements. The additional owner attribute can be used to find the GWE Server that manages this element, which is very important for sending influences and other element related messages to the correct server. This kind of message is probably the most commonly used.
See the GCS XML Schema for the structure of a valid GElementInfluence XML message.
Additional to the given structure in the XML Schema, the following attribute must be included in the <GElementInfluence> tag:
Additional attributes in <GElementInfluence> tag:
target (GCS::GElementID, target element), defines the target element to which the influence should be forwarded.
A GElementInfluence message is used to transport influencing information. The additional target attribute must specify the actual target element since the influence itself does not contain target information.
<reparent> <element> element id which is reparented (GCS::GElementID) </element> <from> old parent GElementID (GCS::GElementID) </from> <to> new parent GElementID (GCS::GElementID) </to> <transformation> transformation matrix (GCS::GMatrix44) </transformation> </reparent>
The IDs are in the form of GCS::GElementID XML representations, the transformation matrix is in the form of GCS::GMatrix44 XML representation. The <transformation> tag is optional, if it is not present, an identity matrix is assumed (usually the case with formless elements).
For reparenting notifications this message is used. The same construct is sent to all servers that manage one of the three affected elements. Each server modifies the parent-child relations of its primary elements.
Whenever a server managing a particular element detects that reparenting is necessary, this message is used to notify the old and new parent. Such a message should only be generated by a server which manages the reparented element (as primary element).
<register> descriptive text </register>
The registration construct is simply empty or can contain some description. The sender can be identified through the XMPP protocol, so it doesn't need to be provided through this message.
The use of this message is to register a new child server at a master GWE server. This is usually done after server startup.
<unregister> descriptive text </unregister>
Like the register message, the unregister message is also an empty element with optional descriptive text in the body.
The use of this message is to unregister a GWE server that is about to shutdown from a master server.
<requestfreeids> unsigned long number, holding the amount of requested free element IDs </requestfreeids>
The requestfreeids message only holds the amount of requested IDs.
If a G World Engine server is running low on available element IDs it usually sends a requestfreeids message to its master server to request more free element IDs. Such a request is usually answered by a <freeids> message.
<freeids> <from> range 1, lower bound </from> <to> range 1, upper bound </to> <from> range 2, lower bound </from> <to> range 2, upper bound </to> <!-- and so on, any number of ranges allowed --> </freeids>
The freeids message ranges of element IDs that can be used for additional element creation.
The <freeids> message is usually an answer to a <requestfreeids> message. These two messages make it possible to distribute free element IDs within the server infrastructure.
Note that it is not uncommon for a GWE server to send free IDs to its master server in case many IDs get available because elements are removed. This way used element IDs get reused.