Chat System

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(Using the Base System)
(Using the Base System)
Line 218: Line 218:
  
 
After unsubscribing from a channel, that channels noderefs should no longer exist on the client. Perform another query node in the CLI to verify this.
 
After unsubscribing from a channel, that channels noderefs should no longer exist on the client. Perform another query node in the CLI to verify this.
 +
 +
==== Chat Panel Integration ====
 +
The Chat System supports slash command input from the HeroBlade Chat Panel. The following slash commands are currently supported.
 +
 +
/hechatarea <text message>
 +
Sends a chat message to the area channel for the area in which the player currently resides.
 +
 +
/hechatworld <text message>
 +
Sends a chat message to the world channel, visible to all players in each area of the world.
 +
 +
/hechat <unique identifier> <text message>
 +
Sends a chat message to the channel with the provided unique identifier.
 +
 +
/hechatsubscribe <unique identifier> <password (optional)>
 +
Subscribes the client to the chat channel with the given unique identifier. If it doesn't yet exist, it will be created.
 +
 +
/hechatunsubscribe <unique identifier>
 +
Unsubscribes the client from the chat channel with the given unique identifier. By default, chat channels are deleted once the last subscriber unsubscribes.
  
 
== Advanced Usage  ==
 
== Advanced Usage  ==

Revision as of 17:55, 2 August 2011

He intermediate.png

This page documents an upcoming feature and is not currently deployed to any customer world. Features are subject to final review.

The HeroEngine Chat System is a framework for passing messages between clients and across server areas.

Contents

Issues addressed by the Chat System


Features not in the current version

Overview

The Chat System delegates the majority of its processes to the Chat System Area: a System Area with a customizable number of instances. Each instance can house an arbitrary number of chat channels. Channels may be subscribed to by users. All messages accepted by the channels are subsequently replicated to their subscribers.

The Chat System Area

The Chat System Area is composed of n-1 Instances and one EDIT Instance, referred to as the "Control Instance". The Control Instance is responsible for registration and initialization of the Chat System and spinning-up of Chat System Instances at world-load time. It also catches requests that fail if one of the Chat System Instances is unexpectedly found down.

When a channel is "created" within the Chat System, a channel object with the same unique identifier is instantiated from a spec within each Chat System Instance. Assume Each instance houses x _ChatChannel objects. If there are n Chat System Area instances (including the Control Instance), then there will be x*n total _ChatChannel objects in the System Area.

This is done so that requests can go to any of the Chat System Instances and traffic does not congregate onto one instance.

Every Play Area Instance should communicate with only one Chat System Instance. Within the Chat System Node in every Play Area Instance in the world, there is a field called "_designatedChatInstance" of type ID. This field corresponds to the Chat System Area Instance that Play Area Instance should communicate with. As New Play Instances are spun up, one of the existing Chat System Instances will be designated to them. This behavior is not dynamic; the Chat System Area will not automatically spin up new System Instances as traffic increases. The relationship between Chat System Instances and Play Area Instances is one-to-many.


High level overview of the Chat System Area architecture.


The Server Play Area

The area in which the client's player character is currently residing is considered the Play Area. Communication from the client to the server must always go through this area before proceeding to the Chat System Area. When a client subscribes to or unsubscribes from a channel, that request is broadcast to the same channel in each instance. The request first goes to the Chat System Area Designated Instance for that Server Play Area and then disperses to all other Chat System Instances. This reduces the amount of remote calls made from the Server Play Area.



Subscription requests are broadcast from the Designated Instance.

The Client

Clients may send requests which include but are not limited to subscribing to, unsubscribing from or send a messages to a given channel. All GUI-related operations are also handled exclusively on the client. Since there are n copies of each channel replicating to the client, _LogicalChatChannel objects are used to aggregate their respective Chat Channels.


_ChatChannel (Server)

_ChatChannel objects exist within the Chat System Area instances in order to handle incoming messages from all potential subscribers. They dictate who can and cannot subscribe through a simple password field, but more advanced restrictions can be implemented by creating subclasses of _ChatChannel.

