rcon

package
v0.0.0-...-d73579a Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2025 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MSGLEN = 8196
)

Variables

View Source 
var (
	CommandFailed          = errors.New("FAIL")
	ReconnectTriesExceeded = errors.New("there are no reconnects left")
)
View Source 
var (
	ErrUnsupportedGameMode = errors.New("the command is not available for the current gamemode")
)
View Source 
var (
	ErrWriteSentUnequal = errors.New("write wrote less or more bytes than command is long")
)

Functions

func IsBrokenHllConnection 

func IsBrokenHllConnection(err error) bool

Types

type AdminId 

type AdminId struct {
	Name      string
	SteamId64 string
	Role      string
}

type CapPoint 

type CapPoint string

func (CapPoint) String 

func (c CapPoint) String() string

type CapPoints 

type CapPoints []CapPoint

func (CapPoints) Exists 

func (c CapPoints) Exists(p string) bool

type Connection 

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

Connection represents a persistent connection to a HLL server using RCon. It can be used to issue commands against the HLL server and query data. The connection can either be utilised using the higher-level API methods, or by sending raw commands using ListCommand or Command.

A Connection is not thread-safe by default. Do not attempt to run multiple commands (either of the higher-level or low-level API). Doing so may either run into non-expected indefinitely blocking execution (until the context.Context deadline exceeds) or to mixed up data (sending a command and getting back the response for another command). Instead, in goroutines use a ConnectionPool and request a new connection for each goroutine. The ConnectionPool will ensure that one Connection is only used once at the same time. It also speeds up processing by opening a number of Connections until the pool size is reached.

func (*Connection) AddAdmin 

func (c *Connection) AddAdmin(id AdminId) error

AddAdmin adds a player to the list of admins with the specified role. The role needs to be a role available on the server. Use the AdminGroups command to get available roles.

func (*Connection) AddProfanities 

func (c *Connection) AddProfanities(p []string) error

func (*Connection) AddToMapRotation 

func (c *Connection) AddToMapRotation(mapName string, afterMap string) error

AddToMapRotation Adds a map to the map rotation after the mentioned map.

func (*Connection) AddVip 

func (c *Connection) AddVip(id VipId) error

AddVip adds a player to the list of players who can utilize the vip slots (set by SetVipSlots).

func (*Connection) AdminGroups 

func (c *Connection) AdminGroups() ([]string, error)

AdminGroups returns a list of potentially customized roles that are available for this server. A role can have a specific set of permissions and can be used in AddAdmin command.

func (*Connection) AdminIds 

func (c *Connection) AdminIds() ([]AdminId, error)

AdminIds returns a list of admins on the server. An admin is identified by their Steam ID, and an optional name/comment. The role is a potentially custom-defined role that can have a set of permissions. Use AdminGroups to get a list of available roles for this server.

func (*Connection) AutobalanceEnabled 

func (c *Connection) AutobalanceEnabled() (bool, error)

func (*Connection) AutobalanceThreashold 

func (c *Connection) AutobalanceThreashold() (int, error)

func (*Connection) Command 

func (c *Connection) Command(cmd string) (string, error)

Command executes the raw command provided and returns the result as a plain string.

func (*Connection) CurrentMapSequence 

func (c *Connection) CurrentMapSequence() ([]string, error)

func (*Connection) DeleteAdmin 

func (c *Connection) DeleteAdmin(steamId string) error

DeleteAdmin removes a player from the list of admins. Correspond to AddAdmin and AdminIds for more details.

func (*Connection) GameLayout 

func (c *Connection) GameLayout(points []string) error

GameLayout changes the cap layout of the current map to the provided one. The points parameter is required to be a slice of 5 elements, identifying the name of the cap point for each row/column index of the new cap layout. The ordering is always left-to-right for horizontal maps and top-to-bottom for vertical map layouts.

If at least one cap point is invalid for the current map, this method returns an error. If the current game mode does not support changing the cap layout, a ErrUnsupportedGameMode error is returned (e.g. in Skirmish game mode).

func (*Connection) GameState 

func (c *Connection) GameState() (GameState, error)

GameState returns information about the currently played round on the server.

