Client API Creation

⚠️ WORK IN PROGRESS ⚠️

Table of Contents

• Getting Started
• API Structuring
• WebSocket Callbacks
  • Open Callback
  • Close Callback
  • Message Callback

📘 Getting started

Creating a client from scratch for Gopher Game Server requires close attention to what the server and client expect from each other. This guide will describe in detail the process of making a client for any language of your choice. Though, for simplicity's sake, we will use JavaScript and references to the JavaScript API as a means of describing how to accomplish all client-side tasks.

First off, we need to be able to connect to a WebSocket as a client. Download and install any libraries for your language that you would need for WebSocket clients. Now we can run an instance of Gopher Gamer Server locally and try to connect with a function similar to:

(gopher-client.js:177)

GopherServerClient.prototype.connect = function(ip, port, ssl){
	// ...
	this.ip = ip;
	this.port = port;
	this.ssl = ssl;
	if(ssl){
		this.socketURL = "wss://"+ip+":"+port+"/wss";
	}else{
		this.socketURL = "ws://"+ip+":"+port+"/ws";
	}

	//START WEBSOCKET
	this.socket = new WebSocket(this.socketURL);
	this.socket.addEventListener("open", this.sO);
	this.socket.addEventListener("close", this.sD);
	this.socket.addEventListener("message", this.sR);
}

NOTE: If you are writing a client API that you would like to submit as an official client, please make sure that there is an option for connecting via SSL/TLS encrypted sockets as shown above. A WebSocket library that does not support SSL/TLS will not be accepted for an official client!

As shown above, the server will start a WebSocket server on it's configured IP address and port number: "ws://"+ip+":"+port+"/ws" or "wss://"+ip+":"+port+"/wss" for SSL/TLS connections. Taking that into account, I build the socketURL either way, depending on the ssl Boolean parameter option. Then you need to listen for the three WebSocket client operations open, close, and message:

this.socket.addEventListener("open", this.sO);
this.socket.addEventListener("close", this.sD);
this.socket.addEventListener("message", this.sR);

With the code above, the open listener calls sO() when the socket successfully connects to the server, the close listener calls sD() when the socket disconnects, and the message listener calls sR when the client receives a message from the server. Test out your library's open listener and if it gets called, you've successfully connected to the server and completed the first step to making a client! Congrats!

NOTE: Some WebSocket client libraries will have an option between binary and text for the message type received from the server. Gopher Game Server uses JSON, which is a text type.

📘 API Structuring

This section is for anyone who would like to create an official client API. The structure for your classes (or structs/prototypes/etc.) should be consistent and comparable to the JavaScript, or any other client API. That being said, let's take a look at the structure for the JavaScript API:

• Class: GopherServerClient
  • Methods
    • connect(ip, port, ssl)
    • disconnect()
    • addEventListener(type, callback)
    • ...
• Class: GopherVoiceChat
  • Methods
    • openMic()
    • closeMic()
    • setVolume(volume)
    • setBufferSize(size)
    • ...

There should be two separate classes within your API, one that takes care of everything for voice chat (GopherVoiceChat), and one that takes care of everything else (GopherServerClient). Of course, bonus points if you run the voice chat buffering and data stream conversions on separate threads!

The classes should follow these rules, and everything else is up to you:

• Use camel case, and same class/method names used in this guide and in the JavaScript API
• Do not expose any class member variables (only private if possible)
• Do not accept invalid or unformulated input, and return or throw errors when applicable
• Do not use any commercial, unstable, or incomplete third-party libraries

📘 WebSocket Callbacks