🟢 Fujinet Lobby Server on-line

Welcome to the Lobby Server (ver. 5.3.0) for 8 bit computers. Even if this software has been created by as part of the Fujinet project, it's not constrained by it.

The lobby server objective is to publish the availability of third party network games so game clients now where they need to conect.

So you're making an online game and want to use Lobby Server?

Lobby Server uses http json calls to set and update the Game Server status (including server address, game name, number of users, etc) as well as for publishing the status of the games.

How do I register a game in Lobby Server?

You just need to POST a valid json to http://:8080/server, with the correct "Content-Type": "application/json" and the following format:

            
{
    "game": "5 Card Stud",
    "server": "Mock Server (Bots) Table NORM",
    "region": "us",
    "serverurl": "https://5card.carr-designs.com/?table=NORM&count=2",
    "status": "online",
    "maxplayers": 8,
    "curplayers": 1,
    "clients": [
        {
            "platform": "atari",
            "url": "TNFS://ec.tnfs.io/atari/5card.xex"
        },
        {
            "platform": "apple2",
            "url": "TNFS://ec.tnfs.io/apple2/5card.po"
        }
    ]
}
            
            
Field Value Spec
game Name of the game to be showed by the game client to the user required
printable ascii characters (regex="^[\x20-\x7E]*$")
2-16 chars
appkey Registered id of game required
integer ⊂ [1, 255]
server Name (and version) of the game server used required
printable ascii characters (regex="^[\x20-\x7E]*$")
32 chars max
region Region where the server is hosted (reserved for future use) required
printable ascii characters (regex="^[\x20-\x7E]*$")
2 chars max
serverurl url of the server where game clients will connect required
valid url
64 url chars max
status status of the game server required
status = online|offline
maxplayers maximum number of players the server can accept required
maxplayers ≥ 0
curplayers current number of players conected to the server required
integer
curplayers ≥ 0
curplayers ≤ maxplayers
clients
FieldValueSpec
platform name of the 8bit platform specific client required
printable ascii characters (regex="^[\x20-\x7E]*$")
url platform specific url of the game clinent required
valid url
64 url chars max

Any additional fields will be ignored by the server.

In case of errors, the server will reply with a http status 400 and the following json payload

{
  "success": false,
  "message": "VALIDATEERR - Invalid Json",
  "errors":  [<list of errors identified>]
}
        
        
in case of a successful submission the server will return a http status 201 (created) and the following payload:
{
  "success": true,
  "message": "Server correctly updated"
}

How do I update game values in Lobby Server?

During the life of the game server, it will probably need to update the data in the Lobby server: availability of free user slots in curplayers, updates to client.url if a new client is released, or flagging the game server if offline via the status field.

For this, the game server will have to resubmit the json via a valid POST to http://:8080/server, with the correct "Content-Type": "application/json". The format is the same one as adding the server for the first time.

How do I retrieve which games are available? (full data)

If your game server or game client require to have a view of all the games served the way to have a full dump of games in the server is to GET to http://:8080/viewFull, with the correct "Content-Type": "application/json".

The server will answer with an array of servers as described in server json structure. In addition to the fields described there, the array will contain an additional field:

Field Value Spec
lastping Last time the server data was updated in UTC Always included
format according to RFC3339
2023-05-05T00:37:42.02033875Z

The endpoint will return error http error 404 if no servers are available. Additionally, the server will return the following json:

{
  "success": false,
  "message": "No servers available"
}

How do I retrieve which games are available? (minimised)

In addition to being possible to retrieve the Lobby game servers in full, Lobby servers allow to do a extraction of the game server data in a minimised format, with the objective of not overloading the 8bit system.

The minimisation works at two levels: (a) filtering by client platform and/or appkey and (b) minimising of json structure.

The filtering makes sure that the game server data sent back to the client applies only to a certain 8bit platform. For this work, client neets to GET to http://:8080/view?platform=<platform_name>&appkey=<appkeyid> for platform_name games to be returned.

Pagination is also supported, see form spec below:
Field Value Spec
platform Name of the client that we want all the game clients retrieved always included
printable ascii characters (regex="^[\x20-\x7E]*$")
appkey Registered id of the game always included
integer ⊂ [1, 255]
pagesize Part of pagination. Number of clients to be sent back to the client optional
integer
page Part of pagination. Page number, starts with 1 optional
integer

