Solo Practice Contract

Solo Practice ensures the game is fully playable without a live network connection, serving as a fallback, tutorial, and platform embed requirement.

1. Embed Constraints & Initialization

When embedded in the platform (e.g., on a creator’s profile), games must not autonomously start consuming heavy resources or audio.

GetReady Gate: The game MUST load assets and then halt in a “Get Ready” or “Start Practice” idle state.
Physics/Audio Freeze: Physics engines and background music must remain paused until the user explicitly interacts with the start gate.

2. Bot Fallback Architecture

To fulfill the requirements of local mode in the unifiedGameState, missing network players must be substituted with simulated inputs.

Local Dispatch: When gameMode === 'local', opponent turns are handled by a BotService or Simulator.
State Parity: The bot must dispatch the exact same Action payloads that a remote player would send over the network.
No Hacks: Do not mutate unifiedGameState directly from the bot. The bot must go through the standard action queue.

3. Mapping to Unified State

During Solo Practice, the mapping behaves as follows:

// Setup
gameMode.set('local');
localStore.initialize(player, botOpponent);
 
// Gameplay
function onInput(action) {
  if (get(gameMode) === 'local') {
    localStore.processAction(action);
    if (isBotTurn()) {
      setTimeout(() => botService.takeTurn(), 500);
    }
  }
}

4. Acceptance & Verification

Criteria: The game can be played indefinitely without an internet connection, and never starts autonomously on page load.
- Verify: Throttle the browser network to “Offline”. Hard refresh the page. The game must present a “Start” button. Clicking it must trigger a fully simulated match against an AI or deterministic logic.

5. Rationale & Anti-Patterns

Why Solo Practice Matters

Every game on the platform must be playable when embedded on third-party creator pages. These embeds often do not instantiate a full multiplayer Nakama session immediately. Furthermore, a local tutorial serves as a safer entry point for new users.

Common Anti-Patterns

Forced Network Wait: Blocking the UI with an infinite “Connecting to Server…” spinner without allowing the user to bypass into practice mode. Why it fails: Breaks the embed requirement.
Leaky Bot Logic: Injecting the BotService directly into UI components instead of running it entirely headless as a unified state mutator. Why it fails: It entangles simulation logic with presentation.
Auto-Play Audio: Starting game music or sfx the moment the iframe loads. Why it fails: Browsers will actively block the audio context, and it disrupts the parent page experience.

6. Implementation Checklist

When integrating the Solo Practice fallback, ensure the following tasks are completed:

Provide an explicit button to start a solo session if the network fails or if the user is in an embedded context.
Initialize localStore with dummy profiles or AI opponents.
Build a test script that triggers onInput automatically to verify that the core loop functions completely offline.
Make sure your gameMode store switches properly and gracefully unsubscribes from any Nakama events if they were active.
Hook up the GetReady UI to the physics engine so that update loops don’t burn CPU cycles while idling.