Dated source reference. Current release status: handoff state. Full original relative paths are in the developer archive.
OpenHoops public extension API requirements
Current API checkpoint (October15,2026):
0.2.0.dev36, HTTP v1, snapshot ABI14/event ABI4, college profile4/court definition3. Use the current contract, verification ledger and remaining scope. Research milestones below retain their original versions, results and uncertainties; their former next-step statements are historical. Latest natural college OT/export and18 both-end release-contact cases passed; rare live exceptions remain unverified. No public release or extra live smoke is required for this documentation pass.
User clarification, October12,2026: OpenHoops enables other people to build dynasty tools and mods through its in-game API. A first-party application is one client. These are the Windows-first deep-extension requirements; Mac/Linux integration is deferred until the Windows feature set works and is tested. Full engine decompilation/recompilation is no longer a deliverable. The October13 development implementation now supplies a tested subset through HTTP/JSON and SSE: see API implementation and evidence and v1 contract. Remaining requirements below must not be mistaken for available features.
Consumer-independent boundary
Expose documented, versioned game concepts instead of Windows pointers or one application's database model. Support independent dynasty/career/league managers, roster tools, scoreboards, presentation systems, analytics and rule mods. The core must operate without a first-party service/account. Adapters hide executable/platform differences; clients discover supported capabilities and evidence quality. Future platform adapters should preserve the public concepts and conformance tests. A standalone native engine is not required; compatibility/translation layers are acceptable for later Mac/Linux delivery.
Provide multiple simultaneous read subscriptions. A scoreboard and a dynasty recorder must be able to observe the same match without competing. Mutating clients need explicit ownership, conflict handling and deterministic command ordering. Do not let whichever mod writes memory last silently win. Mods should declare identifiers, versions, dependencies, supported API versions and capabilities; exact manifest syntax remains undecided.
Required surfaces
| Surface | Required contract |
|---|---|
| Session discovery | API version, adapter/build identity, verified platform, supported/experimental/unavailable capabilities |
| Match control | Create/launch with client-provided match ID, roster/team mapping and ruleset; explicit accepted/rejected/applied responses; resume and abandon semantics |
| Live snapshot | Coherent game-thread boundary; clocks with units and run/pause status, scores, period, lineups, player/team stats, physical possession and legal state distinguished |
| Event stream | Monotonic sequence scoped to a run; stable event IDs, causal references where known, correction/retraction revisions, gaps and snapshot recovery |
| Result export | Finalization reason, immutable result revision, stable participants, reconciled totals, per-period detail with explicit OT limits, source/ruleset identity and completeness flags |
| Rule extension | Validated parameters and eventually native/in-process decision callbacks at authoritative engine boundaries; preserve dependent counting, clocks, UI and AI behavior |
| Presentation | Read-only event/snapshot access, custom scoreboard and overlays, asset/presentation capabilities explicitly advertised |
| Developer support | Reference schemas, examples, recorded fixtures, compatibility policy and conformance tests usable by third parties |
A transport-neutral semantic model comes first. The development API uses local HTTP/JSON and SSE; WebSocket is not implemented. In-process plugins need a separately versioned ABI and bounded execution at safe engine points. Network round trips must not be required for a live foul or shot decision. Multiple languages are supported through published schemas, with Python and Node examples; no first-party SDK is mandatory.
Identity and durable behavior
Use distinct match ID, process/run ID, checkpoint/revision ID, event sequence and result revision. Roster imports map external team/player IDs to current engine objects. Pointers, player names and cyberface/appearance IDs are not durable identity. A reconnect resumes or requests a snapshot; it never silently replays old events as new. A loaded checkpoint can rewind game time and stats, and must invalidate/supersede the affected timeline explicitly.
Final-result consumers apply an idempotency key (match_id,result_revision) and acknowledge durable receipt. Persist an export outbox before announcing completion; retry without double-counting. A crash, manual quit or demo is not a completed match. Corrections after a provisional result produce a new revision, never silent mutation. The development implementation supplies durable result revisions and independent acknowledgements, with conservative observed finalization and identity limits documented in its contract.
Evidence and honesty
Every exposed field has a type, unit, lifetime, origin, sampling/commit boundary and validity rule. Unknown values remain unknown; unavailable capability is distinct from zero. Physical attachment is not automatically legal possession. A stopped clock is not automatically dead ball. A routine call is not automatically a committed event. Clients can request capabilities they need and fail clearly rather than accepting guessed data.
Research must continue proving event/rule semantics before a production rule API. Current validated and missing areas: RULE-EVENT-MAPPING. The tested development API does not establish all desired rules, all executable versions or all operating systems.