Subscription Based Message Router

Download Code File

Changelog
27th June 2004
posted resource

28th June 2004
made code handle re-entrancy by queueing messages while system is sending
fixed missing platform import statement

1st of July 2004
Due to request, I rewrote the initial parts of this resource to better explain what this is

1st of August 2004
Added object reference to the callback

7th of August 2004
Added a data field and an example "messaging trigger"

30th of October 2005
Bugfixes to prevent crashes on deleting subscribers during sending
SimObjects can now subscribe and send instead of ShapeBase objects
Rewrote script API

21th of September 2007
Wow - new update!
Fixed spelling mistake in receive vs. recieve
Partially rewrote the code to get rid of the internal delete queue. This fixes a bug where ojects could delete other objects that also were subscribers, and is more pleasing + logical.
Also fixed tiny bug with wrong error message in subscribe method

Subscription what? What the hell is this? What can I use it for?

OK OK - read through this, and you will know that you can use this in your game. Its almost guaranteed.

This resource is all about minimizing overhead - so this saves you from e.g. polling for status/ray casts and similar. it also saves you from coding dependancy into your objects about other objects. In the long run this will save you from errors and extra work.

Example:
A simple pac man game. The pac man eats a power pill and somehow the ghosts need to turn blue for a short period of time.

You can do this at least 3 ways
1) ghosts ask pac man every 50 ms about "did you eat the powerpill?"
2) pac man tells each ghost "I ate the powerpill, and thus you have to turn blue"
3) pac man sends a message to the "power pill eaten" queue, and the ghosts get the message as an event

Problem with method 1: overhead - huuuuuge overhead. It might be OK for 4 ghosts to do this, but in 99.9999% of the cases the answer is negative and thus overhead.

Problem with method 2: pac man needs to know about each and every ghost, so that he can tell them about the power pill. This creates a dependency between code objects, and if you later add a 5th ghost, you have to make sure you run through all your code and add it to where pac man talks to the ghosts = error prone process

Along comes method 3 (this resource). There is no overhead.

Only ghosts that are interested in the "power pill eaten" messages subscribe to the queue. And only when there is a message will they be bothered with it (they have a method onRecieveMessage() that is called when there is a message - and not before)

And pac man doesnt need to know about the ghosts at all - all he needs to do is send the message that he ate the pill. And the ghosts dont need to know if it was mr. pac man or mrs. pac man who ate the pill - all they need to know is that someone ate the pill and now they need to turn blue. This enables you to add more content into the game without having to run through your logic over and over again.

So event driven messaging that is subscription based saves overhead and precious CPU cycles, as well as allows for much cleaner code, as well as more complex AI.

The basic mechanism of this resource is that you (from script) create a message queue. Script objects can now subscribe to these queues and every message send to queue X is then send to a subscriber of queue X.

Some example usages:

Example: exploding rocket
A rocket is fired and it collides with something and explodes. In its onCollision() it sends out a message saying "I, the rocket, exploded at coordinates x,y,z. I have a blast radius of 20 meters, and everyone inside the radius takes 20 hitpoints damage" to the "damage" message queue

All damageable objects have subscribed to this message queue and will now recieve the message send in their onRecieveMessage(). It is now up to them to check if they are invulnerable, in range, protected against rocket damage, have armour points to spend before health etc.etc.

Example: faction system
In an RPG game all player actions are send to a "playeraction" message queue. E.g. during this particular example game the player has succesfully pick pocketed 10 NPC players. Every time a message "I succesfully pickpocketed NPC with id ###" to the queue.

The game has 2 factions. The police faction and the thieves guild faction. Both subscribe to the queue and recieve these pick pocket messages. Based on these actions they recieve each factions can adjust their AI responses to real events. In this example case the players reputation in the thieves guild has preceeded him, and he will be recieved with open arms.

In this case it would be extremely easy to add another faction - without having ANY direct coupling of the player himself and the faction AI.

Example: zoning your game
To save CPU time and get better performance in your game, you divide the world into separate zones/mission regions/trigger areas. When the player enters and exits these areas, a message is send to the "zone information" message queue, saying "player entered/exited zone X". All the NPC AI's in the zone can now go from idle to active, and process input as they have subscribed to this message queue, and been informed of the arrival of a player. While the zone you just left can now be shut down. No need to have the parrots fly around, the NPC guards doing radius checks to see if you are in range or similar if the player is on the other side of the map.

