gomcsmp

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Dec 22, 2025 License: MIT Imports: 12 Imported by: 0

README

go-mc-smp

Go client for Minecraft JSON-RPC

Installation

go get github.com/eterline/go-mc-smp

Features

  • Players management: list, kick
  • Allowlist management: get, add, remove, clear
  • Server control: status, save, stop, system messages
  • Gamerules: list, update
  • Fully asynchronous JSON-RPC over WebSocket
  • Context support and configurable call timeout
  • Another in process

Usage

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/eterline/go-mc-smp"
)

func main() {
	smp, err := gomcsmp.NewClient("127.0.0.1", 9100, "YOUR_RPC_TOKEN", gomcsmp.WithCallTimeout(10*time.Second))
	if err != nil {
		panic(err)
	}
	defer smp.Close()

	msg := gomcsmp.SystemMessage{
		ReceivingPlayers: []gomcsmp.Player{gomcsmp.NewPlayer("EterLine")},
		Overlay:          false,
		Message:          gomcsmp.NewMessage("hello", "hello"),
	}

	sent, err := smp.ServerSystemMessage(context.Background(), msg)
	if err != nil {
		panic(err)
	}
	fmt.Println("Message sent:", sent)
}

Sending a System Message Use Screen

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClientOption

type ClientOption func(*clientConfig)

func WithCallTimeout

func WithCallTimeout(t time.Duration) ClientOption

func WithPath

func WithPath(path string) ClientOption

func WithTLS

func WithTLS() ClientOption

type GameRule

type GameRule struct {
	Type  GameRuleType `json:"type,omitempty"`
	Value string       `json:"value"`
	Key   string       `json:"key"`
}

GameRule - represents a game rule key-value pair in the server.

func NewGameRule

func NewGameRule(value, key string) GameRule

NewGameRule - creates a new GameRule with the given key and value.

func NewGameRuleBoolean added in v0.1.0

func NewGameRuleBoolean(value bool, key string) GameRule

func NewGameRuleInteger added in v0.1.0

func NewGameRuleInteger(value int, key string) GameRule

func NewGameRuleTyped

func NewGameRuleTyped(value, key string, ruleType GameRuleType) GameRule

func (GameRule) Boolean

func (gr GameRule) Boolean() (bool, error)

func (GameRule) Integer

func (gr GameRule) Integer() (int, error)

func (GameRule) Untyped

func (gr GameRule) Untyped() bool

type GameRuleType

type GameRuleType string
const (
	UntypedGameRule GameRuleType = ""
	IntegerGameRule GameRuleType = "integer"
	BooleanGameRule GameRuleType = "boolean"
)

type IPBan

type IPBan struct {
	Reason  string `json:"reason"`
	Expires string `json:"expires"`
	IP      string `json:"ip"`
	Source  string `json:"source"`
}

IPBan - represents an IP ban record. Contains the reason, expiration time, IP address, and the source of the ban.

func NewIPBan

func NewIPBan(ip net.IP, expires time.Time, reason, source string) (IPBan, error)

NewIPBan - creates a new IPBan with the given parameters.

func (IPBan) Addr

func (ipb IPBan) Addr() (netip.Addr, error)

Addr - parses the IP field into a netip.Addr. Returns an error if the IP is invalid.

func (IPBan) ExpireIn

func (ipb IPBan) ExpireIn() time.Time

ExpireIn - parses the Expires field into a time.Time object. Returns zero time (time.Time{}) if parsing fails.

func (IPBan) Expired

func (ipb IPBan) Expired() bool

Expired - checks if the ban has already expired. Returns true if Expires is valid and the current time is after it.

func (IPBan) NetIP

func (ipb IPBan) NetIP() (net.IP, error)

NetIP - parses the IP field into a net.IP. Returns an error if the IP is invalid.

type IncomingIPBan

type IncomingIPBan struct {
	Reason  string `json:"reason"`
	Expires string `json:"expires"`
	IP      string `json:"ip"`
	Source  string `json:"source"`
	Player  Player `json:"player"`
}

IncomingIPBan - represents an incoming IP ban request or record. Contains the reason, expiration time, IP address, source of ban, and the associated player.

func (IncomingIPBan) Addr

