Creative Golf OpenAPI
Examples 1.0.0 · Protocol 2

Creative Golf OpenAPI - protocol version 2

Requires a game build that supports OpenAPI; see Start here to run the examples.

Transport and handshake

TCP port 4356, one connected client. Each message is one UTF-8 JSON object followed by CRLF (\r\n). TCP may split one message across reads or combine multiple messages. Maximum JSON size is 1 MiB; maximum nesting depth is 16. Numbers use decimal dots and must be finite.

The client first sends:

{"type":"hello","protocolVersion":2,"clientName":"MySimulator","clientVersion":"1.0"}

clientName is required and nonempty; clientVersion is optional. The game confirms:

{"type":"hello","protocolVersion":2}

Then it sends the current state.

Game state (game -> client)

{"type":"state","ready":true,"club":"driver","rightHanded":true,"surface":"tee","useTee":true,"distanceToTargetM":228.66,"distanceToStickM":228.66,"windSpeedMs":0,"windDirectionDeg":184.53,"elevationM":152.4}

The game always sends ready. During play it also sends the current shot and environment values below. Without game context, for example in the main menu, it sends only {"type":"state","ready":false}. A change to ready can still include the environment values.

Each state is a complete snapshot. Clear values omitted from the message.

Field Meaning
ready Always sent. true when the game is waiting for a shot; otherwise false.
club Suggested club: driver or putter. Omitted when neither is suggested.
rightHanded true for a right-handed player, false for a left-handed player.
useTee Whether a tee is used.
surface tee, fairway, green, fringe, rough, deepGrass, sand, asphalt, concrete, trees, footpath.
distanceToTargetM Distance to hole/target, metres.
distanceToStickM Distance to aiming point, metres.
windSpeedMs, windDirectionDeg Wind speed (m/s) and direction (game convention, degrees).
elevationM Altitude from game conditions, metres; not height difference to the hole. The internal trajectory model currently retains its existing default altitude.

Shot (client -> game)

{"type":"shot","shotId":"3ca55470-b06f-41e9-81b6-564963c5d359","ball":{"speedMs":43.64,"azimuthDeg":0,"launchAngleDeg":18.65}}

Required: a new nonempty shotId (UUID recommended, maximum 4096 UTF-8 bytes without NUL), and ball.speedMs (>0 m/s), ball.azimuthDeg and ball.launchAngleDeg (degrees).

Optional ball fields: backspinRpm, sidespinRpm, isPutt (boolean). Omit unknown measurements; zero means a measured zero. Missing backspin is estimated and missing sidespin defaults to zero. Omitted isPutt selects the game's automatic mode; true selects putt, false tries normal flight first. If normal flight cannot be prepared for otherwise valid measurements, the game may use ground roll and report ROLLING_FALLBACK. Out-of-range measurements are rejected, including when a trajectory is supplied.

Do not queue shots while not ready or replay after reconnect. Readiness can change before arrival: a rejected shot is not played later. Send a new ID for a new attempt. The game rejects duplicate processed IDs with DUPLICATE_SHOT and retains a bounded history of 256 IDs, including rejected shots, across ordinary reconnects during the listener's lifetime.

Result / error (game -> client)

{"type":"result","for":"shot","shotId":"3ca55470-b06f-41e9-81b6-564963c5d359","accepted":true,"warnings":[]}
{"type":"result","for":"shot","shotId":"3ca55470-b06f-41e9-81b6-564963c5d359","accepted":false,"error":{"code":"NOT_READY","message":"The game is not waiting for this shot."}}
{"type":"error","code":"INVALID_MESSAGE","message":"Missing or invalid field.","field":"ball.speedMs"}

for is shot or clubData. Match results by shotId. accepted:true means accepted for processing, not a completed flight/result. Accepted results may contain warnings; rejected results contain an error and omit warnings. Diagnostics have code, message and optional field. Use codes for program logic; message text is explanatory. Standalone errors can lack a shot ID.

Typical rejection codes: NOT_READY, DUPLICATE_SHOT, SHOT_OUT_OF_RANGE, SHOT_BUILD_FAILED, SHOT_CLOSED_OR_UNKNOWN, INVALID_MESSAGE, INVALID_JSON, UNSUPPORTED_VERSION. Connection/protocol failures may close the socket; do not automatically resend an uncertain shot.

Optional club measurements

Include clubData in a shot, or send it separately for an accepted shot:

{"type":"clubData","shotId":"3ca55470-b06f-41e9-81b6-564963c5d359","clubData":{"speedMs":30,"faceAngleDeg":1.2,"pathAngleDeg":-2,"attackAngleDeg":-3,"dynamicLoftDeg":15}}

All five fields are optional; include at least one usable measurement. Speed is m/s; other values are degrees. Separate messages update supplied fields for that shot while its delayed-data window is still open. Do not wait for the next ready state: finalized/unknown shots return SHOT_CLOSED_OR_UNKNOWN; there is no guaranteed delay duration.

Optional trajectory

Include this trajectory object in a shot:

{"timeStepS":0.05,"points":[[0,0,0],[2,0.8,0],[4,1.2,0],[6,0.8,0],[8,0,0]]}

Use 3-1000 finite [x,y,z] triples in metres, relative to launch: x forward, y up, z right. timeStepS is a positive interval in seconds. The game validates the trajectory; an unusable supplied trajectory may be replaced by game physics with a warning. Putt physics does not use supplied trajectory/spin to calculate motion.

Optional device status

{"type":"status","ballReady":true}
{"type":"status","ballReady":false,"reason":"Multiple balls detected."}

The device decides ballReady for the in-game device indicator. This does not set state.ready. Optional reason is diagnostic text, at most 512 UTF-8 bytes without NUL; the game does not interpret it as a code. Each status replaces readiness and reason; omitted reason clears it. Connection changes reset device readiness. Successful status messages have no separate acknowledgment.

Game/product rules

Full OpenAPI needs its own game entitlement; an active supported demo also permits OpenAPI with demo restrictions. Client names do not grant device identity or change the selected game mode. Public OpenAPI tournaments are separate from public official/all-device tournaments; private tournaments and Online can allow mixed devices. These examples do not add account, licensing or tournament-management APIs.