golem

package module
v0.0.0-...-ad8f84f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 14, 2026 License: MIT Imports: 7 Imported by: 0

README

golem

CI Go License

Typed Go client for Minecraft Java RCON built on top of github.com/gorcon/rcon.

Compatibility

golem sends plain Minecraft commands by default, such as difficulty, time query time, and whitelist list.

This is the compatibility baseline for the library because plain commands work on:

  • Vanilla
  • Fabric
  • Paper

Testing

Fast tests:

go test ./...

Integration tests against a live vanilla server container:

go test -tags=integration ./...

Or via make:

make test

Documentation

Overview

Package golem provides a typed Minecraft Java RCON client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddWhitelistUserInput

type AddWhitelistUserInput struct {
	Player string
}

AddWhitelistUserInput adds a player to the whitelist.

type AddWhitelistUserResult

type AddWhitelistUserResult struct {
	Player string
}

AddWhitelistUserResult reports the added player.

type BanEntry

type BanEntry struct {
	Reason string
	Source string
	Target string
}

BanEntry describes a single ban list entry.

type BanIPInput

type BanIPInput struct {
	Address string
	Reason  string
}

BanIPInput bans an IP address, optionally with a reason.

type BanIPResult

type BanIPResult struct {
	Address string
}

BanIPResult reports the banned IP address.

type BanListType

type BanListType string

BanListType represents a filter for the ban list.

const (
	BanListTypeIPs     BanListType = "ips"
	BanListTypePlayers BanListType = "players"
)

type BanPlayerInput

type BanPlayerInput struct {
	Player string
	Reason string
}

BanPlayerInput bans a player, optionally with a reason.

type BanPlayerResult

type BanPlayerResult struct {
	Player string
}

BanPlayerResult reports the banned player.

type BroadcastMessageInput

type BroadcastMessageInput struct {
	Message string
}

BroadcastMessageInput broadcasts a chat message.

type BroadcastMessageResult

type BroadcastMessageResult struct {
	Message string
}

BroadcastMessageResult reports the broadcast message.

type Client

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

Client implements MinecraftClient on top of an RCON executor.

func NewClient

func NewClient(conn *rcon.Conn) *Client

NewClient returns a Client backed by a gorcon RCON connection.

func NewClientWithExecutor

func NewClientWithExecutor(executor Executor) (*Client, error)

NewClientWithExecutor returns a Client backed by a custom executor.

func (*Client) AddWhitelistUser

func (c *Client) AddWhitelistUser(
	ctx context.Context,
	input AddWhitelistUserInput,
) (*Response[AddWhitelistUserResult], error)

AddWhitelistUser adds a player to the whitelist.

func (*Client) BanIP

func (c *Client) BanIP(ctx context.Context, input BanIPInput) (*Response[BanIPResult], error)

BanIP bans an IP address.

func (*Client) BanPlayer

func (c *Client) BanPlayer(ctx context.Context, input BanPlayerInput) (*Response[BanPlayerResult], error)

BanPlayer bans a player.

func (*Client) BroadcastMessage

func (c *Client) BroadcastMessage(
	ctx context.Context,
	input BroadcastMessageInput,
) (*Response[BroadcastMessageResult], error)

BroadcastMessage broadcasts a message to the server.

func (*Client) DeopPlayer

func (c *Client) DeopPlayer(ctx context.Context, input DeopPlayerInput) (*Response[DeopPlayerResult], error)

DeopPlayer removes operator status from a player.

func (*Client) DisableAutoSave

func (c *Client) DisableAutoSave(ctx context.Context) (*Response[DisableAutoSaveResult], error)

DisableAutoSave disables automatic world saves.

func (*Client) DisableWhitelist

func (c *Client) DisableWhitelist(ctx context.Context) (*Response[DisableWhitelistResult], error)

DisableWhitelist disables the whitelist.

func (*Client) EnableAutoSave

func (c *Client) EnableAutoSave(ctx context.Context) (*Response[EnableAutoSaveResult], error)

EnableAutoSave enables automatic world saves.

func (*Client) EnableWhitelist