func (iipb IncomingIPBan) Addr() (netip.Addr, error)

Addr - parses the IP field into a netip.Addr. Returns an error if the IP is invalid.

func (IncomingIPBan) ExpireIn

func (iipb IncomingIPBan) ExpireIn() time.Time

ExpireIn - parses the Expires field into a time.Time object. Returns zero time (time.Time{}) if parsing fails.

func (IncomingIPBan) Expired

func (iipb IncomingIPBan) Expired() bool

Expired - checks if the ban has already expired. Returns true if Expires is valid and the current time is after it.

func (IncomingIPBan) NetIP

func (iipb IncomingIPBan) NetIP() (net.IP, error)

NetIP - parses the IP field into a net.IP. Returns an error if the IP is invalid.

type KickPlayer

type KickPlayer struct {
	Player  Player  `json:"player"`
	Message Message `json:"message"`
}

func NewKickPlayer

func NewKickPlayer(name string, msg Message) KickPlayer

type Message

type Message struct {
	Translatable       string   `json:"translatable"`
	TranslatableParams []string `json:"translatableParams"`
	Literal            string   `json:"literal"`
}

func NewMessage

func NewMessage(literal string, translatable string, params ...string) Message

type Operator

type Operator struct {
	Permission          int    `json:"permissionLevel"`
	BypassesPlayerLimit bool   `json:"bypassesPlayerLimit"`
	Player              Player `json:"player"`
}

func NewOperator

func NewOperator(player Player, perms int, bypassLimit bool) Operator

type Player

type Player struct {
	Name string     `json:"name"`
	ID   *uuid.UUID `json:"id,omitempty"`
}

Player - represents a Minecraft player. Name is the player's username, ID is the optional UUID of the player.

func NewPlayer

func NewPlayer(name string) Player

NewPlayer - creates a new Player instance with the given name. The UUID is left nil and can be set later.

func (Player) Kick added in v0.1.0

func (player Player) Kick(literal string, translatable string, params ...string) KickPlayer

type PlayerRegistry added in v0.1.0

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

func NewPlayerRegistry added in v0.1.0

func NewPlayerRegistry(players []Player) *PlayerRegistry

func NewPlayerRegistryNames added in v0.1.0

func NewPlayerRegistryNames(name ...string) *PlayerRegistry

func (*PlayerRegistry) Add added in v0.1.0

func (r *PlayerRegistry) Add(player Player)

func (*PlayerRegistry) Filter added in v0.1.0

func (r *PlayerRegistry) Filter(f func(data Player) bool) *PlayerRegistry

func (*PlayerRegistry) IsOnline added in v0.1.0

func (r *PlayerRegistry) IsOnline(name string) bool

func (*PlayerRegistry) MarshalJSON added in v0.1.0

func (r *PlayerRegistry) MarshalJSON() ([]byte, error)

func (*PlayerRegistry) Online added in v0.1.0

func (r *PlayerRegistry) Online() int

func (*PlayerRegistry) PlayerByName added in v0.1.0

func (r *PlayerRegistry) PlayerByName(name string) (player Player, ok bool)

func (*PlayerRegistry) Players added in v0.1.0

func (r *PlayerRegistry) Players() []Player

func (*PlayerRegistry) UUIDByName added in v0.1.0

func (r *PlayerRegistry) UUIDByName(name string) (id uuid.UUID, ok bool)

func (*PlayerRegistry) UnmarshalJSON added in v0.1.0

func (r *PlayerRegistry) UnmarshalJSON(b []byte) error

type RPCClient

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

func NewClient

func NewClient(host string, port uint16, token string, opts ...ClientOption) (*RPCClient, error)

func (*RPCClient) AllowlistAdd

func (rpc *RPCClient) AllowlistAdd(ctx context.Context, p ...Player) error

AllowlistAdd - Add players to the allowlist

func (*RPCClient) AllowlistClear

func (rpc *RPCClient) AllowlistClear(ctx context.Context) error

AllowlistClear - Clear all players in allowlist

func (*RPCClient) AllowlistGet

func (rpc *RPCClient) AllowlistGet(ctx context.Context) (*PlayerRegistry, error)

AllowlistGet - Get the allowlist