_DebugChatChannel is a sample child of _ChatChannel with basic string messaging functionality. When a user subscribes to a _ChatChannel object, that user is added to the replication group of that object and every other _ChatChannel object with the same _chatChannelUniqueIdentifier field. Therefore, whenever anyone sends a message to a _ChatChannel object, the message is replicated down to all clients within its replication group.

_ChatChannel (Client)

_ChatChannel nodes are replicated to the client and aggregated with a _LogicalChatChannel node. Recall that for each channel which is visible to the user, n copies of that channel exist in the Chat System Area Instances, one for each instance.


Request traffic traveling to a specific channel

_LogicalChatChannel (Client only)

Since _ChatChannel nodes with the same _chatChannelUniqueIdentifier exist across all spun-up Chat System Area Instances, it's helpful to have all their replicated events aggregated into one object. The purpose of the _LogicalChatChannel is to allow client listeners to refer to this one object for replicated messages and events across any number of _ChatChannels which could exist on the server.

The _LogicalChatChannel node will associates itself with all replicated channels with the same _chatChannelUniqueIdentifier. In this way, all traffic from these channels are collected into one place for reference by any listeners.

_LogicalChatChannel objects inherit from ObsSubject allowing other systems to listen to them for events. Any listeners may use ObsListener as a parent and implement method calls _LogicalChatChannel generates for its events such as

method _SubscribeToChatChannel( chat_channel as NodeRef )
 
method _UnsubscribeFromChatChannel( chat_channel as NodeRef )
 
method _GotChatChannelMessage( chat_message as NodeRef of Class _ChatMessage )


Channel information and messages replicating to the client

Subscription and Message Command Objects

ChatSystemCommand objects are used to carry information from the client to and across server areas. There are three kinds of ChatSystemCommand objects.

To create a new custom client command, subclasses of these three objects should be implemented. For new server-only commands, a subclass of ChatSystemCommand (server) is all that needs to be implemented.

The Chat System abstracts requests between the client and channels located on the server. Since requests are passed between servers and clients, remote methods on the system nodes accept marshaled command objects as parameters.

Sending a command from a client to the server requires the use of these three separate objects. In the case of a subscription, a _ChatSystemClientCommandSubscription object would have to be created or allocated on the client, have its fields set and sent to the Client Chat System Node. The Server Chat System Node will receive the serialized _ChatSystemClientCommandSubscription and deserialize that into a server version of the class _ChatSystemClientCommandSubscription which has the ability to transfer the values in it's fields to a _ChatSystemCommandSubscription object reference passed to it. 

All Chat System Command classes provided derive from _ChatPoolItem, following the object pool design pattern. This was done to reduce the memory footprint of creating a new object every time a request is made.

The $CHAT system node on the server contains pool maps for _ChatSystemCommand and _ChatSystemClientCommand pool objects so that Command pools can be stored on the server system node. The $CHAT system node on the client has a single pool map for _ChatSystemClientCommand pool objects.

Usage

Sending System Commands

To subscribe to a channel, the user sends a remote call from the client-side $CHAT system node. Client Chat System Commands can contain any set of instructions. They simply need to be inherited from _ChatSystemClientCommand. The method for sending a basic client command from the $CHAT system node on the client is

method _SendChatSystemCommand( chat_system_client_command as NodeRef of Class _ChatSystemClientCommand)

The Play Area accommodating that client's character receives the request on the server-side $CHAT system node. The server class for this node is _ChatHandler. The receiving method for this request is

untrusted method _ReceiveChatSystemClientCommand(serialized_chat_system_client_command as String, client_command_type as String)

Recall the purpose of server-side _ChatSystemClientCommand objects is to store and transfer information from client-side _ChatSystemClientCommand objects into _ChatSystemCommand objects. Therefore, this method first deserializes the _ChatSystemClientCommand into its server counterpart object. It then tasks the server-side _ChatSystemClientCommand with transferring its values to a _ChatSystemCommand (server-only) object.

Once the _ChatSystemCommand has been created and populated with values from the client command, it is passed to another method in charge of setting server-only values so that the command can be routed correctly across the Chat System Area.

remote method _SendChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )

The Chat System Command is then serialized and sent to the $CHAT system node in the Chat System Area. The method which receives the serialized object is