func (c *Client) EnableWhitelist(ctx context.Context) (*Response[EnableWhitelistResult], error)

EnableWhitelist enables the whitelist.

func (*Client) GetBooleanGameRule

func (c *Client) GetBooleanGameRule(
	ctx context.Context,
	input GetBooleanGameRuleInput,
) (*Response[GetBooleanGameRuleResult], error)

GetBooleanGameRule returns the current value of a boolean game rule.

func (*Client) GetDifficulty

func (c *Client) GetDifficulty(ctx context.Context) (*Response[GetDifficultyResult], error)

GetDifficulty returns the current difficulty.

func (*Client) GetGameRule

func (c *Client) GetGameRule(ctx context.Context, input GetGameRuleInput) (*Response[GetGameRuleResult], error)

GetGameRule returns the current value of a game rule.

func (*Client) GetIntegerGameRule

func (c *Client) GetIntegerGameRule(
	ctx context.Context,
	input GetIntegerGameRuleInput,
) (*Response[GetIntegerGameRuleResult], error)

GetIntegerGameRule returns the current value of an integer game rule.

func (*Client) GetSeed

func (c *Client) GetSeed(ctx context.Context) (*Response[GetSeedResult], error)

GetSeed returns the world seed.

func (*Client) GetTime

func (c *Client) GetTime(ctx context.Context, input GetTimeInput) (*Response[GetTimeResult], error)

GetTime returns a selected time counter.

func (*Client) GetVersion

func (c *Client) GetVersion(ctx context.Context) (*Response[GetVersionResult], error)

GetVersion returns the server version string.

func (*Client) KickPlayer

func (c *Client) KickPlayer(ctx context.Context, input KickPlayerInput) (*Response[KickPlayerResult], error)

KickPlayer kicks a player.

func (*Client) ListBans

func (c *Client) ListBans(ctx context.Context, input ListBansInput) (*Response[ListBansResult], error)

ListBans returns bans for the selected filter.

func (*Client) ListUsers

func (c *Client) ListUsers(ctx context.Context) (*Response[ListUsersResult], error)

ListUsers returns online players.

func (*Client) ListWhitelistUsers

func (c *Client) ListWhitelistUsers(ctx context.Context) (*Response[ListWhitelistUsersResult], error)

ListWhitelistUsers returns whitelisted players.

func (*Client) OpPlayer

func (c *Client) OpPlayer(ctx context.Context, input OpPlayerInput) (*Response[OpPlayerResult], error)

OpPlayer grants operator status to a player.

func (*Client) PardonIP

func (c *Client) PardonIP(ctx context.Context, input PardonIPInput) (*Response[PardonIPResult], error)

PardonIP removes an IP ban.

func (*Client) PardonPlayer

func (c *Client) PardonPlayer(ctx context.Context, input PardonPlayerInput) (*Response[PardonPlayerResult], error)

PardonPlayer removes a player ban.

func (*Client) ReloadData

func (c *Client) ReloadData(ctx context.Context) (*Response[ReloadDataResult], error)

ReloadData reloads data packs, loot tables, and functions from disk.

func (*Client) ReloadWhitelist

func (c *Client) ReloadWhitelist(ctx context.Context) (*Response[ReloadWhitelistResult], error)

ReloadWhitelist reloads the whitelist from disk.

func (*Client) RemoveWhitelistUser

func (c *Client) RemoveWhitelistUser(
	ctx context.Context,
	input RemoveWhitelistUserInput,
) (*Response[RemoveWhitelistUserResult], error)

RemoveWhitelistUser removes a player from the whitelist.

func (*Client) SaveAll

func (c *Client) SaveAll(ctx context.Context) (*Response[SaveAllResult], error)

SaveAll saves the world to disk.

func (*Client) SetBooleanGameRule

func (c *Client) SetBooleanGameRule(
	ctx context.Context,
	input SetBooleanGameRuleInput,
) (*Response[SetBooleanGameRuleResult], error)

SetBooleanGameRule sets a boolean game rule value.

func (*Client) SetDefaultGameMode

