Channels and data formats

In theory, you can use anything you like for (de-)serialization, like JSON or XML. The idea, however, is to use Protobuf. The client libraries contain a lot of functionality that take care of serialization/deserialization for you, and provide you with typed messages (which looks a little different depending on which platform you’re on).

How to define a data exchange model (data contract) for your project

If you’re unfamiliar with Protobuf, start by looking at the Protobuf Language Guide.

1. Create a bunch of .proto files.
2. Use the protoc compiler to generate source files for your language.
3. Get protobuf generation into your build system.

Take a look at proto-definitions for common messages for inspiration.

Common patterns using protobufs

Request-response and state updates

A certain aspect of the simulation (i.e. a set of states for a certain type of object) is typically defined by one .proto definition, communicated on one channel. A lot of times one wants to send state updates periodically or triggered by changes, but also allow for other clients to request a full state update. Or, you might want to send something only on request, i.e. request-response.

This can be achieved by using two channels (one for requests and one for response), or you might find it cleaner using a top-level oneof to combine it into one channel.

syntax = "proto3";
import "google/protobuf/empty.proto";

message Items {
  oneof {
    google.protobuf.Empty request_items = 1;
    Item item = 2;
  }

  message Item {
    string name = 1;
  }
}

See the standard Scenarios message for an example.