Events

From PX Documentation

1 Overview
2 Event Set-up
3 Event Data Accessors
4 Event callbacks

Overview

Events are the underlying basis for all Netdog activities - they are any and all data transfers and can exist as in-game movements, data transfer, voice interaction, collisions, etc. Netdog processes events by linking an in-game activity with a networking event. These activities are matched with a call-back function that is stored on the client which then executes the event. To set up events, the event must be registered with Netdog using the NDInstallEventCallback function, these events are then run on servers using NDEventLoop.

In addition to basic event processing, Netdog has tools that allow for customization of in-game events - Channel functions process events in different Channels allowing for specific event information to be retrieved about channels. The Data Accessors allow user to access data within events in other parts of their game system.

Event Set-up

Events are comprised of the following two components:

Event Type
Event Callback Function

Event Types

Events are first set up and installed using the following:

  int NDInstallEventType(int typeID, 
                         NDEventCallback callback = NULL,  
                         NDEventCallback validateCallback = NULL
                         char* name = NULL, 
                         int flags = NDEventFlags::defaults);

Where:

typeID is the event type identifier
callback is the pointer indicating the function to be called whenever a validated event of typeID is executed, for processing (see Callback Functions)
validateCallback is the pointer indicating the function to be called whenever an event of typeID is received, to determine whether or not to execute the event (by calling callback) and send it on to other users on the network. If this argument is NULL, all events of this type are considered validated by this computer. In a traditional client-server architecture, only the server will need to validate events.
name is the name of the specific event
flags indicates the NDEventFlags that control attributes

Sending Events

NDSendEvent sends a user-defined event (installed by NDInstallEventType) over the network. ND handles all appropriate routing. NDSendEvent takes in-game events and relays the actions to all users within the game network. _NDSendEvent allows the user to specify a specific destination and data size (NDSendEvent automatically determines the size of the data structure passed as usrEvent, but requires a typed pointer).

  int NDSendEvent(void* usrEvent, 
                   int type);

  NDSendEventResult::Type _NDSendEvent(void* usrEvent, 
                   int type, 
                   int size, 
                   int ownerID = -1,
                   int channelID = -1);

This function takes the following arguments:

usrEvent is the event - in-game or other - that occurs and is relayed over the network
type is the event type
size is the size of the associated data packet for the event
ownerID is the ID of the intended recipient of the event. It defaults to -1, which means to broadcast to all computers on the channel.
channelID is the ID of the channel through which the event will be communicated. It defaults for channel =-1, for the default channel.

Executing Events

To process network packets and execute Events you must periodically call NDEventLoop() on both the client and server. For optimal performance, NDEventLoop() should be called at least once per frame.

  void NDEventLoop();

Event Data Accessors

The following functions provide for the retrieval of data from inside events that are in process. Each specific function returns data regarding the specific data type as below:

User Events:

  void* NDEventDataGetUserEvent(NDEventData eventData);

Channel ID:

  int NDEventDataGetChannelID(NDEventData eventData);

Connection ID:

  int NDEventDataGetConnID(NDEventData eventData);

Event Type:

  int NDEventDataGetType(NDEventData eventData);

Time Stamp:

  int NDEventDataGetTime(NDEventData eventData);

Event Originator ID:

  int NDEventDataGetOriginID(NDEventData eventData);

Event callbacks

Event callback functions are called when processing or validating events. The above accessor functions can be used to extract information about events or their contents from a NDEventData reference.

  typedef int (*NDEventCallback)(NDEventData);

For example,

 int ExecuteEventCallback(NDEventData eventData)
 {
   return(0);
 }

does nothing but tell ND it has successfully processed an event. For event callbacks, a return value of -1 means an event was not processed by the callback, and a return value of 0 means the event was processed successfully by the callback.

Validation callbacks have no return value. Rather they use a set of API calls which behave as a filter, indicating which set of players should receive the event:

NDInstallEventType(EventType::jump, &JumpCallback, &JumpValidationCallback, "jump");
...
void JumpValidationCallback(NDEventData evtData){
  //NDEventDataSetAllIDsValid(evtData); // This would send the event to everyone if uncommented (and the line below was commented)
  NDEventDataSetAllIDsInvalid(evtData); // Send the event to nobody
  NDEventDataSetIDValid(evtData, 3);    // except player with "ownerID" 3
  return;
}