server

Documentation

Overview

Package server implements a high-level implementation of a Minecraft server. Creating such a server may be done using the `server.New()` function. Additional configuration may be passed by using server.Config{...}.New(). `Server.Listen()` may be called to start and run the server. It should be followed up by a loop as such:

  for srv.Accept(nil) {
	 }

`Server.Accept()` blocks until a new player connects to the server and spawns in the default world, and calls the function passed to it once this happens. If `Server.Accept()` returns false, this means the server was closed.

Index

• type Allower
• type Config
  • func (conf Config) New() *Server
• type HandleFunc
• type Listener
• type Server
  • func New() *Server
  • func (srv *Server) Accept(f HandleFunc) bool
  • func (srv *Server) Close() error
  • func (srv *Server) CloseOnProgramEnd()
  • func (srv *Server) End() *world.World
  • func (srv *Server) Listen()
  • func (srv *Server) MaxPlayerCount() int
  • func (srv *Server) Nether() *world.World
  • func (srv *Server) Player(uuid uuid.UUID) (*player.Player, bool)
  • func (srv *Server) PlayerByName(name string) (*player.Player, bool)
  • func (srv *Server) PlayerByXUID(xuid string) (*player.Player, bool)
  • func (srv *Server) Players() []*player.Player
  • func (srv *Server) World() *world.World
• type UserConfig
  • func DefaultConfig() UserConfig
  • func (uc UserConfig) Config(log *slog.Logger) (Config, error)

Types

type Allower

type Allower interface {
	// Allow filters what connections are allowed to connect to the Server. The
	// address, identity data, and client data of the connection are passed. If
	// Admit returns false, the connection is closed with the string returned as
	// the disconnect message. WARNING: Use the client data at your own risk, it
	// cannot be trusted because it can be freely changed by the player
	// connecting.
	Allow(addr net.Addr, d login.IdentityData, c login.ClientData) (string, bool)
}

Allower may be implemented to specifically allow or disallow players from joining a Server, by setting the specific Allower implementation through a call to Server.Allow.

type Config

type Config struct {
	// Log is the Logger to use for logging information. If nil, Log is set to
	// slog.Default(). Errors reported by the underlying network are only logged
	// if Log has at least debug level.
	Log *slog.Logger
	// Listeners is a list of functions to create a Listener using a Config, one
	// for each Listener to be added to the Server. If left empty, no players
	// will be able to connect to the Server.
	Listeners []func(conf Config) (Listener, error)
	// Name is the name of the server. By default, it is shown to users in the
	// server list before joining the server and when opening the in-game menu.
	Name string
	// Resources is a slice of resource packs to use on the server. When joining
	// the server, the player will then first be requested to download these
	// resource packs.
	Resources []*resource.Pack
	// ResourcesRequires specifies if the downloading of resource packs is
	// required to join the server. If set to true, players will not be able to
	// join without first downloading and applying the Resources above.
	ResourcesRequired bool
	// DisableResourceBuilding specifies if automatic resource pack building for
	// custom items should be disabled. Dragonfly, by default, automatically
	// produces a resource pack for custom items. If this is not desired (for
	// example if a resource pack already exists), this can be set to false.
	DisableResourceBuilding bool
	// Allower may be used to specify what players can join the server and what
	// players cannot. By returning false in the Allow method, for example if
	// the player has been banned, will prevent the player from joining.
	Allower Allower
	// AuthDisabled specifies if XBOX Live authentication should be disabled.
	// Note that this should generally only be done for testing purposes or for
	// local games. Allowing players to join without authentication is generally
	// a security hazard.
	AuthDisabled bool
	// MaxPlayers is the maximum amount of players allowed to join the server at
	// once.
	MaxPlayers int
	// MaxChunkRadius is the maximum view distance that each player may have,
	// measured in chunks. A chunk radius generally leads to more memory usage.
	MaxChunkRadius int
	// JoinMessage, QuitMessage and ShutdownMessage are the messages to send for
	// when a player joins or quits the server and when the server shuts down,
	// kicking all online players. JoinMessage and QuitMessage may have a '%v'
	// argument, which will be replaced with the name of the player joining or
	// quitting.
	JoinMessage, QuitMessage, ShutdownMessage string
	// PlayerProvider is the player.Provider used for storing and loading player
	// data. If left as nil, player data will be newly created every time a
	// player joins the server and no data will be stored.
	PlayerProvider player.Provider
	// WorldProvider is the world.Provider used for storing and loading world
	// data. If left as nil, world data will be newly created every time and
	// chunks will always be newly generated when loaded. The world provider
	// will be used for storing/loading the default overworld, nether and end.
	WorldProvider world.Provider
	// ReadOnlyWorld specifies if the standard worlds should be read only. If
	// set to true, the WorldProvider won't be saved to at all.
	ReadOnlyWorld bool
	// Generator should return a function that specifies the world.Generator to
	// use for every world.Dimension (world.Overworld, world.Nether and
	// world.End). If left empty, Generator will be set to a flat world for each
	// of the dimensions (with netherrack and end stone for nether/end
	// respectively).
	Generator func(dim world.Dimension) world.Generator
	// RandomTickSpeed specifies the rate at which blocks should be ticked in
	// the default worlds. Setting this value to -1 or lower will stop random
	// ticking altogether, while setting it higher results in faster ticking. If
	// left as 0, the RandomTickSpeed will default to a speed of 3 blocks per
	// sub chunk per tick (normal ticking speed).
	RandomTickSpeed int
	// Entities is a world.EntityRegistry with all entity types registered that
	// may be added to the Server's worlds. If no entity types are registered,
	// Entities will be set to entity.DefaultRegistry.
	Entities world.EntityRegistry
}