func (*RPCClient) AllowlistRemove

func (rpc *RPCClient) AllowlistRemove(ctx context.Context, p ...Player) error

AllowlistRemove - Remove players from allowlist

func (*RPCClient) AllowlistSet

func (rpc *RPCClient) AllowlistSet(ctx context.Context, p ...Player) error

AllowlistSet - Set the allowlist to the provided list of players

func (*RPCClient) BansAdd added in v0.1.0

func (rpc *RPCClient) BansAdd(ctx context.Context, ban ...UserBan) error

BansAdd - Add players to the ban list

func (*RPCClient) BansClear added in v0.1.0

func (rpc *RPCClient) BansClear(ctx context.Context) error

BansClear - Clear all players in ban list

func (*RPCClient) BansGet added in v0.1.0

func (rpc *RPCClient) BansGet(ctx context.Context) ([]UserBan, error)

BansGet - Get the ban list

func (*RPCClient) BansRemove added in v0.1.0

func (rpc *RPCClient) BansRemove(ctx context.Context, player ...Player) error

BansRemove - Remove players from ban list

func (*RPCClient) BansSet added in v0.1.0

func (rpc *RPCClient) BansSet(ctx context.Context, ban ...UserBan) error

BansSet - Set the banlist

func (*RPCClient) Close

func (rpc *RPCClient) Close() error

func (*RPCClient) GamerulesGet

func (rpc *RPCClient) GamerulesGet(ctx context.Context) ([]GameRule, error)

GamerulesGet - Get the available game rule keys and their current values

func (*RPCClient) GamerulesUpdate

func (rpc *RPCClient) GamerulesUpdate(ctx context.Context, rule GameRule) (*GameRule, error)

GamerulesUpdate - Update game rule value

func (*RPCClient) IPBansAdd added in v0.1.0

func (rpc *RPCClient) IPBansAdd(ctx context.Context, ban ...IPBan) error

IPBansAdd - Add players to the ip ban list

func (*RPCClient) IPBansClear added in v0.1.0

func (rpc *RPCClient) IPBansClear(ctx context.Context) error

IPBansClear - Clear all players in ip ban list

func (*RPCClient) IPBansGet added in v0.1.0

func (rpc *RPCClient) IPBansGet(ctx context.Context) ([]IPBan, error)

IPBansGet - Get the ip ban list

func (*RPCClient) IPBansRemove added in v0.1.0

func (rpc *RPCClient) IPBansRemove(ctx context.Context, player ...IPBan) error

IPBansRemove - Remove players from ip ban list

func (*RPCClient) IPBansSet added in v0.1.0

func (rpc *RPCClient) IPBansSet(ctx context.Context, ban ...IPBan) error

IPBansSet - Set the ip ban list

func (*RPCClient) OperatorsAdd added in v0.1.0

func (rpc *RPCClient) OperatorsAdd(ctx context.Context, p ...Operator) error

OperatorsAdd - Op players

func (*RPCClient) OperatorsClear added in v0.1.0

func (rpc *RPCClient) OperatorsClear(ctx context.Context) error

OperatorsClear - Deop all players

func (*RPCClient) OperatorsGet added in v0.1.0

func (rpc *RPCClient) OperatorsGet(ctx context.Context) ([]Operator, error)

OperatorsGet - Get all oped players

func (*RPCClient) OperatorsRemove added in v0.1.0

func (rpc *RPCClient) OperatorsRemove(ctx context.Context, p ...Player) error

OperatorsRemove - Deop players

func (*RPCClient) OperatorsSet added in v0.1.0

func (rpc *RPCClient) OperatorsSet(ctx context.Context, p ...Operator) error

OperatorsSet - Set all oped players

func (*RPCClient) PlayersGet

func (rpc *RPCClient) PlayersGet(ctx context.Context) (*PlayerRegistry, error)

PlayersGet - Get all connected players

func (*RPCClient) PlayersKick

func (rpc *RPCClient) PlayersKick(ctx context.Context, kicks ...KickPlayer) (*PlayerRegistry, error)

PlayersKick - Kick players

func (*RPCClient) ServerSave

func (rpc *RPCClient) ServerSave(ctx context.Context, flush bool) (bool, error)

