Historical API55 integration guide. Use the final dev58 OpenAPI and current handoff for crowd additions and current limits.
Develop without launching a game
The bundled scenario runner uses the production HTTP, persistence, reconciliation and ACK machinery with explicit synthetic snapshots. No game, roster, GPU or installed hook is needed.
.\OpenHoops.cmd scenarios --state "C:\MyDynasty\sandbox-success" --scenario successful-match
It chooses a free loopback port and prints its listening URL and private token-file path. Keep it running while the client connects. Use --resume only for a matching existing scenario directory. Ctrl+C stops the scenario broker. No production state should be reused as a sandbox.
| Scenario | Client behavior |
|---|---|
| successful-match | Bind, step play/finish, receive synthetic 4–2 final, commit then ACK. |
| startup-refused | Failed launch with started:false; no invented result. |
| uncertain-start | started:null and lost command response; inspect the same command receipt. |
| stale-command | Preimage conflict returns HTTP 409. |
| disconnect-recovery | Preserve run/match identities across simulated source loss/reconnect. |
| abandoned | Explicit abandonment; no ordinary successful result. |
| review-required | Changed context needs app attention; no fabricated result. |
| lost-ack | ACK applies but its response is lost; recover from the app's committed inbox. |
Authenticate GET /v1/scenario to obtain the synthetic binding, request ID, scripted commands and actions. Bind its supplied body with POST /v1/matches. Then POST /__scenario/step with exactly {"action":"play"} or {"action":"finish"}; other supported actions are disconnect/reconnect/abandon/review. These controls exist only in the scenario runner; the real broker returns 404.
Results retain metadata.openhoops_simulation:true and the scenario name. Never import these into a real league. Game-free checks establish client behavior, not native loading, rules, assets, controller input or visual acceptance.
The TypeScript SDK exposes literal operation keys, e.g. client.request('GET /v1/matches/{id}', {path:{id:matchId}}). Convenience methods include session(), snapshot(), results(), acknowledge() and receiveResult({matchId,consumerId,store}). The supplied SqliteInbox implements durable store/load and can recover an ACK whose response was lost. The Python equivalent is openhoops_api.game_flow.ResultInbox.
Before shipping your app, exercise all eight scenarios, your own request's compatibility report and an isolated real match. Store raw immutable result revisions, not only derived standings, so reconciliation and recovery remain possible.