README
¶
Gopher Game Server provides a flexible and diverse set of tools that greatly ease developments of any type of online multiplayer game, or real-time application. GGS does all the heavy lifting for you, ensuring you never need to worry about synchronizing or data type conversions.
Moreover, Gopher has a built-in, fully customizable SQL client authentication mechanism that creates and manages users' accounts for you. It even ties in a friending tool, so users can befriend and invite one another to groups, check each other's status, and more. All components are easily configurable and customizable for any specific project's needs.
⭐ Main features
- Super easy APIs for server, database, and client coding
- Chat, private messaging, and voice chat
- Customizable client authentication (*1)
- Built-in friending mechanism (*1)
- Supports multiple connections on the same User
- Server saves state on shut-down and restores on reboot (*2)
(*1) A MySQL (or similar SQL) database is required for the authentication/friending feature, but is an optional (like most) feature that can be enabled or disabled to use your own implementations.
(*2) When updating and restarting your server, you might need to be able to recover any rooms that were in the middle of a game. This enables you to do so with minimal effort.
Upcoming features
- Distributed load balancer and server coordinator
- Distributed server broadcasts
- GUI for administrating and monitoring servers
- Integration with GopherDB when stable (*1)
(*1) MySQL isn't very scalable on it's own, and the SQL implementation for storing friend info is probably not the most efficient. Hence, it is recommended to put the friends table into a separate database cluster. GopherDB, on the other hand, is a very promising database project that will greatly increase server efficiency, and could possibly even outperform MySQL overall. It has a built-in authentication table type, which takes a substantial load off the game servers, and further secures your users' private information. It also supports nested values which are deep-validated through table schemas, so you can store complex information using a wide variety of data types and rules. You can follow the project and get more info with the link above!
Change Log
🎮 Client APIs
- JavaScript: GopherClientJS
If you want to make a client API in an unsupported language and want to know where to start and/or have any questions, feel free to open a new issue!
📁 Installing
Gopher Game Server requires at least Go v1.8+ (and MySQL v5.7+ for the authentication and friending features).
First, install the dependencies:
go get github.com/gorilla/websocket
go get github.com/go-sql-driver/mysql
go get golang.org/x/crypto/bcrypt
Then install the server:
go get github.com/hewiefreeman/GopherGameServer
📚 Usage
Table of Contents
📜 Documentation
Package gopher - Main server package for startup and settings
Package core - Package for all User and Room functionality
Package actions - Package for making custom client actions
Package database - Package for customizing your database
🌌 Contributions
Contributions are open and welcomed! Help is needed for everything from documentation, cleaning up code, performance enhancements, client APIs and more. Don't forget to show your support with a ⭐!
If you want to make a client API in an unsupported language and want to know where to start and/or have any questions, feel free to open a new issue!
Please read the following articles before submitting any contributions or filing an Issue:
GopherGameServer and all of it's contents Copyright 2022 Dominique Debergue
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Package gopher is used to start and change the core settings for the Gopher Game Server. The type ServerSettings contains all the parameters for changing the core settings. You can either pass a ServerSettings when calling Server.Start() or nil if you want to use the default server settings.
Index ¶
- Constants
- func ClientsConnected() int
- func Pause()
- func Resume()
- func SetAccountInfoChangeCallback(cb interface{}) error
- func SetClientConnectCallback(cb interface{}) error
- func SetDeleteAccountCallback(cb interface{}) error
- func SetLoginCallback(cb interface{}) error
- func SetLogoutCallback(cb interface{}) error
- func SetPasswordChangeCallback(cb interface{}) error
- func SetPauseCallback(cb interface{}) error
- func SetResumeCallback(cb interface{}) error
- func SetShutDownCallback(cb interface{}) error
- func SetSignupCallback(cb interface{}) error
- func SetStartCallback(cb interface{}) error
- func ShutDown() error
- func Start(s *ServerSettings)
- type ServerSettings
Constants ¶
const ( // ErrorIncorrectFunction is thrown when function input or return parameters don't match with the callback ErrorIncorrectFunction = "Incorrect function parameters or return parameters" // ErrorServerRunning is thrown when an action cannot be taken because the server is running. Pausing the server // will enable you to run the command. ErrorServerRunning = "Cannot call when the server is running." )
Variables ¶
This section is empty.
Functions ¶
func ClientsConnected ¶
func ClientsConnected() int
ClientsConnected returns the number of clients connected to the server. Includes connections not logged in as a User. To get the number of Users logged in, use the core.UserCount() function.
func Pause ¶
func Pause()
Pause will log all Users off and prevent anyone from logging in. All rooms and their variables created by the server will remain in memory. Same goes for rooms created by Users unless RoomDeleteOnLeave in ServerSettings is set to true.
func SetAccountInfoChangeCallback ¶
func SetAccountInfoChangeCallback(cb interface{}) error
SetAccountInfoChangeCallback sets the callback that triggers when a client changes an `AccountInfoColumn`. The function passed must have the same parameter types as the following example:
func clientChangedAccountInfo(userName string, databaseID int, receivedColumns map[string]interface{}, clientColumns map[string]interface{}) bool {
//code...
}
`userName` is the name of the User changing info, `databaseID` is the index of the User on the database, `receivedColumns` are the custom `AccountInfoColumn` (keys) and their values received from the database, and `clientColumns` have the same keys as the `receivedColumns`, but are the input from the client.
The function returns a boolean. If false is returned, the client will receive a `helpers.ErrorActionDenied` (1052) error and will be denied from changing the info. This can be used to, for instance, make extra input requirements for this action.
Note: the `clientColumns` decides which `AccountInfoColumn`s were fetched from the database, so the keys will always be the same as `receivedColumns`. You can compare the `receivedColumns` and `clientColumns` to, for instance, compare the keys named 'email' to make sure the client also provided the right email address for that account on the database.
func SetClientConnectCallback ¶
func SetClientConnectCallback(cb interface{}) error
SetClientConnectCallback sets the callback that triggers when a client connects to the server. The function passed must have the same parameter types as the following example:
func clientConnected(writer *http.ResponseWriter, request *http.Request) bool {
//code...
}
The function returns a boolean. If false is returned, the client will receive an HTTP error `http.StatusForbidden` and will be rejected from the server. This can be used to, for instance, make a black/white list or implement client sessions.
func SetDeleteAccountCallback ¶
func SetDeleteAccountCallback(cb interface{}) error
SetDeleteAccountCallback sets the callback that triggers when a client deletes their account. The function passed must have the same parameter types as the following example:
func clientDeletedAccount(userName string, databaseID int, receivedColumns map[string]interface{}, clientColumns map[string]interface{}) bool {
//code...
}
`userName` is the name of the User deleting their account, `databaseID` is the index of the User on the database, `receivedColumns` are the custom `AccountInfoColumn` (keys) and their values received from the database, and `clientColumns` have the same keys as the `receivedColumns`, but are the input from the client.
The function returns a boolean. If false is returned, the client will receive a `helpers.ErrorActionDenied` (1052) error and will be denied from deleting the account. This can be used to, for instance, make extra input requirements for this action.
Note: the `clientColumns` decides which `AccountInfoColumn`s were fetched from the database, so the keys will always be the same as `receivedColumns`. You can compare the `receivedColumns` and `clientColumns` to, for instance, compare the keys named 'email' to make sure the client also provided the right email address for that account on the database.
func SetLoginCallback ¶
func SetLoginCallback(cb interface{}) error
SetLoginCallback sets the callback that triggers when a client logs in as a User. The function passed must have the same parameter types as the following example:
func clientLoggedIn(userName string, databaseID int, receivedColumns map[string]interface{}, clientColumns map[string]interface{}) bool {
//code...
}
`userName` is the name of the User logging in, `databaseID` is the index of the User on the database, `receivedColumns` are the custom `AccountInfoColumn` (keys) and their values received from the database, and `clientColumns` have the same keys as the `receivedColumns`, but are the input from the client.
The function returns a boolean. If false is returned, the client will receive a `helpers.ErrorActionDenied` (1052) error and will be denied from logging in. This can be used to, for instance, suspend or ban a User.
Note: the `clientColumns` decides which `AccountInfoColumn`s were fetched from the database, so the keys will always be the same as `receivedColumns`. You can compare the `receivedColumns` and `clientColumns` to, for instance, compare the key 'email' to make sure the client also provided the right email address for that account on the database.
func SetLogoutCallback ¶
func SetLogoutCallback(cb interface{}) error
SetLogoutCallback sets the callback that triggers when a client logs out from a User. The function passed must have the same parameter types as the following example:
func clientLoggedOut(userName string, databaseID int) {
//code...
}
`userName` is the name of the User logging in, `databaseID` is the index of the User on the database.
func SetPasswordChangeCallback ¶
func SetPasswordChangeCallback(cb interface{}) error
SetPasswordChangeCallback sets the callback that triggers when a client changes their password. The function passed must have the same parameter types as the following example:
func clientChangedPassword(userName string, databaseID int, receivedColumns map[string]interface{}, clientColumns map[string]interface{}) bool {
//code...
}
`userName` is the name of the User changing their password, `databaseID` is the index of the User on the database, `receivedColumns` are the custom `AccountInfoColumn` (keys) and their values received from the database, and `clientColumns` have the same keys as the `receivedColumns`, but are the input from the client.
The function returns a boolean. If false is returned, the client will receive a `helpers.ErrorActionDenied` (1052) error and will be denied from changing the password. This can be used to, for instance, make extra input requirements for this action.
Note: the `clientColumns` decides which `AccountInfoColumn`s were fetched from the database, so the keys will always be the same as `receivedColumns`. You can compare the `receivedColumns` and `clientColumns` to, for instance, compare the keys named 'email' to make sure the client also provided the right email address for that account on the database.
func SetPauseCallback ¶
func SetPauseCallback(cb interface{}) error
SetPauseCallback sets the callback that triggers when the server is paused. The function passed must have the same parameter types as the following example:
func serverPaused(){
//code...
}
func SetResumeCallback ¶
func SetResumeCallback(cb interface{}) error
SetResumeCallback sets the callback that triggers when the server is resumed after being paused. The function passed must have the same parameter types as the following example:
func serverResumed(){
//code...
}
func SetShutDownCallback ¶
func SetShutDownCallback(cb interface{}) error
SetShutDownCallback sets the callback that triggers when the server is shut down. The function passed must have the same parameter types as the following example:
func serverStopped(){
//code...
}
func SetSignupCallback ¶
func SetSignupCallback(cb interface{}) error
SetSignupCallback sets the callback that triggers when a client makes an account. The function passed must have the same parameter types as the following example:
func clientSignedUp(userName string, clientColumns map[string]interface{}) bool {
//code...
}
`userName` is the name of the User logging in, `clientColumns` is the input from the client for setting custom `AccountInfoColumn`s on the database.
The function returns a boolean. If false is returned, the client will receive a `helpers.ErrorActionDenied` (1052) error and will be denied from signing up. This can be used to, for instance, deny user names or `AccountInfoColumn`s with profanity.
func SetStartCallback ¶
func SetStartCallback(cb interface{}) error
SetStartCallback sets the callback that triggers when the server first starts up. The function passed must have the same parameter types as the following example:
func serverStarted(){
//code...
}
func ShutDown ¶
func ShutDown() error
ShutDown will log all Users off, save the state of the server if EnableRecovery in ServerSettings is set to true, then shut the server down.
func Start ¶
func Start(s *ServerSettings)
Start will start the server. Call with a pointer to your `ServerSettings` (or nil for defaults) to start the server. The default settings are for local testing ONLY. There are security-related options in `ServerSettings` for SSL/TLS, connection origin testing, administrator tools, and more. It's highly recommended to look into all `ServerSettings` options to tune the server for your desired functionality and security needs.
This function will block the thread that it is ran on until the server either errors, or is manually shut-down. To run code after the server starts/stops/pauses/etc, use the provided server callback setter functions.
Types ¶
type ServerSettings ¶
type ServerSettings struct {
ServerName string // The server's name. Used for the server's ownership of private Rooms. (Required)
MaxConnections int // The maximum amount of concurrent connections the server will accept. Setting this to 0 means infinite.
HostName string // Server's host name. Use 'https://' for TLS connections. (ex: 'https://example.com') (Required)
HostAlias string // Server's host alias name. Use 'https://' for TLS connections. (ex: 'https://www.example.com')
IP string // Server's IP address. (Required)
Port int // Server's port. (Required)
TLS bool // Enables TLS/SSL connections.
CertFile string // SSL/TLS certificate file location (starting from system's root folder). (Required for TLS)
PrivKeyFile string // SSL/TLS private key file location (starting from system's root folder). (Required for TLS)
OriginOnly bool // When enabled, the server declines connections made from outside the origin server (Admin logins always check origin). IMPORTANT: Enable this for web apps and LAN servers.
MultiConnect bool // Enables multiple connections under the same User. When enabled, will override KickDupOnLogin's functionality.
MaxUserConns uint8 // Overrides the default (255) of maximum simultaneous connections on a single User
KickDupOnLogin bool // When enabled, a logged in User will be disconnected from service when another User logs in with the same name.
UserRoomControl bool // Enables Users to create Rooms, invite/uninvite(AKA revoke) other Users to their owned private rooms, and destroy their owned rooms.
RoomDeleteOnLeave bool // When enabled, Rooms created by a User will be deleted when the owner leaves. WARNING: If disabled, you must remember to at some point delete the rooms created by Users, or they will pile up endlessly!
EnableSqlFeatures bool // Enables the built-in SQL User authentication and friending. NOTE: It is HIGHLY recommended to use TLS over an SSL/HTTPS connection when using the SQL features. Otherwise, sensitive User information can be compromised with network "snooping" (AKA "sniffing").
SqlIP string // SQL Database IP address. (Required for SQL features)
SqlPort int // SQL Database port. (Required for SQL features)
SqlProtocol string // The protocol to use while comminicating with the MySQL database. Most use either 'udp' or 'tcp'. (Required for SQL features)
SqlUser string // SQL user name (Required for SQL features)
SqlPassword string // SQL user password (Required for SQL features)
SqlDatabase string // SQL database name (Required for SQL features)
EncryptionCost int // The amount of encryption iterations the server will run when storing and checking passwords. The higher the number, the longer encryptions take, but are more secure. Default is 4, range is 4-31.
CustomLoginColumn string // The custom AccountInfoColumn you wish to use for logging in instead of the default name column.
RememberMe bool // Enables the "Remember Me" login feature. You can read more about this in project's wiki.
EnableRecovery bool // Enables the recovery of all Rooms, their settings, and their variables on start-up after terminating the server.
RecoveryLocation string // The folder location (starting from system's root folder) where you would like to store the recovery data. (Required for recovery)
AdminLogin string // The login name for the Admin Tools (Required for Admin Tools)
AdminPassword string // The password for the Admin Tools (Required for Admin Tools)
}
ServerSettings are the core settings for the Gopher Game Server. You must fill one of these out to customize the server's functionality to your liking.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package actions contains all the tools for making your custom client actions.
|
Package actions contains all the tools for making your custom client actions. |
|
Package core contains all the tools to make and work with Users and Rooms.
|
Package core contains all the tools to make and work with Users and Rooms. |
|
Package database contains helpers for customizing your database with the SQL features enabled.
|
Package database contains helpers for customizing your database with the SQL features enabled. |