func (c *Client) SetDefaultGameMode(
	ctx context.Context,
	input SetDefaultGameModeInput,
) (*Response[SetDefaultGameModeResult], error)

SetDefaultGameMode sets the default game mode.

func (*Client) SetDifficulty

func (c *Client) SetDifficulty(
	ctx context.Context,
	input SetDifficultyInput,
) (*Response[SetDifficultyResult], error)

SetDifficulty sets the current difficulty.

func (*Client) SetGameRule

func (c *Client) SetGameRule(ctx context.Context, input SetGameRuleInput) (*Response[SetGameRuleResult], error)

SetGameRule sets a game rule value.

func (*Client) SetIdleTimeout

func (c *Client) SetIdleTimeout(
	ctx context.Context,
	input SetIdleTimeoutInput,
) (*Response[SetIdleTimeoutResult], error)

SetIdleTimeout sets the idle timeout in minutes.

func (*Client) SetIntegerGameRule

func (c *Client) SetIntegerGameRule(
	ctx context.Context,
	input SetIntegerGameRuleInput,
) (*Response[SetIntegerGameRuleResult], error)

SetIntegerGameRule sets an integer game rule value.

func (*Client) SetTime

func (c *Client) SetTime(ctx context.Context, input SetTimeInput) (*Response[SetTimeResult], error)

SetTime sets the current time.

func (*Client) SetWeather

func (c *Client) SetWeather(ctx context.Context, input SetWeatherInput) (*Response[SetWeatherResult], error)

SetWeather sets the current weather.

func (*Client) SetWorldSpawn

func (c *Client) SetWorldSpawn(ctx context.Context, input SetWorldSpawnInput) (*Response[SetWorldSpawnResult], error)

SetWorldSpawn sets the world spawn position.

func (*Client) StopServer

func (c *Client) StopServer(ctx context.Context) (*Response[StopServerResult], error)

StopServer stops the server.

type CommandError

type CommandError struct {
	Command string
	Raw     string
	Message string
}

CommandError reports that the server rejected an otherwise well-formed command.

func (CommandError) Error

func (e CommandError) Error() string

Error implements the error interface.

type DeopPlayerInput

type DeopPlayerInput struct {
	Player string
}

DeopPlayerInput removes operator status from a player.

type DeopPlayerResult

type DeopPlayerResult struct {
	Player string
}

DeopPlayerResult reports the affected player.

type Difficulty

type Difficulty string

Difficulty represents a Minecraft difficulty value.

const (
	DifficultyEasy     Difficulty = "easy"
	DifficultyHard     Difficulty = "hard"
	DifficultyNormal   Difficulty = "normal"
	DifficultyPeaceful Difficulty = "peaceful"
)

type DisableAutoSaveResult

type DisableAutoSaveResult struct{}

DisableAutoSaveResult reports automatic save disable completion.

type DisableWhitelistResult

type DisableWhitelistResult struct{}

DisableWhitelistResult reports whitelist disable completion.

type EnableAutoSaveResult

type EnableAutoSaveResult struct{}

EnableAutoSaveResult reports automatic save enable completion.

type EnableWhitelistResult

type EnableWhitelistResult struct{}

EnableWhitelistResult reports whitelist enable completion.

type Executor

type Executor interface {
	Execute(command string) (string, error)
}

Executor executes a raw RCON command.

type GameMode

type GameMode string

GameMode represents a Minecraft game mode value.

const (
	GameModeAdventure GameMode = "adventure"
	GameModeCreative  GameMode = "creative"
	GameModeSpectator GameMode = "spectator"
	GameModeSurvival  GameMode = "survival"
)

type GetBooleanGameRuleInput

type GetBooleanGameRuleInput struct {
	Name string
}

GetBooleanGameRuleInput queries a boolean game rule.

type GetBooleanGameRuleResult

type GetBooleanGameRuleResult struct {
	Name  string
	Value bool
}

GetBooleanGameRuleResult contains a queried boolean game rule value.

type GetDifficultyResult

type GetDifficultyResult struct {
	Difficulty Difficulty
}

GetDifficultyResult contains the current difficulty.

type GetGameRuleInput

type GetGameRuleInput struct {
	Name string
}

