lobby

README

Nox lobby server

This project provides a Nox game lobby which exposes a simple HTTP API for both listing and registering Nox game servers.

XWIS games will also appear in the list returned by the API, so the lobby is backward-compatible. Due to technical limitations, however, games registered via HTTP won't be registered on XWIS.

The main use case for the lobby is to support OpenNox, but the API can also be used for bots that want to notify players about currently active Nox games.

Public lobby

To get a list of games on the public lobby:

curl 'http://nox.nwca.xyz:8088/api/v0/games/list'

A Go client library for HTTP API is also available (see docs).

Running locally

The simplest way to run the lobby server locally is via Docker:

docker run -d --restart always --name nox-lobby -p 8080:80 ghcr.io/noxworld-dev/lobby

To get a list of games via local lobby:

curl 'http://127.0.0.1:8080/api/v0/games/list'

Documentation

Index

• Constants
• func KeepRegistered(ctx context.Context, l Registerer, update <-chan time.Time, h GameHost) error
• type Client
  • func NewClient(serverURL string) *Client
  • func NewClientWith(serverURL string, client *http.Client) *Client
  • func (c *Client) ListGames(ctx context.Context) ([]GameInfo, error)
  • func (c *Client) RegisterGame(ctx context.Context, s *Game) error
  • func (c *Client) SetUserAgent(agent string)
• type Game
  • func GameFromXWIS(g *xwis.GameInfo) *Game
  • func (g *Game) Clone() *Game
• type GameAccess
• type GameHost
• type GameInfo
  • func (g *GameInfo) Clone() *GameInfo
• type GameMode
• type IPResp
• type Lister
  • func Cache(l Lister, expire time.Duration) Lister
  • func NewXWISWithClient(c *xwis.Client) Lister
• type Lobby
  • func Overlay(over Lobby, base Lister) Lobby
• type PlayerInfo
• type PlayersInfo
  • func (v *PlayersInfo) Clone() *PlayersInfo
• type QuestInfo
  • func (v *QuestInfo) Clone() *QuestInfo
• type Registerer
• type Resolution
  • func (v *Resolution) Clone() *Resolution
