OPENHOOPSTeam build 2026.10.20-team1 · Windows

Build a match request

Use the exact JSON schema in OpenAPI. This page explains the values your app must supply. The examples below are templates: physical row numbers, player names and hashes must come from your actual roster. A syntactically valid template is not a loadable finished roster.

Required document

{
  "format": "openhoops.match_request",
  "version": 1,
  "request_id": "season2026-game001",
  "client_id": "my-dynasty",
  "roster": {"path": "C:\\MyDynasty\\Prepared.ros", "sha256": "YOUR_64_CHARACTER_SHA256"},
  "launch_configuration": {
    "version": 1,
    "rules": {"profile": "college", "half_length_minutes": 20, "media_timeouts": 4, "overtime_policy": "scaled"},
    "participation": {"mode": "cpu_vs_cpu"}
  },
  "preparation": {
    "home_team": "team-row:0", "away_team": "team-row:1",
    "home_uniform": "uniform-row:0", "away_uniform": "uniform-row:1",
    "arena": "arena:0", "home_playbook": "playbook:0", "away_playbook": "playbook:1",
    "quarter_length_minutes": 10
  },
  "identity": {
    "version": 1,
    "match_id": "season2026:game001",
    "teams": {"home": "school-a", "away": "school-b"},
    "players": {
      "home:0": {"id": "player-a", "name": "EXACT LOADED PLAYER NAME"},
      "away:0": {"id": "player-b", "name": "EXACT LOADED PLAYER NAME"}
    },
    "ruleset": {"id": "my-college-profile", "version": "1"},
    "metadata": {"season": "2026-27"}
  },
  "loading_screen": {"title": "My Dynasty", "subtitle": "Championship"}
}

Expand identity.players to describe every player actually instantiated on both sides with exact expected slot/name. Native match slots, physical roster rows and app IDs are separate namespaces. In the expanded test roster, 15 assigned records per team produce 12 instantiated players per side; the other six planned entries remain metadata only. No active status or statistics are invented for them. The API does not enlarge the active bench.

request_id is single-use and portable: 1–96 letters/digits/underscore/hyphen, starting with a letter/digit; Windows reserved filenames are refused. Other external IDs use the documented identifier domain, including dots, colons and hyphens. Team IDs differ and all player IDs must be unique. identity.ruleset describes the app's identity metadata; it does not apply game rules. launch_configuration.rules applies rules.

Roster intake and selections

roster is exactly one of {path,sha256}, {archive_path,sha256} for a Roster Studio export ZIP, or {id:"roster:<sha256>"} already registered in this broker state. Request-relative local paths resolve beside the request document. A plain ROS can have its matching <filename>.ros.openhoops.json companion alongside it; an editor ZIP carries the checked pair. Hash the actual supplied file, including the whole ZIP when using archive_path.

The thirteen preparation fields are difficulty, game speed, quarter length, fatigue, injuries, arena, both playbooks, game style, both teams and both uniforms. Discover numeric ranges through GET /v1/preparation. Loaded catalogs use GET /v1/preparation/catalog?kind=teams and the returned paging/catalog identity; inspect the reference for the supported kind names and cursor parameters. Uniform choices must belong to the selected team's graphics identity. Re-read catalogs after replacing a roster.

Arena IDs are native HCParamsID values, not physical arena row indices. Team and uniform choices use physical team-row:N and uniform-row:N. A game's s070.iff identity does not prove its arena record is physical row 70. Select from verified roster data and read the native resolved arena state before assuming a filename mapping.

Optional roster_edits applies up to 512 unique named-field changes to a new roster. Optional roster_preparation supplies distinct home/away team rows, assigned-player roster_order and minutes; order and identity slots must match the final authored roster. Discover fields through /v1/roster-tools/fields, query with /v1/rosters/query, and export immutable outputs through /v1/rosters/{sha256}/content. The bundled writer is selected automatically. It neither changes your source roster nor uses a community editor program.

Rules, settings and participation

Original rules use {"profile":"original"}; preparation.quarter_length_minutes supplies 1–12-minute quarters. College uses half_length_minutes 1–20, media_timeouts 0/3/4 and overtime_policy:"scaled". The generic quarter field is not college half duration. Default scaled OT is 1/2/3/4/5 minutes for half lengths 1–4/5–8/9–12/13–16/17–20. TV marks are fixed, not proportional: a 10-minute half uses under8/under4. Native UI can still show quarter labels; use the result's logical periods.

launch_configuration.settings accepts startup options, both slider banks, stored controller preferences, a supported native camera, home/away coaching and opponent-specific defense. Base game style applies before explicit sliders. Get exact setting IDs, enum choices and ranges from /v1/launch/settings and the relevant catalogs; do not invent numeric enum equivalences. Controls describes live changes.

Participation modes include cpu_vs_cpu, primary_home, primary_away, and the schema's explicit connected-input assigned mapping. Stored controller preferences do not assign a device to a side. Physical multi-controller verification remains unavailable because no test controllers were supplied. Apps should specify participation explicitly for repeatability.

Optional launch_configuration.rotations supplies bounded game-clock lineup intent. Native dead-ball entry remains separate from a scheduled request or accepted queue. Optional extensions, native_metadata and assets are advanced contracts covered in Rules, Metadata and Assets.

Generate and check

Create choices.json from your verified selections and identities.json from your final roster mapping, then use the helper to hash the roster and produce a request:

.\OpenHoops.cmd example make-request --roster "C:\MyDynasty\Prepared.ros" --choices "C:\MyDynasty\choices.json" --identity "C:\MyDynasty\identities.json" --output "C:\MyDynasty\request.json" --request-id season2026-game001 --client-id my-dynasty --profile college --half-minutes 20
.\OpenHoops.cmd check --request "C:\MyDynasty\request.json" --state "C:\MyDynasty\sessions\game001" --game "C:\Games\OpenHoops\nba2k14.exe" --output "C:\MyDynasty\report.json"

Compatibility is read-only and does not reserve request IDs or start a game. Exit 0 means passed, 1 failed, 2 incomplete. Even a passed report has live_readiness:"not_established"; callbacks, actual rendering and runtime state can still refuse. Output paths are exclusive. Keep the report and fix specific failed/unknown checks before launching.