Gideros Unite Framework
Gideros Unite Framework
ar2rsawseen 2012/07/25 Gideros Mobile, updated 2023/12/13 (V2)
Gideros Unite framework provides a way to implement Multiplayer games:
- using LuaSocket to establish socket connections and create server/client instances
- device discovery over Local Area Network
- call methods on devices through the network
- protocols: tcp, udp or both (binding some method to tcp if reliability is needed, and others to udp for faster data processing)
You can download the Gideros Unite Framework: Unite.zip
And an application project: DrawTogetherV2.zip
Standard scenario
This is a standard scenario that can be created using Gideros Unite framework:
- Server starts broadcasting or skip to step 5, if all clients know server IP address
- Client's start listening to servers
- Client receives broadcast message from server, newServer event is initiated
- Client autoconnects to server or user manually (by pushing button) connects to specific server
- Server receives newClient event
- Server accepts client automatically or user manually (by pushing button) accepts specific client
- Client receives onAccept event
- Implement your game logic here, where both clients and server can call methods on all devices or on one specific device in the network
- When one of the clients becomes unreachable, all clients and server get onClientClose event
- When server becomes unreachable, all clients get onServerClose event
- When you are finished, close client or server using close method, which stops all timers, closes all connections and destroys instance
Client Method list
Constructor
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
local serverlink = Client.new({
username = "ar2rsawseen",
ip = nil,
port = 15000,
multicast = "239.192.1.1",
serverIP = nil,
connectionType = "tcp"
})
Start Listening
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)
Stop Listening
Method name stopListening()
Description Stop Listening to server, both when server is broadcasting/multicasting for discovery, or when client is already connected to server
Connect to specified 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)
Add Method
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)
Call Method
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)
Call Method of specific device
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)
Get devices
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()
Close Client
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()
Server Method list
Constructor
Method name new(config)
Description Create 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
local serverlink = Server.new({
username = "IAmAServer",
ip = nil,
port = 15000,
multicast = "239.192.1.1",
maxClients = 0,
connectionType = "tcp"
})
Start Broadcasting
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
Stop Broadcasting
Method name stopBroadcast()
Description Stop Broadcasting to clients
Start Listening
Method name startListening()
Description Start Listening to clients
Stop Listening
Method name stopListening()
Description Stop Listening to clients
Accept specified Client
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)
Add Method
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)
Call Method
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)
Call Method of specific device
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)
Get devices
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()
Close Server
Method name close()
Description Closes 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
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
serverlink:addEventListener("device", function(e)
print(e.data.id)
print(e.data.ip)
print(e.data.host)
end)
Accept Event
Event name onAccepted
Description Event called when server accepted connection from this client
Example
serverlink:addEventListener("onAccepted", function(e)
print("connection accepted")
end)
Server closed Event
Event name onServerClose
Description Event called when server is unreachable
Example
serverlink:addEventListener("onServerClose", function(e)
print("server closed connection")
end)
Another Client closed Event
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
serverlink:addEventListener("onClientClose", function(e)
print("client "..e.data.id.." closed connection")
end)
Server Event list
Device Event
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)
Client closed connection Event
Event name onClientClose
Description Event 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)
