Introduction Manual Class Reference Header Reference

Node Events

Sending Events

Node events are created by creating a ZCom_BitStream object and filling it with data.

ZCom_BitStream *event = new ZCom_BitStream();
event->addInt(42, 8);
event->addString("What was the question?");

Next, an initialized node is needed. The node's role can be anything, Proxy, Owner or Authority. It should be connected to at least one remote node, otherwise there is no recipient for the event. That means, an authority node should have been replicated to one or more clients. Or a proxy node needs to have a remote authority node connected to it.

There are two different ways to send an event. The first one specifies the recipients by their role, e.g. using ZCOM_REPRULE_AUTH_2_PROXY as parameter will send the event only if the local node has the role 'Authority' and it will be received by all nodes with the role 'Proxy'. This equals a broadcast to all clients except the client whose node has the 'Owner' role. To send an event like this, call ZCom_Node::sendEvent().

The second way is to specify the target node directly by it's connection id. Each client has it's own connection id on a server. This connection id can be used to address only the node on the client with this very id, regardless of the node's roles. To send an event like this, call ZCom_Node::sendEventDirect().

This code is assumed to run on the server, the event gets sent from the authority node:

node->sendEvent(eZCom_Reliable, event, ZCOM_REPRULE_AUTH_2_ALL);

This broadcasts the data in the 'event' bitstream to all replicated copies of 'node'. eZCom_Reliable makes sure that the event will arrive, even in case some packets get dropped. Other sendmodes are eZCom_ReliableUnordered and eZCom_Unreliable.

Receiving Events

The standard way to receive events is to poll the nodes on a regular basis. ZCom_Node::checkEventWaiting() returns true when an event can be fetched. ZCom_Node::getNextEvent() will give to you:

The first four values are received by passing pointers to variables as parameters to the function. The event data is returned as a bitstream pointer.

This code gets all available data:

while (node->checkEventWaiting()) {
  eZCom_Event        eve_type;
  eZCom_NodeRole     eve_senderrole;
  ZCom_ConnID        eve_senderid;
  zU32               eve_sendtime;
  
  ZCom_BitStream *eve_data = node->getNextEvent(&eve_type, &eve_senderrole, &eve_senderid, &eve_sendtime);
  
  // compute travel time of event
  zU32 eve_latency = ZoidCom::getTime() - eve_sendtime;
}

Events sent by the application always have the type eZCom_EventUser. If you care about such events only, just check if eve_type is eZCom_EventUser, then read the data from eve_data.

This unpacks the data from the event we created above:

  if (eve_type == eZCom_EventUser) {
    // number will contain '42'
    zU32 number = eve_data->getInt(8);
    // text will contain 'What was the question?'
    const char *text = eve_data->getStringStatic();
  }

Naturally, the node event polling should be done somewhere inside each game object's update()/process()/tick() function.

System Events

Zoidcom generates a few events automatically. Four of them (eZCom_EventFile_*) will be received when the node is performing file transfer. They won't be discussed here. The most important group of system events informs the application about connection and disconnection of remote nodes.

eZCom_EventInit

Imagine the gameobject 'Door', which can be either open or closed. Whenever a door is created, the default state is 'Closed'. Now a player opens the door and another player joins the game after that. The door will be replicated to the new client, but the client will create it with the 'Closed' state, as this is the default. At this point, it is necessary to update the new door to the current state.

eZCom_EventInit will be received by nodes on both sides when a new replicated node has connected to the authority node. Whenever the server door's node receives eZCom_EventInit, it means a new client door has been created. As each event comes with the connection id of the sender, it is now possible to create and send an application event to this newly created client node only.

if (eve_type == eZCom_EventInit && node->getRole() == eZCom_RoleAuthority) {
  ZCom_BitStream *doorstate = new ZCom_BitStream();
  doorstate->addString("Open");
  node->sendEventDirect(eZCom_Reliable, doorstate, eve_senderid);
}

Note the condition 'node->getRole() == eZCom_RoleAuthority'. Because client nodes receive eZCom_EventInit, too, it ensures that only the server will send the current state to the client, and prevents the client from doing the same to the server.

Attention:
As this event is disabled by default, ZCom_Node::setEventNotification() needs to be used to activate it.

eZCom_EventRemoved

When the object 'Door' gets blown away by a rocket, it is deleted from the game. On the server, you can just delete the object and it's node and Zoidcom will handle the rest. The rest consists of delivering all remaining events to clients and notifying them about the deletion. This results in receival of eZCom_EventRemoved on all connected client nodes.

eZCom_EventRemoved is the inverse to eZCom_EventInit. When this is received, a remote node is no longer available. If a Proxy or Owner node receive this, it means that the authority node on the server has been deleted. This in turn means(at least in most cases), that the Proxy or Owner object and it's node should be deleted, too.

eZCom_EventSyncRequest

TODO
This file is part of the documentation for Zoidcom. Documentation copyright © 2004-2008 by Jörg Rüppel. Generated on Sat Aug 16 15:26:51 2008 for Zoidcom by doxygen 1.4.6-NO