Bridge Contract

The Bridge Contract defines the explicit message surface via postMessage between the Funday iframe shell and the game client. All games MUST use the FundayBridge SDK to normalize these communications.

1. Handshake & Initialization

• funday:handshake (Inbound): The shell sends this containing the protocol version to establish the connection origin.
• funday:ack (Outbound): Sent by the SDK automatically to acknowledge the handshake.
• funday:game-ready (Outbound): Emitted by the game once the engine, assets, and start screens are fully loaded and awaiting player input.

2. Platform to Game (Inbound)

These messages mutate the game’s external state based on platform context.

// Theme Sync
{
  type: "funday:theme",
  theme: "funday-dark",
  colors: { "primary": "#ff0000", "background": "#000000" }
}
 
// Session Injection (Guest/User Auth)
{
  type: "funday:session",
  session: {
    token: "jwt...",
    userId: "uuid",
    username: "Player1"
  }
}
 
// Shell-Driven Match Start
{
  type: "funday:match-start",
  matchId: "uuid",
  joinType: "quick" | "invite" | "host"
}

3. Game to Platform (Outbound)

These messages report lifecycle events to the shell for navigation and leaderboards.

// Score Submission
{
  type: "game:score",
  leaderboardId: "game_highscores",
  score: 1500,
  metadata: { "time": 120 }
}
 
// Match Lifecycle
{
  type: "game:matchEnd",
  matchId: "uuid",
  reason: "completed" | "abandoned",
  results: { "winnerId": "uuid" }
}

4. Error Cases & Limitations

• Origin Mismatch: The bridge MUST drop messages from origins that do not match the trusted host or the initial handshake origin.
• Premature Messages: Outbound messages sent before handshake will be queued by the FundayBridge and replayed upon connection.
• Binary Payloads: The bridge strictly normalizes Uint8Array subarrays. Impostor objects will be discarded to prevent cross-site payload corruption.

5. Acceptance & Verification

• Criteria: The game flawlessly coordinates with the shell’s lifecycle.
  • Verify: Load the game inside the tinkerbench wrapper. Verify that changing the global platform theme correctly cascades to the game canvas, and that finishing a local session successfully emits game:score.