Gideros Unite framework provides a way to implement Multiplayer games using Gideros Mobile. It uses LuaSocket to establish socket connections and even create server/client instances.

It provides the means of device discovery in Local Area Network, and allows to call methods of other devices throught network

You can also download a DrawTogether app's source code created using Gideros Unite framework as example, of how you can use Gideros Unite

This is a standard scenario that can be created using Gideros Unite framework:

  • 1. Server starts broadcasting or skip to step 5, if all clients know server IP address
  • 2. Client's start listening to servers
  • 3. Client receives broadcast message from server, newServer event is initiated
  • 4. Client autoconnects to server or user manually (by pushing button) connects to specific server
  • 5. Server receives newClient event
  • 6. Server accepts client automatically or user manually (by pushing button) accepts specific client
  • 7. Client receives onAccept event
  • 8. Implement your game logic here, where both clients and server can call methods on all devices or on one specific device in the network
  • 9. When one of the clients becomes unreachable, all clients and server get onClientClose event
  • 10. When server becomes unreachable, all clients get onServerClose event
  • 11. When you are finished, close client or server using close method, which stops all timers, closes all connections and destroys instance

About protocols, it is possible to use tcp, udp or both (by binding some method to tcp, if reliability is needed, and others to udp for faster data processing)

Package contains Unite.lua and example Gideros application project - DrawTogether app.

Contents

Download

Server example code

function onAccept(e)	
	--auto accept client with provided id
	serverlink:accept(e.data.id)
end
	
--create a server instance
serverlink = Server.new({username = 'myServer'})
--add event to monitor when new client wants to join
serverlink:addEventListener('newClient', onAccept)
--start broadcasting to discover devices
serverlink:startBroadcast()


--and then before entering game logic
--if we are ready toplay
--stop broadcasting
serverlink:stopBroadcast()
--and start only listening to clients
serverlink:startListening()

Client example code

function onJoin(e)
	--auto connect to server with provided id
	serverlink:connect(e.data.id)
end
	
--create client instance
serverlink = Client.new({username = 'IAmAClient'})
--create event to monitor when new server starts broadcasting
serverlink:addEventListener('newServer', onJoin)

--event to listen if server accepted our connection
serverlink:addEventListener('onAccepted', function()
	print('server accepted our connection')
end)

Game logic example

Game logic is the same for server and clients

--we can get all devices that are connected to our network
local devices = {}
serverlink:addEventListener('device', function(e)
	print(e.data.id, e.data.ip, e.data.host)
	devices[e.data.id] = {}
	devices[e.data.id].ip = e.data.ip
	devices[e.data.id].name = e.data.host
end)
	
serverlink:getDevices()
	
	
--add some methods, that could be called by other clients or server through network
--draw something
serverlink:addMethod('draw', self.drawLine, self)
--end drawing
serverlink:addMethod('end', self.stopDrawing, self)
--clear drawing
serverlink:addMethod('clear', self.reset, self)


--then you can call this methods when needed
serverlink:callMethod('clear')
serverlink:callMethod('draw', someX, someY)


--or call method of specific device using it's id
serverlink:callMethodOf('clear', 112233)
serverlink:callMethodOf('draw', someX, someY, 112233)


--and when game is finished
serverlink:close()


--and that's all

Example video

Video of module example app:

Client Method list

Constructor

Back to client method list

Method namenew(config)
DescriptionCreate client instance
Input parameters

