vrage

README

go-vrage

go-vrage is a Go client for the VRage Remote API of Space Engineers 1.

It can be used to programmatically manage and monitor Dedicated Servers, including retrieving server status, managing players, and executing server commands.

[!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.

Features

coming soon

Installation

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

go get -u 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
• Variables
• type APIServerPingV1Data
• type APIServerStatusData
• type BaseResponse
• type Client
  • func NewClient(config ClientConfig) (*Client, error)
• type ClientConfig
  • func (c *ClientConfig) SetDefaults()
  • func (c *ClientConfig) Validate() error
• type Meta

Constants

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

Default configuration values for the VRage Remote API client.

Variables

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

var (
	ErrAPIConnectionFailed   = errors.New("failed to connect to the server: check if the server is running and reachable")
	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")
)

ErrAPI... are errors for API request failures

Types

type APIServerPingV1Data

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

type APIServerStatusData

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"`
}

type BaseResponse

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

BaseResponse represents the base response structure of the API.

type Client

type Client struct {
	Config  ClientConfig
	HTTP    httpClient
	Session apiSession
	Server  apiServer
	Admin   apiAdmin
}

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

func (c *ClientConfig) SetDefaults()

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

func (*ClientConfig) Validate

func (c *ClientConfig) Validate() error

Validate checks the ClientConfig for required fields and valid values.

type Meta

type Meta 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"`
}

Meta represents the metadata of the API response.