remote method _ReceiveChatSystemCommand( command_type as String, serialized_chat_system_command as String )
This method deserializes the string into an object again allocated from a pool. If the command is a broadcast-type command, this method will call itself in the remaining Chat System Instances, forwarding those instances copies of the serialized command.

By design, each instance holds a _ChatChannel object for every channel with the same _chatChannelUniqueIdentifier. Hence, subscriptions and Unsubscriptions are broadcast-type commands. Because each subscriber is subscribed to all copies of a channel, messages need not be broadcast to all copies of a channel. Therefore messages are not broadcast-type commands. Your custom commands may or may not be broadcast commands. The intended use will dictate which type they will be.

Finally, this method calls a method on the chat system command object itself.

method _ProcessChatSystemCommand()

Each Chat System Command is implemented to perform its own custom set of instructions. The method on _ChatSystemCommand itself is abstract and must be overridden. _ChatSystemCommandSubscribe, _ChatSystemCommandUnsubscribe and _ChatSystemCommandMessage all inherit from _ChatSystemCommand.

Subscribing

The _ChatSystemCommandSubscribe command implements the method _ProcessChatSystemCommand() with the following behavior. It attempts to get the _ChatChannel with the corresponding unique identifier in its own fields. If that channel does not yet exist, it is created. The command then sends itself to the channel through the method

method _SubscribeToChatChannelThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )

Where the subscription sender is added to the replication group of the channel and decorators to that channel are notified.


After a channel approves a subscription request from the play area, it will notify the client and the channel will replicate its information to all subscribers. When all initial set fields in the channel have replicated to the client for the first time,

method _OnReplicationGroupAdded()
is called on the client _ChatChannel class. This method requests the spec from the server so more information can be accessed later.

_logicalChatChannelIdentifier fields are located on each channel's spec. The Logical Chat Channel Identifier is what is used to determine which replicated channel arriving on the client should be associated with which Logical Chat Channels. The _AreaChatChannelSpec has a _logicalChatChannelIdentifier value of "area". Hence all channels replicated to the client iwth that field value will be associated with the same Logical Chat Channel with a _logicalChatChannelIdentifier of "area". Chat Channels are associated to corresponding Logical Chat Channels through a logical_chat_channel_association.

The Logical Chat Channel generates events so that listeners such as a GUI can respond to incoming communication by registering as a listener and implementing the same method signatures. The events in the base _LogicalChatChannel class are

method _SubscribeToChatChannel( chat_channel as NodeRef )
 
method _UnsubscribeFromChatChannel( chat_channel as NodeRef )
 
method  _GotChatChannelMessage( chat_message as NodeRef of Class _ChatMessage )
Subscribers will receive all future communication until that subscriber disconnects or unsubscribes.

Unsubscribing

Unsubscription requests are handled nearly identically to subscription requests. Practically, there are few reasons to deny a subscriber from purposefully unsubscribing from a channel. Ergo, the unsubscription routine follows the same steps, usually without as many checks to credentials on the _ChatChannel level. All that is required to send an unsubcription request is to create or allocate a _ChatSystemCommandUnsubscribe object, populate it with the appropriate fields and pass it to

//From Chat_Handler (client)
method _SendChatSystemCommand( chat_system_client_command as NodeRef of Class _ChatSystemClientCommand)

Where the command will follow the same routine as the subscription scenario above apart from ultimately removing the client from the replication group of the _ChatChannel objects in the Chat System Area.

Sending a Message

Likewise, _ChatSystemMessageCommandText is a child of _ChatSystemCommandMessage and follows the same routine as the previous two commands. Apart from containing a slightly different set of fields (which includes a message string), the text message command is not a broadcast-type command, meaning it does not propagate to all other Chat System instances upon arriving at the designated instance for its originating area.

When passed to a chat channel, a text message command's fields will be applied to that channel. Detecting a change in their values, the channel will replicate its fields to all subscribing clients. Since all clients subscribe to each occurrence of a given channel across each instance in the Chat System Area, messages need to be sent to only one channel.

Using the Base System

The following calls should be made from a client script.

Subscribing

To request a subscription to a channel, execute the following calls in your client script.

