JSON Message Specification

WARNING

This is an experimental implementation of RLBot. The message format here is likely to change, if and when this gets adopted.

Messages sent from RLBot (JSON format)

When a match starts, or your bot connects to RLBot mid-match, it will receive an Initialize message once. This describes information about the game that does not change over time.

{
  "type": "Initialize",
  "map": "Mannfield",
  "mode": "soccer",
  "match_length": "5 minutes",
  "max_score": "unlimited",
  "overtime": "unlimited",
  "series": "unlimited",
  "speed": "default",
  "max_ball_speed": "default",
  "ball_shape": "default",
  "ball_weight": "default",
  "ball_size": "default",
  "ball_bounciness": "default",
  "boost": "default",
  "boost_strength": "default",
  "gravity": "default",
  "demolition": "default",
  "respawn": "3 seconds",
  
  "ball": {
    "shape": 0,
    "radius": 92.15,
    "height": -1.0
  },
  
  "cars": [{
      "name": "Botimus",
      "team": 0,
      "is_bot": true,
      "body_type": 0,
      "hitbox_offset": {0.2, 1.3, 0.2},
      "hitbox_dimensions": {65.0, 23.0, 120.0}
    }, {
    ...
  }],
  
  "pads": [{
      "type": 0,
      "position": {1024.0, -512.0, 0.0}
    }, {
    ...  
  }],
  
  "goals": [{
      "team": 0,
      "position": {0.0, -5120.0, 0.0},
      "direction": {0.0, 1.0, 0.0},
      "width": 600.0,
      "height": 500.0
    }, {
    ...  
  }]
}

The up to date game information is included in every packet as a message of type Update:

{
  "type": "Update",
  "frame": 193,
  "time_left": 91,
  "state": "Kickoff",
  "score": [2, 3],
  "ball": {
    "position": {1.0, 2.0, 3.0},
    "velocity": {1.0, 2.0, 3.0},
    "euler_angles": {1.0, 2.0, 3.0},
    "angular_velocity": {1.0, 2.0, 3.0}
  },
  "cars": [{
    "position": {1.0, 2.0, 3.0},
    "velocity": {1.0, 2.0, 3.0},
    "euler_angles": {1.0, 2.0, 3.0},
    "angular_velocity": {1.0, 2.0, 3.0},
    "boost": 25,
    "state": "OnGround"
  }, {
    ...
  }],
  "boost_pads": [0, 1, 0, 0, 1, 1, 1, ... 1, 0],
  "goals": [0, 0]
}

Bots can also receive custom messages from the controller process, or other bots. The id field describes who sent the message (65535 if sent from the controller process).

{
  "type": "Custom",
  "contents": "I've got it! Hitting ball on frame 281",
  "id": 0
}

A terminate message is also part of the specification, so RLBot and/or the controller process can kill execution of any bot.

{
  "type": "Terminate"
}

Messages sent to RLBot (JSON format)

The ready message is used to let RLBot know the bot has been initialized and is ready to go. RLBot can be configured to start the new match once all of the bots in the lobby are ready. By specifiying multiplicity greater than 1, a process can manage multiple bots over a single TCP connection (all on the same team, with the same loadout).

{
  "type": "Ready",  
  "name": "Botimus",
  "id": 0,
  "team": 0,
  "multiplicity": 1
  "loadout": {
    "primary": {127, 255, 0},
    "secondary": {0, 255, 0},
    "car_id": 23,
    "car_paint_id": 12,
    "decal_id": 0,
    "decal_paint_id": 0,
    "wheels_id": 1565,
    "wheels_paint_id": 12,
    "boost_id": 35,
    "boost_paint_id": 7,
    "antenna_id": 0,
    "antenna_paint_id": 0,
    "hat_id": 0,
    "hat_paint_id": 0,
    "engine_audio_id": 0,
    "custom_finish_id": 1681,
    "paint_finish_id": 1681,
    "trails_id": 3220,
    "trails_paint_id": 2,
    "goal_explosion_id": 3018,
    "goal_explosion_paint_id": 0
  }
}

The main response message is the PlayerInput, which determines how the bot will behave.

{
  "type": "PlayerInput",  
  "steer": 0.53,
  "throttle": 0.2,
  "roll": 0.8,
  "pitch": 0.1,
  "yaw": -0.3,
  "jump": 0,
  "boost": 0,
  "use_item": 0,
  "handbrake": 0
}

State setting messages are also supported in non-league play. The car and ball states can be set by sending the following messages:

{
  "type": "SetCarState",
  "id": 1,
  "position": {1.0, 2.0, 3.0},
  "velocity": {1.0, 2.0, 3.0},
  "euler_angles": {1.0, 2.0, 3.0},
  "angular_velocity": {1.0, 2.0, 3.0},
  "boost": 25  
}

{
  "type": "SetBallState",
  "position": {1.0, 2.0, 3.0},
  "velocity": {1.0, 2.0, 3.0},
  "euler_angles": {1.0, 2.0, 3.0},
  "angular_velocity": {1.0, 2.0, 3.0}
}

As before, bots can send each other custom messages. When sending, the id describes the intended recipient.

{
  "type": "Custom",
  "contents": "I've got it! Hitting ball on frame 281",
  "id": 2
}

Basic debug rendering is supported in the Draw message type. It allows for batch rendering of polylines and 2D text. The id field associates a number with the batch of lines and text, so that a bot can leave some rendered content active for longer periods of time, and selectively clear others. Note: text currently uses normalized coordinates between 0 and 1 for the position.

{
  "type": "Draw",
  "id": 0,
  "lines": [{
    "color": [255, 0, 0],
    "points": [
      [0, 0, 0],
      [1, 2, 3],
      [1, 23, 169],
      ...
    ]
  },{
      ...
  }],
  "text": [{
    "color": [255, 0, 0],
    "position": [0.25, 0.1],
    "scale": 0.1,
    "text": "this is what I want to display"
  },{
    ...
  }]
}

Rendered content associated with a bot is automatically cleared when that bot disconnects from RLBot. To clear render groups, a bot can also issue Clear messages with an appropriate id.

{
  "type": "Clear",
  "id": 0
}