Difference between revisions of "Gideros Unite Framework"

From GiderosMobile
Line 30: Line 30:
 
# When you are finished, close client or server using close method, which stops all timers, closes all connections and destroys instance
 
# When you are finished, close client or server using close method, which stops all timers, closes all connections and destroys instance
  
−
=== Client Method list ===
+
== Client Method list ==
−
==== Constructor ====
+
=== Constructor ===
 
'''Method name''' new(config)
 
'''Method name''' new(config)
  
Line 58: Line 58:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Start Listening ====
+
=== Start Listening ===
 
'''Method name''' startListening()
 
'''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)
 
'''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 ====
+
=== Stop Listening ===
 
'''Method name''' stopListening()
 
'''Method name''' stopListening()
  
 
'''Description''' Stop Listening to server, both when server is broadcasting/multicasting for discovery, or when client is already connected to server
 
'''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 ====
+
=== Connect to specified Server ===
 
'''Method name''' connect(id)
 
'''Method name''' connect(id)
  
Line 80: Line 80:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Add Method ====
+
=== Add Method ===
 
'''Method name''' addMethod(name, method, scope)
 
'''Method name''' addMethod(name, method, scope)
  
Line 98: Line 98:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Call Method ====
+
=== Call Method ===
 
'''Method name''' callMethod(...)
 
'''Method name''' callMethod(...)
  
Line 112: Line 112:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Call Method of specific device ====
+
=== Call Method of specific device ===
 
'''Method name''' callMethodOf(...)
 
'''Method name''' callMethodOf(...)
  
Line 128: Line 128:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Get devices ====
+
=== Get devices ===
 
'''Method name''' getDevices()
 
'''Method name''' getDevices()
  
Line 138: Line 138:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Close Client ====
+
=== Close Client ===
 
'''Method name''' close()
 
'''Method name''' close()
  
Line 148: Line 148:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== Server Method list ===
+
 
−
==== Constructor ====
+
== Server Method list ==
 +
=== Constructor ===
 
'''Method name''' new(config)
 
'''Method name''' new(config)
  
Line 176: Line 177:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Start Broadcasting ====
+
=== Start Broadcasting ===
 
'''Method name''' startBroadcast()
 
'''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
 
