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, which accepts a `*Config` and a logger implementation. Nil may be passed as config to use the default config. After creation of the server, `Server.Start()` 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 DefaultConfig() Config
• type HandleFunc
• type Listener
• type Logger
• type Server
  • func New(c *Config, log Logger) *Server
  • func (srv *Server) Accept(f HandleFunc) bool
  • func (srv *Server) AddResourcePack(pack *resource.Pack)
  • func (srv *Server) Allow(a Allower)
  • func (srv *Server) Close() error
  • func (srv *Server) CloseOnProgramEnd()
  • func (srv *Server) End() *world.World
  • func (srv *Server) JoinMessage(a ...any)
  • func (srv *Server) Listen(l Listener)
  • 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) PlayerCount() int
  • func (srv *Server) PlayerProvider(provider player.Provider)
  • func (srv *Server) Players() []*player.Player
  • func (srv *Server) QuitMessage(a ...any)
  • func (srv *Server) Resources() []*resource.Pack
  • func (srv *Server) SetName(a ...any)
  • func (srv *Server) Start() error
  • func (srv *Server) World() *world.World

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 {
	// 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 {
		// Name is the name of the world that the server holds. A world with this name will be loaded and
		// the name will be displayed at the top of the player list in the in-game pause menu.
		Name string
		// 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
	}
	// WorldConfig, if non-nil, is called for every default world that a Server creates. It may be used to change the
	// world.Config that these worlds are created with. The default world.Config is passed to the function and should
	// be edited, then returned by the WorldConfig function.
	WorldConfig func(def world.Config) world.Config `toml:"-"`
}

Config is the configuration of a Dragonfly server. It holds settings that affect different aspects of the server, such as its name and maximum players.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a configuration with the default values filled out.

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 Logger

type Logger interface {
	world.Logger
	session.Logger
	Infof(format string, v ...any)
	Fatalf(format string, v ...any)
}

Logger is used to report information and errors from a dragonfly Server. Any Logger implementation may be used by passing it to server.New.

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(c *Config, log Logger) *Server

New returns a new server using the Config passed. If nil is passed, a default configuration is returned. (A call to server.DefaultConfig().) The Logger passed will be used to log errors and information to. If nil is passed, a default Logger is used by calling logrus.New(). Note that no two servers should be active at the same time. Doing so anyway will result in unexpected behaviour.

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) AddResourcePack

func (srv *Server) AddResourcePack(pack *resource.Pack)

AddResourcePack loads a resource pack to the server. The pack will eventually be sent to clients who join the server when started.

func (*Server) Allow

func (srv *Server) Allow(a Allower)

Allow makes the Server filter which connections to the Server are accepted. Connections on which the Allower returns false are rejected immediately. If nil is passed, all connections are accepted.

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) JoinMessage

func (srv *Server) JoinMessage(a ...any)

JoinMessage changes the join message for all players on the server. Leave this empty to disable it. %v is the placeholder for the username of the player

func (*Server) Listen

func (srv *Server) Listen(l Listener)

Listen makes the Server listen for new connections from the Listener passed. This may be used to listen for players on different interfaces. Note that the maximum player count of additional Listeners added is not enforced automatically. The limit must be enforced by the Listener.

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) PlayerCount

func (srv *Server) PlayerCount() int

PlayerCount returns the current player count of the server. It is equivalent to calling len(server.Players()).

func (*Server) PlayerProvider

func (srv *Server) PlayerProvider(provider player.Provider)

PlayerProvider changes the data provider of a player to the provider passed. The provider will dictate the behaviour of player saving and loading. If nil is passed, the NopProvider will be used which does not read or write any data.

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) QuitMessage

func (srv *Server) QuitMessage(a ...any)

QuitMessage changes the leave message for all players on the server. Leave this empty to disable it. %v is the placeholder for the username of the player

func (*Server) Resources

func (srv *Server) Resources() []*resource.Pack

Resources returns a list of all resource packs currently loaded on the server.

func (*Server) SetName

func (srv *Server) SetName(a ...any)

SetName sets the name of the Server, also known as the MOTD. This name is displayed in the server list. The formatting of the name passed follows the rules of fmt.Sprint.

func (*Server) Start

func (srv *Server) Start() error

Start runs the server but does not block, unlike Run, but instead accepts connections on a different goroutine. Connections will be accepted until the listener is closed using a call to Close. Once started, players may be accepted using Server.Accept().

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.