Lua Client#

This client provides functionality to interact with a kRPC server from programs written in Lua. It can be installed using LuaRocks or downloaded from GitHub.

Installing#

The client runs on Lua 5.1 to 5.4 and LuaJIT. It and all of its dependencies can be installed using luarocks with a single command:

luarocks install krpc

Getting Started#

Once it’s installed, simply require 'krpc' and you are good to go!

Connecting to the Server#

To connect to a server, use the krpc.connect() function. This returns a connection object through which you can interact with the server. For example to connect to a server running on the local machine:

local krpc = require 'krpc'
local conn = krpc.connect('Example')
print(conn.krpc.get_status().version)

This function also accepts arguments that specify what address and port numbers to connect to. For example:

local krpc = require 'krpc'
local conn = krpc.connect('Remote example', 'my.domain.name', 1000)
print(conn.krpc.get_status().version)

Interacting with the Server#

Interaction with the server is performed via the client object (of type krpc.Client) returned when connecting to the server using krpc.connect().

Upon connecting, the client interrogates the server to find out what functionality it provides and dynamically adds all of the classes, methods, properties to the client object.

For example, all of the functionality provided by the SpaceCenter service is accessible via conn.space_center and the functionality provided by the InfernalRobotics service is accessible via conn.infernal_robotics.

Calling methods, getting or setting properties, etc. are mapped to remote procedure calls and passed to the server by the lua client.

Many procedures return an object identifying something in the game, such as a vessel or a part. See Object Lifetime for how such an object behaves when a game is loaded or what it identifies is destroyed.

Streams and Events#

These features are not supported by the Lua client.

Reference#

connect([name=''][, address='127.0.0.1'][, rpc_port=50000])#

This function creates a connection to a kRPC server. It returns a krpc.Client object, through which the server can be communicated with.

Parameters:

name (string) – A descriptive name for the connection. This is passed to the server and appears, for example, in the client connection dialog on the in-game server window.
address (string) – The address of the server to connect to. Can either be a hostname or an IP address in dotted decimal notation. Defaults to ‘127.0.0.1’.
rpc_port (number) – The port number of the RPC Server. Defaults to 50000.

krpc.connect_local([name][, rpc_path])#

This function connects to a kRPC server running on the same machine, over a unix domain socket rather than TCP/IP. It returns a Client object, just as krpc.connect() does, and the connection behaves identically thereafter.

This needs luasocket’s socket.unix module, which luasocket builds on Linux and macOS.

Note

luasocket does not yet build socket.unix on Windows. Connect with krpc.connect() there instead.

Parameters:

name (string) – A descriptive name for the connection. This is passed to the server and appears, for example, in the client connection dialog on the in-game server window.
rpc_path (string) – The path of the socket the RPC Server is listening on. This should match the RPC socket path shown in the in-game server window. Defaults to the path the server uses unless it was configured with another.

krpc.get_object_id(obj)#

The identifier of a remote object on the server, e.g. to pass to KRPC.Expression.constant_object(). Raises an error if the object is nil or krpc.types.none.

Parameters:: obj – The remote object.
Return type:: number

class krpc.Client#

This class provides the interface for communicating with the server. It is dynamically populated with all the functionality provided by the server. Instances of this class should be obtained by calling krpc.connect().

close()#: Closes the connection to the server.

krpc: #

The built-in KRPC class, providing basic interactions with the server.

Return type:: krpc.KRPC

class krpc.KRPC#

This class provides access to the basic server functionality provided by the KRPC service. An instance can be obtained by calling krpc.Client.krpc. Most of this functionality is used internally by the lua client and therefore does not need to be used directly from application code. The only exception that may be useful is:

get_status()#

Gets a status message from the server containing information including the server’s version string and performance statistics.

For example, the following prints out the version string for the server:

local krpc = require 'krpc'
local conn = krpc.connect()
print('Server version = ' .. conn.krpc.get_status().version)

Or to get the rate at which the server is sending and receiving data over the network:

local krpc = require 'krpc'
local conn = krpc.connect()
local status = conn.krpc.get_status()
print(string.format('Data in = %.2f KB/s', status.bytes_read_rate/1024))
print(string.format('Data out = %.2f KB/s', status.bytes_written_rate/1024))

Numeric Limits#

The krpc.limits module names the extremes of the numeric types kRPC carries over the wire. A service can declare one of these limits as a parameter’s default value, and it is then documented as the constant here.

The minimum of an unsigned type is 0, so it has no constant.

From Lua 5.3 on, a 64-bit value is an exact integer. Lua has no unsigned integer type. A uint64 above \(2^{63} - 1\) wraps to a negative integer, so krpc.limits.UINT64_MAX is -1. math.ult compares two such values.

Note

In Lua 5.1, 5.2 and LuaJIT every number is a double, which holds an integer exactly up to \(2^{53}\). krpc.limits.SINT64_MAX and krpc.limits.UINT64_MAX round up to \(2^{63}\) and \(2^{64}\), as does a 64-bit value arriving from the server.

limits.DOUBLE_MAX#
limits.DOUBLE_LOWEST#: The largest and most negative finite 64-bit float.

limits.FLOAT_MAX#
limits.FLOAT_LOWEST#: The largest and most negative finite 32-bit float.

limits.SINT32_MAX#
limits.SINT32_MIN#: The largest and most negative 32-bit signed integer.

limits.SINT64_MAX#
limits.SINT64_MIN#: The largest and most negative 64-bit signed integer.

limits.UINT32_MAX#: The largest 32-bit unsigned integer.

limits.UINT64_MAX#: The largest 64-bit unsigned integer.