Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

kRPC-rb Gem Version Build Status

kRPC-rb is a Ruby client library for kRPC, a Kerbal Space Program mod that allows you to control KSP from external scripts running outside of the game.

kRPC-rb image


gem install krpc

or install the latest pre-release version (if available): gem install krpc --pre

Basic usage

require 'krpc'
client = KRPC.connect(name: "client name here")
vessel = client.space_center.active_vessel
ctrl = vessel.control = true
ctrl.sas_mode = :stability_assist
ctrl.throttle = 1
puts "Launching #{}!"

Most of the API is very similar to what can be found in (official) Python client library. So official documentation at is definitely a good read. The rest of this file describes few differences there are between Ruby and Python client libraries.

Connecting and disconnecting

When you are in REPL, you can connect to kRPC server in this way:

client = KRPC.connect(name: {name for the client}, host: {kRPC server host}, rpc_port: {kRPC server rpc port}, stream_port: {kRPC server stream port})
# use client here...

All of the KRPC.connect's arguments are optional, so client = KRPC.connect might be enough for you. Alternatively you can be more explicit (yet still obtain the same result):

client = {The same argument list as KRPC.connect has} ).connect!
# use client here...

If you are writing a script, you can pass a block into KRPC.connect, Client#connect or Client#connect! methods. Connection to kRPC server is closed at the end of the block.

KRPC.connect do |client|
# do something with client here...
end # closes connection

Data structures mapping

kRPC server (and KSP itself) is written in C#. This means that during communication with the server there must be some data structure mapping being done. Most of the mappings are pretty obvious: numbers are mapped to Floats and Integers, Strings to Strings, Lists to Arrays, Dictionaries to Hashes etc.

It may be less obvious that Enum values are mapped to Symbols:

client.space_center.active_vessel.situation # => :orbiting
client.space_center.active_vessel.control.sas_mode = :prograde

To see all values for enum, you can call method that expects enum argument or returns enum value with _doc suffix. Alternatively you can print the hash that represents given enum:

puts KRPC::Gen::SpaceCenter::SASMode # => {:stability_assist=>0, :maneuver=>1, :prograde=>2, :retrograde=>3, :normal=>4, :anti_normal=>5, :radial=>6, :anti_radial=>7, :target=>8, :anti_target=>9}

Tuples are mapped to Arrays:

client.space_center.active_vessel.flight.center_of_mass # => [-0.0015846538639403215, 0.0005474663704413168, 0.000849766220449432]

Get your fingers dirty

The best way to explore the API is to run REPL and try what each method does for yourself. I highly recommend using Pry as REPL. This way you can ls any object you receive and see what methods you can call on it. When you want to know more about specific method, then just stuck _doc at the end of it's name and press enter:

[29] pry(main)> client.space_center.transform_position_doc
	position :Array[Float, Float, Float], - Position vector in reference frame from.
	from :ReferenceFrame, - The reference frame that the position vector is in.
	to :ReferenceFrame - The reference frame to covert the position vector to.
) :Array[Float, Float, Float] - The corresponding position vector in reference frame to.

 Converts a position vector from one reference frame to another.
=> nil

I recommend ending the line with ; to suppress printing return value (the => nil line at the end). If you want doc for method whose name ends with a = sign, you can put _doc before the =. Alternatively use Object#send, like in: client.space_center.send "active_vessel=_doc".

Combination of lss and _docs should teach you API in no time (also don't be surprised if you have a lot of fun with it too :))

kRPC-rb in-REPL documentation example


A stream repeatedly executes a function on the server, with a fixed set of argument values. It provides a more efficient way of repeatedly getting the result of calling function on the server, without having to invoke it directly – which incurs communication overheads.

To create a stream, call a method with _stream suffix. This will return KRPC::Streaming::Stream instance. You can call get (or value) on the Stream instance to get the recent value received by this stream. To deactivate the stream call remove (or close) on the Stream instance.

Example without streaming:

vessel = client.space_center.active_vessel
refframe = vessel.orbit.body.reference_frame
loop do
  puts vessel.position(refframe)

Equivalent example with streaming:

vessel = client.space_center.active_vessel
refframe = vessel.orbit.body.reference_frame
pos_stream = vessel.position_stream(refframe)
loop do
  puts pos_stream.get
pos_stream.remove #note: dead code - just as an example

Want to know more?