ServerSave - Save server state

func (*RPCClient) ServerStatus

func (rpc *RPCClient) ServerStatus(ctx context.Context) (*ServerState, error)

ServerStatus - Get server status

func (*RPCClient) ServerStop

func (rpc *RPCClient) ServerStop(ctx context.Context) (bool, error)

ServerStop - Stop server

func (*RPCClient) ServerSystemMessage

func (rpc *RPCClient) ServerSystemMessage(ctx context.Context, message SystemMessage) (bool, error)

ServerSystemMessage - Send a system message

func (*RPCClient) SettingsAcceptTransfers added in v0.1.0

func (rpc *RPCClient) SettingsAcceptTransfers(ctx context.Context) (bool, error)

SettingsAcceptTransfers - Get whether the server accepts player transfers from other servers

func (*RPCClient) SettingsAcceptTransfersSet added in v0.1.0

func (rpc *RPCClient) SettingsAcceptTransfersSet(ctx context.Context, accept bool) (bool, error)

SettingsAcceptTransfersSet - Set whether the server accepts player transfers from other servers

func (*RPCClient) SettingsAllowFlight added in v0.1.0

func (rpc *RPCClient) SettingsAllowFlight(ctx context.Context) (bool, error)

SettingsAllowFlight - Get whether flight is allowed for players in Survival mode

func (*RPCClient) SettingsAllowFlightSet added in v0.1.0

func (rpc *RPCClient) SettingsAllowFlightSet(ctx context.Context, allow bool) (bool, error)

SettingsAllowFlightSet - Set whether flight is allowed for players in Survival mode

func (*RPCClient) SettingsAutosave added in v0.1.0

func (rpc *RPCClient) SettingsAutosave(ctx context.Context) (bool, error)

SettingsAutosave - Get whether automatic world saving is enabled on the server

func (*RPCClient) SettingsAutosaveSet added in v0.1.0

func (rpc *RPCClient) SettingsAutosaveSet(ctx context.Context, enable bool) (bool, error)

SettingsAutosaveSet - Enable or disable automatic world saving on the server

func (*RPCClient) SettingsDifficulty added in v0.1.0

func (rpc *RPCClient) SettingsDifficulty(ctx context.Context) (string, error)

SettingsDifficulty - Get the current difficulty level of the server

func (*RPCClient) SettingsDifficultySet added in v0.1.0

func (rpc *RPCClient) SettingsDifficultySet(ctx context.Context, difficulty string) (string, error)

SettingsDifficultySet - Set the difficulty level of the server

func (*RPCClient) SettingsEnforceAllowlist added in v0.1.0

func (rpc *RPCClient) SettingsEnforceAllowlist(ctx context.Context) (bool, error)

SettingsEnforceAllowlist - Get whether allowlist enforcement is enabled (kicks players immediately when removed from allowlist)

func (*RPCClient) SettingsEnforceAllowlistSet added in v0.1.0

func (rpc *RPCClient) SettingsEnforceAllowlistSet(ctx context.Context, enforce bool) (bool, error)

SettingsEnforceAllowlistSet - Enable or disable allowlist enforcement (when enabled, players are kicked immediately upon removal from allowlist)

func (*RPCClient) SettingsEntityBroadcastRange added in v0.1.0

func (rpc *RPCClient) SettingsEntityBroadcastRange(ctx context.Context) (int, error)

SettingsEntityBroadcastRange - Get the entity broadcast range as a percentage

func (*RPCClient) SettingsEntityBroadcastRangeSet added in v0.1.0

func (rpc *RPCClient) SettingsEntityBroadcastRangeSet(ctx context.Context, percentage_points int) (int, error)

SettingsEntityBroadcastRangeSet - Set the entity broadcast range as a percentage

func (*RPCClient) SettingsForceGameMode added in v0.1.0

func (rpc *RPCClient) SettingsForceGameMode(ctx context.Context) (bool, error)

SettingsForceGameMode - Get whether players are forced to use the server's default game mode

func (*RPCClient) SettingsForceGameModeSet added in v0.1.0

func (rpc *RPCClient) SettingsForceGameModeSet(ctx context.Context, forced bool) (bool, error)

