Unity

Generate the HTTP layer

Write the contract first. From the project root, pithy contract writes apps/<worker>/openapi.json, and asyncapi.json beside it for a Worker that serves a socket.

Generate from it with OpenAPI Generator’s csharp generator and its unityWebRequest library, which runs on IL2CPP and WebGL where HttpClient does not. The library is marked experimental, so the generator is pinned:

openapitools/openapi-generator-cli:v7.26.0

From the project root, where <unity project> is your Unity project’s folder:

docker run --rm -v "$PWD:/local" -w /local openapitools/openapi-generator-cli:v7.26.0 generate -i apps/<worker>/openapi.json -g csharp --library unityWebRequest --additional-properties=packageName=Pithy.Client -o <unity project>/Assets/Pithy/Client

Use this version and no other. The kit’s CI generates a client from its own contract with it on every pull request; 7.10.0 crashes on the OpenAPI 3.1 document. Do not upgrade it in passing.

Regenerate after every pithy contract, and never hand-edit Assets/Pithy/Client. The next run overwrites it.

Generated, not compiled. The client calls UnityWebRequest, which exists only in Unity’s own assemblies, so it compiles in your project and nowhere else. Open it in the editor once after each regeneration. Set the base URL yourself: generating a client says why the document names none.

Write the socket layer

No generator emits a Unity socket client, so write a small one against asyncapi.json. The socket contract is the whole rule. For Unity it comes to this:

  • Open the socket with the subprotocol in Sec-WebSocket-Protocol: pithy.multiplayer.v1 for a session, pithy.presence.v1 for presence.
  • Switch on type. Deserialize the envelope, switch on type, then deserialize the body into the type asyncapi.json names.
  • Ignore a type you do not know, and a key you do not know. A store build lags its Worker by months, and the Worker only adds optional fields within a subprotocol.
  • Send a move as { "type": "action", "payload": … }, shaped by the game’s <gameKey>.action schema. An error arrives as an error frame, not a closed socket. Show it and keep the socket.
  • Presence’s ping and pong are plain text, the one exception to JSON.

Unity’s constraints

IL2CPP strips code it cannot see used. The generated client and its JSON serializer are reached by reflection. Add a link.xml that preserves the generated assembly and the serializer, or a release build fails at runtime on a call that worked in the editor.

WebGL has no HttpClient and no raw sockets. The generated client already uses UnityWebRequest. For the socket, use the browser’s WebSocket through a .jslib plugin, or a WebSocket package that supports WebGL. Keep one socket interface with a native and a WebGL implementation behind it.

In Claude Code, an agent does this for you. The pithy-games add-on’s client-unity agent generates the HTTP layer at this version, writes the socket layer against asyncapi.json, and adds the link.xml. Compiling is still yours, in the editor.

Two things a client must never decide

Choosing a client credential settles what you hold. Getting players into a session is matchmaking, randomness and wagering is why the server holds the seed, and versus platform leaderboards is the trade against Game Center and Play Games.

A score. Boards are server-authoritative by default — every vendor that offers this ships it off; this ships it on. Submitting requires a scope that auth grants only to a caller proving it is your backend, never to a player. So the game client hands its result to your server, and your server submits it. Server-authoritative writes is how the server proves it.

A result. Recording a rating outcome needs the record scope, for the same reason: a rating a client can write is a rating a client can invent, and every ladder, queue and rank downstream inherits the lie.

A submission body carries a score and nothing else — the player comes from the session, the timestamp from the server’s clock, the rank from the data. A client that could name any of those could score as somebody else or backdate past the tiebreak.

Sign in

Passwordless — a magic link or an emailed code. Send the session token the sign-in answers with as Authorization: Bearer, and keep it in the Keychain on iOS or the Keystore on Android, never in PlayerPrefs. Rotate it at POST /auth/token/rotate before it expires, and do not fire two rotations at once from two coroutines. Rotation also answers with an accessToken JWT, which the kit’s routes do not accept: it is for a service outside your Worker. On WebGL there is no secure storage: keep the session token in memory and sign in again on reload.

Register the device with x-pithy-device-id and a stable id.

Getting into a match

Four ways in, all authenticated, all binding to the caller rather than an id the client sends:

A room code — WXYZ-1234, alphabet without I, O, 0 or 1, tolerant of lowercase and a missing dash. The zero-discovery path: play with whoever is beside you.

A direct invite by email, or best-effort by screen name.

Friends, by mutual accept.

The open queue, bucketed by region and skill, with the band widening every second waited.

Learn you matched through presence, not by polling:

GET /matchmaking/presence      (WebSocket)
→ { "type": "match_found", "sessionId": "…", "gameKey": "duel" }

Playing

GET  /multiplayer/sessions/<id>          your redacted view
POST /multiplayer/sessions/<id>/action   your move
GET  /multiplayer/sessions/<id>/socket   live play

The action body is whatever the game’s model defines, and its <gameKey>.action schema in asyncapi.json says what that is. A body the schema refuses is a validation/invalid_input 400.

GET /sessions/:id returns your view. Opponents’ hidden state stays hidden — there is no route that returns the raw state, so a client cannot read what it should not know.

This is turn-based, and deliberately

Fairness you can show the player

Every session commits its random seed’s SHA-256 hash up front — before a die is rolled — and reveals the seed when the session ends.

Show the commitment in your UI. An auditor, or a suspicious player, can hash the revealed seed against it and replay the stream to verify every roll.

Money

Hold the stake at the wager, capture or release at the result. The balance is unchanged while held, so the stake is unspendable without having been spent.

A hold a player cannot cover rejects the action, and the transition is never persisted.

ESC