Example: game objectives
You can have a central "game objectives controller" that tracks game events. If your game for example wants you to kill 4 enemies before you win, the controller listens in on the "death queue" and increases a counter. Once counter reaches X, the game is won. This system can be altered in any way needed for game objectives - chained, parallel objectives etc.etc.

Only your imaginations sets the limits for usage of this.

How to add to the engine
Easy to add. The code is not complicated at all.


First of all dump the attached code into your engine\game folder.

Then we need to create a new script callback in the SimObject.

open console/simBase.h and before this

class SimEvent;
class SimObject;

add

struct Message;

then find this

bool isHidden();
   void setHidden(bool b);

and add this after the above

/// Added for Message Router callback method
   void onReceiveMessage(char* queueName, Message message);
   /// End add

Now open simBase.cc. In the top after this

#include "console/consoleInternal.h"
#include "console/typeValidators.h"

include this

#include "game/messageRouter.h"

And all the way in the end of the file add this

void SimObject::onReceiveMessage(char* queueName, Message message)
{
	// If this object has a datablock, then send to that instead of the object itself
	GameBase* gameBaseObj = static_cast<GameBase*>(this);
	if (gameBaseObj) {
		Con::executef(gameBaseObj->getDataBlock(), 6, "onReceiveMessage", gameBaseObj->scriptThis(), queueName, message.mSenderId, message.mMessage, message.mData);
	} else {
		Con::executef(this, 5, "onReceiveMessage", queueName, message.mSenderId, message.mMessage, message.mData);
	}
}

This now means that ALL SimBase objects can override the onReceiveMessage in script. Since not all have datablocks, we have 2 kinds of callbacks. I need the datablock for my game, so thus both are in there.

Compile the engine and thats it.

Script API

In the examples below I have a global variable on the server side holding the MessageRouter object. This might not be what you want.

To create a new Message Router object, you could do the following:
$MessageRouter = new MessageRouter(char* routerName) {};

To create/delete a message queue or to clear/remove all existing subscribers from a queue you use

bool $MessageRouter.createMessageQueue(char* queueName);
bool $MessageRouter.deleteMessageQueue(char* queueName);
bool $MessageRouter.clearMessageQueue(char* queueName);

To subscribe or unsubscribe %simbaseObject from a queue you use

bool $MessageRouter.subscribeMessageQueue(%simbaseObject, char* queueName);
bool $MessageRouter.unsubscribeMessageQueue(%simbaseObject, char* queueName);

where %simbaseObject is your object that you want to subscribe

To send a message you use

bool $MessageRouter.sendMessage(%simbaseObject, char* queueName, char* message, char* data);

where %simbaseObject is the object that sends the message.

Lastly there is a debug function that you can use to see all queues and their subscribers. Simply type

void dumpMessageQueues();

on the console.


Message Trigger
For my own games I've made a special type of generic trigger. What is does is than when a player enters it, a predefined message is sent to all who listen.

The code is here

//-----------------------------------------------------------------------------
// Message Trigger
// Sends a message into the "MessageTriggerQueue" when the player enters
// Takes the values from the "message" and "data" fields defined in the 
// world editor for this trigger and sends it to the "MessageTriggerQueue"
//-----------------------------------------------------------------------------


datablock TriggerData(MessageTrigger)
{
   // The period is value is used to control how often the console
   // onTriggerTick callback is called while there are any objects
   // in the trigger.  The default value is 100 MS.
   tickPeriodMS = 100;
};

function MessageTrigger::onEnterTrigger(%this,%trigger,%obj)
{
   if (isObject(%obj.client.player)) 
   {
	$MessageRouter.sendMessage(%obj, "MessageTriggerQueue", %trigger.message, %trigger.data);
   }
}

Its generally useful for everything. For e.g. applying damage to the player, for triggering sounds - for anything you can use triggers for without having to code game functionality into the triggers themselves.

Where to go from here
The code itself still needs just a little more work to be truly generic usable. Currently the message can only hold 2 fields containing information (the message and the data). This is useful for maybe 90% of the uses you can think of, but it should be expanded to "unlimited" data fields. Its easy to add to the message router if your game needs it.
E.g. in the rocket explodes situation the message should contain 4 fields:
"rocket explosion" text as a type you can filter on
x,y,z coordinates
blast radius
damage count

One can do this with the 2 field and then cut it up using the getWord function, but its not as robust and can be error prone.

Another thing the code lacks is security. You might not want clients to be able to listen in on the messages and/or send messages in a multiplayer game to prevent cheating.

Other than that, its fully usable (I hope) for everyone. Enjoy!