Config contains options for starting a Minecraft server.

func (Config) New

func (conf Config) New() *Server

New creates a Server using fields of conf. The Server's worlds are created and connections from the Server's listeners may be accepted by calling Server.Listen() and Server.Accept() afterwards.

type HandleFunc

type HandleFunc func(p *player.Player)

HandleFunc is a function that may be passed to Server.Accept(). It can be used to prepare the session of a player before it can do anything.

type Listener

type Listener interface {
	// Accept blocks until the next connection is established and returns it. An error is returned if the Listener was
	// closed using Close.
	Accept() (session.Conn, error)
	// Disconnect disconnects a connection from the Listener with a reason.
	Disconnect(conn session.Conn, reason string) error
	io.Closer
}

Listener is a source for connections that may be listened on by a Server using Server.listen. Proxies can use this to provide players from a different source.

type Server

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

Server implements a Dragonfly server. It runs the main server loop and handles the connections of players trying to join the server.

func New

func New() *Server

New creates a Server using a default Config. The Server's worlds are created and connections from the Server's listeners may be accepted by calling Server.Listen() and Server.Accept() afterwards.

func (*Server) Accept

func (srv *Server) Accept(f HandleFunc) bool

Accept accepts an incoming player into the server. It blocks until a player connects to the server. A HandleFunc may be passed which is run immediately before a *player.Player is accepted to the Server. This function may be used to add a player.Handler to the player and prepare its session. The function may be nil if player joining does not need to be handled. Accept returns false if the Server is closed using a call to Close.

func (*Server) Close

func (srv *Server) Close() error

Close closes the server, making any call to Run/Accept cancel immediately.

func (*Server) CloseOnProgramEnd

func (srv *Server) CloseOnProgramEnd()

CloseOnProgramEnd closes the server right before the program ends, so that all data of the server are saved properly.

func (*Server) End

func (srv *Server) End() *world.World

End returns the end world of the server. Players are transported to it when entering an end portal in the world returned by the World method.

func (*Server) Listen

func (srv *Server) Listen()

Listen starts running the server's listeners but does not block, unlike Run. Connections will be accepted on a different goroutine until the listeners are closed using a call to Close. Once started, players may be accepted using Server.Accept().

func (*Server) MaxPlayerCount

func (srv *Server) MaxPlayerCount() int

MaxPlayerCount returns the maximum amount of players that are allowed to play on the server at the same time. Players trying to join when the server is full will be refused to enter. If the config has a maximum player count set to 0, MaxPlayerCount will return Server.PlayerCount + 1.

func (*Server) Nether