subscribe_command_pool as NodeRef of Class _ChatSystemCommandPool = $CHAT._GetChatSystemCommandPool( "_ChatSystemCommandSubscribe" )
subscribe_command as NodeRef of Class _ChatSystemCommandSubscribe = subscribe_command_pool._GetChatPoolObject()
subscribe_command._chatChannelSpecKey = $CHAT._GetDefaultChatChannelSpecKey()
subscribe_command._chatChannelSubscriberID = SYSTEM.INFO.PLAYERCHARACTER
subscribe_command._chatChannelUniqueIdentifier = "test_channel_123"
subscribe_command._chatChannelSubscriptionPassword = ""      
$CHAT._SendChatSystemCommand( subscribe_command )

If the channel does not exist prior to the subscription request, the _chatChannelPassword field on the _ChatChannel is set as the password in the subscription request.

n _ChatChannel objects should now be replicated to your client (one for each Chat System Instance). Perform a query node command for _ChatChannel objects on the client to see them.

Upon entering an area, each player is automatically subscribed to world and area chat channels.

Sending a Message

This example will send a message to the channel with the same unique_identifier that was specified in the subscription calls above. Execute the following code in your client script to do so.

message_command_pool as NodeRef of Class _ChatSystemCommandPool = $CHAT._GetChatSystemCommandPool( "_ChatSystemCommandMessageText" )
message_command as NodeRef of Class _ChatSystemCommandMessageText = message_command_pool._GetChatPoolObject()
message_command._chatChannelMessage = "Bow ties are cool." 
message_command._chatChannelMessageSenderID = SYSTEM.INFO.PLAYERCHARACTER
message_command._chatChannelUniqueIdentifier = "test_channel_123"
$CHAT._SendChatSystemCommand( message_command )

Once the message is received by the _ChatChannel object in the system area, its fields will be set and replicated to the client. One of the _ChatChannel nodes on the client should have "Bow ties are cool." as its _chatChannelMessage field value. Perform a show node command on the CLI to view the fields of the _ChatChannel nodes individually and verify this.

Unsubscribing

To unsubscribe and remove yourself from the replication group of a _ChatChannel, make the following calls from your client script.

unsubscribe_command_pool as NodeRef of Class _ChatSystemCommandPool = $CHAT._GetChatSystemCommandPool( "_ChatSystemCommandUnsubscribe" )
unsubscribe_command as NodeRef of Class _ChatSystemCommandUnsubscribe = unsubscribe_command_pool._GetChatPoolObject()
unsubscribe_command._chatChannelUnsubscriberID = SYSTEM.INFO.PLAYERCHARACTER
unsubscribe_command._chatChannelUniqueIdentifier = "test_channel_123"
$CHAT._SendChatSystemCommand( unsubscribe_command )

After unsubscribing from a channel, that channels noderefs should no longer exist on the client. Perform another query node in the CLI to verify this.

Chat Panel Integration

The Chat System supports slash command input from the HeroBlade Chat Panel. The following slash commands are currently supported.

/hechatarea <text message> Sends a chat message to the area channel for the area in which the player currently resides.

/hechatworld <text message> Sends a chat message to the world channel, visible to all players in each area of the world.

/hechat <unique identifier> <text message> Sends a chat message to the channel with the provided unique identifier.

/hechatsubscribe <unique identifier> <password (optional)> Subscribes the client to the chat channel with the given unique identifier. If it doesn't yet exist, it will be created.

/hechatunsubscribe <unique identifier> Unsubscribes the client from the chat channel with the given unique identifier. By default, chat channels are deleted once the last subscriber unsubscribes.

Advanced Usage

Almost every Massive Multiplayer game has some kind of guild system. A Guild Chat System can be developed by extending the existing structure of the Chat System. This example leverages components of the Social System. This example assumes there is a guild which currently exists as a  _SocialCircle associated with a _SocialAnchor.

GuildChatChannel

Create and configure new child classes of _DebugChatChannelSpec and _DebugChatChannel; call them _GuildChatChannelSpec and _GuildChatChannel. _DebugChatChannel implementes the method

