Gameye + AWS FlexMatch

Updated July 1, 2026

What changes vs. GameLift-hosted FlexMatch

The key change in your codebase: one Lambda function that calls POST /session instead of creating a GameLift game session. Everything upstream — matchmaking configuration, rule set, ticket submission — is identical.

What you need

Integration

{
  "Name": "your-matchmaking-config",
  "FlexMatchMode": "STANDALONE",
  "RequestTimeoutSeconds": 30,
  "AcceptanceRequired": false,
  "BackfillMode": "MANUAL",
  "RuleSetName": "your-ruleset",
  "NotificationTarget": "arn:aws:sns:us-east-1:YOUR_ACCOUNT:matchmaking-events"
}

// Fetch available regions for your image
const { locations } = await fetch(
  'https://api.gameye.io/available-location/your-image-name',
  { headers: { Authorization: `Bearer ${GAMEYE_TOKEN}` } }
).then(r => r.json());

// Measure latency to each region's pingable IP
const latencies: Record<string, number> = {};
for (const loc of locations) {
  latencies[loc.location] = await measurePing(loc.latencyIp); // ms
}

// Submit ticket — include latency as playerAttributes
await gamelift.startMatchmaking({
  ConfigurationName: 'your-matchmaking-config',
  Players: [{
    PlayerId: player.id,
    PlayerAttributes: {
      skill:             { N: player.mmr },
      gameye_europe_ms:  { N: latencies['europe']    ?? 9999 },
      gameye_useast_ms:  { N: latencies['us-east']   ?? 9999 },
      gameye_asia_ms:    { N: latencies['asia-east'] ?? 9999 },
    }
  }]
}).promise();

export async function handler(event: EventBridgeEvent) {
  const { matchId, tickets } = event.detail;
  const players = tickets.flatMap(t => t.players);

  // Select region with lowest worst-case latency across all players
  const region = selectBestRegion(players);

  // Start Gameye session
  const res = await fetch('https://api.gameye.io/session', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.GAMEYE_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      location: region,
      image:    'your-image-name',
      version:  process.env.GAME_IMAGE_VERSION,
      args:     ['/Game/Maps/Gameplay', `-maxplayers=${players.length}`],
      labels:   { match_id: matchId },
      ttl:      3600,
    }),
  });

  const session = await res.json();
  // session.host  → IP address
  // session.ports → [{ type: 'udp', container: 7777, host: 34521 }]
  const port = session.ports.find(p => p.type === 'udp').host;

  await saveMatchSession(matchId, session.host, port); // e.g. DynamoDB
  await notifyPlayers(players, { host: session.host, port });
}

function selectBestRegion(players: FlexMatchPlayer[]): string {
  const regions = {
    'europe':    'gameye_europe_ms',
    'us-east':   'gameye_useast_ms',
    'asia-east': 'gameye_asia_ms',
  };
  return Object.entries(regions)
    .map(([region, attr]) => ({
      region,
      worstMs: Math.max(...players.map(p => p.playerAttributes?.[attr]?.N ?? 9999))
    }))
    .sort((a, b) => a.worstMs - b.worstMs)[0].region;
}

# Player connected
POST https://api.gameye.io/session/player/join
{ "sessionId": "session-id", "playerId": "player-id" }

# Player disconnected
POST https://api.gameye.io/session/player/leave
{ "sessionId": "session-id", "playerId": "player-id" }

Session lifecycle

Backfill

If players drop mid-match, keep BackfillMode: MANUAL. When a player leaves:

1. Your game server notifies the backend of the open slot.
2. Backend calls StartMatchBackfill with the current session roster.
3. FlexMatch finds a replacement and fires MatchmakingBackfillSucceeded.
4. Lambda receives the event — no new session — reads the existing session from your data store and notifies the new player with the current host and port.
5. Backend calls POST /session/player/join for the new player.

Migration from GameLift

If your game is live on FlexMatch + GameLift today, this migration can be done without player-facing downtime:

1. 1
   Register your Docker image with Gameye — onboarding, no code changes required.
2. 2
   Deploy the Lambda bridge in parallel — it doesn't affect live GameLift sessions.
3. 3
   Create a new FlexMatch config in STANDALONE mode pointing to the Lambda.
4. 4
   Route a small percentage of traffic to the new config via a feature flag in your matchmaking request logic.
5. 5
   Validate — session starts, latency, cost metrics.
6. 6
   Shift 100% of traffic and decommission your GameLift fleet.

FlexMatch standalone mode: developer reference

The questions developers hit most when wiring FlexMatch to external hosting — answered against the standalone flow above.

What's in the FlexMatch MatchmakingSucceeded event?