GetGameRuleInput queries a game rule.

type GetGameRuleResult

type GetGameRuleResult struct {
	Name  string
	Value string
}

GetGameRuleResult contains the queried game rule value.

type GetIntegerGameRuleInput

type GetIntegerGameRuleInput struct {
	Name string
}

GetIntegerGameRuleInput queries an integer game rule.

type GetIntegerGameRuleResult

type GetIntegerGameRuleResult struct {
	Name  string
	Value int
}

GetIntegerGameRuleResult contains a queried integer game rule value.

type GetSeedResult

type GetSeedResult struct {
	Seed int64
}

GetSeedResult contains the current world seed.

type GetTimeInput

type GetTimeInput struct {
	Mode TimeQueryMode
}

GetTimeInput selects the queried time counter.

type GetTimeResult

type GetTimeResult struct {
	Mode  TimeQueryMode
	Value int
}

GetTimeResult contains the queried time value.

type GetVersionResult

type GetVersionResult struct {
	Version string
}

GetVersionResult contains the server version string.

type KickPlayerInput

type KickPlayerInput struct {
	Player string
	Reason string
}

KickPlayerInput kicks a player, optionally with a reason.

type KickPlayerResult

type KickPlayerResult struct {
	Player string
}

KickPlayerResult reports the kicked player.

type ListBansInput

type ListBansInput struct {
	Type BanListType
}

ListBansInput filters the listed ban entries.

type ListBansResult

type ListBansResult struct {
	Details []BanEntry
	Entries []string
	Type    BanListType
}

ListBansResult contains ban entries for a selected filter.

type ListUsersResult

type ListUsersResult struct {
	MaxPlayers  int
	Players     []string
	PlayerCount int
}

ListUsersResult contains currently connected players.

type ListWhitelistUsersResult

type ListWhitelistUsersResult struct {
	Players     []string
	PlayerCount int
}

ListWhitelistUsersResult contains whitelisted players.

type MinecraftClient

type MinecraftClient interface {
	AddWhitelistUser(ctx context.Context, input AddWhitelistUserInput) (*Response[AddWhitelistUserResult], error)
	BanIP(ctx context.Context, input BanIPInput) (*Response[BanIPResult], error)
	BanPlayer(ctx context.Context, input BanPlayerInput) (*Response[BanPlayerResult], error)
	BroadcastMessage(
		ctx context.Context,
		input BroadcastMessageInput,
	) (*Response[BroadcastMessageResult], error)
	DeopPlayer(ctx context.Context, input DeopPlayerInput) (*Response[DeopPlayerResult], error)
	DisableAutoSave(ctx context.Context) (*Response[DisableAutoSaveResult], error)
	DisableWhitelist(ctx context.Context) (*Response[DisableWhitelistResult], error)
	EnableAutoSave(ctx context.Context) (*Response[EnableAutoSaveResult], error)
	EnableWhitelist(ctx context.Context) (*Response[EnableWhitelistResult], error)
	GetBooleanGameRule(
		ctx context.Context,
		input GetBooleanGameRuleInput,
	) (*Response[GetBooleanGameRuleResult], error)
	GetDifficulty(ctx context.Context) (*Response[GetDifficultyResult], error)
	GetGameRule(ctx context.Context, input GetGameRuleInput) (*Response[GetGameRuleResult], error)
	GetIntegerGameRule(
		ctx context.Context,
		input GetIntegerGameRuleInput,
	) (*Response[GetIntegerGameRuleResult], error)
	GetSeed(ctx context.Context) (*Response[GetSeedResult], error)
	GetTime(ctx context.Context, input GetTimeInput) (*Response[GetTimeResult], error)
	GetVersion(ctx context.Context) (*Response[GetVersionResult], error)
	KickPlayer(ctx context.Context, input KickPlayerInput) (*Response[KickPlayerResult], error)
	ListBans(ctx context.Context, input ListBansInput) (*Response[ListBansResult], error)
	ListUsers(ctx context.Context) (*Response[ListUsersResult], error)
	ListWhitelistUsers(ctx context.Context) (*Response[ListWhitelistUsersResult], error)
	OpPlayer(ctx context.Context, input OpPlayerInput) (*Response[OpPlayerResult], error)
	PardonIP(ctx context.Context, input PardonIPInput) (*Response[PardonIPResult], error)
	PardonPlayer(ctx context.Context, input PardonPlayerInput) (*Response[PardonPlayerResult], error)
	ReloadData(ctx context.Context) (*Response[ReloadDataResult], error)
	ReloadWhitelist(ctx context.Context) (*Response[ReloadWhitelistResult], error)
	RemoveWhitelistUser(
		ctx context.Context,
		input RemoveWhitelistUserInput,
	) (*Response[RemoveWhitelistUserResult], error)
	SaveAll(ctx context.Context) (*Response[SaveAllResult], error)
	SetBooleanGameRule(
		ctx context.Context,
		input SetBooleanGameRuleInput,
	) (*Response[SetBooleanGameRuleResult], error)
	SetGameRule(ctx context.Context, input SetGameRuleInput) (*Response[SetGameRuleResult], error)
	SetDefaultGameMode(
		ctx context.Context,
		input SetDefaultGameModeInput,
	) (*Response[SetDefaultGameModeResult], error)
	SetDifficulty(
		ctx context.Context,
		input SetDifficultyInput,
	) (*Response[SetDifficultyResult], error)
	SetIdleTimeout(
		ctx context.Context,
		input SetIdleTimeoutInput,
	) (*Response[SetIdleTimeoutResult], error)
	SetIntegerGameRule(
		ctx context.Context,
		input SetIntegerGameRuleInput,
	) (*Response[SetIntegerGameRuleResult], error)
	SetTime(ctx context.Context, input SetTimeInput) (*Response[SetTimeResult], error)
	SetWeather(ctx context.Context, input SetWeatherInput) (*Response[SetWeatherResult], error)
	SetWorldSpawn(ctx context.Context, input SetWorldSpawnInput) (*Response[SetWorldSpawnResult], error)
	StopServer(ctx context.Context) (*Response[StopServerResult], error)
}