method _GotChatChannelMessage(chat_message as NodeRef of Class _DebugChatMessage)
which accepts a _DebugChatMessage object. After verifying whether the sender of the object is a subscriber, it applies the information located within that message to the channel itself. The information is then replicated to all subscribers. If communication within Guild Chat Channels is to be restricted to guild members, an additional check should be performed against the Social Anchor field within _GuildChatChannel to determine whether the message sender is allowed to actually send the message. This behavior should be implemented in
method _AllowMessageToBeSentOnChatChannel(sender_id as ID) as Boolean
and called from within _GotChannelMessage() before applying the message fields to the channel.

As there is no particular need to implement special logic to unsubscribe from a _DebugChatChannel, the unsubscription method was not overridden when creating _DebugChatChannel. The only other method which was overridden was

method _SubscribeToChatChannel(chat_channel_subscription as NodeRef of Class _ChatChannelSubscription)

Which compares the password of the subscription object against the channel password, adds the subscriber to the replication group and sends a confirmation message to that subscriber.

method _UnsubscribeFromChatChannel(chat_channel_unsubscription as NodeRef of Class _ChatChannelUnsubscription)

Can be implemented to prevent those within the guild from unsubscribing from the guild chat. This can be done by verifying the user is a member through the Social Anchor field in the GuildChatChannel.

_ChatChannelSubscription, _ChatChannelUnsubscription and _ChatMessage all inherit from _ChatPoolObject, allowing them to be allocated via the object pool pattern. This is preferable to creating a new object every time one is needed.

<span class="Apple-style-span" style="font-size: 20px; font-weight: normal; " />These three objects mainly serve as containers, but can be tasked with responding to their requests. Respectfully: 

method _NotifyClientOfSubscriptionResult(success as Boolean, message as String)
 
method _NotifyClientOfUnsubscriptionResult(success as Boolean, message as String)<br>method _NotifyClientOfMessageResult(success as Boolean, message as String)

These methods can each be overridden in order to send a reply message to the subcriber, notifying that user of the result of the request.


Important Methods

Many of the following methods all have HE_Overrides, allowing override of their default behaviors by writing new methods with the signatures "HE_<method signature>".

method _GetDefaultChatSystemAreaInstanceCount() as Integer
can be overridden as
method HE_GetDefaultChatSystemAreaInstanceCount() as Integer
and implemented to return 5 instead of the default value of 3.

_ChatHandler (Server)

//Checked when the world spins up to determine whether to initialize the Chat System
method _IsChatSystemEnabled() as Boolean
 
//Request that the world spin up the Chat System Edit instance 
//(the Control Instance)
remote method _SpinupChatSystemArea()
 
//Spin down all the Chat System Area Instances
remote method _SpindownChatSystemArea()
 
//Initialize the Chat System Area when the world is spun up
remote method _ChatSystemOnWorldLoad()
 
//Distribute the current system node id to all areas which existed before the 
//Chat System Area was spun up
remote method _UpdateChatSystemNodeAcrossAllAreas(chat_system_area_id as ID)
 
//Initialize the Chat System, register it for events with the world,
//add it to the keepup list and change its spindown spec
//spin up n Chat System Instances
remote method _RegisterChatSystemArea()
 
//Request the refresh of Chat System Area data for newly spun-up instances
remote method _UpdateChatSystemAreaInstance(instance_id as ID)
 
//Unregister the Chat System Area for events from the world
remote method _UnregisterForEventsWithWorld()
 
//Called before a Chat System Area instance is shut down
remote method _UnregisterChatSystemArea(instance_id as ID)
 
//Called to explicitly shut down the system area even when the it has
//been added to the keep-up list
remote method _ForceUnregisterChatSystemArea(instance_id as ID)
 
//Go to this Play Areas designated Chat System Instance and request to create a new 
//channel in all system instances
remote method _BroadcastCreateChatChannel(spec_key as ID, unique_channel_identifier as String, channel_display_name as String)
 
//Create a single channel on a given instance
remote method _CreateChatChannelInInstance(instance_id as ID, spec_key as ID, unique_channel_identifier as String, channel_display_name as String)
 
//Destroy all occurances of a channel in all system instances
remote method _DestroyChatChannels(channel_id as String)
 
