Event Listeners

Events can be registered to different listeners to take action on them. In almost all cases, there should only be one listener for an event at any given time. This means you will need to be mindful of "removing" a listener when appropiate.

To remove an event listener use removeEventListener:

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

You should always be listening for the OnClientList and OnClosed event throughout your application while connected to your instance. The OnClientList event provides a syncing point for the clients currently connected to the room. This event is trigged when a client joins, leaves, or makes a name change in the room. If you're not listening for this event, you will not know what the current state of the room is.

The OnClosed event is important for clean up associated with a client disconnecting from the server.

The OnJoined and OnLeft events are helpful for cleaning up client specfic state.

Client Names

When a client connects to a room, it's possible for two (or more) clients to have the same name. A clients name can be changed with the changeName action. If you want to impose unique names, you can write logic in the OnJoined event to check the client list for a matching name, and prompt the user to change their name.

System Messages

System messages can facilitate more complex applications. A system message contains two properties, an action and payload. Using this message type allows you to control your application without having to parse through "chat" based messages.

The action property should be a unique key that you can check for on the OnSystemMessage event. The payload is any data required for that action. It can be a simple value, or a complex data table.

By listening for system messages, and checking the action key you can implement limitless functionality:

local cb = require('chatterbox.client')

local function onSystemMessage( evt )
  local action = evt.action
  local payload = evt.payload

  if action == 'open_broswer' then
    --possible function, payload is a data table
    openWebView(payload.url)
  elseif action == 'flash_screen' then
    --possible function, payload contains a number
    flashScreen({repeat=payload})
  end
end

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

Acting on a specific client:

local cb = require('chatterbox.client')

local function onSystemMessage( evt )
  local action = evt.action
  local payload = evt.payload --a data table

  if action == 'set_score' then
    if payload.client_id == cs:getId() then
      client_score = payload.score
    end
  end
end

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

You can also sync application state by passing a data table as the payload:

...

local function onSystemMessage( evt )
  if evt.action == 'state' then
    app_state = evt.payload
    --do stuff with the app_state
  end
end

...