table config - lua table with configuration options:

  • string username - username to display on devices (default: hostname or device's IP address)
  • string ip - ip address to use for server (default: current device's IP address)
  • int tcpPort - port to use for tcp connection (default: 5883)
  • int udpPort - port to use for udp connection (default: 5884)
  • int discoveryPort - port to use for device discovery (default: 5885)
  • int multicast - multicast ip address for device discovery (default: 239.192.1.1)
  • int serverIP - ip address of server, if no discovery needed and can connect tp server directly (default: nil)
  • string connectionType - which connection protocol to use tcp, udp or both (default: 'both')
Example input
local serverlink = Client.new({
	username = "ar2rsawseen",
	ip = nil,
	port = 15000,
	multicast = "239.192.1.1",
	serverIP = nil,
	connectionType = "tcp"
});

Start Listening

Back to method list

Method namestartListening()
DescriptionStart Listening to server, both when server is broadcasting/multicasting for discovery, or when client is already connected to server (for example, by providing it's ip address)

Stop Listening

Back to method list

Method namestopListening()
DescriptionStop Listening to server, both when server is broadcasting/multicasting for discovery, or when client is already connected to server

Connect to specified Server

Back to method list

Method nameconnect(id)
DescriptionWhen server is broadcasting/multicasting, if client is not yet connected to any server, it recieves new server events with server ID. You need to provide that ID to connect method, to connect to specified server
Input parameters

int id - server id received from new server event

Example

serverlink:connect(111222333)

Add Method

Back to method list

Method nameaddMethod(name, method, scope)
DescriptionAdd method which can be called through the network by other devices
Input parameters

Input parameters are similar to adding new event listener

string name - name of command to associate with this method, could be simply method name as string

function method - method that will be called from other connected devices. This function will be called by other devices, and all parameters provided by other devices will be passed to this function. Additionally, the last providd parameter will be the source of message - id of device from which message originated

object scope - scope to use for method, if for example using class method and not simple function, you can provide self variable if defined inside class, of class instance if defiend outside class (default: nil)

Example

serverlink:addMethod("draw", self.draw, self)

Call Method

Back to method list

Method namecallMethod(...)
DescriptionCall specific method for all connected devices
Input parameters

string command - name of command, to call the method associated with this command

Other parameters can be any values, that will be passed to called method

Example

serverlink:callMethod("draw", 100, 200)

Call Method of specific device

Back to method list

Method namecallMethodOf(...)
DescriptionCall specific method for specific connected devices
Input parameters

string command - name of command, to call the method associated with this command

Other parameters can be any values, that will be passed to called method

Last parameter should be the ID of device, to which to send command

Example

serverlink:callMethodOff("draw", 100, 200, 111222333)

Get devices

Back to method list

Method namegetDevices()
DescriptionGet ID of all devices connected to server. Due to limitation, that ID's of devices are retrieved through sockets on the network, this method does not return list of devices, but rather generates multiple "device" events, one for each connected device
Example

serverlink:getDevices()

Close Client

Back to method list

Method nameclose()
DescriptionCloses the client, disconnects it from server, disabled listening and erases ID. Serves as destructor for the class
Example

serverlink:close()

Server Method list

Constructor

Back to server method list

Method namenew(config)
DescriptionCreate server instance
Input parameters

table config - lua table with configuration options:

  • string username - username to display on devices (default: hostname or device's IP address)
  • string ip - ip address to use for server (default: curret devices IP address)
  • int tcpPort - port to use for tcp connection (default: 5883)
  • int udpPort - port to use for udp connection (default: 5884)
  • int discoveryPort - port to use for device discovery (default: 5885)
  • int multicast - multicast ip address for device discovery (default: 239.192.1.1)
  • int maxClients - maximal amount of clients server can serve (default: unlimited amount)
  • string connectionType - which connection protocol to use tcp, udp or both (default: 'both')
Example input
local serverlink = Server.new({
	username = "IAmAServer",
	ip = nil,
	port = 15000,
	multicast = "239.192.1.1",
	maxClients = 0,
	connectionType = "tcp"
});

Start Broadcasting

Back to method list

Method namestartBroadcast()
DescriptionStart Broadcasting to clients, both broadcast and multicast to discover other listening devices. Broadcasting includes listening, so if server is broadcasting, there is no need to call startListening method

Stop Broadcasting

Back to method list

Method namestopBroadcast()
DescriptionStop Broadcasting to clients

Start Listening

Back to method list

Method namestartListening()
DescriptionStart Listening to clients

Stop Listening

Back to method list

Method namestopListening()
DescriptionStop Listening to clients

Accept specified Client

Back to method list

Method nameaccept(id)
DescriptionWhen client responded to broadcasting/multicasting message, server recieves new client events with client ID. You need to provide that ID to accept method, to accept specified client
Input parameters

int id - client id received from new client event

Example

serverlink:accept(111222333)

Add Method

Back to method list

Method nameaddMethod(name, method, scope)
DescriptionAdd method which can be called through the network by other devices
Input parameters

Input parameters are similar to adding new event listener

string name - name of command to associate with this method, could be simply method name as string

function method - method that will be called from other connected devices. This function will be called by other devices, and all parameters provided by other devices will be passed to this function. Additionally, the last providd parameter will be the source of message - id of device from which message originated

object scope - scope to use for method, if for example using class method and not simple function, you can provide self variable if defined inside class, of class instance if defiend outside class (default: nil)

Example

serverlink:addMethod("draw", self.draw, self)

Call Method

Back to method list

Method namecallMethod(...)
DescriptionCall specific method for all connected devices
Input parameters

string command - name of command, to call the method associated with this command

Other parameters can be any values, that will be passed to called method

Example

serverlink:callMethod("draw", 100, 200)

Call Method of specific device

Back to method list

Method namecallMethodOf(...)
DescriptionCall specific method for specific connected devices
Input parameters

string command - name of command, to call the method associated with this command

Other parameters can be any values, that will be passed to called method

Last parameter should be the ID of device, to which to send command

Example

serverlink:callMethodOff("draw", 100, 200, 111222333)

Get devices

Back to method list

Method namegetDevices()
DescriptionGet ID of all devices connected to server. Due to limitation, that ID's of devices are retrieved through sockets on the network, this method does not return list of devices, but rather generates multiple "device" events, one for each connected device
Example

serverlink:getDevices()

Close Server

Back to method list

Method nameclose()
DescriptionCloses the server, disconnects all clients, disables listening and/or broadcasting and erases ID. Serves as destructor for the class
Example

serverlink:close()

Client Event list

Device Event

Back to client event list

Event namedevice
DescriptionEvents spawned after calling getDevices method
Event properties
  • e.data.id - id of client
  • e.data.ip - ip address of client
  • e.data.host - username or hostname of client or ip if no hostname provided
Example input
serverlink:addEventListener("device", function(e)
	print(e.data.id)
	print(e.data.ip)
	print(e.data.host)
end)

Accept Event

Back to client event list

Event nameonAccepted
DescriptionEvent called when server accepted connection from this client
Example input
serverlink:addEventListener("onAccepted", function(e)
	print("connection accepted")
end)

Server closed Event

Back to client event list

Event nameonServerClose
DescriptionEvent called when server is unreachable
Example input
serverlink:addEventListener("onServerClose", function(e)
	print("server closed connection")
end)

Another Client closed Event

Back to client event list

Event nameonClientClose
DescriptionEvent called when another client connected to the same server becomes unreachable
Event properties
  • e.data.id - id of client that disconnects
Example input
serverlink:addEventListener("onClientClose", function(e)
	print("client "..e.data.id.." closed connection")
end)

Server Event list

Device Event

Back to server event list

Event namedevice
DescriptionEvents spawned after calling getDevices method
Event properties
  • e.data.id - id of client
  • e.data.ip - ip address of client
  • e.data.host - username or hostname of client or ip if no hostname provided
Example input
serverlink:addEventListener("device", function(e)
	print(e.data.id)
	print(e.data.ip)
	print(e.data.host)
end)

Client closed connection Event

Back to server event list

Event nameonClientClose
DescriptionEvent called when one of the clients is unreachable
Event properties
  • e.data.id - id of client
Example input
serverlink:addEventListener("onClientClose", function(e)
	print(e.data.id)
end)

Latest changes

None for now