'''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 ====
+
=== Stop Broadcasting ===
 
'''Method name''' stopBroadcast()
 
'''Method name''' stopBroadcast()
  
 
'''Description''' Stop Broadcasting to clients
 
'''Description''' Stop Broadcasting to clients
  
−
==== Start Listening ====
+
=== Start Listening ===
 
'''Method name''' startListening()
 
'''Method name''' startListening()
  
 
'''Description''' Start Listening to clients
 
'''Description''' Start Listening to clients
  
−
==== Stop Listening ====
+
=== Stop Listening ===
 
'''Method name''' stopListening()
 
'''Method name''' stopListening()
  
 
'''Description''' Stop Listening to clients
 
'''Description''' Stop Listening to clients
  
−
==== Accept specified Client ====
+
=== Accept specified Client ===
 
'''Method name''' accept(id)
 
'''Method name''' accept(id)
  
Line 209: Line 210:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Add Method ====
+
=== Add Method ===
 
'''Method name''' addMethod(name, method, scope)
 
'''Method name''' addMethod(name, method, scope)
  
Line 227: Line 228:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Call Method ====
+
=== Call Method ===
 
'''Method name''' callMethod(...)
 
'''Method name''' callMethod(...)
  
Line 241: Line 242:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Call Method of specific device ====
+
=== Call Method of specific device ===
 
'''Method name''' callMethodOf(...)
 
'''Method name''' callMethodOf(...)
  
Line 257: Line 258:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Get devices ====
+
=== Get devices ===
 
'''Method name''' getDevices()
 
'''Method name''' getDevices()
  
Line 267: Line 268:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==== Close Server ====
+
=== Close Server ===
 
'''Method name''' close()
 
'''Method name''' close()
  
Line 278: Line 279:
  
  
 +
== 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
  
−
=== Client Event list ===
+
'''Example'''
−
    • New Server Event
+
<syntaxhighlight lang="lua">
−
    • Device Event
 
−
    • Accept Event
 
−
    • Server closed Event
 
−
    • Another Client closed Event
 
−
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
 
−
1
 
−
2
 
−
3
 
−
4
 
−
5
 
 
serverlink:addEventListener("device", function(e)
 
serverlink:addEventListener("device", function(e)
−
    print(e.data.id)
+
print(e.data.id)
−
    print(e.data.ip)
+
print(e.data.ip)
−
    print(e.data.host)
+
print(e.data.host)
 
end)
 
end)
 +
</syntaxhighlight>
 +
 +
=== Accept Event ===
 +
'''Event name''' onAccepted
 +
 +
'''Description''' Event called when server accepted connection from this client
  
−
Accept Event
+
'''Example'''
−
Event name
+
<syntaxhighlight lang="lua">
−
onAccepted
 
−
Description
 
−
Event called when server accepted connection from this client
 
−
Example input
 
−
1
 
−
2
 
−
3
 
 
serverlink:addEventListener("onAccepted", function(e)
 
serverlink:addEventListener("onAccepted", function(e)
 
    print("connection accepted")
 
    print("connection accepted")
 
end)
 
end)
 +
</syntaxhighlight>
 +
 +
=== Server closed Event ===
 +
'''Event name''' onServerClose
 +
 +
'''Description''' Event called when server is unreachable
  
−
Server closed Event
+
'''Example'''
−
Event name
+
<syntaxhighlight lang="lua">
−
onServerClose
 
−
Description
 
−
Event called when server is unreachable
 
−
Example input
 
−
1
 
−
2
 
−
3
 
 
serverlink:addEventListener("onServerClose", function(e)
 
serverlink:addEventListener("onServerClose", function(e)
−
    print("server closed connection")
+
print("server closed connection")
 
end)
 
end)
 +
</syntaxhighlight>
 +
 +
=== Another Client closed Event ===
 +
'''Event name''' onClientClose
  
−
Another Client closed Event
+
'''Description''' Event called when another client connected to the same server becomes unreachable
−
Event name
+
 
−
onClientClose
+
'''Event properties'''
−
Description
+
*e.data.id - id of client that disconnects
−
Event called when another client connected to the same server becomes unreachable
+
 
−
Event properties
+
'''Example'''
−
    • e.data.id - id of client that disconnects  
+
<syntaxhighlight lang="lua">
−
Example input
 
−
1
 
−
2
 
−
3
 
 
serverlink:addEventListener("onClientClose", function(e)
 
serverlink:addEventListener("onClientClose", function(e)
−
    print("client "..e.data.id.." closed connection")
+
print("client "..e.data.id.." closed connection")
 
end)
 
end)
 +
</syntaxhighlight>
  
−
Server Event list
 
−
    • New Client Event
 
−
    • Device Event
 
−
    • Client closed connection Event
 
−
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
 
−
1
 
−
2
 
−
3
 
−
4
 
−
5
 
−
serverlink:addEventListener("device", function(e)
 
−
    print(e.data.id)
 
−
    print(e.data.ip)
 
−
    print(e.data.host)
 
−
end)
 
  
−
Client closed connection Event
+
== Server Event list ==
−
Event name
+
=== Device Event ===
−
onClientClose
+
'''Event name''' device
−
Description
 
−
Event called when one of the clients is unreachable
 
−
Event properties
 
−
    • e.data.id - id of client
 
−
Example input
 
−
1
 
−
2
 
−
3
 
−
serverlink:addEventListener("onClientClose", function(e)
 
−
    print(e.data.id)
 
−
end)
 
  
−
Latest changes
+
'''Description''' Events spawned after calling getDevices method
−
None for now
 
−
About me
 
−
Arturs Sosins is young, but ambitious webdeveloper from Latvia.
 
−
Spending his days at university or work and spending evenings with his wife and little son, he still manages to find himself new challenges and contribute his work to the developer community.
 
−
Follow him on Twitter @ar2rsawseen or his blogs WebcodingEasy.com or AppcodingEasy.com to know what he’s up to.
 
  
 +
'''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'''
 +
<syntaxhighlight lang="lua">
 +
serverlink:addEventListener("device", function(e)
 +
print(e.data.id)
 +
print(e.data.ip)
 +
print(e.data.host)
 +
end)
 +
</syntaxhighlight>
  
 +
=== 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'''
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 +
serverlink:addEventListener("onClientClose", function(e)
 +
print(e.data.id)
 +
end)
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
  
 
'''[[Multiplayer]]'''
 
'''[[Multiplayer]]'''
 
{{GIDEROS IMPORTANT LINKS}}
 
{{GIDEROS IMPORTANT LINKS}}

Revision as of 07:05, 14 December 2023


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:

  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

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)


Multiplayer

Retrieved from ‘https://wiki.gideros.rocks/index.php?title=Gideros_Unite_Framework&oldid=23276’