MinecraftClient defines the stable v1 Minecraft command surface.

type OpPlayerInput

type OpPlayerInput struct {
	Player string
}

OpPlayerInput grants operator status to a player.

type OpPlayerResult

type OpPlayerResult struct {
	Player string
}

OpPlayerResult reports the affected player.

type PardonIPInput

type PardonIPInput struct {
	Address string
}

PardonIPInput removes an IP ban.

type PardonIPResult

type PardonIPResult struct {
	Address string
}

PardonIPResult reports the unbanned IP address.

type PardonPlayerInput

type PardonPlayerInput struct {
	Player string
}

PardonPlayerInput removes a player ban.

type PardonPlayerResult

type PardonPlayerResult struct {
	Player string
}

PardonPlayerResult reports the affected player.

type ParseError

type ParseError struct {
	Command string
	Raw     string
	Message string
}

ParseError reports that a command response could not be parsed.

func (ParseError) Error

func (e ParseError) Error() string

Error implements the error interface.

type Position

type Position struct {
	X int
	Y int
	Z int
}

Position represents a block position.

type ReloadDataResult

type ReloadDataResult struct{}

ReloadDataResult reports data reload completion.

type ReloadWhitelistResult

type ReloadWhitelistResult struct{}

ReloadWhitelistResult reports whitelist reload completion.

type RemoveWhitelistUserInput

type RemoveWhitelistUserInput struct {
	Player string
}

RemoveWhitelistUserInput removes a player from the whitelist.

type RemoveWhitelistUserResult

type RemoveWhitelistUserResult struct {
	Player string
}

RemoveWhitelistUserResult reports the removed player.

type Response

type Response[T any] struct {
	Command string
	Data    T
}

Response contains the normalized command and typed data.

type SaveAllResult

type SaveAllResult struct{}

SaveAllResult reports save completion.

type SetBooleanGameRuleInput

type SetBooleanGameRuleInput struct {
	Name  string
	Value bool
}

SetBooleanGameRuleInput sets a boolean game rule value.

type SetBooleanGameRuleResult

