vrage

package module
v0.0.22 Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 14 Imported by: 0

README

go-vrage

license version go reference GitHub

go-vrage is a Go client for the VRage Remote API, which is used by Space Engineers 1 Dedicated Servers to expose server management functionality over HTTP.

[!WARNING] This project is in an early development stage. Breaking changes may be introduced without prior notice. Use in production environments is strongly discouraged. When the first stable release is published, this notice will be removed.

Compatibility with Space Engineers

Hotfix 1.210.013

API Coverage

Root Endpoint Coverage
/v1/server
/v1/admin
/v1/session
Click to see an image of all endpoints

This is a copy of an image provided at https://www.spaceengineersgame.com/dedicated-servers.

./assets/endpoints.png

Features

  • Request authentication (nonce + HMAC-SHA1 signature).
  • Flexible usage styles:
    • High-level typed clients via Client.Server, Client.Session, Client.Admin.
    • Low-level response access via HTTPClient methods (like HTTPClient.GetV1ServerPing) when you need more control.
  • Sentinel error types for better error handling.

Installation

To install the package to your Go module, run the following command:

go get github.com/space-engineers-tools/go-vrage

Usage

Please check out the examples directory for usage examples.

Contributing

We welcome contributions! Please read our contributing guidelines for details on how to get started.

Disclaimer

This project is not affiliated with Keen Software House or the Space Engineers game.

Documentation

Overview

Package vrage provides a client for interacting with the Space Engineers VRage Remote API.

Before using this package, check your SpaceEngineers-Dedicated.cfg and ensure the following setting is enabled: 

<RemoteApiEnabled>true</RemoteApiEnabled>

Index

Constants

View Source 
const (
	DefaultTimeout      time.Duration = time.Second * 5
	DefaultBaseEndpoint string        = "/vrageremote"
	DefaultPort         uint32        = 8080
)

Default configuration values for the VRage Remote API client.

Variables

View Source 
var (
	ErrConfigIncomplete   = errors.New("invalid config: missing required fields")
	ErrConfigInvalid      = errors.New("invalid config: field validation failed")
	ErrConfigIncompatible = errors.New("invalid config: conflicting settings")
)

ErrConfig... are errors for configuration validation.

View Source 
var (
	ErrAPIConnectionFailed   = errors.New("failed to connect to the server: connection refused or host not available")
	ErrAPIInvalidSecurityKey = errors.New("server returned StatusForbidden: security key is invalid or missing")
	ErrAPIRequestTimeout     = errors.New("request timed out: the server did not respond in time")
	ErrAPIUnexpectedCode     = errors.New("unexpected status code from the server")
	ErrAPIUnexpectedBody     = errors.New("unexpected response body from the server")
)

ErrAPI... are errors for API request failures.

Functions

func IsResponseSuccessful added in v0.0.15 

func IsResponseSuccessful(resp *http.Response) bool

IsResponseSuccessful checks if the HTTP response starts with 2.

Types

type APIAdmin added in v0.0.12 

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

APIAdmin provides access to the /v1/admin API routes.

func (*APIAdmin) BanPlayer added in v0.0.21 

func (a *APIAdmin) BanPlayer(steamID uint64) (APIResponseWithoutData, error)

BanPlayer bans a player with the specified Steam ID.

func (*APIAdmin) BannedPlayers added in v0.0.21 

func (a *APIAdmin) BannedPlayers() (APIResponseWithData[APIAdminBannedPlayersData], error)

BannedPlayers fetches a list of banned players.

func (*APIAdmin) DemotePlayer added in v0.0.20 

func (a *APIAdmin) DemotePlayer(steamID uint64) (APIResponseWithoutData, error)

DemotePlayer demotes a player with the specified Steam ID.

func (*APIAdmin) KickPlayer added in v0.0.22 

func (a *APIAdmin) KickPlayer(steamID uint64) (APIResponseWithoutData, error)

KickPlayer kicks a player with the specified Steam ID.

This will prevent the player from joining the server for 5 minutes. 

POST /v1/admin/kickedPlayers/{steam_id}

func (*APIAdmin) KickedPlayers added in v0.0.22 

func (a *APIAdmin) KickedPlayers() (APIResponseWithData[APIAdminKickedPlayersData], error)

KickedPlayers fetches a list of kicked players. 

GET /v1/admin/kickedPlayers

func (*APIAdmin) PromotePlayer added in v0.0.20 

func (a *APIAdmin) PromotePlayer(steamID uint64) (APIResponseWithoutData, error)

PromotePlayer promotes a player with the specified Steam ID.

func (*APIAdmin) UnbanPlayer added in v0.0.21 

func (a *APIAdmin) UnbanPlayer(steamID uint64) (APIResponseWithoutData, error)

UnbanPlayer unbans a player with the specified Steam ID.

func (*APIAdmin) UnkickPlayer added in v0.0.22 

func (a *APIAdmin) UnkickPlayer(steamID uint64) (APIResponseWithoutData, error)

UnkickPlayer un-kicks a player with the specified Steam ID. 

DELETE /v1/admin/kickedPlayers/{steam_id}

type APIAdminBannedPlayer added in v0.0.22 

type APIAdminBannedPlayer struct {
	SteamID     uint64 `json:"SteamId"`
	DisplayName string `json:"DisplayName"` // DisplayName can be empty
}

APIAdminBannedPlayer represents a banned player.

type APIAdminBannedPlayersData added in v0.0.21 

type APIAdminBannedPlayersData struct {
	BannedPlayers []APIAdminBannedPlayer `json:"BannedPlayers"`
}

APIAdminBannedPlayersData represents the data returned by the GET /v1/admin/bannedPlayers endpoint.

type APIAdminKickedPlayer added in v0.0.22 

type APIAdminKickedPlayer struct {
	SteamID uint64 `json:"SteamID"`
	// DisplayName is the display name of the player. It can be an empty string.
	DisplayName string `json:"DisplayName"`
	// Time is the remaining kick duration in milliseconds.
	// It gets negative when the player is allowed to join again and the entry is deleted when the player joins again.
	Time int64 `json:"Time"`
}

APIAdminKickedPlayer represents a kicked player.

func (APIAdminKickedPlayer) CanJoin added in v0.0.22 

func (p APIAdminKickedPlayer) CanJoin() bool

CanJoin returns true if the player is allowed to join again (Time <= 0).

type APIAdminKickedPlayersData added in v0.0.22 

type APIAdminKickedPlayersData struct {
	KickedPlayers []APIAdminKickedPlayer `json:"KickedPlayers"`
}

APIAdminKickedPlayersData represents the data returned by the GET /v1/admin/kickedPlayers endpoint.

type APIMeta added in v0.0.20 

type APIMeta struct {
	// APIVersion is the version of the API.
	APIVersion string `json:"apiVersion"`
	// QueryTime is the time taken (in seconds) to process the request.
	QueryTime float64 `json:"queryTime"`
}

APIMeta represents the metadata of the API response.

type APIResponseWithData added in v0.0.20 

type APIResponseWithData[T any] struct {
	Data T       `json:"data"`
	Meta APIMeta `json:"meta"`
}

APIResponseWithData represents an API with a data field.

type APIResponseWithoutData added in v0.0.20 

type APIResponseWithoutData struct {
	Meta APIMeta `json:"meta"`
}

APIResponseWithoutData represents an API response without a data field.

type APIServer added in v0.0.12 

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

APIServer provides access to the /v1/server API routes.

func (*APIServer) Ping added in v0.0.13 

func (s *APIServer) Ping() (APIResponseWithData[APIServerPingData], error)

Ping returns a ping response from the server, which can be used to check if the server is reachable and responding.

func (*APIServer) Status added in v0.0.13 

func (s *APIServer) Status() (APIResponseWithData[APIServerStatusData], error)

Status returns the current status of the server. This includes information about the performance and the world.

func (*APIServer) Stop added in v0.0.15 

func (s *APIServer) Stop() (APIResponseWithoutData, error)

Stop stops the server. Some hosting providers may restart the server instead of stopping it, depending on their configuration.

Use with caution.

type APIServerPingData added in v0.0.13 

type APIServerPingData struct {
	Result string `json:"result"`
}

APIServerPingData represents the data returned by the GET /v1/server/ping endpoint.

type APIServerStatusData added in v0.0.9 

type APIServerStatusData struct {
	Game              string  `json:"Game"`
	IsReady           bool    `json:"IsReady"`
	PirateUsedPCU     int     `json:"PirateUsedPCU"`
	Players           int     `json:"Players"`
	ServerID          int64   `json:"ServerId"`
	ServerName        string  `json:"ServerName"`
	SimSpeed          float64 `json:"SimSpeed"`
	SimulationCPULoad float64 `json:"SimulationCpuLoad"`
	TotalTime         int     `json:"TotalTime"`
	UsedPCU           int     `json:"UsedPCU"`
	Version           string  `json:"Version"`
	WorldName         string  `json:"WorldName"`
}

APIServerStatusData represents the data returned by the GET /v1/server endpoint.

type APISession added in v0.0.12 

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

APISession provides access to the /v1/session API routes.

type Client 

type Client struct {
	Config  ClientConfig
	HTTP    HTTPClient
	Session APISession
	Server  APIServer
	Admin   APIAdmin
}

Client is the main entry point for interacting with the VRage API.

It provides access to various API endpoints through its sub-clients.

func NewClient 

func NewClient(config ClientConfig) (*Client, error)

NewClient creates a new Client instance with the provided configuration.

type ClientConfig 

type ClientConfig struct {
	// RemoteApiIP is the IP address or DNS name of the Space Engineers server.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	//  <RemoteApiIP>
	//
	// Examples:
	//  "127.0.0.1"
	//  "example.com"
	//  "play.cool-server.com"
	RemoteApiIP string `validate:"required,ip|fqdn"` //nolint:revive // so the name is closer to the .cfg file

	// RemoteSecurityKey is the security key used for authenticating API requests.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	// 	<RemoteSecurityKey>
	RemoteSecurityKey string `validate:"required"`

	// RemoteApiPort is the port of the Remote API on the Space Engineers server.
	//
	// Corresponding Setting in SpaceEngineers-Dedicated.cfg:
	//  <RemoteApiPort>
	//
	// Default:
	//  8080
	RemoteApiPort uint32 `validate:"port"` //nolint:revive // so the name is closer to the .cfg file

	// Timeout specifies the maximum duration for an API request before an vrage.ErrRequestTimeout error is returned.
	//
	// Default:
	//  vrage.DefaultTimeout
	Timeout time.Duration `validate:"gte=0"`

	// UseHTTPS indicates whether to use HTTPS for API requests.
	//
	// Note: While the Space Engineers server does not natively support HTTPS, this option
	// can be used when routing through a reverse proxy.
	//
	// Default:
	//  false
	UseHTTPS bool `validate:"-"`

	// BaseEndpoint is the base route path for API requests.
	//
	// Note: While this path is fixed by the Space Engineers server, this option
	// allows customization when routing through a reverse proxy.
	//
	// Example: "/custompath", "/", or ""
	//
	// Default:
	//  ToPtr(DefaultAPIEndpoint)
	BaseEndpoint *string `validate:"-"`

	// HTTPClient allows the use of a custom HTTP client for making requests.
	//
	// If not provided, a default client with the specified Timeout will be used.
	//
	// Warning: when using a custom HTTPClient the Timeout field in ClientConfig will be ignored.
	// In this case, ensure the custom HTTPClient has an appropriate timeout set to avoid hanging requests.
	HTTPClient *http.Client `validate:"-"`
}

ClientConfig holds the configuration settings for the VRage Remote API client.

func (*ClientConfig) SetDefaults added in v0.0.7 

func (c *ClientConfig) SetDefaults()

SetDefaults initializes default values for ClientConfig fields that are not explicitly set.

func (*ClientConfig) Validate added in v0.0.6 

func (c *ClientConfig) Validate() error

Validate checks the ClientConfig for required fields and valid values.

type HTTPClient added in v0.0.12 

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

HTTPClient handles all HTTP requests.

func (*HTTPClient) DeleteV1AdminBannedPlayersSteamID added in v0.0.21 

func (c *HTTPClient) DeleteV1AdminBannedPlayersSteamID(steamID uint64) (*http.Response, error)

DeleteV1AdminBannedPlayersSteamID unbans a player with the specified Steam ID and returns the HTTP response. 

