gRPC#
kRPC includes a gRPC server. It lets you control the game from any
language gRPC supports, with a client generated from .proto files.
Note
Where your language has a kRPC client, use it instead. The kRPC clients support streams and events, and have a more concise syntax.
Configuring the Server#
The gRPC server is not enabled by default. To add it in the server window:
Open the server window from kRPC > Server in the game’s menu bar at the top.
Click Add server, then Edit on the new server.
Set Protocol to gRPC, and the Port, by default 50002. Click Save.
Start the servers with Start servers.
The server auto-accepts a new client as the other servers do. With Auto-accept new clients turned off, the game asks before a client’s first call runs.
Generating a Client#
The stubs/grpc folder of the release archive holds a .proto file for each kRPC service.
Generate a client from them with protoc and the gRPC plugin for your language.
The gRPC documentation has a quick start and a basics tutorial for each supported language, covering code generation, channels and calls.
For Python, with the KSA kRPC service:
pip install grpcio grpcio-tools
python -m grpc_tools.protoc -I stubs/grpc --python_out=. --grpc_python_out=. \
stubs/grpc/KSA.proto stubs/grpc/StdLib.proto
This Python script uses the generated client to print the name of the active vehicle and the universal time:
import grpc
# Generated from stubs/grpc/KSA.proto
import KSA_pb2 as ksa
import KSA_pb2_grpc
channel = grpc.insecure_channel("127.0.0.1:50002")
# The server shows this name in its list of clients
metadata = (("krpc-client-name", "Example"),)
service = KSA_pb2_grpc.KSAServiceStub(channel)
vehicles = KSA_pb2_grpc.VehicleServiceStub(channel)
vehicle = service.GetActiveVehicle(
ksa.KSA.GetActiveVehicleRequest(), metadata=metadata
).value
name = vehicles.GetName(ksa.Vehicle.GetNameRequest(this=vehicle), metadata=metadata)
print(name.value)
ut = service.GetUT(ksa.KSA.GetUTRequest(), metadata=metadata)
print(f"UT {ut.value:.0f} s")
channel.close()
Names#
A gRPC client calls methods, which are grouped into gRPC services. Each method takes one
request message and returns one response message. The .proto file of a kRPC service lays
out its procedures this way:
Each class becomes a gRPC service named after it, such as
VehicleService.Each procedure becomes a method. A property becomes a
Getmethod, and aSetmethod if it can be set.The arguments are fields of the request message, and the return value is the
valuefield of the response. For a method on an object, the object is the request’sthisfield.
In the script above, this call reads the Vehicle.Name property:
vehicles.GetName(ksa.Vehicle.GetNameRequest(this=vehicle))
Each kind of procedure maps as follows. Each request message has a matching response message,
such as Vehicle.GetNameResponse.
Kind |
kRPC |
gRPC method |
gRPC request message |
|---|---|---|---|
Procedure |
|
|
|
Property |
|
|
|
Class property getter |
|
|
|
Class property setter |
|
|
|
Class method |
|
|
|
Static class method |
|
|
|
Types#
The values in the messages have these forms:
kRPC |
gRPC |
|---|---|
Parameter |
Field in |
Parameter with a default value |
Field left out to use the default |
Object |
Message holding the id, such as |
Tuple |
Message with fields |
List and set |
|
Dictionary |
|
Enumeration value |
Prefixed with the enumeration name, such as |
Features#
The gRPC server provides procedures as unary calls:
Calls only. Streams and events have no gRPC form, so poll a value to follow it.
One client per connection. Each HTTP/2 connection is one kRPC client, named by the
krpc-client-namemetadata on its calls. The client connects with its first call, and the server list shows it like any other.Calls run in game. A call that waits, such as
WarpTo, holds up only the calls of its own connection. The game finishes a call even after the client cancels it or its deadline passes, and drops the response.Errors are status codes. An argument error is
INVALID_ARGUMENT, an invalid operation isFAILED_PRECONDITIONand any other error isUNKNOWN. Thekrpc-error-nameandkrpc-error-servicetrailers name the exception, as the other clients raise it.