func (*Connection) IdleTimeout 

func (c *Connection) IdleTimeout() (int, error)

func (*Connection) Kick 

func (c *Connection) Kick(name, reason string) error

Kick kicks the player with the given name from the server. The reason will be displayed to the user in the kick screen.

func (*Connection) ListCommand 

func (c *Connection) ListCommand(cmd string) ([]string, error)

ListCommand executes the raw command provided and returns the result as a list of strings. A list with regard to the RCon protocol is delimited by tab characters. The result is split by tab characters to produce the resulting list response.

func (*Connection) Map 

func (c *Connection) Map() (string, error)

func (*Connection) MapRotation 

func (c *Connection) MapRotation(filters ...MapFilter) ([]string, error)

MapRotation Returns a list of map names, which are currently in the map rotation. Maps can be duplicated in the list.

func (*Connection) MapShuffleEnabled 

func (c *Connection) MapShuffleEnabled() (bool, error)

func (*Connection) Maps 

func (c *Connection) Maps(filters ...MapFilter) ([]string, error)

Maps Returns the available maps on the server. These map names can be used in commands like SwitchMap and AddToMapRotation

func (*Connection) MaxPingAutokick 

func (c *Connection) MaxPingAutokick() (int, error)

func (*Connection) MessagePlayer 

func (c *Connection) MessagePlayer(steamId string, message string) error

MessagePlayer sends a message to the player with the steam ID, if the player is on the server. The message can contain newline characters.

func (*Connection) ObjectivePoints 

func (c *Connection) ObjectivePoints() (MapCapPoints, error)

ObjectivePoints returns a list of available cap points for the current map. This is a two-dimensional list of row/column index and the available cap names for that row. The index will be 0-5 from left-to-right for horizontal maps and top-to-bottom for vertical map layouts. Skirmish maps do not have any cap points available, as the cap layout is fixed (mid-cap only). Using this command for a skirmish map will return a ErrUnsupportedGameMode error.

func (*Connection) PermaBan 

func (c *Connection) PermaBan(playerId, reason, adminName string) error

PermaBan bans the player permanently with the provided reason. This player will not be able to join the server anymore. The adminName parameter is optional and can be an empty string.

func (*Connection) PermaBans 

func (c *Connection) PermaBans() ([]string, error)

func (*Connection) PlayerIds 

func (c *Connection) PlayerIds() ([]PlayerId, error)

PlayerIds issues the `get playerids` command to the server and returns a list of parsed PlayerIds. The players returned are the ones currently connected to the server.

func (*Connection) PlayerInfo 

func (c *Connection) PlayerInfo(name string) (PlayerInfo, error)

PlayerInfo returns more information about a specific player by using its name. The player needs to be connected to the server for this command to succeed.

func (*Connection) Players 

func (c *Connection) Players() ([]string, error)

func (*Connection) Profanities 

func (c *Connection) Profanities() ([]string, error)

func (*Connection) Punish 

func (c *Connection) Punish(name, reason string) error

Punish kills the player for the given reason. The player can spawn again afterward.

func (*Connection) QueueLength 

func (c *Connection) QueueLength() (int, error)

func (*Connection) RemovePermaBan 

func (c *Connection) RemovePermaBan(playerId string) error

RemovePermaBan removes a permanent ban for this player.

func (*Connection) RemoveProfanities 

func (c *Connection) RemoveProfanities(p []string) error

func (*Connection) RemoveTempBan 

func (c *Connection) RemoveTempBan(playerId string) error

RemoveTempBan removes a temp ban for this player.

func (*Connection) RemoveVip 

func (c *Connection) RemoveVip(id VipId) error

RemoveVip removes the player from the VIP list, if they are on the list.

func (*Connection) ResetVotekickThreshold 

func (c *Connection) ResetVotekickThreshold() error

func (*Connection) ServerName 

func (c *Connection) ServerName() (string, error)

ServerName returns the currently set server name

func (*Connection) SetAutobalanceEnabled 

func (c *Connection) SetAutobalanceEnabled(e bool) error

func (*Connection) SetAutobalanceThreshold 

func (c *Connection) SetAutobalanceThreshold(ms int) error

