Reconnection and game recovery

Handle recovery in the game loop

The firmware retries a broken relay connection. The SDK reports CF_RECONNECTING while it waits. Keep polling, show a recovery screen and pause simulation before applying new local inputs.

This is an integration fragment; the rendering and reconciliation functions belong to your game:

uint8_t message[CF_MAX_MESSAGE];
uint16_t length = cf_poll(message, sizeof(message));

switch (cf_status()) {
case CF_CONNECTED:
    if (!cf_in_room()) {
        show_online_menu();
        break;
    }
    if (length) {
        handle_message(cf_last_sender(), cf_last_sender_generation(),
                       cf_last_was_reliable(), message, length);
    }
    update_if_game_state_is_synchronised();
    draw_game();
    break;
case CF_RECONNECTING:
    draw_reconnecting();
    break;
default:
    show_connection_lost();
    break;
}

Do not call cf_connect() every recovery frame: it resets local session state. Let recovery resolve; explicitly disconnect/reconnect when starting a new session after failure.

What can be resumed

A dropped relay connection reserves its occupied seat for 30 seconds by default, measured by the relay after it detects the disconnection. This is a server setting, not a guaranteed duration controlled by the game.

The firmware retains the room code and a random seat token and authenticates with the same account. Games do not handle the token. Successful resume preserves room, slot and seat generation.

If the seat expired, the device reset, the relay restarted, or reliable delivery invalidated the seat, the old session cannot be resumed. A failed resume does not silently create a replacement room.

A connected menu can recover without a room. Recovery while a new join or leave is unresolved can fail deliberately because membership is uncertain.

Timing is not one fixed timeout

The firmware retries with backoff, for up to 60 seconds during recovery. The relay's seat reservation can expire sooner. A successful Wi-Fi association does not imply that TLS, authentication and room resume have completed.

TLS handshakes can delay serial servicing. The SDK treats consecutive failed ticks as trouble after 30 attempts and failure after 600. At 20 successful frame-paced attempts per second those correspond nominally to 1.5 and 30 seconds, but actual elapsed time depends on frame rate and exchange delays.

Do not promise a fixed recovery countdown based on those thresholds. The status returned by the SDK determines whether play can continue.

Restore application state

Normal updates can be lost while away. Admitted reliable events for a reserved recipient are retained within the live session, subject to bounded queues, but this is not a saved game or a complete state snapshot.

After reconnecting, have your game reconcile a round/state version with the current master. Apply queued events in the appropriate round and request a fresh snapshot if needed. Continue polling and consuming packets during this process.

Admission acknowledgement is not proof that all games processed an event. Use application event IDs and acknowledgements when that distinction matters.

Other players going away

cf_away_mask() identifies reserved, temporarily absent seats:

uint8_t away = cf_away_mask();
if (away & (1u << other_slot)) {
    show_player_reconnecting(other_slot);
}

An away occupant still counts in cf_peers() and cf_peer_mask(). Your game can pause for them or continue with a defined resynchronisation policy. The SDK provides no kick API.

If the master drops, another present player can become master immediately. If all occupants drop, the room retains their seats for the grace period; the first valid resume acquires the role if no master remains.

Cable loss and deliberate exit

A serial cable interruption is different from a Wi-Fi interruption. The SDK continues its tick attempts, but a device reset or a broken serial session may require a fresh connection. Do not assume every physical interruption resumes.

A successfully processed voluntary leave releases the seat without a grace reservation. cf_disconnect() also attempts a voluntary close, but cannot guarantee remote receipt if the physical or network connection is already gone.

Keep polling while online: current firmware treats roughly 60 seconds without GBA contact as a dead Link session. This differs from the relay's default 30-second seat grace and the device's ordinary standby timeout.