If there are any game available for the platform_name the server will return a http status 200 and the following payload:

          
[
{
    "g": "5 Card Stud",
    "t": 1,
    "u": "https://5card.carr-designs.com/?table=NORM&count=2",
    "c": "TNFS://ec.tnfs.io/atari/5card.xex",
    "s": "Mock Server (Bots) Table NORM",
    "r": "us",
    "o": 1,
    "m": 8,
    "p": 1,
    "a": 301479
},
⋯
]
          
        
Field Value Spec
g Name of the game to be showed by the game client to the user always included
printable ascii characters (regex="^[\x20-\x7E]*$")
len(game) ≤ 12
t Registered id of the game always included
integer ⊂ [1, 255]
s Name (and version) of the game server used always included
printable ascii characters (regex="^[\x20-\x7E]*$")
len(game) ≤ 32
r Name of the region where the server is hosted always included
printable ascii characters (regex="^[\x20-\x7E]*$")
12 alphanum chars max
u url of the server where game clients will connect always included
valid url
64 url chars max
o status of the game server always included
o = 1 (online)|0 (offline)
m maximum number of players the server can accept always included
m ≥ 0
p current number of players conected to the server always included
integer
p ≥ 0
p ≤ m
c platform specific url of the game client always included
valid url
64 url chars max
a Last time the server data was updated in seconds Always included
integer a ≥ 0

For errors, see http://:8080/view may return the following errors:

The endpoint will return error http error 404 if no servers are available. Additionally, the server will return the following json:

{
  "success": false,
  "message": "No servers available"
}

The endpoint will return error http error 400 if no variable platform is sent as part of the endpoint. Additionally, the server will return the following json:

{
  "success": false,
  "message": "you need to submit a platform"
}

The endpoint will return error http error 404 if servers are available but not for your selected platform. Additionally, the server will return the following json:

{
  "success": false,
  "message": "No servers available for <platform>"
}

How do I delete a server from Lobby Server?

If your game server requires to delete its presence from Lobby server they can DELETE to a valid json to http://:8080/server with the correct "Content-Type": "application/json" and the following format:

{
  "serverurl": "url since it is the primary key"
}
If the delete is correct, the server will return an http status 204 No Content with no json message. In case of errors, the error list will be sent with a with a http status 400:

{
  "success": false,
  "message": "VALIDATEERR - Invalid Json",
  "errors":  [<list of errors identified>]
}

How do I check the status of the server?

You can check this page http://:8080/ where you will find the status of the server, but if you prefer to do it via json, there's an specific GET for this: to http://:8080/version. If server is online, you'll receive a reponse with http code 200 and the following json payload:

{
  "success": true,
  "uptime": "97h20m26.231376672s",
  "version": "fujinet persistent lobby 5.3.0/freebsd (c) Roger Sen 2023"
}
Take into account that uptime field will change with the time since the server has been running and version will represent the current version of the Lobby Server.

In case the server is not functional, you may receive no response will receive a json with the reason of the error http code 503 and the following json:

{
  "success": false,
  "message": "<Reason for the server being non-functional>",
  "version": "fujinet persistent lobby 5.3.0/freebsd (c) Roger Sen 2023"
}
Again, the version message will change with new releases.

So you're a sysadmin and want to install the Lobby Server?

Lobby server needs no parameter to start, but requires sqlite installed and the database schema setup. Once Lobby Server has been downloaded from github, run:

$ make install-db
sqlite3 -bail db/lobby.sqlite3 < lobby_schema.sql
to set up the database in the db/ directory.

Once the database has been created, starting the server without parameters...

$ ./lobbyPersist 
DB: 2023/10/22 20:50:04 Connected to lobby.sqlite3
...
Some gin framework debug cruft
...
[GIN-debug] Listening and serving HTTP on :8080
will bind the server to http://localhost:8080. Because Lobby Server uses gin framework internally, it will start in debug mode and will show some [GIN-debug] messages.

For starting it in production the recommended command line is:

$ GIN_MODE=release ./lobbyPersist -srvaddr http://my.server.address:port/
DB: 2023/10/22 20:47:14 Connected to lobby.sqlite3 
This will bind the server to the address provided in the -srvaddr field (http://my.server.address:port/)

Additionally, you can request the Lobby Server to update a Fujinet Game Alert server with the availabilty of the games servers. For this, use the param -evtaddr:

$ ./lobbyPersist -srvaddr http://my.server.address:port/ -evtaddr http://fujinetGameAlerts.server/
        

You can also get the version of the Lobby server with the -version param:

# ./lobbyPersist -version
5.3.0