README
¶
Unity Game Server Hosting Server Library
A Golang game server can be integrated with the platform quickly by using this library. A fully-formed usage example can be found here.
Short Demonstration
A basic server can be set up by using the server.New() function with the Start(), Stop() and message channels:
package main
import "github.com/Unity-Technologies/unity-gaming-services-go-sdk/game-server-hosting/server"
func main() {
s, err := server.New(server.TypeAllocation)
if err != nil {
// ...
}
// Handle server events (i.e. allocation, deallocation, errors)
done := make(chan struct{})
go handleEvents(s, done)
if err = s.Start(); err != nil {
// ...
}
if err = s.WaitUntilTerminated(); err != nil {
close(done)
// ...
}
}
func handleEvents(s *server.Server, done chan struct{}) {
for {
select {
case <-s.OnAllocate():
// handle allocation
case <-s.OnDeallocate():
// handle deallocation
case <-s.OnError():
// handle error
case <-s.OnConfigurationChanged():
// handle configuration change
case <-done:
return
}
}
}
Documentation
¶
Index ¶
- Constants
- Variables
- type Config
- type Option
- type QueryProtocol
- type Server
- func (s *Server) Config() Config
- func (s *Server) OnAllocate() <-chan string
- func (s *Server) OnConfigurationChanged() <-chan Config
- func (s *Server) OnDeallocate() <-chan string
- func (s *Server) OnError() <-chan error
- func (s *Server) PlayerJoined() int32
- func (s *Server) PlayerLeft() int32
- func (s *Server) PushError(err error)
- func (s *Server) SetGameMap(gameMap string)
- func (s *Server) SetGameType(gameType string)
- func (s *Server) SetMaxPlayers(max int32)
- func (s *Server) SetServerName(name string)
- func (s *Server) Start() error
- func (s *Server) Stop() error
- func (s *Server) WaitUntilTerminated() error
- type Type
Constants ¶
const ( // QueryProtocolA2S represents the 'a2s' query protocol. // Although A2S is supported, SQP is the recommended query implementation. // Documentation: https://docs.unity.com/game-server-hosting/en/manual/concepts/a2s QueryProtocolA2S = QueryProtocol("a2s") // QueryProtocolSQP represents the 'sqp' query protocol. // SQP is the recommended query protocol. // Documentation: https://docs.unity.com/game-server-hosting/en/manual/concepts/sqp QueryProtocolSQP = QueryProtocol("sqp") // QueryProtocolRecommended represents the recommended query protocol. QueryProtocolRecommended )
const ( // TypeAllocation represents a server which is using the 'allocations' model of server usage. TypeAllocation = Type(iota) // TypeReservation represents a server which is using the 'reservations' model of server usage. TypeReservation )
const ( // DefaultWriteBufferSizeBytes represents the default size of the write buffer for the query handler. DefaultWriteBufferSizeBytes = 1024 // DefaultWriteDeadlineDuration represents the default write deadline duration for responding in the query handler. DefaultWriteDeadlineDuration = 1 * time.Second // DefaultReadDeadlineDuration represents the default read deadline duration for consuming a query request. DefaultReadDeadlineDuration = 3 * time.Second // DefaultReadBufferSizeBytes represents the default size of the read buffer for the query handler. DefaultReadBufferSizeBytes = 1024 )
Variables ¶
var ErrReservationsNotYetSupported = errors.New("reservations are not yet supported")
ErrReservationsNotYetSupported represents that a reservation-based server is not yet supported by the SDK.
var ErrUnsupportedQueryType = errors.New("supplied query type is not supported")
ErrUnsupportedQueryType is an error that specifies the provided query type is not supported by this library.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// AllocatedUUID is the allocation ID provided to an event.
AllocatedUUID string `json:"allocatedUUID"`
// IP is the IPv4 address of this server.
IP string `json:"ip"`
// IPV6 is the IPv6 address of this server. This can be empty.
IPv6 string `json:"ipv6"`
// LocalProxyURL is the URL to the local proxy service, which can handle interactions with the allocations payload store.
LocalProxyURL string `json:"localProxyUrl"`
// Port is the port number this server uses for game interactions. It is up to the implemented to bind their game
// server to this port.
Port json.Number `json:"port"`
// QueryPort is the port number this server uses for query interactions. These interactions are handled over UDP.
QueryPort json.Number `json:"queryPort"`
// QueryType represents the query protocol used by this server.
QueryType QueryProtocol `json:"queryType"`
// ServerID is the ID of the running server in the Unity Game Server Hosting platform.
ServerID json.Number `json:"serverID"`
// ServerLogDir is the directory where the server should place its log files. These will be detected by Unity Game Server
// Hosting and made available in the dashboard.
ServerLogDir string `json:"serverLogDir"`
// Extra represents any other arguments passed to this server, for example, those specified in a build configuration.
Extra map[string]string `json:"-"`
}
Config represents the game server configuration variables provided from the Unity Game Server Hosting platform.
type Option ¶
type Option func(s *Server)
Option represents a function that modifies a property of the game server.
func WithConfigPath ¶
WithConfigPath sets the configuration file to use when starting the server. In most circumstances, the default value is reasonable to use.
func WithQueryReadBuffer ¶
WithQueryReadBuffer sets the read buffer size for the query handler.
func WithQueryReadDeadlineDuration ¶ added in v0.2.0
WithQueryReadDeadlineDuration sets the read deadline duration for consuming query requests in the query handler.
func WithQueryWriteBuffer ¶
WithQueryWriteBuffer sets the write buffer size for the query handler.
func WithQueryWriteDeadlineDuration ¶
WithQueryWriteDeadlineDuration sets the write deadline duration for responding to query requests in the query handler.
type QueryProtocol ¶
type QueryProtocol string
QueryProtocol represents the query type the server uses. Documentation: https://docs.unity.com/game-server-hosting/en/manual/concepts/query-protocols
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server represents an instance of a game server, handling changes to configuration and responding to query requests.
func (*Server) OnAllocate ¶
OnAllocate returns a read-only channel that receives messages when the server is allocated.
func (*Server) OnConfigurationChanged ¶
OnConfigurationChanged returns a read-only channel that receives messages when the server detects a change in the configuration file.
func (*Server) OnDeallocate ¶
OnDeallocate returns a read-only channel that receives messages when the server is de-allocated.
func (*Server) OnError ¶
OnError returns a read-only channel that receives messages when the server encounters an error.
func (*Server) PlayerJoined ¶
PlayerJoined indicates a new player has joined the server.
func (*Server) PlayerLeft ¶
PlayerLeft indicates a player has left the server.
func (*Server) PushError ¶
PushError pushes an error to a channel consumer. Listening for errors is optional, so this makes sure we don't deadlock if nobody is listening.
func (*Server) SetGameMap ¶
SetGameMap sets the server game map for query / metrics purposes.
func (*Server) SetGameType ¶
SetGameType sets the server game type for query / metrics purposes.
func (*Server) SetMaxPlayers ¶
SetMaxPlayers sets the maximum players this server will host. It does not enforce this number, it only serves for query / metrics.
func (*Server) SetServerName ¶
SetServerName sets the server name for query / metrics purposes.
func (*Server) Start ¶
Start starts the server, opening the configured query port which responds with the configured protocol. The event loop will also listen for changes to the `server.json` configuration file, publishing any changes in the form of allocation or de-allocation messages. As the server can start in an allocated state, make sure that another goroutine is consuming messages from at least the `OnAllocated()` and `OnDeallocated()` channels before calling this method.
func (*Server) Stop ¶
Stop stops the game, pushing a de-allocation message and closing the query port.
func (*Server) WaitUntilTerminated ¶
WaitUntilTerminated waits until the server receives a termination signal from the platform. The Unity Gaming Services process management daemon will signal the game server to stop. A graceful stop signal (SIGTERM) will be sent if the game server fleet has been configured to support it.
Source Files
Directories