func (*Connection) SetBroadcast 

func (c *Connection) SetBroadcast(msg string) error

func (*Connection) SetIdleTimeout 

func (c *Connection) SetIdleTimeout(m int) error

func (*Connection) SetMapShuffle 

func (c *Connection) SetMapShuffle(e bool) error

func (*Connection) SetMaxPingAutokick 

func (c *Connection) SetMaxPingAutokick(ms int) error

func (*Connection) SetQueueLength 

func (c *Connection) SetQueueLength(ql int) error

func (*Connection) SetTeamSwitchCooldown 

func (c *Connection) SetTeamSwitchCooldown(m int) error

func (*Connection) SetVipSlots 

func (c *Connection) SetVipSlots(vs int) error

func (*Connection) SetVotekickEnabled 

func (c *Connection) SetVotekickEnabled(e bool) error

func (*Connection) SetWelcomeMessage 

func (c *Connection) SetWelcomeMessage(msg string) error

func (*Connection) ShowLog 

func (c *Connection) ShowLog(d time.Duration) ([]string, error)

ShowLog is a higher-level method to read logs using RCon using the `showlog` raw command. While it would be possible to execute `showlog` with Command, it is not recommended to do so. Showlog has a different response size depending on the duration from when logs should be returned. As RCon does not provide a way to communicate the length of the response data, this method will try to guess if the returned data is complete and reads from the underlying stream of data until it has all. This is not the case with Command.

func (*Connection) Slots 

func (c *Connection) Slots() (int, int, error)

Slots returns the current number of players connected to the server as the first return value. The second return value is the total number of players allowed to be connected to the server at the same time.

func (*Connection) SwitchMap 

func (c *Connection) SwitchMap(mapName string) error

SwitchMap Changes the map on the server. The map name must be one that is available on the server. You can get the available maps with the Maps function. If the map is not in the map rotation, yet, then it will be added to the Map Rotation.

func (*Connection) SwitchTeam 

func (c *Connection) SwitchTeam(name string) error

SwitchTeam switches the player from their current team to the opposing team instantly.

func (*Connection) SwitchTeamOnDeath 

func (c *Connection) SwitchTeamOnDeath(name string) error

SwitchTeamOnDeath switches the player to the opposing team after the next death.

func (*Connection) TeamSwitchCooldown 

func (c *Connection) TeamSwitchCooldown() (int, error)

func (*Connection) TempBan 

func (c *Connection) TempBan(playerId string, d time.Duration, reason, adminName string) error

TempBan bans the player for the provided duration with the provided reason. This player will not be able to join the server anymore until the duration elapsed. The duration d will be rounded to full hours. The adminName parameter is optional and can be an empty string.

func (*Connection) TempBans 

func (c *Connection) TempBans() ([]string, error)

func (*Connection) VipIds 

func (c *Connection) VipIds() ([]VipId, error)

func (*Connection) VipSlots 

func (c *Connection) VipSlots() (int, error)

func (*Connection) VotekickEnabled 

func (c *Connection) VotekickEnabled() (bool, error)

func (*Connection) VotekickThreshold 

func (c *Connection) VotekickThreshold() (int, error)

func (*Connection) WithContext 

func (c *Connection) WithContext(ctx context.Context) error

WithContext inherits applicable values from the given context.Context and applies them to the underlying RCon connection. There is generally no need to call this method explicitly, the ConnectionPool (where you usually get this Connection from) takes care of propagating the outer context.

However, n cases where you want to have a different context.Context for retrieving a Connection from the ConnectionPool and when executing commands, using this method can be useful. One use case might be to have a different timeout while waiting for a Connection from the ConnectionPool, as when executing a command on the Connection.

Returns an error if context.Context values could not be applied to the underlying Connection.

type ConnectionPool 

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

func NewConnectionPool 

func NewConnectionPool(opts ConnectionPoolOptions) (*ConnectionPool, error)

func (*ConnectionPool) GetWithContext 

func (p *ConnectionPool) GetWithContext(ctx context.Context) (*Connection, error)

GetWithContext returns a connection from the pool. This method does not guarantee you to get a new, fresh Connection. A Connection might either be opened newly for this request, re-used from the pool of idle connections or one that was returned to the pool just now.