//Destroy a single channel and remove it from the channelmap located in the instance
remote method _DestroyChatChannel(channel_id as String)
 
//The entry point on the server for sending different kinds of message objects from the client
untrusted method _RequestSendChatChannelMessage(unique_channel_identifier as String, serialized_chat_message as String, message_type as String)
 
//Set the message field of a single channel (in a single instance)
remote method _SendChatChannelMessage(unique_channel_identifier as String, serialized_chat_message as String, message_type as String)
 
//Catch a failed send message request. Send the request to the control instance, process it 
//and reassign the designated instance for the play instance which failed
remote method _SendChatChannelMessageFailure(unique_channel_identifier as String, serialized_chat_message as String, message_type as String)
 
//The entry point on the server for sending different kinds of subscription objects from the client
untrusted method _RequestSubscribeUserIDToChannels(serialized_chat_channel_subscription as String, subscription_type as String)  
 
//Subscribe a user by ID to all channels with the same channel unique identifier
remote method _SubscribeUserIDToChannels(subscription_type as String, serialized_chat_channel_subscription as String)
 
//Reassign the designated instance for the play instance which failed to contact the
//system instance and reroute the request through the control instance
remote method _SubscribeUserIDToChannelsFailure(subscription_type as String, serialized_chat_channel_subscription as String)
 
//Subscribe a user by GUID to a single channel
remote method _SubscribeUserIDToChannel(instance_id as ID, serialized_chat_channel_subscription as String, subscription_type as String)
 
//Reassign the designated instance for the play instance which failed
remote method _SubscribeUserIDToChannelFailure(instance_id as ID, serialized_chat_channel_subscription as String, subscription_type as String)
 
//The entry point on the server for sending different kinds of unsubscription objects from the client
untrusted method _RequestUnsubscribeUserIDFromChannels(serialized_chat_channel_unsubscription as String, unsubscription_type as String)  
 
//Unsubscribe a user by ID to all channels with the same unique identifier
remote method _UnsubscribeUserIDFromChannels(unsubscription_type as String, serialized_chat_channel_unsubscription as String)
 
//Reassign the designated instance for the play instance which failed to contact the 
//system instance and reroute the request through the control instance
remote method _UnsubscribeUserIDFromChannelsFailure(unsubscription_type as String, serialized_chat_channel_unsubscription as String)
 
//Unsubscribe a user by GUID from a single channel
remote method _UnsubscribeUserIDFromChannel(instance_id as ID, serialized_chat_channel_unsubscription as String, unsubscription_type as String)
 
//Reassign the designated instance for the play instance which failed
remote method _UnsubscribeUserIDFromChannelFailure(instance_id as ID, serialized_chat_channel_unsubscription as String, unsubscription_type as String)
 
//Request a specific Chat System Area Instance for this play area to speak to directly
remote method _RequestInstanceDesignation()

_ChatHandler (Client)

//Return a noderef pointing to the logical chat channel requested via its _chatChannelUniqueIdentifier field.
//Create it if the requested Logical Channel doesn't exist
method _GetLogicalChatChannel(unique_channel_identifier as String) as NodeRef of Class _LogicalChatChannel 
 
//Add (associate) a channel to a logical chat channel.
//Individual channels can be queried through the logical channel.
method _AddChannelToLogicalChannel(channel as NodeRef of Class _ChatChannel) as NodeRef of Class _LogicalChatChannel 
 
//Remove (disassociate) a channel from a logical chat channel
method _RemoveChannelFromLogicalChannel(channel as NodeRef of Class _ChatChannel)
 
//Destroy a Logical Chat Channel
method _DestroyLogicalChannel(unique_channel_identifier as String) 
 
//Add a listener to a Logical Chat Channel
remote method _ListenToLogicalChannel(unique_channel_identifier as String, observer as NodeRef)
 
//Delete all listeners observing a logical channel
method _DestroyListeners(unique_channel_identifier as String)
 
//Make a request to subscribe to all channels with the same given _chatChannelUniqueIdentifier
method _RequestChatChannelSubscription(unique_channel_identifier as String, display_name as String, chat_channel_password as String, subscription_type as String) 
 