DELETE /v1/admin/bannedPlayers/{steam_id}

func (*HTTPClient) DeleteV1AdminKickedPlayersSteamID added in v0.0.22 

func (c *HTTPClient) DeleteV1AdminKickedPlayersSteamID(steamID uint64) (*http.Response, error)

DeleteV1AdminKickedPlayersSteamID un-kicks a player with the specified Steam ID and returns the HTTP response. 

DELETE /v1/admin/kickedPlayers/{steam_id}

func (*HTTPClient) DeleteV1AdminPromotedPlayersSteamID added in v0.0.20 

func (c *HTTPClient) DeleteV1AdminPromotedPlayersSteamID(steamID uint64) (*http.Response, error)

DeleteV1AdminPromotedPlayersSteamID demotes a player with the specified Steam ID and returns the HTTP response. 

DELETE /v1/admin/promotedPlayers/{steam_id}

func (*HTTPClient) DeleteV1Server added in v0.0.13 

func (c *HTTPClient) DeleteV1Server() (*http.Response, error)

DeleteV1Server stops the server and returns the HTTP response.

returns 200 OK with empty body if the server was successfully stopped 

DELETE /v1/server

func (*HTTPClient) Do added in v0.0.12 

func (c *HTTPClient) Do(
	method httpMethod,
	endpoint string,
	jsonPayload jsonMap,
	headers httpHeaders,
) (*http.Response, error)

Do sends an HTTP request to the API with the specified method, endpoint, JSON payload, and headers and returns the pure HTTP response and error without any wrapping.

func (*HTTPClient) DoErr added in v0.0.16 

func (c *HTTPClient) DoErr(
	method httpMethod,
	endpoint string,
	jsonPayload jsonMap,
	headers httpHeaders,
) (*http.Response, error)

DoErr sends an HTTP request to the API and returns the HTTP response or sentinel errors defined in errors.go.

func (*HTTPClient) GetV1AdminBannedPlayers added in v0.0.21 

func (c *HTTPClient) GetV1AdminBannedPlayers() (*http.Response, error)

GetV1AdminBannedPlayers fetches a list of banned players and returns the HTTP response. 

GET /v1/admin/bannedPlayers

func (*HTTPClient) GetV1AdminKickedPlayers added in v0.0.22 

func (c *HTTPClient) GetV1AdminKickedPlayers() (*http.Response, error)

GetV1AdminKickedPlayers fetches a list of kicked players and returns the HTTP response. 

GET /v1/admin/kickedPlayers

func (*HTTPClient) GetV1ServerPing added in v0.0.13 

func (c *HTTPClient) GetV1ServerPing() (*http.Response, error)

GetV1ServerPing fetches a ping response from the server and returns the HTTP response. 

GET /v1/server/ping

func (*HTTPClient) GetV1ServerStatus added in v0.0.13 

func (c *HTTPClient) GetV1ServerStatus() (*http.Response, error)

GetV1ServerStatus fetches the current status of the server and returns the HTTP response. 

GET /v1/server

func (*HTTPClient) PostV1AdminBannedPlayersSteamID added in v0.0.21 

func (c *HTTPClient) PostV1AdminBannedPlayersSteamID(steamID uint64) (*http.Response, error)

PostV1AdminBannedPlayersSteamID bans a player with the specified Steam ID and returns the HTTP response. 

POST /v1/admin/bannedPlayers/{steam_id}

func (*HTTPClient) PostV1AdminKickedPlayersSteamID added in v0.0.22 

func (c *HTTPClient) PostV1AdminKickedPlayersSteamID(steamID uint64) (*http.Response, error)

PostV1AdminKickedPlayersSteamID kicks a player with the specified Steam ID and returns the HTTP response. 

POST /v1/admin/kickedPlayers/{steam_id}

func (*HTTPClient) PostV1AdminPromotedPlayersSteamID added in v0.0.20 

func (c *HTTPClient) PostV1AdminPromotedPlayersSteamID(steamID uint64) (*http.Response, error)

PostV1AdminPromotedPlayersSteamID promotes a player with the specified Steam ID and returns the HTTP response. 

POST /v1/admin/promotedPlayers/{steam_id}

Source Files

View all Source files

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.