ball2d 0.0.1 → 0.1.0

package/README.md

@@ -1,7 +1,156 @@
-# Ball 2D
+# Ball2D SDK
 
-Ball 2D by Fillbyte.
+```ts
+import { createRoom, type RoomConfig } from 'ball2d';
 
-- Website: https://ball2d.com
-- Source: https://github.com/fillbyte-com/ball2d
-- Issues and wiki: https://github.com/fillbyte-com/ball2d-issues
+const config: RoomConfig = { roomName: 'My room', noPlayer: true };
+const room = await createRoom(config);
+room.onPlayerJoin = (player) => room.setPlayerTeam(player.id, 1);
+await room.startGame();
+// When the host is finished:
+// room.close();
+```
+
+This initial entry runs in a browser on an origin serving the matching Ball2D
+Worker API, WASM and stadium assets. The separate experimental `ball2d/node` entry provides native Node hosting. The
+browser entry does not provide remote-origin hosting or an isolated plugin runtime.
+Importing it does not register a window global or allocate a room. Creating a
+room explicitly starts the existing browser host and its network lifecycle.
+
+`RoomConfig`, `Room`, `HostPlayer`, `HostScores` and `HostDiscProperties` are exported
+types. `readReplay` reads Ball2D recordings. This is not a complete HaxBall
+compatibility shim.
+
+State-changing SDK commands return Promises and run in call order. A synchronous
+getter immediately after a command still observes the earlier state; await the
+command before reading its result. Inputs are copied at call time. Up to 256
+commands may wait; overflow rejects without dropping accepted work. Live command
+errors also reach `onError`; cancellation and calls after closure only reject their
+Promises. `close()` immediately rejects pending SDK work and closes the
+host; it does not undo operations already applied remotely. Getters and recording
+start/stop remain synchronous. Chat filters must synchronously return false.
+Callbacks receive the SDK facade as `this`; engine/network internals are not
+part of that facade. This is an API boundary, not a sandbox for untrusted code.
+
+`createRoom()` accepts omitted options. Defaults are a private room named
+`Headless Room`, capacity 12, and an admin host player named `Host`. Set
+`noPlayer: true` for an unattended playerless room and `public: true` to list it.
+Integer capacity is clamped to 2–30; malformed numeric or privacy values reject
+before engine/network allocation. Omitted/null optional default fields resolve
+to defaults. The standalone `/headless` and `/headless.html` pages have been
+retired; import the SDK instead. No `window.Ball2D` global is registered.
+
+Version 0.1.0 is the first functional SDK release. For native hosting use Node.js
+24 and the `ball2d/node` entry below. This is an early API; the native transport
+remains experimental and the acceptance limits below still apply.
+
+Validate a stadium before allocating a room:
+
+```ts
+import { validateStadium } from 'ball2d';
+
+const report = validateStadium('{name:"Training", canBeStored:false}');
+console.log(report.name, report.canBeStored, report.warnings);
+```
+
+`validateStadium(source)` is synchronous and works without browser globals,
+network requests or a WASM instance. It uses the same parser and limits as room
+creation. Malformed/unsupported input throws; ignored field names become bounded
+warnings. The returned `StadiumValidation` and warning array are readonly and
+frozen. No geometry or internal engine objects are exposed. Passing validation
+means Ball2D can parse the source, not that its physics are identical to HaxBall.
+Use the separate `ball2d/node` entry for native room hosting.
+
+`room.signal` is a readonly `AbortSignal` that aborts once when host closure
+begins, including a fatal transport closure. Use it to cancel your own room-bound
+work. It signals cancellation, not completion of every cleanup operation. Pending
+SDK commands are cancelled from the same signal; cancellation never reenters the
+room's error callback. A terminal transport error can still be reported once.
+
+SDK `setScoreLimit` and `setTimeLimit` clamp integer arguments to 0–99 (goals
+and minutes respectively); zero disables that limit. Await them before reading
+updated state. Active-match calls remain no-ops. Non-integer or non-numeric
+values reject when settings are editable. These commands use the same queued
+contract in browser and native SDK hosts.
+
+## Experimental native Node host
+
+```ts
+import { createRoom, type NodeRoom } from 'ball2d/node';
+
+const room: NodeRoom = await createRoom({
+  serviceOrigin: 'http://127.0.0.1:8787', // A matching Ball2D deployment
+  roomName: 'Native room',
+  noPlayer: true,
+});
+room.onPlayerJoin = (player) => room.setPlayerTeam(player.id, 1);
+await room.setDefaultStadium('Classic');
+await room.startGame();
+// Later:
+room.close();
+await room.closed; // Native peer cleanup finished; rejects on cleanup failure.
+```
+
+Verified on Node 24.19.0 and Bun 1.4.2 on macOS arm64 with local Worker signaling
+and real Chrome guests. Both use the same `ball2d/node` entry, runtime WebSocket
+and bundled, patched werift 0.24.4; no
+browser host, postinstall patching or external transport dependency is required.
+WASM and default stadium files are included and the engine identity is checked.
+`serviceOrigin` defaults to `https://ball2d.com`; the deployment's client/protocol
+and engine must match this SDK version. Importing the package does not
+open a room. Browser consumers continue to import from `ball2d`.
+
+On a deployment with accounts and SDK keys configured, supply an account-owned
+key from an environment variable:
+
+```ts
+const apiKey = process.env.BALL2D_API_KEY;
+if (!apiKey) throw new Error('Set BALL2D_API_KEY from your Ball2D account.');
+const room = await createRoom({ roomName: 'My room host', noPlayer: true, apiKey });
+```
+
+`apiKey` is optional for existing anonymous hosting. When supplied, it is sent
+only in the authenticated room-creation request's Authorization header, never
+in a URL or peer message. Keys currently authorize only `rooms:create`. New keys
+expire after 90 days by default; the account page offers 7, 30, 90 or 365 days.
+Expiry and revocation prevent new room creation without stopping an existing match. Never include this key in browser bundles or version control.
+Account access depends on configured social providers and Worker bindings.
+Anonymous room hosting is available without an API key.
+
+The matching Worker limits room creation to 10 attempts per minute per
+API key and 20 per minute across an account's keys, in addition to the IP gate.
+HTTP rate-limit responses include `Retry-After: 60`; avoid immediate retry loops.
+These are approximate, location-local abuse limits, not globally exact quotas.
+Exhausting a creation budget does not interrupt an established match.
+Node.js 24 is the primary supported development target; Bun uses the same entry
+without a separate implementation.
+
+Native room callbacks and commands use the same SDK facade. `signal` aborts when
+close begins; `closed` settles after native cleanup. Neither is a confirmation
+that every remote player has received a shutdown message. This is not yet WAN,
+Linux, other Bun versions, automatic outage recovery, sustained churn or capacity acceptance.
+Bundled dependency licenses are in
+`dist/licenses`; the transport includes DCEP unordered-bit and ICE restart fixes.
+
+TypeScript Node consumers can use `module: "NodeNext"`, `lib: ["ES2022"]` and
+`types: ["node"]` with their Node type package. Public declarations do not require
+DOM/WebRTC globals or `skipLibCheck`; browser runtime classes remain internal.
+`Replay` is exported as a data type from both SDK entries.
+
+Both SDK entries accept `createRoom(config, { signal })`. The optional
+`AbortSignal` cancels startup only; aborting it after creation does not close the
+room. Use `room.close()` for an active room. Startup has a 15-second overall
+deadline for engine assets, HTTP admission/body and signaling, while the existing
+12-second signaling timeout can fail earlier. Rejection preserves the caller's
+abort reason; the overall deadline rejects with `TimeoutError`. In-flight asset
+and admission requests receive the startup signal, and late results cannot
+continue admission after cancellation.
+
+## Install
+
+```sh
+npm install ball2d@0.1.0
+```
+
+The application source remains private. The package retains its existing
+UNLICENSED designation; bundled third-party notices are included separately.