//Make a request to unsubscribe from all channels with the same given _chatChannelUniqueIdentifier
method _RequestChatChannelUnsubscription(unique_channel_identifier as String, unsubscription_type as String)
 
//Make a request to send a message to a channel with the given _chatChannelUniqueIdentifier
remote method _SendDebugChatChannelMessage(unique_channel_identifier as String, message as String, message_type as String) 
 
//Instantiate n _ChatMessage objects and index them within a pool
method _AddPoolToChatMessagePoolMap(what_type as String, how_many as Integer) 
 
//Return the appropriate pool based on the message type
method _GetChatMessagePool(chat_message_type as String) as NodeRef of Class _ChatMessagePool
 
//Instantiate n _ChatChannelSubscription objects and index them within a pool
method _AddPoolToChatChannelSubscriptionPoolMap(what_type as String, how_many as Integer)
 
//Return the appropriate pool based on the subscription type
method _GetChatChannelSubscriptionPool(chat_channel_subscription_type as String) as NodeRef of Class _ChatChannelSubscriptionPool
 
//Instantiate n _ChatChannelUnsubscription objects and index them within a pool
method _AddPoolToChatChannelUnsubscriptionPoolMap(what_type as String, how_many as Integer)
 
//Return the appropriate pool based on the unsubscription type
method _GetChatChannelUnsubscriptionPool(chat_channel_unsubscription_type as String) as NodeRef of Class _ChatChannelUnsubscriptionPool
 
//Receive a string from the server with the subscription of the 
//channel corresponding to the previously sent subscription request
//use this to confirm subscription and notify the desired listener
remote method _ReceiveChatChannelSubscription(serialized_subscription as String, subscription_type as String)

_ChatChannel (Server)

//Initialize fields and set up the replication group
method _InitChatChannel(unique_channel_identifier as String, channel_display_name as String)
 
//Compare the subscription object password to the password field of the channel
method _ValidateChatChannelPassword(subscription_password as String) as Boolean
 
//Add a user to the replication group of the channel.
method _SubscribeToChatChannel(chat_channel_subscription as NodeRef of Class _ChatChannelSubscription)
 
//Remove a user from the replication group of the channel.
method _UnsubscribeFromChatChannel(chat_channel_unsubscription as NodeRef of Class _ChatChannelUnsubscription)
 
//return the replication group for this channel
// Parameters:
//   create - create the replication group if it does not yet exist?
method _getReplicationGroup(create as Boolean) as NodeRef of Class _ReplicationGroup
 
//Event triggered prior to applying the received message to the channel
method _GotChatChannelMessage(chat_message as NodeRef of Class _ChatMessage)
 
//Determine whether message sender id is in the replication group
method _AllowMessageToBeSentOnChatChannel(sender_id as ID) as Boolean 
 
//Event method
shared function _OnChatChannelCreated(chat_channel_unique_identifier as String, chat_channel_subscription_password as String)
 
//Event method
shared function _OnChatChannelDestroyed(chat_channel_unique_identifier as String)
 
//Event method
shared function _OnSubscribedToChatChannel(chat_channel_unique_identifier as String, user_id as ID)
 
//Event method
shared function _OnUnsubscribedFromChatChannel(chat_channel as NodeRef of Class _ChatChannel)
 
//Event method
shared function _OnReceivedChatMessage(chat_channel_unique_identifier as String, chat_message as NodeRef of Class _ChatMessage)

_ChatChannel (Client)

//Called when all of the nodes that are part of the replication group have been added.  At this point, all nodes are present
//with those of their fields marked "Initial Set" set to the replicated values
//Find the logical channel for this channel and associate the two
method _OnReplicationGroupAdded()  
 
//Return a noderef to the _LogicalChatChannel associated with this _ChatChannel
method _GetMyLogicalChatChannel() as NodeRef of Class _LogicalChatChannel
 
// Called when fields whose Client Callback propery was set to YES are updated
shared function _OnReplicationFieldUpdated(update_node as NodeRef, update_field as String)
 
//Tell the logical channel to unsubscribe itself from this channels replication events
method _OnReplicationNodeRelease(releasedNode as NodeRef) as Boolean

_LogicalChatChannel