When a match forms, FlexMatch publishes a MatchmakingSucceeded event. The payload carries the match result — who matched, their team assignments, and the per-player latency data you use to pick a region. In STANDALONE mode no game session is created, so gameSessionInfo.ipAddress and port come back empty: that's the slot your server-allocation call fills.

{
  "type": "MatchmakingSucceeded",
  "matchId": "1f9c8e7a-…",
  "matchmakingConfigurationArn": "arn:aws:gamelift:us-east-1:…:matchmakingconfiguration/your-config",
  "tickets": [
    {
      "ticketId": "ticket-1",
      "players": [
        {
          "playerId": "player-9241",
          "team": "red",
          "attributes": {
            "skill":       { "valueAttribute": 50 },
            "latencyInMs": { "valueAttribute": { "us-east-1": 28, "eu-west-1": 96 } }
          }
        }
      ]
    }
  ],
  "gameSessionInfo": {
    "ipAddress": "",
    "port": null,
    "players": [ { "playerId": "player-9241", "team": "red" } ]
  }
}

Parse three things: matchId (to correlate the session), tickets[].players[] (rosters and teams), and each player's latencyInMs map (to choose the closest region). Then call Gameye's POST /session with that region and return the host and port to your players. The full schema — including MatchmakingTimedOut, MatchmakingCancelled, and MatchmakingFailed — is in the AWS FlexMatch docs; the fields above are the ones the bridge actually reads.

Does FlexMatch deliver match events over SNS or EventBridge?

Both. Set a NotificationTarget on the matchmaking configuration to publish events to an SNS topic, and FlexMatch matchmaking events are also emitted to Amazon EventBridge automatically. Subscribe your Lambda bridge to whichever you already operate — the MatchmakingSucceeded payload is identical either way.

FlexMatch standalone vs. integrated (managed hosting) mode

In integrated mode FlexMatch is attached to a GameLift queue: on a successful match it automatically creates a GameLift game session on a managed fleet, so matchmaking and hosting are coupled to GameLift. In standalone mode (FlexMatchMode: STANDALONE) FlexMatch only forms the match and emits the event — it places no server. That decoupling is exactly what lets you keep FlexMatch matchmaking while hosting elsewhere, like Gameye. Your rule sets and tickets are identical in both modes.

How do FlexMatch latency rules map to a Gameye region?

Latency-based matchmaking has each player submit a latencyInMs attribute per region in their ticket; your rule set's latency rules then only match players who share a low-latency region. Because that same per-region latency data rides along in the MatchmakingSucceeded event, your bridge reuses it to pick the launch region — take the region with the best aggregate latency across the matched players and pass it to POST /session. FlexMatch decides who plays together; the latency data decides where the Gameye server spins up.

What does the StartMatchmaking flow look like end to end?

1. Your backend calls StartMatchmaking with a ticket — players plus their per-region latencyInMs attributes.
2. FlexMatch evaluates the ticket against your rule set and forms a match.
3. FlexMatch emits MatchmakingSucceeded to SNS/EventBridge.
4. Your Lambda bridge reads the event, selects a region from the latency data, and calls Gameye POST /session.
5. Gameye returns a host and port in ~0.5s; the bridge hands them to the matched players.

What does FlexMatch cost in standalone mode?

FlexMatch standalone is billed on matchmaking volume — AWS measures it in player packages (effectively the number of players matched), independent of any hosting. Check the current AWS GameLift pricing page for the per-package rate. The hosting math is where standalone pays off: you pay FlexMatch for matchmaking only — no GameLift fleet hours, no GameLift egress — and run the servers on Gameye at $0.07/vCPU/hr with zero egress fees.

Does FlexMatch with Gameye scale to 1M+ concurrent players?

Yes — the two layers scale independently. FlexMatch matchmaking is an AWS-managed service that scales with ticket volume, and because standalone mode places no servers, matchmaking throughput isn't bound by any fleet (account-level matchmaking limits are soft and adjustable via AWS support). Server allocation scales on Gameye: a single POST /session starts a container in ~0.5s, and the orchestrator bursts across 21 providers and 200+ datacenters — peak concurrency is limited by the capacity you reserve, not a fleet ceiling. Chivalry 2 ran a 250,000-CCU launch on Gameye with zero downtime; reaching 1M+ is adding capacity, not re-architecting.

What happens to matchmaking or hosting if a region or provider fails?

Failure isolation comes from the decoupling. FlexMatch runs in AWS's managed control plane, independent of where your servers run, so a hosting-provider issue doesn't stop matches forming. On the hosting side, Gameye runs multi-provider in every region: if a provider degrades, the orchestrator places new sessions on healthy capacity automatically — GameLift-managed hosting is AWS-only with no cross-provider failover. Your Lambda bridge can also re-drive a MatchmakingSucceeded event if a POST /session call fails, so a transient allocation error retries onto healthy capacity rather than dropping the match.

Frequently asked questions