Skip to content

RLBot Sockets Specification

Data Types

Bold items indicate the messages that bots/scripts/etc. can recieved from RLBot.

  1. None
    • Aka the disconnect request. This can be sent to indicate that you want to disconnect, and this message will be sent back as confirmation of the disconnect. Ideally your bot only disconnects after this message is sent. If anything else happens, an error should be put out.
  2. GamePacket
    • Received by sessions at a high rate according to tick rate
  3. FieldInfo
    • Received by a session after it sends ConnectionSettings.
  4. StartCommand
    • Starts a new match after reading the given config file.
  5. MatchConfiguration
    • Received by a session after it sends ConnectionSettings.
    • Can be sent by sessions to start a new match.
  6. PlayerInput
    • Sent by sessions to control their cars.
  7. DesiredGameState
    • Sent by sessions to change the game state.
    • Ignored if state setting was disabled in the match settings.
  8. RenderGroup
    • Sent by sessions to render lines & text in the game.
    • Ignored if render setting was disabled in the match settings.
  9. RemoveRenderGroup
    • Sent by sessions to remove a render group.
    • Ignored if render setting was disabled in the match settings.
  10. MatchComm
    • A copy is received by sessions when another session sends the message.
    • Messages may not be received if the message was filtered due to team_only being requested in the message.
    • Only received if enabled in ConnectionSettings.
  11. BallPrediction
    • Received by sessions right before every GamePacket if enabled in ConnectionSettings.
  12. ConnectionSettings
    • Sessions send this immediately after connecting.
    • Tells the server what kind of data it wants to receive.
  13. StopCommand
    • Ends the current match, and optionally tells RLBotServer.exe to shut itself down.
  14. SetLoadout
    • Sent by sessions to change the loadout of their cars.
    • Will always work if a loadout was not specified in match settings and when sent before InitComplete.
    • Ignored if state setting was disabled in the match settings, and a loadout was set in match settings.
  15. InitComplete
    • Indicates that the session has finished all initialization and is ready to start receiving game messages without delay.
    • The match will not start until all sessions have sent this message.
    • There is no data associated with this message.
  16. ControllableTeamInfo
    • Contains information about the cars that the client can control.
    • Received by a session after it sends ConnectionSettings.
    • There may be more than one car in case the bot is a hivemind.

Connecting to RLBotServer

  1. Read the environment variable RLBOT_SERVER_IP and default to 127.0.0.1
  2. Read the environment variable RLBOT_SERVER_PORT and default to 23234
  3. Connect to the given IP/port via TCP.

Message format

This project uses flatbuffers as the data format, prefixed with a 2 32-bit unsigned integer. All messages should be big endian.

  • Read the first 32-bit unsigned integer. This is the data type.
  • Read the second 32-bit unsigned integer. This is n, the length of the flatbuffer in bytes.
  • Read n bytes, and deserialize this into the correct flatbuffer according to the data type.

Replace "read" with "write" to send a message.

Connection handshake

After connecting to RLBotServer via TCP, bots and scripts must perform a handshake to get access to game data. If this is not performed, then various functionality will be limited, for example, all player inputs will be rejected by the server.

  1. Send a ConnectionSettings
    • The environment variable RLBOT_AGENT_ID will be set by RLBotServer before launching your process. This can be passed as AgentId, or a hardcoded default can be used if the environment variable was not present. A hardcoded default is useful during development when the process may be getting started manually.
    • For bots & scripts, CloseBetweenMatches should always be true with no alternate option.
  2. Recieve match information - In no guarenteed order, wait for all of the following to arrive:
    • MatchConfiguration
    • FieldInfo
    • ControllableTeamInfo - sent for bots & scripts. If AgentId was invalid or blank, this will be empty. If this was intentional, continue as normal.
  3. Parse ControllableTeamInfo for your team, index(s), and spawnId(s). There will be multiple if this is a bot that was designated as a hivemind.
    • If team is 0 or 1: index will be the index of your bot in GamePacket
    • If team is 2: index will be the index of your script in MatchConfiguration
  4. spawnId can be used to find your bot/scripts's name in MatchConfiguration.
    • DO NOT USE index FOR BOTS, they are not in the correct order in MatchConfiguration. Using index is ok for scripts but spawnId can be used for both.
  5. Perform heavy initialization.
    • At this point, most information needed for bots to initialize most of their variables is known. Have some kind of callback that lets developers do this now. RLBotServer will load the map but won't start the match while bots are initializing.
  6. Send InitComplete. This is a message with no content, and signifies to RLBotServer that the match can be started.
  7. Done, enter main control loop

Main control loop

Requires the connection handshake to have been performed first. Depending on what was sent in ConnectionSettings, some of the following packets may not be sent.

  • Every tick, BallPrediction will always be sent before GamePacket.
  • If BallPrediction is not sent, it's because it was disabled in ConnectionSettings
  • MatchComm will arrive in between ticks. The sending of these messages can be disabled in ConnectionSettings