Revision as of 18:00, 2 November 2012 (view source) HE-SCOTT (Talk | contribs) ← Older edit		Revision as of 18:09, 22 May 2013 (view source) HE-ALEX (Talk | contribs) (→Chat Panel Integration: corrected the chat command formatting) Newer edit →
Line 224:		Line 224:
	The Chat System supports slash command input from the HeroBlade Chat Panel. The following slash commands are currently supported.		The Chat System supports slash command input from the HeroBlade Chat Panel. The following slash commands are currently supported.
−	'''<u>/hechatarea&nbsp;</u>'''<u>&lt;text message&gt;</u> Sends a chat message to the area channel for the area in which the player currently resides.	+	'''<u>/hechat area&nbsp;</u>'''<u>&lt;text message&gt;</u> Sends a chat message to the area channel for the area in which the player currently resides.
−	<u>'''/hechatworld '''&lt;text message&gt;</u> Sends a chat message to the world channel, visible to all players in each area of the world.	+	'''<u>/hechat world '''&lt;text message&gt;</u> Sends a chat message to the world channel, visible to all players in each area of the world.
−	<u>'''/hechat''' &lt;unique identifier&gt; &lt;text message&gt;</u> Sends a chat message to the channel with the provided unique identifier.	+	'''<u>/hechat''' &lt;unique identifier&gt; &lt;text message&gt;</u> Sends a chat message to the channel with the provided unique identifier.
−	'''<u>/hechatsubscribe&nbsp;</u>'''<u>&lt;unique identifier&gt; &lt;password (optional)&gt;</u> Subscribes the client to the chat channel with the given unique identifier. If it doesn't yet exist, it will be created.	+	'''<u>/hechat subscribe&nbsp;</u>'''<u>&lt;unique identifier&gt; &lt;password (optional)&gt;</u> Subscribes the client to the chat channel with the given unique identifier. If it doesn't yet exist, it will be created.
−	<u>'''/hechatunsubscribe''' &lt;unique identifier&gt;</u> Unsubscribes the client from the chat channel with the given unique identifier. By default, chat channels are deleted once their last subscriber unsubscribes.	+	'''<u>/hechat unsubscribe''' &lt;unique identifier&gt;</u> Unsubscribes the client from the chat channel with the given unique identifier. By default, chat channels are deleted once their last subscriber unsubscribes.
	New Chat Panel slash commands or the behaviors of the existing one can be implemented by overriding the following method on the $CHAT server system node <hsl>		New Chat Panel slash commands or the behaviors of the existing one can be implemented by overriding the following method on the $CHAT server system node <hsl>
Line 241:		Line 241:
	unique method _ProcessCommand(connection as NodeRef, input as String)		unique method _ProcessCommand(connection as NodeRef, input as String)
	method _isHECommand(command as String) as Boolean		method _isHECommand(command as String) as Boolean
−	</hsl>	+	</hsl>
	== Advanced Usage  ==		== Advanced Usage  ==

---

Revision as of 18:09, 22 May 2013

Contents 1 Issues addressed by the Chat System 2 Features not in the current version 3 Overview 3.1 The Chat System Area 3.2 The Server Play Area 3.3 The Client 3.4 _ChatChannel (Server) 3.5 _ChatChannel (Client) 3.6 _LogicalChatChannel (Client only) 3.7 Subscription and Message Command Objects 4 Usage 4.1 Sending System Commands 4.2 Subscribing 4.3 Unsubscribing 4.4 Sending a Message 5 Using the Base System 5.1 Subscribing 5.2 Sending a Message 5.3 Unsubscribing 5.4 Chat Panel Integration 6 Advanced Usage 6.1 GuildChatChannel 6.2 Unsubscription 6.3 Guild Chat System Commands 7 Important Methods 7.1 _ChatHandler (Server) 7.2 _ChatHandler (Client) 7.3 _ChatChannel (Server) 7.4 _ChatChannel (Client) 7.5 _LogicalChatChannel 7.6 _ChatObjectPool 8 Important Fields 9 Default Configurations

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

Issues addressed by the Chat System

• Provides a framework for building robust chat systems
• Channels run in a dedicated Chat System Area to reduce overhead in the World's Play Areas.
• Distributes load across multiple Chat System Areas to service a large amounts of communication
• Contains working samples with basic messaging functionality
• Provides a method of inter-area communication
• Supports arbitrarily named channels, each with its own unique ID
• Messages, Subscriptions and Unsubscriptions are passed as easily extensible command objects
• By default, channels delete themselves when no longer needed.
• Accepts slash-commands as input through the HeroBlade Chat panel

Features not in the current version

• Custom behaviors for Chat Channels, if desired, must be implemented.
• The current version of the Chat System does not contain its own dedicated GUI.
• The Chat System provides a basic framework for building robust chat functionality. Specific behavior (such as party, guild or combat chat) is left as the responsibility of the developer to implement.

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 Commands 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.

Chat Channels are aggregated by Logical Chat Channels on the client

_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.

Non-broadcast-type command 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.

• _ChatSystemClientCommand (Client) - A command object with fields only applicable to a client.
• _ChatSystemCommand (Server) - A command object with fields and methods necessary for tracking its progress across server areas. 
• _ChatSystemClientCommand (Server) - Once a serialized client command reaches the server, it is deserialized and placed into a ChatSystemClientCommand object on the server. The server script for this command is capable of accepting the reference to a ChatSystemCommand object and setting its fields based on what operation the command needs to perform. 

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 Client Chat System Command through 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. 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 methods on _ChatSystemCommand itself are 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.

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 _ChatChannel object 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 with 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 server 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.

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

/hechat world <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.

/hechat subscribe <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.

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

New Chat Panel slash commands or the behaviors of the existing one can be implemented by overriding the following method on the $CHAT server system node

method _ProcessChatSlashCommandInput(account as NodeRef of Class _PlayerAccount, input as String)

and including the string input as recognizable commands in the following two methods in _CommandHandlerClassMethods (server script).

unique method _ProcessCommand(connection as NodeRef, input as String)
method _isHECommand(command as String) as Boolean

Advanced Usage

This example will illustrate how to extend the chat system to include Guild Channels and Guild-specific system commands. This scenario leverages components of the Social System and will assume 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 on both the client and server. _DebugChatChannel implementes the method

method _GotChatChannelMessageThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )

which is abstract in _ChatChannel. Override this method in GuildChatChannel and implement the logic for accepting message system commands.

_DebugChatChannel on the server is a good example of how to override this method. 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 a Social Anchor field within _GuildChatChannel to determine whether the message sender is allowed to actually send the message. This restriction (as well as others) could be implemented in

method _AllowMessageToBeSentOnChatChannel(chat_system_command as NodeRef of Class _ChatSystemCommand) as Boolean

and called from within the _GotChatChannelMessageThroughChatSystemCommand method before applying the message fields to the channel because doing so will result in immediate replication to all subscribers.

Unsubscription

The behavior to prevent members of guild from unsubscribing to Guild Chat is an understandable restriction. To implement this, override the parent method <hsl>method _UnsubscribeFromChatChannelThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )</hsl> and before removing the subscriber from the channel's replication group, use the same social data to determine whether that client is a member of the guild for this channel. If so, simply ignore the request.

Assuming that Guild chat should be subscribed to when a client logs in, a subscription command can be sent from the following method on the $CHAT server system node

untrusted method _ChatSystemOnPlayerEnteredArea(player_character as ID)

Logically, the subscriber should be unsubscribed when logging off. Within the if(sessionEnd) condition block, send an unsubscription command from the following method on the $CHAT server system node.

untrusted method _ChatSystemOnPlayerExitingArea(player_character as ID, sessionEnd as Boolean)

Guild Chat System Commands

This example demonstrated implementing a new channel and using it from within the Chat System Area to address custom restrictions. Checking whether a given client is a member of the guild to which the channel belongs is possible from within the Subscription and Message commands themselves. This is an alternative and entirely acceptable implementation. It should be noted however that this task would best be performed from within the Chat System Area so the area the player is currently in is not taxed with additional operations which need not be performed there.

To add custom behavior to a chat system command, it will have to be subclassed just as the _DebugChatChannel was in the above example. However, all three commands

• _ChatSystemCommand (server-only)
• _ChatSystemClientCommand (server)
• _ChatSystemClientCommand (client)

Will have to be overridden appropriately to translate the new behavior from the client to the server in an extensible way. _ChatSystemCommandMessageText is a subclass of _ChatSystemCommandMessage which is, in turn, a subclass of _ChatSystemCommand. Likewise, both _ChatSystemClientCommandMessageText classed (server and client) share the same hierarchy with _ChatSystemClientCommandMessage and _ChatSystemClientCommand. Hence,

• _ChatSystemCommandMessageText (server-only)
• _ChatSystemClientCommandMessageText (server)
• _ChatSystemClientCommandMessageText (client)

are already included in the Chat System and a good set of examples on how to extend the base command objects to perform custom and extensible operations across the client and servers.

Important Methods

Methods located on the system nodes (_ChatHandler) 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)

//Interpret slash command input from the Chat Panel
method _ProcessChatSlashCommandInput(account as NodeRef of Class _PlayerAccount, input as String)
 
//details on how to use available slash commands are output to the Chat Panel
method _ProcessChatSlashCommandInputCommandUsage(account as NodeRef of Class _PlayerAccount, input as String)
 
//Receive a _ChatSystemClientCommand from a client, translate it to a _ChatSystemCommand and forward
//it along to the Chat System Area
untrusted method _ReceiveChatSystemClientCommand(serialized_chat_system_client_command as String, client_command_type as String)
 
//Sends a chat system command to the system area instance that handles the current area server's chat traffic
//destroys the command node when it finishes with it.
remote method _SendChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )
 
//Receive a serialized _ChatSystemCommand object within the Chat System Area
//Deserialize and process it
remote method _ReceiveChatSystemCommand( command_type as String, serialized_chat_system_command as String )
 
//Calling _ReceiveChatSystemCommand() has failed on the the initial call to the Designated Instance
//Reassign the designated instance for the play instance which failed
remote method _ReceiveChatSystemCommandFailure(command_type as String, serialized_chat_system_command as String)
 
//Create a single chat channel in this instance
method _CreateChatChannel( chat_system_command as NodeRef of Class _ChatSystemCommand ) as NodeRef of Class _ChatChannel
 
//Remove the chat channel from the channel map in this instance
method _RemoveChatChannelFromRegistration( chat_channel as NodeRef of Class _ChatChannel )
 
//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()
 
//Initialize the Chat System Area when the world is spun up
//And create a World Chat Channel
remote method _ChatSystemOnWorldLoad()
 
//return the unique identifier string field for the area chat channel for this area
method _GetAreaChatChannelUniqueIdentifier() as String
 
//return the unique identifier string field for the world chat channel
method _GetWorldChatChannelUniqueIdentifier() as String
 
//Called when a player is exiting an area
untrusted method _ChatSystemOnPlayerExitingArea(player_character as ID, sessionEnd as Boolean)
 
//Called when a player has entered an area
untrusted method _ChatSystemOnPlayerEnteredArea(player_character as ID)
 
method _ChatSystemOnAreaLoad()
 
//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)
 
//Spin down all the Chat System Area Instances
remote method _SpindownChatSystemArea()
 
//Unregister the Chat System Area for events from the world
remote method _UnregisterForEventsWithWorld()
 
//Called to explicitly shut down the system area even when the it has
//been added to the keep-up list
remote method _UnregisterChatSystemArea(instance_id as ID)
 
//Request a specific Chat System Area Instance for this play area to speak to directly
remote method _RequestChatSystemDesignatedInstance(command_type as String, serialized_chat_system_command as String)
 
//Serialize a _ChatSystemClientCommand object
method _SerializeChatSystemClientCommand(chat_system_client_command as NodeRef of Class _ChatSystemClientCommand) as String
 
//Deserialize a _ChatSystemClientCommand object
method _DeserializeChatSystemClientCommand(serialized_chat_system_client_command as String, chat_system_client_command as NodeRef of Class _ChatSystemClientCommand, fail_silently as Boolean)
 
//Serialize a _ChatSystemCommand object
method _SerializeChatSystemCommand(chat_system_command as NodeRef of Class _ChatSystemCommand) as String
 
//Deserialize a _ChatSystemCommand object
method _DeserializeChatSystemCommand(serialized_chat_system_command as String, chat_system_command as NodeRef of Class _ChatSystemCommand, fail_silently as Boolean)
 
//default starting instance count for the chat system area (not counting the Control Instance)
method _GetDefaultChatSystemAreaInstanceCount() as Integer
 
//maximum starting instance count for the chat system area
method _GetMaximumChatSystemAreaInstanceCount() as Integer
 
//return the noderef of a channel in the current instance
method _GetChatChannel(unique_channel_identifier as String) as NodeRef of Class _ChatChannel
 
// Determine whether a channel exists within the channel map for this instance
method _IsChatChannelUniqueIdentifierRegistered( unique_channel_identifier as String) as Boolean
 
//Add the chat system area to the keepup list
remote method _KeepChatSystemAreaInstanceUp(instance_id as ID)
 
//apply the designation to this instance
remote method _SetChatSystemDesignatedInstance(instance_id as ID)
 
//retrieve the ID of the chat system area instance that has been designated as servicing the current area instance
method _GetChatSystemDesignatedInstance() as ID
 
//return the default spec value for a _DebugChatChannel
method _GetDefaultChatChannelSpecKey() as ID
 
//return the default spec value for a _WorldChatChannel
method _GetWorldChatChannelSpecKey() as ID
 
//return the default spec value for an _AreaChatChannel
method _GetAreaChatChannelSpecKey() as ID
 
//return the chat system area ID
method _GetChatSystemAreaID() as ID
 
remote method _FindChatSystemAreaID(area_id as ID, instance_id as ID)
 
//assign the chat system area id to a field for future reference
remote method _GoToAndSetChatSystemAreaID(area_id as ID, instance_id as ID, chat_system_area_id as ID)
 
//assign the chat system area id to a field on this system node for future reference
method _SetChatSystemAreaID(chat_system_area_id as ID)
 
//determine whether the script is in the chat system area (any instance)
method _InChatSystemArea() as Boolean
 
//check whether in specific instance of the chat system area
method _InChatSystemAreaInstance(instance_id as ID) as Boolean
 
//return the control instance ID
method _GetChatSystemAreaControlInstanceID() as ID
 
//determine whether the script is in the edit/control instance of the chat system area
method _InChatSystemAreaControlInstance() as Boolean
 
//return the apporpriate pool 
method _GetChatSystemCommandPool(chat_system_command_type as String) as NodeRef of Class 
 
//return the apporpriate pool 
method _GetChatSystemClientCommandPool(chat_system_client_command_type as String) as NodeRef of 
 
//return a list of currently running instances in the chat system area
method _GetAllInstancesForChatSystemArea() as List of ID
 
//  Called from C++ when the area has a chat message to interpret.
unique method _AreaGotChat(fromPlayer as ID, message as String, channel as String)
 
//  Called from C++ when the world has a chat message to interpret.
unique method _WorldGotChat(message as String, channel as String)
 
//  Called from C++ when the world has a chat message to interpret.
unique method _WorldGotError(message as String, errorType as Enum _ErrorTypes)
 
// Send a chat message to specified client
method ChatPlayer(toPlayer as ID, channel as String, message as String)
 
// Send a message to players currently loaded in the area
method ChatArea(channel as String, message as String)
 
// Send a message to players loaded in the area and all currently loaded
//   player reference tokens
method ChatAreaAndPlayerReferences( channel as String, message as String )
 
// Send a message to all currently loaded player reference tokens
method ChatPlayerReferences( channel as String, message as String )
 
// Send a message to a list of clients
method ChatList(toPlayers as List of ID, channel as String, message as String)
 
// Send a message to all clients loaded in the current area excluding those in a list
method ChatExcludeList(excludedPlayers as List of ID, channel as String, message as String)
 
// Send a message to all clients logged into the world
remote method ChatWorld(channel as String, message as String)

_ChatHandler (Client)

//Using a timer, delay the call to the server until client is reliably updated to the chat system area
remote method _ChatSystemOnPlayerEnteredArea()
 
//Tick function for the _chatSystemOnPlayerEnteredAreaTimer
function _chatSystemOnPlayerEnteredAreaTimer_tick()
 
//Stop the timer and notify the server the client has entered the area
method _ChatSystemNotifyServerOnPlayerEnteredArea()
 
//Serialize and forward a _ChatSystemClientCommand noderef to the server
method _SendChatSystemCommand( chat_system_client_command as NodeRef of Class _ChatSystemClientCommand)
 
//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( logical_channel_identifier as String) as NodeRef of Class _LogicalChatChannel
 
//List the channels a user is currently subscribed to within the logical channel map
method _GetChatChannelListFromLogicalChatChannel() as List of String
 
//return the apporpriate pool 
method _GetChatSystemClientCommandPool(chat_system_client_command_type as String) as NodeRef of Class _ChatSystemClientCommandPool
 
//Serialize a _ChatSystemClientCommand object
method _SerializeChatSystemClientCommand(chat_system_client_command as NodeRef of Class _ChatSystemClientCommand) as String
 
//Deserialize a _ChatSystemClientCommand object
method _DeserializeChatSystemClientCommand(serialized_chat_system_client_command as String, chat_system_client_command as NodeRef of Class _ChatSystemClientCommand, fail_silently as Boolean)
 
unique method _GotChatMessage(chatMessage as String, channelName as String)
 
//  Puts chatMessage in HeroBlade's chat panel.
unique method _GotChatMessageForHBPanel(chatMessage as String, channelName as String)
 
//  Called from HeroBlade's chat panel when ENTER is pressed.  (Won't be called for blank lines.)
//  The in-game chat GUI can use this or not as desired.
unique method _ProcessChatInput(chatMessage as String)

_ChatChannel (Server)

//Receive a subscription command and add use the data within to add a user to the channel's replication group
method _SubscribeToChatChannelThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )
 
//Remove a user from the replication group of the channel.
method _UnsubscribeFromChatChannelThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )
 
//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
 
//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
 
//Destroy self
method _Delete()
 
//receive a _ChatSystemCommandMessage 
method _GotChatChannelMessageThroughChatSystemCommand( chat_system_command as NodeRef of Class _ChatSystemCommand )
 
//determine whether message sender is allowed to send messages to this channel
method _AllowMessageToBeSentOnChatChannel(chat_system_command as NodeRef of Class 
 
//shared function called when the channel is created
shared function _OnChatChannelCreated( chat_channel as NodeRef of Class _ChatChannel )
 
//shared function called when the channel is destroyed
shared function _OnChatChannelDestroyed( chat_channel as NodeRef of Class _ChatChannel )
 
//shared function called when a user subscribes to the channel
shared function _OnSubscribedToChatChannel( chat_channel as NodeRef of Class _ChatChannel, chat_system_command as NodeRef of Class _ChatSystemCommand)
 
//shared function called when a user unsubscribes from the channel
shared function _OnUnsubscribedFromChatChannel( chat_channel as NodeRef of Class _ChatChannel, chat_system_command as NodeRef of Class _ChatSystemCommand )
 
//shared function called when a user sends a message to the channel
shared function _OnReceivedChatMessage( chat_channel as NodeRef of Class _ChatChannel, chat_system_command as NodeRef of Class _ChatSystemCommand)

_ChatChannel (Client)

// As each node is added by replication, a callback is made to the primary node notifying it that a new node
// has arrived with its initial set data.
method _OnReplicationNodeAdded(addedNode as NodeRef)
 
//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
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 replicaiton events 
method _OnReplicationNodeRelease(releasedNode as NodeRef) as Boolean
 
// Only important there are fields that are reference frame adjusted for seamless world as a part of this class, which there are not
method _OnReplicationGroupRehomed(oldArea as ID, oldInstance as ID, oldOffset as Vector3, 
 
//SpecOracle method
method getMySpecOracle() as NodeRef of Class SpecOracle
 
//Receives the corresponding _ChatChannel spec from the server and subscribes
//the channel to the appropriate logical channel based on the logicalChannelIdentifier
//field within the spec
method EventRaised( obs as NodeRef of Class ObsSubject, data as NodeRef )

_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 _ChatSystemClientCommandMessage )
 
//Set the display name field for the logical channel
method _SetChatChannelDisplayName(display_name as String)
 
//Destroy self
method _Delete()
 
//event signature define
method _GotChatChannelSubscription(chat_channel as NodeRef)
 
//event signature define
method _GotChatChannelUnsubscription(chat_channel as NodeRef)

_ChatObjectPool

//Allocate n _ChatPoolObjects and put them in the pool
method _CreateChatPoolObjects(object_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 _GetDefaultChatObjectPoolSize() as Integer
 
//Return the number of allocated objects in this pool
method _GetChatObjectCount() as Integer
 
//set the pool object type
//the object type must be set before any objects can be created within the pool
method _SetChatObjectType(object_type as String)
 
//return the maximum size the pool can achieve at any given time
method _GetMaximumChatObjectPoolSize() as Integer
 
//return the maximum number of objects which can be created by this pool
method _GetChatObjectCreationLimit() 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 individual channels with which they are associated.

_chatChannelSubscriberID - ID
 
_chatChannelUnsubscriberID - ID
 
_chatChannelMessageSenderID - ID

The GUID of the user or node making the request. These are necessary for callbacks to the subscriber from the chat channels receiving the request and to later acquire more information about that subscriber.

_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.

_chatSystemCommandPool - NodeRef of Class _ChatSystemCommandPool
 
_chatSystemClientCommandPool - NodeRef of Class _ChatSystemClientCommandPool

Pool fields stored on the Chat System Nodes, referenced so that pools do not have to be created every time _chatPoolObjects are needed.

 _chatSystemCommandPoolMap - LookupList indexed by String of NodeRef of Class _ChatSystemCommandPool
 
_chatSystemClientCommandPoolMap - LookupList indexed by String of NodeRef of Class _ChatSystemClientCommandPool

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. 

• Privacy policy
• About HEWIKI
• Disclaimers

• Copyright (c) 2006-2013 Idea Fabrik Plc. All Rights Reserved.
• HeroCloud is a registered trademark of IdeaFabrik Plc, all rights reserved
• HeroEngine is a registered trademark of IdeaFabrik Plc, all rights reserved

•