Gideros Unite framework for multiplayer games

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.

Download
Server example code
Client example code
Game logic example
Example video
Client Method list
Server Method list
Client Event list
Server Event list
Latest changes

Download

Back to contents

Server example code

Back to contents

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

Back to contents

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

Back to contents

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

Back to contents

Video of module example app:

Client Method list

Back to contents

Constructor
Start Listening
Stop Listening
Connect to specified Server
Add Method
Call Method
Call Method of specific device
Get devices
Close Client

Constructor

Back to client method list

Method name	new(config)
Description	Create 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" });

Method name	startListening()
Description	Start 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)

Method name	stopListening()
Description	Stop Listening to server, both when server is broadcasting/multicasting for discovery, or when client is already connected to server

Method name	connect(id)
Description	When 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)

Method name	addMethod(name, method, scope)
Description	Add 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)

Method name	callMethod(...)
Description	Call 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)

Method name	callMethodOf(...)
Description	Call 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)

Method name	getDevices()
Description	Get 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()

Method name	close()
Description	Closes the client, disconnects it from server, disabled listening and erases ID. Serves as destructor for the class
Example	serverlink:close()

Method name	startBroadcast()
Description	Start 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

Method name	stopBroadcast()
Description	Stop Broadcasting to clients

Method name	accept(id)
Description	When 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)

Event name	device
Description	Events 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)

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

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

Event name	onClientClose
Description	Event 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)

Recommended:

Recent Comments

Gideros Unite framework for multiplayer games

You may also be interested in:

About me

Latest Tweets

Follow me

My projects

Contact me