func (srv *Server) Nether() *world.World

Nether returns the nether world of the server. Players are transported to it when entering a nether portal in the world returned by the World method.

func (*Server) Player

func (srv *Server) Player(uuid uuid.UUID) (*player.Player, bool)

Player looks for a player on the server with the UUID passed. If found, the player is returned and the bool returns holds a true value. If not, the bool returned is false and the player is nil.

func (*Server) PlayerByName

func (srv *Server) PlayerByName(name string) (*player.Player, bool)

PlayerByName looks for a player on the server with the name passed. If found, the player is returned and the bool returns holds a true value. If not, the bool is false and the player is nil

func (*Server) PlayerByXUID

func (srv *Server) PlayerByXUID(xuid string) (*player.Player, bool)

PlayerByXUID looks for a player on the server with the XUID passed. If found, the player is returned and the bool returned is true. If no player with the XUID was found, nil and false are returned.

func (*Server) Players

func (srv *Server) Players() []*player.Player

Players returns a list of all players currently connected to the server. Note that the slice returned is not updated when new players join or leave, so it is only valid for as long as no new players join or players leave.

func (*Server) World

func (srv *Server) World() *world.World

World returns the overworld of the server. Players will be spawned in this world and this world will be read from and written to when the world is edited.

type UserConfig

type UserConfig struct {
	// Network holds settings related to network aspects of the server.
	Network struct {
		// Address is the address on which the server should listen. Players may
		// connect to this address in order to join.
		Address string
	}
	Server struct {
		// Name is the name of the server as it shows up in the server list.
		Name string
		// ShutdownMessage is the message shown to players when the server shuts
		// down. If empty, players will be directed to the menu screen right
		// away.
		ShutdownMessage string
		// AuthEnabled controls whether players must be connected to Xbox Live
		// in order to join the server.
		AuthEnabled bool
		// JoinMessage is the message that appears when a player joins the
		// server. Leave this empty to disable it. %v is the placeholder for the
		// username of the player
		JoinMessage string
		// QuitMessage is the message that appears when a player leaves the
		// server. Leave this empty to disable it. %v is the placeholder for the
		// username of the player
		QuitMessage string
	}
	World struct {
		// SaveData controls whether a world's data will be saved and loaded.
		// If true, the server will use the default LevelDB data provider and if
		// false, an empty provider will be used. To use your own provider, turn
		// this value to false, as you will still be able to pass your own
		// provider.
		SaveData bool
		// Folder is the folder that the data of the world resides in.
		Folder string
	}
	Players struct {
		// MaxCount is the maximum amount of players allowed to join the server
		// at the same time. If set to 0, the amount of maximum players will
		// grow every time a player joins.
		MaxCount int
		// MaximumChunkRadius is the maximum chunk radius that players may set
		// in their settings. If they try to set it above this number, it will
		// be capped and set to the max.
		MaximumChunkRadius int
		// SaveData controls whether a player's data will be saved and loaded.
		// If true, the server will use the default LevelDB data provider and if
		// false, an empty provider will be used. To use your own provider, turn
		// this value to false, as you will still be able to pass your own
		// provider.
		SaveData bool
		// Folder controls where the player data will be stored by the default
		// LevelDB player provider if it is enabled.
		Folder string
	}
	Resources struct {
		// AutoBuildPack is if the server should automatically generate a
		// resource pack for custom features.
		AutoBuildPack bool
		// Folder controls the location where resource packs will be loaded
		// from.
		Folder string
		// Required is a boolean to force the client to load the resource pack
		// on join. If they do not accept, they'll have to leave the server.
		Required bool
	}
}

UserConfig is the user configuration for a Dragonfly server. It holds settings that affect different aspects of the server, such as its name and maximum players. UserConfig may be serialised and can be converted to a Config by calling UserConfig.Config().

func DefaultConfig

func DefaultConfig() UserConfig

DefaultConfig returns a configuration with the default values filled out.

func (UserConfig) Config

func (uc UserConfig) Config(log *slog.Logger) (Config, error)

Config converts a UserConfig to a Config, so that it may be used for creating a Server. An error is returned if creating data providers or loading resources failed.