Adding The Nodes

Node Creation

As stated in the replication Introduction, each instance of a networkable object needs it's own node. Let's pick up the Rock and Tree code again, and expand the classes from the Sample Base.

// this code is not meant to be functional as it is

class GameObject
{
protected:
  // this is new
  ZCom_Node*          m_node;
public:
  // creates the node
  GameObject() { m_node = new ZCom_Node(); }
  // when object get deleted, just delete the node, too
  // there is no need for unregistering or anything else
  virtual ~GameObject() { if (m_node) delete m_node; }
};

This extends the GameObject class by a new member of type ZCom_Node*. Each game object is now able to hold it's own node object. As Rock and Tree are subclasses of GameObject, they of course will derive the m_node member.

Choose Replication Mode

Before the node is going to be registered with a ZCom_Control for action, it is a good idea to decide what replication mode is desired for it. Zoidcom offers basically three different modes:

Unique
Dynamic
Tag

Unique Replication

A unique node is unique in one ZCom_Control in respect to the class it represents. All singletons are good canditates for this replication mode. Objects using this mode need these properties:

They need to exist on both, client and server, before the two systems connect
They can not be created on demand
It is only possible to have one object of a type on each system (That is where the 'unique' comes from)

Dynamic Replication

Dynamically replicated nodes are assumed not to be existent on any client beforehand. This is the replication mode used for normal world objects, like Rocks, Trees, Playercharacters. While uniquely replicated nodes are identified and linked solely by their type, dynamic nodes get dynamic network ids. These are the properties:

Not allowed to be in existence on clients before server announces them
When a dynamically replicated node is created on server, it is announced to interested clients
Clients create the nodes and their corresponding objects as reaction to the announcement
When the node is deleted on server, clients will receive a deannouncement effectively requesting deletion of the node and object
Many nodes of the same type allowed

Tag Replication

Nodes replicated in tag mode are a mixture between uniquely and dynamically replicated nodes. They can be created on demand, but they may as well exist prior to Zoidcom's announcement. The authority node on the server is registered with an application-defined tag which is used to identify the counterpart node on the client. You can think of tags as manually assigned ids.

May, but don't need to, exist prior to the announcement by the server
Work similarly to uniquely replicated nodes, but use application-defined tag to find counterparts
When counterpart is not found on client, the application has to create the node the same way as it works with dynamically replicated nodes
When server node is deleted, a deannouncement is received on client

When you have a fixed number of networkable objects of a certain class/type, tagnodes may come in handy. They are created on the server and registered with a tag, which is nothing more than a simple integer. When announced, the client will receive the netclass id as well as the tag. When a node with this class and tag is already registered on the client everything is fine and will be handled behind the scenes, if no such node is found, it has to be created by the app in a callback.

Node Registration

After deciding which replication mode to use, registration itself is a simple one-liner. ZCom_Node defines three registration methods, one for each replication mode:

registerNodeByTag()
registerNodeUnique()
registerNodeDynamic()

All of these methods require at least the ZCom_ClassID previously acquired by registering the type with ZCom_registerClass() as well as a pointer to a ZCom_Control instance, since ZCom_Control manages the nodes.

We have trees and rocks, and choose the dynamic mode. The following code adds constructors to Tree and Rock which will register the node to a ZCom_Control object (Server and Client are subclasses of ZCom_Control).

// tree constructor
Tree::Tree(ZCom_Control *_control)  {
  m_node->registerNodeDynamic(m_classid, _control);
}

// rock constructor
Rock::Rock(ZCom_Control *_control)  {
  m_node->registerNodeDynamic(m_classid, _control);
}

One call adds the object to the network.

Sample usage:

// create a tree in the world and register it with the server
Tree *tree = new Tree(server);

// create a rock in the world and register it with the server
Rock *rock = new Rock(server);

Node Dependencies

It is possible to specify node replication order, in case it is needed. By calling

node1->dependsOn(node2);

node2 will be replicated before node1 whenever possible. See the documentation for ZCom_Node::dependsOn() for more information.

1.4.6-NO