type SetBooleanGameRuleResult struct {
	Name  string
	Value bool
}

SetBooleanGameRuleResult reports the applied boolean game rule value.

type SetDefaultGameModeInput

type SetDefaultGameModeInput struct {
	Mode GameMode
}

SetDefaultGameModeInput sets the default game mode.

type SetDefaultGameModeResult

type SetDefaultGameModeResult struct {
	Mode GameMode
}

SetDefaultGameModeResult reports the applied default game mode.

type SetDifficultyInput

type SetDifficultyInput struct {
	Difficulty Difficulty
}

SetDifficultyInput sets the current difficulty.

type SetDifficultyResult

type SetDifficultyResult struct {
	Difficulty Difficulty
}

SetDifficultyResult reports the applied difficulty.

type SetGameRuleInput

type SetGameRuleInput struct {
	Name  string
	Value string
}

SetGameRuleInput sets a game rule value.

type SetGameRuleResult

type SetGameRuleResult struct {
	Name  string
	Value string
}

SetGameRuleResult reports the applied game rule value.

type SetIdleTimeoutInput

type SetIdleTimeoutInput struct {
	Minutes int
}

SetIdleTimeoutInput sets the idle timeout in minutes.

type SetIdleTimeoutResult

type SetIdleTimeoutResult struct {
	Minutes int
}

SetIdleTimeoutResult reports the applied idle timeout.

type SetIntegerGameRuleInput

type SetIntegerGameRuleInput struct {
	Name  string
	Value int
}

SetIntegerGameRuleInput sets an integer game rule value.

type SetIntegerGameRuleResult

type SetIntegerGameRuleResult struct {
	Name  string
	Value int
}

SetIntegerGameRuleResult reports the applied integer game rule value.

type SetTimeInput

type SetTimeInput struct {
	Value TimeValue
}

SetTimeInput sets the current time.

type SetTimeResult

type SetTimeResult struct {
	Value string
}

SetTimeResult reports the applied time value.

type SetWeatherInput

type SetWeatherInput struct {
	DurationSeconds int
	Weather         Weather
}

SetWeatherInput sets the current weather.

type SetWeatherResult

type SetWeatherResult struct {
	DurationSeconds int
	Weather         Weather
}

SetWeatherResult reports the applied weather.

type SetWorldSpawnInput

type SetWorldSpawnInput struct {
	AngleDegrees *float64
	Position     Position
}

SetWorldSpawnInput sets the world spawn position.

type SetWorldSpawnResult

type SetWorldSpawnResult struct {
	AngleDegrees *float64
	Position     Position
}

SetWorldSpawnResult reports the applied world spawn position.

type StopServerResult

type StopServerResult struct{}

StopServerResult reports stop command submission.

type TimePreset

type TimePreset string

TimePreset represents a supported /time set preset.

const (
	TimePresetDay      TimePreset = "day"
	TimePresetMidnight TimePreset = "midnight"
	TimePresetNight    TimePreset = "night"
	TimePresetNoon     TimePreset = "noon"
)

type TimeQueryMode

type TimeQueryMode string

TimeQueryMode represents a supported /time query mode.

const (
	TimeQueryModeDay      TimeQueryMode = "day"
	TimeQueryModeDaytime  TimeQueryMode = "daytime"
	TimeQueryModeTime     TimeQueryMode = "time"
	TimeQueryModeGametime TimeQueryMode = "gametime"
)

type TimeValue

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

TimeValue represents a typed /time set value.

func NewTimePresetValue

func NewTimePresetValue(preset TimePreset) TimeValue

NewTimePresetValue returns a preset-backed time value.

func NewTimeTickValue

func NewTimeTickValue(ticks int) (TimeValue, error)

NewTimeTickValue returns a tick-backed time value.

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError reports invalid user input before command execution.

func (ValidationError) Error

func (e ValidationError) Error() string

Error implements the error interface.

type Weather

type Weather string

Weather represents a supported /weather mode.

const (
	WeatherClear   Weather = "clear"
	WeatherRain    Weather = "rain"
	WeatherThunder Weather = "thunder"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL