Skip to content

Getting Started

Jump to bottom
Dominique Debergue edited this page Dec 12, 2021 · 12 revisions

📘 Set-Up

Installing

If you have not done so already, you should first download the dependencies:

go get github.com/gorilla/websocket
go get github.com/go-sql-driver/mysql
go get golang.org/x/crypto/bcrypt

Then (of course) download the server:

go get github.com/hewiefreeman/GopherGameServer

Now you can start using Gopher Game Server!

Running The Server

The root package gopher has 4 main methods: Start(), Pause(), Resume(), and ShutDown().

The Start() method starts the server:

package main

import (
	"github.com/hewiefreeman/GopherGameServer"
)

func main() {
	gopher.Start(nil)
}

The method gopher.Start() blocks the thread that it is called on until the server shuts down, so any server initialization must be done before calling Start() on the main thread. In the above example, we've passed nil to Start() to run the server with all the default core server settings. The next section will tell you more about the core server settings and their functionalities.

The methods Pause(), Resume(), and ShutDown() can be called just like Start() in the above example. Their functionalities are pretty self-explanatory, and you can read more about them in the documentation by clicking the links above.

📘 Core Server Settings

When starting the Gopher Game Server, you can pass a properly filled ServerSettings struct:

package main

import (
	"github.com/hewiefreeman/GopherGameServer"
)

func main() {
	settings := gopher.ServerSettings{
		ServerName: "!s!",
		MaxConnections: 10000,

		HostName: "http://example.com",
		HostAlias: "http://www.example.com",
		IP: "192.168.1.1",
		Port: 8080,

		OriginOnly: true,
	}
	gopher.Start(&settings)
}

There are too many ServerSettings to go through in this section, but here are some explanations for the required (and recommended) settings to start the server:

  • ServerName: The literal name of the server. This is used when making a room that does not have an explicit owner.
  • MaxConnections: The number of concurrent client connections the server will accept. If set to 0, the server will accept as many as the system can handle.
  • HostName: The host name of your server. This could be localhost, or a domain name for web apps.
  • HostAlias: The host name alias of your server. For web apps, this is typically the domain name with the www prefix.
  • IP: The IP address of your server.
  • Port: The port number you want to run the server on.
  • OriginOnly: When set to true, incoming client connections will be tested to see whether the connection is coming from the HostName or HostAlias. If the client connection is not coming from the HostName or HostAlias, the connection will be refused. This is mostly used for web apps.

More ServerSettings will be explained in other sections when they are necessary for certain features. In the mean time, you can take a look at the documentation on ServerSettings.

📘 Server Callbacks

The server callbacks will run a function you make in your code when a specific action happens on the server. You can set a server callback with the setter functions in the gopher package. Lets take a look at a few of the most basic server callbacks:

package main

import (
	"github.com/hewiefreeman/GopherGameServer"
)

func main() {
	gopher.SetStartCallback(serverStarted)
	gopher.SetPauseCallback(serverPaused)
	gopher.SetResumeCallback(serverResumed)
	gopher.SetShutDownCallback(serverShutDown)
	gopher.Start(nil)
}

func serverStarted() {
	// Runs AFTER the server has successfully started
}

func serverPaused() {
	// Runs AFTER the server has successfully paused
}

func serverResumed() {
	// Runs AFTER the server has successfully resumed
}

func serverShutDown() {
	// Runs AFTER the server has successfully shut down
}

These callbacks are easiest to work with since they don't need to accept any parameters, nor return anything. They're also pretty self-explanatory: your function is called directly after the specific server action happens. Now let's take a look at a callback that requires your function to take in some parameters and return a boolean:

package main

import (
	"github.com/hewiefreeman/GopherGameServer"
	"fmt"
)

func main() {
	setErr := gopher.SetClientConnectCallback(clientConnected)
	if setErr != nil {
		fmt.Println(setErr)
	}
	gopher.Start(nil)
}

func clientConnected(*http.ResponseWriter, *http.Request) bool {
	// Runs BEFORE a client finishes handshaking server, but after
	// the initial HTTP connection.
	//
	// Returns a boolean, which when false will prevent the client
	// from finishing connecting, and send back an http.StatusForbidden
	// message.
	return true
}

The client connect callback is also pretty self-explanatory, and I've provided a decent explanation on when it is called, and what the boolean is for in the above comment. This could be used to, for instance, get some user agent information from the client's HTTP connection and determine whether they can connect with some sort of white/black list.

I've also demonstrated how to handle errors that could occur when using any of the server callback setters. If the function reference passed in does not match the callback's parameters and return values, the setter will return an error and cancel the assignment.

There are still a few more server callbacks that we will not go over here, but you can take a look at the documentation for explanations on each server callback:

📘 Macro Commands

Gopher Game Server accepts basic commands in the console, commonly referred to as "macro" commands. You can do all the basic things like pause, resume, and shut down the server, as well as other useful commands. After successfully booting the server, you will see an input in your console labeled [Gopher] Command:. This is where you can enter any of the macro commands. For this section I think it's easiest to list them all and explain how to use them:

  • version: Displays the current running version of the server
  • pause: Pauses the server
  • resume: Resumes the server after being paused
  • shutdown: Shuts the server down and saves state if enabled
  • newroom name roomType isPrivate maxUsers: Makes a new room owned by the server with the name name(string), the room type roomType(string), isPrivate(bool) which makes the room private or not, and maxUsers(int) which determines the maximum User capacity of the room. (Ex: newroom game53942 2v2room false 4)
  • deleteroom name: Deletes a room by the given name(string)
  • kick userName: Logs off all connections under the User name userName(string). (Ex: kick larry_josher)

The command list will most likely grow in the future, and will be posted here. Feel free to open up an Issue to request a new macro command!

If you notice there is lacking information, missing features, or bad explanations, please open an issue. All requests are acceptable and will be taken into consideration.

Clone this wiki locally