SettingsForceGameModeSet - Set whether players are forced to use the server's default game mode

func (*RPCClient) SettingsGameMode added in v0.1.0

func (rpc *RPCClient) SettingsGameMode(ctx context.Context) (string, error)

SettingsGameMode - Get the server's default game mode

func (*RPCClient) SettingsGameModeSet added in v0.1.0

func (rpc *RPCClient) SettingsGameModeSet(ctx context.Context, gamemode string) (string, error)

SettingsGameModeSet - Set the server's default game mode

func (*RPCClient) SettingsHideOnlinePlayers added in v0.1.0

func (rpc *RPCClient) SettingsHideOnlinePlayers(ctx context.Context) (bool, error)

SettingsHideOnlinePlayers - Get whether the server hides online player information from status queries

func (*RPCClient) SettingsHideOnlinePlayersSet added in v0.1.0

func (rpc *RPCClient) SettingsHideOnlinePlayersSet(ctx context.Context, hide bool) (bool, error)

SettingsHideOnlinePlayersSet - Set whether the server hides online player information from status queries

func (*RPCClient) SettingsMaxPlayers added in v0.1.0

func (rpc *RPCClient) SettingsMaxPlayers(ctx context.Context) (int, error)

SettingsMaxPlayers - Get the maximum number of players allowed to connect to the server

func (*RPCClient) SettingsMaxPlayersSet added in v0.1.0

func (rpc *RPCClient) SettingsMaxPlayersSet(ctx context.Context, max int) (int, error)

SettingsMaxPlayersSet - Set the maximum number of players allowed to connect to the server

func (*RPCClient) SettingsMotd added in v0.1.0

func (rpc *RPCClient) SettingsMotd(ctx context.Context) (string, error)

SettingsMotd - Get the server's message of the day displayed to players

func (*RPCClient) SettingsMotdSet added in v0.1.0

func (rpc *RPCClient) SettingsMotdSet(ctx context.Context, motd string) (string, error)

SettingsMotdSet - Set the server's message of the day displayed to players

func (*RPCClient) SettingsOperatorUserPermissionLevel added in v0.1.0

func (rpc *RPCClient) SettingsOperatorUserPermissionLevel(ctx context.Context) (int, error)

SettingsOperatorUserPermissionLevel - Get the permission level required for operator commands

func (*RPCClient) SettingsOperatorUserPermissionLevelSet added in v0.1.0

func (rpc *RPCClient) SettingsOperatorUserPermissionLevelSet(ctx context.Context, level int) (int, error)

SettingsOperatorUserPermissionLevelSet - Set the permission level required for operator commands

func (*RPCClient) SettingsPauseWhenEmptySeconds added in v0.1.0

func (rpc *RPCClient) SettingsPauseWhenEmptySeconds(ctx context.Context) (time.Duration, error)

SettingsPauseWhenEmptySeconds - Get the number of seconds before the game is automatically paused when no players are online

func (*RPCClient) SettingsPauseWhenEmptySecondsSet added in v0.1.0

func (rpc *RPCClient) SettingsPauseWhenEmptySecondsSet(ctx context.Context, duration time.Duration) (time.Duration, error)

SettingsPauseWhenEmptySecondsSet - Set the number of seconds before the game is automatically paused when no players are online

func (*RPCClient) SettingsPlayerIdleTimeout added in v0.1.0

func (rpc *RPCClient) SettingsPlayerIdleTimeout(ctx context.Context) (time.Duration, error)

SettingsPlayerIdleTimeout - Get the number of seconds before idle players are automatically kicked from the server

func (*RPCClient) SettingsPlayerIdleTimeoutSet added in v0.1.0

func (rpc *RPCClient) SettingsPlayerIdleTimeoutSet(ctx context.Context, duration time.Duration) (time.Duration, error)

SettingsPlayerIdleTimeoutSet - Set the number of seconds before idle players are automatically kicked from the server

func (*RPCClient) SettingsSimulationDistance added in v0.1.0

func (rpc *RPCClient) SettingsSimulationDistance(ctx context.Context) (int, error)

SettingsSimulationDistance - Get the server's simulation distance in chunks

func (*RPCClient) SettingsSimulationDistanceSet added in v0.1.0

