Event Table

A complete listing of Coronium ChatterBox events:

Event Name	Description	Scope
OnConnect	The client has connected to the server.	client
OnJoined	A client has joined the current room.	room
OnLeft	A client has left the current room.	room
OnMessage	A room message has been received.	room
OnWhisper	A private message has been received.	client
OnSystemMessage	A system message has been received.	room
OnClientList	The client list of the current room.	room
OnRoomList	A list of rooms active on the server.	client
OnNameChange	A client has changed their name.	room
OnUnknownEvent	An unknown event has been received.	client
OnClosed	The client has disconnected from the server.	client
OnTimeout	The client connection has timed out.	client
OnError	The client has received an error message.	client

Event Listeners

To listen for events, add an event listener:

local function onMessage( evt )
  print(evt.data.name, evt.data.msg)
end

cb.events:addEventListener('OnMessage', onMessage)

Note

All event properties can be found on the data object of the event (evt.data.<prop>). See the following event details for their available properties.

OnClientList

The client has received the client list for the current room.

Data Properties

Property	Description	Type
clients	A table array of clients.	Table
cnt	The client list count.	Number
room	The current room name.	String

Example

local function onClientList( evt )
  print('client count:'..evt.data.cnt)
  local clients = evt.data.clients
  for i=1, #clients do
    local client = clients[i]
    print(client.name, client.id)
  end
end

cb.events:addEventListener('OnClientList', onClientList)

OnClosed

The client has been disconnected from the server.

Data Properties

This event has no available properties.

local function onClosed()
  print('Client has disconnected from the server')
end

cb.events:addEventListener('OnClosed', onClosed)

OnConnect

The client has connected to the server.

Data Properties

This event has no available properties.

Example

local function onConnect()
  print('Client has successfully connected to the server')
end

cb.events:addEventListener('OnConnect', onConnect)

OnError

The client has received an error message.

Note

The OnError event triggers on both local and server-side errors.

Important

The OnError event does not contain a data property. To access the error, use the error key directly on the event: evt.error.

Example

local function OnError( evt )
  print('Client Error: '..evt.error)
end

cb.events:addEventListener('OnError', onError)

OnJoined

A client has joined the current room.

Data Properties

Property	Description	Type
name	Name of the joining client.	String
id	Unique ID of the client.	String
room	The current room name.	String

Example

local function onJoined( evt )
  print(evt.data.name, evt.data.id, evt.data.room)
end

cb.events:addEventListener('OnJoined', onJoined)

OnLeft

A client has left the current room.

Data Properties

Property	Description	Type
name	Name of the joining client.	String
id	Unique ID of the client.	String
room	The current room name.	String

Example

local function onLeft( evt )
  print(evt.data.name, evt.data.id, evt.data.room)
end

cb.events:addEventListener('OnLeft', onLeft)

OnMessage

A room message has been received.

Data Properties

Property	Description	Type
name	Name of the sender.	String
id	Unique ID of the sender.	String
msg	The message content.	String
room	The current room name.	String

Example

local function onMessage( evt )
  print(evt.data.name, evt.data.msg)
end

cb.events:addEventListener('OnMessage', onMessage)

OnNameChange

A client has changed their display name.

Note

After this event is received an OnClientList event will follow with the updated name, allowing for easy updating of the client display list.

Data Properties

Property	Description	Type
name	New name of the client.	String
old_name	Previous name of the client.	String
id	Unique ID of the client.	String
room	The current room name.	String

Example

local function onNameChange( evt )
  print('Old name was: '..evt.data.old_name)
  print('New name is: '..evt.data.name)
end

cb.events:addEventListener('OnNameChange', onNameChange)

OnRoomList

A list of active rooms on the server.

Data Properties

Property	Description	Type
rooms	A table array of rooms names.	String
cnt	The client list count.	String
room	The current room name.	String

Example

local function onRoomList( evt )
  print('room count:'..evt.data.cnt)
  local rooms = evt.data.rooms
  for i=1, #rooms do
    print(rooms[i].name)
  end
end

cb.events:addEventListener('onRoomList', onRoomList)

OnSystemMessage

A system message has been received.

Note

A system message can be used to broadcast a message for service related events outside of the "chat" layer.

Data Properties

Property	Description	Type
action	The system event action ID.	String
payload	The system event payload.	Table
room	The current room name.	String

Example

local function onSystemMessage( evt )
  if evt.data.action == 'player_turn' then
    print('players turn is: '..evt.data.payload)
  end
end

cb.events:addEventListener('OnSystemMessage', onSystemMessage)

OnTimeout

The client has timed out.

Important

The timeout event is only a status message and does not disconnect the client. When the client receives this message you should use the disconnect action to close the connection, if wanted.

Data Properties

This event has no available properties.

Example

local function onTimeout()
  print('The client has timed out')

  --if you'd like to disconnect on a timeout event:
  cs:disconnect()
end

cb.events:addEventListener('OnTimeout', onTimeout)

OnUnknownEvent

An unknown event type was received by the client.

Caution

You should only us this event for logging purposes. Do not perform any actions on it.

Data Properties

This event has no available properties.

Example

local function onUnkownEvent()
  print('An unknown event was received')
end

cb.events:addEventListener('OnUnknownEvent', onUnkownEvent)

OnWhisper

A private message has been received.

Note

This message will only be received by its intended recipient.

Data Properties

Property	Description	Type
name	Name of the sender.	String
id	Unique ID of the sender.	String
msg	The message content.	String
room	The current room name.	String

Example

local function onWhisper( evt )
  print(evt.data.name, evt.data.msg)
end

cb.events:addEventListener('OnWhisper', onWhisper)