//Notify listeners of a subscribed event
method _SubscribeToChatChannel( chat_channel as NodeRef )
 
//Notify listeners of an unsubscribed event
method _UnsubscribeFromChatChannel( chat_channel as NodeRef )
 
//Notify listeners of a got-message event
method  _GotChatChannelMessage( chat_message as NodeRef of Class _ChatMessage )
 
//Set the display name field for the logical channel
method _SetChatChannelDisplayName(display_name as String)
 
//Destroy self
method _Delete()

_ChatObjectPool

//Allocate n _ChatPoolObjects and put them in the pool
method _CreateChatPoolObjects(item_type as String, how_many as Integer)
 
//Add an object to the back of the pool
method _PutChatPoolObject(chat_object as NodeRef of Class _ChatPoolObject) 
 
// Return a _ChatPoolObject and remove it from the pool
method _GetChatPoolObject() as NodeRef of Class _ChatPoolObject
 
//Return the starting pool size
method _GetDefaultPoolSize() as Integer
 
//Return the number of allocated objects in this pool
method _GetChatObjectCount() as Integer

Important Fields

_chatChannelUniqueIdentifier - String
Almost every structure in the Chat System has this field. It is the string value which represents the identification of a specific channel. Message noderefs use it as a destination, Subscriptions use it as a search parameter, Logical Channels use it to identify with which replicated channels to associate themselves.

_possibleChatChannelUniqueIdentifier - String
This is a multipurpose contingency unique channel identifier. When attempting to subscribe to a channel, if the channel does not exist, the _possibleChatChannelUniqueIdentifier (a system generated identifier) is used rather than the user-specified _chatChannelUniqueIdentifier. This prevents users from choosing redundant unique identifiers for their chat channels.

_chatChannelSubscriberID - ID
 
_chatChannelUnsubscriberID - ID
 
_chatChannelMessageSenderID - ID
The GUID of the user or node making the request. This is necessary for callbacks to the subscriber from the chat channels receiving the request.

_chatChannelSubscriptionPassword - String
A string password field in the base _ChatChannel class.

_chatChannelSubscriberCount - Integer
An integer counter used to keep track of how many subscribers are currently in a channel. If the subscriber count is zero and someone is attempting to subscribe to it, the channel has just been created. This is how the channel knows when to set its password field.

_chatChannelMessageID - Integer
A counter used in an Atomic Set on the _DebugChatChannel in order to ensure that even duplicate messages are replicated to all subscribers.

_chatChannelDisplayName - String
The string name of a channel which will be visible to users through a GUI.

_chatChannelMap - Lookuplist indexed by String of ID
A LookupList for all Chat Channels in a given Chat System Instance. This is used to find a channel, if it exists. A channel is added to the LookupList, when it is created and removed when it is destroyed.

_chatChannelSubscriptionPool - NodeRef of Class _ChatChannelSubscriptionPool
 
_chatChannelUnsubscriptionPool - NodeRef of Class _ChatChannelUnsubscriptionPool
 
_chatMessagePool - NodeRef of Class _ChatMessagePool
Pool fields stored on the channels, referenced so that pools do not have to be created every time _chatPoolObjects are needed.

_chatSubscriptionPoolMap - LookupList indexed by String of NodeRef of Class _ChatChannelSubscriptionPool
 
_chatUnsubscriptionPoolMap - LookupList indexed by String of NodeRef of Class _ChatChannelUnsubscriptionPool
 
_chatMessagePoolMap - LookupList indexed by String of NodeRef of Class _ChatMessagePool
Since various types of requests may pass through the system nodes(e.g. _DebugChatMessages and GuildChatMessages), LookupLists of pools are maintained as fields in the system nodes and referenced whenever a specific _ChatPoolItem is required.

Default Configurations

method _GetDefaultChatSystemAreaInstanceCount() as Integer
Will return the number of Chat System Area Instances spun up at world-load time.

method _GetMaximumChatSystemAreaInstanceCount() as Integer
Will return the maximum number of Chat System Area Instances which can be spun up at any given time.

method _GetDefaultPoolSize() as Integer
Will return the default pool size for a _ChatObjectPool. This is set to 4 by default. 
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox