NodeLS, short for Node List Server, is a game server directory application that aims to provide a reliable way of registering, deregistering and informing clients of servers available for your game(s).
When developing a game, let's say a First Person Shooter, you might want to have clients host their own servers. These servers might be host-client ("listen") or pure dedicated instances. However, here comes the next problem...
How the heck do you display servers that are available for you to join?
Enter NodeLS. It's a flexible and open source server listing system that works with pretty much any software that can understand JSON. NodeLS also brings you assurance that you control the data that is being sent and received, not a third party other than the server provider you deal with.
Please consider a donation (see the Ko-Fi button above) if this server software is useful to you.
While issue tickets are the preferred way of support, you may also ask for support on the Oiran Studio Discord. It may be a faster way of getting support if I'm not busy with other client tasks. Sometimes issue ticket notifications get snowed under a truck load of new email.
TODO: Review docker support and update it
If you want to have everything handled for you and you're running a linux server, see the Docker support documentation file for more info. Please note that this will require some additional setup.
Make sure your installation of Node is functional before continuing!
C:\NodeListServer
).
git clone https://github.com/SoftwareGuy/NodeListServer .
NOTE: It is possible to use a GUI such as Git GUI or SourceTree. Use whatever you're familiar with.
Note: The ZIP Installation Method loses the git metadata, so you will not be able to have easy updates.
TODO: Update this
lib/config.js
.config.js
(ie. you edited it via FTP).Note: It's recommended to use a process manager like PM2 which will allow you start and stop the server elegantly, and restart it in case of crashes, etc.
First Run:
npm install --only=production
. This will read the requirements from packages.json.To start the server:
Protip: Check to see if the port is open that you want NodeListServer to listen on. You cannot have more than one list server listening on the same port number.
npm start
or node init
. NodeListServer Gen2: Mirror List Server reimplemented in NodeJS
Report bugs and fork me on GitHub: https://github.com/SoftwareGuy/NodeListServer
Listening on HTTP port 8889!
http://[your-server-ip]:8889/list
. cURL is very useful as a debug tool, so here's a one liner. Replace NodeListServerDefaultKey
with your changed key if you changed that.curl -X POST -d "serverKey=NodeListServerDefaultKey" http://127.0.0.1:8889/list
If all goes well, you should get some JSON as a result. If you don't, or you get Bad Request
then check what the console says - you dun goofed probably.
To stop the server:
Simply CTRL+C the running Node process, or you can use kill
/pkill
to kill the node instance. I'd recommend using ps aux
and kill <pid>
carefully, because pkill node
would try to kill all node instances on your box - and that can be really no bueno.
git pull
from the repository you cloned to your local machine or server instance.
git pull
. Download and extract a new ZIP archive of this repository instead.git pull
.
Section omitted because it needs cleanup. Check back later.
Want a easy, ready to go project? Then grab a copy of the NodeListServer-Example repository.
In fairness, It's pretty easy to use NodeListServer with Unity. You can use UnityWebRequest or another library (ie. Best HTTP Pro) to fetch the server lists and issue add/remove commands. As long as you can decode JSON it returns for the server list, you should be fine.
Important: Do NOT auto-assume that POST functions will be successful. Always check the HTTP status code before doing anything with the returned response.
System.Guid.newGuid()
to generate a random one.As a bonus, here's some generic serializable classes that you can use to translate the JSON into something more usable:
[Serializable]
public class ServerListResponse
{
// Number of known servers.
public int count;
// The container for the known servers.
public List<ServerListEntry> servers;
// Ideally used for client-hosted games, tells you how often you should refresh your server information.
public int updateFrequency;
}
[Serializable]
public class ServerListEntry
{
// Random generated UUID
public string serverUuid;
// IP address. Beware: Might be IPv6 format, and require you to chop off the leading "::ffff:" part. YMMV.
public string ip;
// Port of the server.
public int serverPort;
// Name of the server.
public string serverName;
// Number of players on the server.
public int serverPlayers;
// The number of players maximum allowed on the server.
public int serverCapacity;
// Extra data.
public string extras;
}
Make sure you POST the correct data when you want to add/remove servers. See API Endpoints for more details on the required POST fields.
Thank you for choosing Australian Open Source Software.
npm install
to install dependencies node listServer.js
to start your NodeLS server 1) POST - http://127.0.0.1:8889/add - x-WWW-FORM
ip => ip addres of the node
serverKey => NodeListServerDefaultKey (specified in the Configuration file)
serverName => Lulu
serverPort => 7777
serverPlayers => 2 (optional)
serverCapacity => 20 (optional)
Congratulations! you now have ~ serverUuid || "uuid" ~~ of the created server called "Lulu" !!
2) POST - http://127.0.0.1:8889/list - x-WWW-FORM
serverKey => NodeListServerDefaultKey (specified in the Configuration file)
"Example callback" => {
"count": 2,
"servers": [
{
"ip": "::ffff:127.0.0.1",
"name": "Lulu",
"port": 7777,
"players": 0,
"capacity": 0,
"extras": ""
},
{
"ip": "::ffff:127.0.0.1",
"name": "Lulus",
"port": 7337,
"players": 2,
"capacity": 20,
"extras": ""
}
],
"updateFrequency": "300"
}
3) POST - http://127.0.0.1:8889/remove - x-WWW-FORM
serverKey => NodeListServerDefaultKey (specified in the Configuration file)
serverUuid => de94592c-7672-419b-8fe2-234b48e46607 (the Generated uuid)