If there are no idle connections and if the limit of open connections is already reached, the request to retrieve a Connection will be queued. The request might or might not be fulfilled later, once a Connection is returned to the pool.

It is recommended to provide a context.Context with a deadline. The deadline will be the maximum time the caller is ok with waiting for a connection before a Timeout error is returned. If no deadline is provided in the context.Context, GetWithContext might wait indefinitely.

func (*ConnectionPool) Return 

func (p *ConnectionPool) Return(c *Connection, err error)

Return returns a previously gathered Connection from GetWithContext back to the pool for later use. The Connection might either be closed, put into a pool of "hot", idle connections or directly returned to a queued GetWithContext request.

func (*ConnectionPool) Shutdown 

func (p *ConnectionPool) Shutdown()

func (*ConnectionPool) WithConnection 

func (p *ConnectionPool) WithConnection(ctx context.Context, f func(c *Connection) error) error

WithConnection gathers a connection from the pool, if available, and executes the passed in function f. Once the function returns, the connection is correctly returned to the pool with the error returned from f to ensure the connection is not kept.

This is a helper to reduce the possibility a connection is obtained from the pool, but then not returned to it. It is basically the same as using GetWithContext and Return in your own code.

type ConnectionPoolOptions 

type ConnectionPoolOptions struct {
	// Logger is an optional logging instance. If passed in, the pool will issue debug information to this logger instance
	// for, well, debugging purposes. In a production environment, this instance is not required and can be nil.
	// The passed in logger instance is not modified, meaning if it logs on a logging level higher than slog.LevelDebug,
	// no messages will be seen from the pool.
	Logger *slog.Logger
	// Hostname is the hostname/IP address of the Hell Let Loose server where it can be reached.
	// Only IPv4 addresses are supported.
	Hostname string
	// Port is the Hell Let Loose RCon port of the server. The RCon port can usually be found in the Game Service Provider's
	// server management console.
	Port int
	// Password is the RCon password of the Hell Let Loose server used to authenticate.
	Password string

	// MaxOpenConnections is the maximum number of open connections the pool can not exceed. A request for a connection
	// when the pool reached this size (and no idle connections are available) will be put into a queue and be served
	// once a connection is returned to the pool. This queue is on the best effort basis and might fail based on the
	// provided deadline to GetWithContext.
	// The number of requests that can be put into a queue is not limited.
	MaxOpenConnections *int
	// MaxIdleConnections is the maximum number of idle connections in the pool. Idle connections are established connections to
	// the server (warm) but are not currently in use. Warm connections are preferably used to fulfill connection requests
	// (GetWithContext) to reduce the overhead of opening and closing a connection on every request. Consider a high max
	// idle connection to benefit from re-using connections as much as possible.
	// MaxIdleConnections cannot be greater than MaxOpenConnections
	MaxIdleConnections *int
}

type GameScore 

type GameScore struct {
	Axis   int
	Allies int
}

type GameState 

type GameState struct {
	Players       PlayerCount
	Score         GameScore
	RemainingTime time.Duration
	Map           string
	NextMap       string
}

type MapCapPoints 

type MapCapPoints []CapPoints

type MapFilter 

type MapFilter func(idx int, name string, result []string) bool

MapFilter A filter used in commands that return list of maps, e.g. Maps or MapRotation. The filter should return true, when the map should be included in the result set and false when the map should be skipped.

type PlayerCount 

type PlayerCount struct {
	Axis   int
	Allies int
}

type PlayerId 

type PlayerId struct {
	Name      string
	SteamId64 string
}

type PlayerInfo 

type PlayerInfo struct {
	Name      string
	SteamId64 string
	Team      string
	Role      string
	Loadout   string
	Unit      Unit
	Kills     int
	Deaths    int
	Score     Score
	Level     int
}

type Score 

type Score struct {
	CombatEffectiveness int
	Offensive           int
	Defensive           int
	Support             int
}

type Unit 

type Unit struct {
	Id   int
	Name string
}

type VipId 

type VipId struct {
	Name      string
	SteamId64 string
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.