• type Response
• type Server
  • func NewServer(l Lobby) *Server
  • func (api *Server) Address(w http.ResponseWriter, r *http.Request)
  • func (api *Server) RegisterServer(w http.ResponseWriter, r *http.Request)
  • func (api *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (api *Server) ServersList(w http.ResponseWriter, r *http.Request)
• type ServerListResp
• type Service
  • func NewLobby() *Service
  • func (l *Service) ListGames(ctx context.Context) ([]GameInfo, error)
  • func (l *Service) RegisterGame(ctx context.Context, s *Game) error
  • func (l *Service) SetTimeout(dt time.Duration)

Constants

const (
	ModeKOTR        = GameMode("kotr")
	ModeCTF         = GameMode("ctf")
	ModeFlagBall    = GameMode("flagball")
	ModeChat        = GameMode("chat")
	ModeArena       = GameMode("arena")
	ModeElimination = GameMode("elimination")
	ModeQuest       = GameMode("quest")
	ModeCoop        = GameMode("coop")
	ModeCustom      = GameMode("custom")
)

const (
	AccessOpen     = GameAccess("open")
	AccessPassword = GameAccess("pass")
	AccessClosed   = GameAccess("closed")
)

const (
	// DefaultGamePort is a default UDP port for Nox games.
	DefaultGamePort = 18590
)

const (
	DefaultTimeout = time.Minute
)

Functions

func KeepRegistered

func KeepRegistered(ctx context.Context, l Registerer, update <-chan time.Time, h GameHost) error

KeepRegistered keeps registering server so that it doesn't expire.

The update channel sets a pace for updates. If it's set to nil, a default duration will be used.

Once the channel triggers, GameHost.GameInfo is called to acquire fresh game info.

The function returns when context is canceled, if an error is returned from GameHost.GameInfo, or if lobby becomes unavailable.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an HTTP Nox lobby client.

func NewClient

func NewClient(serverURL string) *Client

NewClient will create new client for our server

func NewClientWith

func NewClientWith(serverURL string, client *http.Client) *Client

NewClientWith accepts URL and custom HTTP client to use.

func (*Client) ListGames

func (c *Client) ListGames(ctx context.Context) ([]GameInfo, error)

ListGames implements Lobby.

func (*Client) RegisterGame

func (c *Client) RegisterGame(ctx context.Context, s *Game) error

RegisterGame implements Lobby.

func (*Client) SetUserAgent

func (c *Client) SetUserAgent(agent string)

SetUserAgent sets the User-Agent header for requests. Format should be "AppName/1.2.3". It is advised to set this to something unique for each app using this library.

type Game

type Game struct {
	Name    string      `json:"name"`
	Address string      `json:"addr,omitempty"`
	Port    int         `json:"port,omitempty"`
	Map     string      `json:"map"`
	Mode    GameMode    `json:"mode"`
	Access  GameAccess  `json:"access,omitempty"`
	Vers    string      `json:"vers,omitempty"`
	Res     Resolution  `json:"res,omitempty"`
	Players PlayersInfo `json:"players"`
	Quest   *QuestInfo  `json:"quest,omitempty"`
}

Game is an information about the Nox game, as provided by the server hosting it. See GameInfo for an information returned by the lobby server.

func GameFromXWIS

func GameFromXWIS(g *xwis.GameInfo) *Game

GameFromXWIS convert xwis.GameInfo to Game type defined by lobby.

func (*Game) Clone

func (g *Game) Clone() *Game

type GameAccess

type GameAccess string

GameAccess specifies access for the game (open, password-protected, etc).

type GameHost

type GameHost interface {
	// GameInfo returns current information about the active game.
	GameInfo(ctx context.Context) (*Game, error)
}

GameHost is an interface for the game server.

type GameInfo

type GameInfo struct {
	Game
	SeenAt time.Time `json:"seen_at,omitempty"`
}

GameInfo is a full information for a registered Nox game, as returned by the Lobby. It extends Game with additional information.

func (*GameInfo) Clone

func (g *GameInfo) Clone() *GameInfo

type GameMode

type GameMode string

GameMode is a Nox game mode.

type IPResp

type IPResp struct {
	IP string `json:"ip"`
}

IPResp represents a response to the address request.

type Lister

type Lister interface {
	// ListGames returns a sorted list of games registered on this lobby.
	ListGames(ctx context.Context) ([]GameInfo, error)
}

Lister is an interface for listing Nox games registered on lobby server.

func Cache

func Cache(l Lister, expire time.Duration) Lister

Cache creates a cache over a game Lister. Expiration time controls how often the cache is invalidated.

func NewXWISWithClient

func NewXWISWithClient(c *xwis.Client) Lister

NewXWISWithClient creates a Lister for a Nox XWIS lobby using an existing xwis.Client.

type Lobby

type Lobby interface {
	Registerer
	Lister
}

Lobby is a Nox game lobby for listing and registering games.

func Overlay

func Overlay(over Lobby, base Lister) Lobby

Overlay one lobby implementation over a second one. Games from the overlay will override games from the base. Registration will happen only on the overlay Lobby.

type PlayerInfo

type PlayerInfo struct {
	Name  string `json:"name"`
	Class string `json:"class,omitempty"`
}

PlayerInfo is an information about a specific player.

type PlayersInfo

type PlayersInfo struct {
	Cur  int          `json:"cur"`
	Max  int          `json:"max"`
	List []PlayerInfo `json:"list,omitempty"`
}

PlayersInfo is an information about players in a specific game.

func (*PlayersInfo) Clone

func (v *PlayersInfo) Clone() *PlayersInfo

type QuestInfo

type QuestInfo struct {
	Stage int `json:"stage"`
}

QuestInfo is additional information for Nox Quest game mode.

func (*QuestInfo) Clone

func (v *QuestInfo) Clone() *QuestInfo

type Registerer

type Registerer interface {
	// RegisterGame registers new game or updates the registration for existing game.
	// The client must call this method periodically to not let the game registration to expire.
	// Using a duration smaller than DefaultTimeout is advised.
	RegisterGame(ctx context.Context, s *Game) error
}

Registerer is an interface for registering Nox games on lobby server.

type Resolution

type Resolution struct {
	HighRes bool `json:"high_res,omitempty"`
	Width   int  `json:"width,omitempty"`
	Height  int  `json:"height,omitempty"`
}

Resolution is a max resolution used for the game. Historically Nox used a limited resolution. For HD-aware servers, HighRes should be set.

func (*Resolution) Clone

func (v *Resolution) Clone() *Resolution

type Response

type Response struct {
	Result interface{} `json:"data,omitempty"`
	Err    string      `json:"error,omitempty"`
}

Response wraps all other HTTP responses to separate errors from the rest of the response.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is an HTTP Nox lobby server.

func NewServer

func NewServer(l Lobby) *Server

NewServer creates a new http.Handler from a Lobby implementation.

func (*Server) Address

func (api *Server) Address(w http.ResponseWriter, r *http.Request)

func (*Server) RegisterServer

func (api *Server) RegisterServer(w http.ResponseWriter, r *http.Request)

func (*Server) ServeHTTP

func (api *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Server) ServersList

func (api *Server) ServersList(w http.ResponseWriter, r *http.Request)

type ServerListResp

type ServerListResp []GameInfo

ServerListResp represents a response to the server list request.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is an in-memory implementation of a Lobby.

func NewLobby

func NewLobby() *Service

NewLobby creates a new in-memory Lobby.

func (*Service) ListGames

func (l *Service) ListGames(ctx context.Context) ([]GameInfo, error)

ListGames implements Lobby.

func (*Service) RegisterGame

func (l *Service) RegisterGame(ctx context.Context, s *Game) error

RegisterGame implements Lobby.

func (*Service) SetTimeout

func (l *Service) SetTimeout(dt time.Duration)

SetTimeout sets an expiration time for game registrations.