@loova/game-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,104 @@
+# @loova/game-sdk
+
+TypeScript ESM SDK for browser games generated by Loova AI Agent. It speaks the
+stable Loova realtime Protocol v1 and treats all server state as authoritative.
+
+## Install and build
+
+```bash
+npm install
+npm run proto
+npm test
+npm run build
+```
+
+The protocol source of truth is
+`../loova-game-realtime/proto/realtime/v1/realtime.proto`. Generated
+Protobuf-ES bindings are committed under `src/gen`; published packages do not
+need `buf` or `protoc` at runtime.
+
+## Runtime client
+
+```ts
+import { InputAction, createLoovaGameSDK } from "@loova/game-sdk";
+
+const sdk = createLoovaGameSDK({
+  apiUrl: "https://api.loova.example",
+});
+
+const room = await sdk.createRoom({ gameId: "my-game" });
+const session = await sdk.joinRoom(room.roomId, { playerId: "player-1" });
+
+await sdk.connect({
+  websocketUrl: session.websocketUrl,
+  ticket: session.ticket,
+  reconnectToken: session.reconnectToken,
+  playerId: session.playerId,
+  roomId: session.roomId,
+});
+
+sdk.sendInput({
+  moveX: 1,
+  moveY: 0,
+  aimX: 1,
+  aimY: 0,
+  actions: InputAction.Fire,
+});
+```
+
+`createRoom()` and `joinRoom()` use the trusted platform HTTP API. Tickets must
+never be created inside an untrusted browser game.
+
+## Events
+
+```ts
+sdk.onPlayerJoin(({ player }) => console.log("join", player.playerId));
+sdk.onSnapshot(({ serverTick, players }) => render(players, serverTick));
+sdk.onPlayerLeave(({ playerId }) => console.log("left", playerId));
+sdk.onDamage(({ playerId, damage }) => showDamage(playerId, damage));
+sdk.onDeath(({ playerId, killerPlayerId }) => showDeath(playerId, killerPlayerId));
+sdk.onMatchEnd(({ winnerPlayerId }) => showWinner(winnerPlayerId));
+```
+
+Every subscription returns an unsubscribe function.
+
+## Prediction and interpolation
+
+- Sent inputs are retained in a bounded input buffer.
+- `FullSnapshot` acknowledges processed input sequences.
+- `ServerCorrection` resets the local player to authoritative state and replays
+  unacknowledged inputs.
+- `getPredictedLocalPlayer()` returns the predicted local state.
+- `getInterpolatedPlayers()` returns remote state sampled behind realtime by the
+  configured interpolation delay.
+
+Prediction is visual only. The SDK never sends predicted positions, health,
+hits, deaths, or match outcomes back to the server.
+
+## Heartbeat and reconnect
+
+The SDK sends protobuf `Ping` frames on a configurable interval. Unexpected
+disconnects use bounded exponential backoff when `reconnectToken` is present.
+The first frame on the replacement socket is `Reconnect` with the last received
+server sequence. Without a reconnect token, the SDK closes instead of replaying
+the one-time Auth ticket.
+
+## Two-player demo
+
+```bash
+npm run build
+npm run demo:build
+python3 -m http.server 4173
+```
+
+Open `http://localhost:4173/demo/`, enter two one-time tickets for the same
+room, and connect. Space fires for player A; Enter fires for player B.
+
+## Protocol stability
+
+- `protocolVersion` is currently `1`.
+- The SDK validates server protocol version and monotonic server sequence.
+- Existing protobuf field numbers and enum values must never be changed or
+  reused.
+- Breaking protocol changes require a new protobuf package and protocol major
+  version.

package/dist/events.d.ts

@@ -0,0 +1,8 @@
+export type Unsubscribe = () => void;
+export declare class EventChannel<T> {
+    #private;
+    subscribe(listener: (event: T) => void): Unsubscribe;
+    emit(event: T): void;
+    clear(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,qBAAa,YAAY,CAAC,CAAC;;IAGzB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW;IAOpD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAMpB,KAAK,IAAI,IAAI;CAGd"}

package/dist/events.js

@@ -0,0 +1,18 @@
+export class EventChannel {
+    #listeners = new Set();
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.#listeners) {
+            listener(event);
+        }
+    }
+    clear() {
+        this.#listeners.clear();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,YAAY;IACd,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEpD,SAAS,CAAC,QAA4B;QACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAQ;QACX,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}