func (rpc *RPCClient) SettingsSimulationDistanceSet(ctx context.Context, distance int) (int, error)

SettingsSimulationDistanceSet - Set the server's simulation distance in chunks

func (*RPCClient) SettingsSpawnProtectionRadius added in v0.1.0

func (rpc *RPCClient) SettingsSpawnProtectionRadius(ctx context.Context) (int, error)

SettingsSpawnProtectionRadius - Get the spawn protection radius in blocks

func (*RPCClient) SettingsSpawnProtectionRadiusSet added in v0.1.0

func (rpc *RPCClient) SettingsSpawnProtectionRadiusSet(ctx context.Context, radius int) (int, error)

SettingsSpawnProtectionRadiusSet - Set the spawn protection radius in blocks

func (*RPCClient) SettingsStatusHeartbeatInterval added in v0.1.0

func (rpc *RPCClient) SettingsStatusHeartbeatInterval(ctx context.Context) (time.Duration, error)

SettingsStatusHeartbeatInterval - Get the interval in seconds between server status heartbeats

func (*RPCClient) SettingsStatusHeartbeatIntervalSet added in v0.1.0

func (rpc *RPCClient) SettingsStatusHeartbeatIntervalSet(ctx context.Context, interval time.Duration) (time.Duration, error)

SettingsStatusHeartbeatIntervalSet - Set the interval in seconds between server status heartbeats

func (*RPCClient) SettingsStatusReplies added in v0.1.0

func (rpc *RPCClient) SettingsStatusReplies(ctx context.Context) (bool, error)

SettingsStatusReplies - Get whether the server responds to connection status requests

func (*RPCClient) SettingsStatusRepliesSet added in v0.1.0

func (rpc *RPCClient) SettingsStatusRepliesSet(ctx context.Context, enabled bool) (bool, error)

SettingsStatusRepliesSet - Set whether the server responds to connection status requests

func (*RPCClient) SettingsUseAllowlist added in v0.1.0

func (rpc *RPCClient) SettingsUseAllowlist(ctx context.Context) (bool, error)

SettingsUseAllowlist - Get whether the allowlist is enabled on the server

func (*RPCClient) SettingsUseAllowlistSet added in v0.1.0

func (rpc *RPCClient) SettingsUseAllowlistSet(ctx context.Context, use bool) (bool, error)

SettingsUseAllowlistSet - Enable or disable the allowlist on the server (controls whether only allowlisted players can join)

func (*RPCClient) SettingsViewDistance added in v0.1.0

func (rpc *RPCClient) SettingsViewDistance(ctx context.Context) (int, error)

SettingsViewDistance - Get the server's view distance in chunks

func (*RPCClient) SettingsViewDistanceSet added in v0.1.0

func (rpc *RPCClient) SettingsViewDistanceSet(ctx context.Context, distance int) (int, error)

SettingsViewDistanceSet - Set the server's view distance in chunks

type ServerState

type ServerState struct {
	Players *PlayerRegistry `json:"players"`
	Started bool            `json:"started"`
	Version Version         `json:"version"`
}

type SystemMessage

type SystemMessage struct {
	ReceivingPlayers *PlayerRegistry `json:"receivingPlayers"`
	Overlay          bool            `json:"overlay"`
	Message          Message         `json:"message"`
}

type UserBan

type UserBan struct {
	Reason  string `json:"reason"`
	Expires string `json:"expires"`
	Source  string `json:"source"`
	Player  Player `json:"player"`
}

UserBan - represents a user ban record. Contains the reason, expiration time, source of the ban, and the banned player.

func NewUserBan

func NewUserBan(player Player, expires time.Time, reason, source string) (UserBan, error)

NewUserBan - creates a new UserBan with the given parameters.

func (UserBan) ExpireIn

func (ub UserBan) ExpireIn() time.Time

ExpireIn - parses the Expires field into a time.Time object. Returns zero time (time.Time{}) if parsing fails.

func (UserBan) Expired

func (ub UserBan) Expired() bool

Expired - checks if the user ban has already expired. Returns true if Expires is valid and the current time is after it.

type Version

type Version struct {
	Protocol int    `json:"protocol"`
	Name     string `json:"name"`
}

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

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