Launch Payload

The launch payload is data you hand a game server for a specific match, like the match id, game mode, or team roster. It's a string, usually JSON, that your server reads through the Game Server SDK.

Unlike environment variables, which are set once when a server starts, the payload can change if a server is reused for a new match.

Who writes the payload

It depends on how the server gets its players:

• Direct allocation: your backend passes a payload string when it starts or allocates a server. Its contents are up to you. See Custom Game Backend.
• Matchmaking: GameFlow formed the match, so GameFlow writes the payload for you.

Matchmaking payload

{
  "match_id": "match-6f1e...",
  "game_mode": "ranked",
  "team_count": 2,
  "teams": [
    {
      "team_index": 0,
      "players": [
        { "player_id": "p1", "ticket_id": "t1", "slot_index": 0 }
      ]
    }
  ]
}

Field	Description
match_id	GameFlow's id for the match. Pass it back when reporting match analytics or results.
game_mode	Game mode of the tickets that formed the match.
team_count	Number of teams.
teams[].team_index	Team position, starting at 0.
teams[].players[]	Players on the team, with their player_id, ticket_id and slot_index.

Reading the payload

Call payload() on startup and parse the string. If a server can be reused for another match, also subscribe to payload changes.

Unity (C#)

var payload = await gf.Payload(); // string (null when none)
// Parse with JsonUtility or Newtonsoft.Json

gf.OnPayloadChange(next => {
    // fires when the platform assigns this server to a new match
});

Unreal (C++)

GF->GetPayload([](FGameFlowError Err, FString Payload) { /* parse it */ });

// Or bind the Blueprint-assignable event:
GF->OnPayloadChanged.AddDynamic(this, &AMyGameMode::HandlePayloadChanged);

Godot

var res := await gf.payload()
if res.value != null:
    var match_config = JSON.parse_string(res.value)

gf.on_payload_change(func(next): pass) # match (re)assignment

TypeScript

const payload = await gf.payload(); // string | undefined
const match = payload ? JSON.parse(payload) : null;

gf.onPayloadChange((next) => {
  // fires when the platform assigns this server to a new match
});

Rust

let payload: Option<String> = gf.payload().await?;

gf.on_payload_change(|next| {
    // fires when the platform assigns this server to a new match
});

Go

payload, _ := gf.Payload(ctx) // string

gf.OnPayloadChange(func(next string) {
    // fires when the platform assigns this server to a new match
})

warning

Always read the payload with payload(). Reading GAMEFLOW_PAYLOAD from the environment may work locally, but returns nothing in production.

Related

• Environment Variables: region, ports and your own configuration.
• Integrating with Your Game: how matchmaking hands matches to your server.
• Match Analytics: using match_id to report how a match went.