@oasiz/sdk 0.1.0 → 1.0.0

package/README.md

@@ -1,19 +1,20 @@
 # @oasiz/sdk
 
-Typed SDK for Oasiz game bridge APIs.
+Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, and app lifecycle events for local development.
 
 ## Install
 
 ```bash
-npm install @oasiz/sdk
+npm install @oasiz/sdk@^0.1.0
 ```
 
-## Usage
+## Quick start
 
 ```ts
-import { oasis } from "@oasiz/sdk";
+import { oasiz } from "@oasiz/sdk";
 
-oasis.emitScoreConfig({
+// 1. Emit score normalization config once on init
+oasiz.emitScoreConfig({
   anchors: [
     { raw: 30, normalized: 100 },
     { raw: 60, normalized: 300 },
@@ -22,21 +23,267 @@ oasis.emitScoreConfig({
   ],
 });
 
-const saved = oasis.loadGameState();
-oasis.saveGameState({ ...saved, level: 3 });
-oasis.triggerHaptic("light");
-oasis.submitScore(42);
+// 2. Load persisted state at the start of each session
+const state = oasiz.loadGameState();
+let level = typeof state.level === "number" ? state.level : 1;
+
+// 3. Save state at checkpoints
+oasiz.saveGameState({ level, coins: 42 });
+
+// 4. Trigger haptics on key events
+oasiz.triggerHaptic("medium");
+
+// 5. Submit score when the game ends
+oasiz.submitScore(score);
+```
+
+---
+
+## Score
+
+### `oasiz.submitScore(score: number)`
+
+Submit the player's final score at game over. Call this exactly once per session, when the game ends. The platform handles leaderboard persistence — do not track high scores locally.
+
+```ts
+private onGameOver(): void {
+  oasiz.submitScore(Math.floor(this.score));
+}
+```
+
+- `score` must be a non-negative integer. Floats are floored automatically.
+- Do not call on intermediate scores or level completions, only on final game over.
+
+---
+
+### `oasiz.emitScoreConfig(config)`
+
+Maps raw score values to the platform's normalized 0–1000 scale. Call once during initialization, not every frame.
+
+```ts
+oasiz.emitScoreConfig({
+  anchors: [
+    { raw: 10,  normalized: 100 }, // beginner
+    { raw: 30,  normalized: 300 }, // good
+    { raw: 75,  normalized: 600 }, // great
+    { raw: 200, normalized: 950 }, // godlike
+  ],
+});
+```
+
+**Anchor rules:**
+- Exactly 4 anchors required.
+- `raw` values must be strictly increasing.
+- `normalized` values must end at exactly `950`.
+- Choose thresholds based on realistic player skill bands.
+
+**Practical guidance by game type:**
+- Survival / time games → use seconds survived as `raw`
+- Score accumulation games → use points as `raw`
+- Puzzle games → use level reached or stars earned as `raw`
+
+---
+
+## Haptics
+
+### `oasiz.triggerHaptic(type: HapticType)`
+
+Trigger native haptic feedback. Always guard with the user's haptics setting.
+
+```ts
+type HapticType = "light" | "medium" | "heavy" | "success" | "error";
+```
+
+| Type | When to use |
+|---|---|
+| `"light"` | UI button taps, menu navigation, D-pad press |
+| `"medium"` | Collecting items, standard collisions, scoring |
+| `"heavy"` | Explosions, major impacts, screen shake |
+| `"success"` | Level complete, new high score, achievement unlocked |
+| `"error"` | Damage taken, game over, invalid action |
+
+```ts
+// UI buttons — always light
+button.addEventListener("click", () => {
+  oasiz.triggerHaptic("light");
+});
+
+// Tiered hit feedback
+private onBallHit(zone: "center" | "edge"): void {
+  if (this.settings.haptics) {
+    oasiz.triggerHaptic(zone === "center" ? "success" : "medium");
+  }
+}
+
+// Game over
+private onGameOver(): void {
+  oasiz.submitScore(this.score);
+  if (this.settings.haptics) {
+    oasiz.triggerHaptic("error");
+  }
+}
+```
+
+Haptics are throttled internally (50ms cooldown) to prevent spam.
+
+---
+
+## Game state persistence
+
+Persist cross-session data such as unlocked levels, inventory, or lifetime stats. State is stored per-user per-game in the Oasiz backend — available across devices and app reinstalls.
+
+### `oasiz.loadGameState(): Record<string, unknown>`
+
+Returns the player's saved state synchronously. Returns `{}` if no state has been saved yet. Call once at the start of the game.
+
+```ts
+private initFromSavedState(): void {
+  const state = oasiz.loadGameState();
+  this.level        = typeof state.level === "number" ? state.level : 1;
+  this.lifetimeHits = typeof state.lifetimeHits === "number" ? state.lifetimeHits : 0;
+  this.unlockedSkins = Array.isArray(state.unlockedSkins) ? state.unlockedSkins : [];
+}
+```
+
+Always validate the shape of loaded data — it may be `{}` on first play.
+
+### `oasiz.saveGameState(state: Record<string, unknown>)`
+
+Queues a debounced save. Saves are batched automatically — call freely at checkpoints without worrying about request spam.
+
+```ts
+// Save after each level completion
+private onLevelComplete(): void {
+  this.level += 1;
+  oasiz.saveGameState({
+    level: this.level,
+    lifetimeHits: this.lifetimeHits,
+    unlockedSkins: this.unlockedSkins,
+  });
+}
 ```
 
-## API
+**Rules:**
+- State must be a plain JSON object (not an array or primitive).
+- Do not use `localStorage` for cross-session progress — use `saveGameState` so data syncs across platforms.
+- Do not store scores here — scores are submitted via `submitScore`.
+
+### `oasiz.flushGameState()`
+
+Forces an immediate write, bypassing the debounce. Use at important checkpoints like game over or before the page unloads.
+
+```ts
+private onGameOver(): void {
+  oasiz.saveGameState({ level: this.level, lifetimeHits: this.lifetimeHits });
+  oasiz.flushGameState(); // ensure it lands before the page closes
+  oasiz.submitScore(this.score);
+}
+```
+
+---
+
+## Lifecycle
+
+The platform dispatches lifecycle events when the app goes to the background or returns to the foreground. Subscribe to pause game loops and audio accordingly.
+
+### `oasiz.onPause(callback: () => void): Unsubscribe`
+### `oasiz.onResume(callback: () => void): Unsubscribe`
+
+Both return an unsubscribe function.
+
+```ts
+const offPause  = oasiz.onPause(() => {
+  this.gameLoop.stop();
+  this.bgMusic.pause();
+});
+
+const offResume = oasiz.onResume(() => {
+  this.gameLoop.start();
+  this.bgMusic.play();
+});
+
+// Clean up when the game is destroyed
+offPause();
+offResume();
+```
+
+---
+
+## Multiplayer
+
+### `oasiz.shareRoomCode(code: string | null)`
+
+Notify the platform of the active multiplayer room so friends can join via the invite system. Pass `null` when leaving a room.
+
+```ts
+import { insertCoin, getRoomCode } from "playroomkit";
+import { oasiz } from "@oasiz/sdk";
+
+await insertCoin({ skipLobby: true });
+oasiz.shareRoomCode(getRoomCode());
+
+// On disconnect
+oasiz.shareRoomCode(null);
+```
+
+### Read-only injected values
+
+These are populated by the platform before the game loads. Always check for `undefined` before using.
+
+```ts
+// The platform's internal game ID
+const gameId = oasiz.gameId;
+
+// Pre-filled room code for auto-joining a friend's session
+if (oasiz.roomCode) {
+  await connectToRoom(oasiz.roomCode);
+}
+
+// Player identity for multiplayer games
+const name   = oasiz.playerName;
+const avatar = oasiz.playerAvatar;
+```
+
+---
+
+## Named exports
+
+All methods are also available as named exports if you prefer not to use the `oasiz` namespace object:
+
+```ts
+import {
+  submitScore,
+  emitScoreConfig,
+  triggerHaptic,
+  loadGameState,
+  saveGameState,
+  flushGameState,
+  shareRoomCode,
+  onPause,
+  onResume,
+  getGameId,
+  getRoomCode,
+  getPlayerName,
+  getPlayerAvatar,
+} from "@oasiz/sdk";
+```
+
+---
+
+## TypeScript types
+
+```ts
+import type { HapticType, ScoreConfig, ScoreAnchor, GameState } from "@oasiz/sdk";
+```
+
+---
+
+## Local development
+
+All methods safely no-op when the platform bridges are not injected. In development mode a console warning is logged so you know the call was made:
+
+```
+[oasiz/sdk] submitScore bridge is unavailable. This is expected in local development.
+```
 
-- `submitScore(score)`
-- `emitScoreConfig(config)`
-- `triggerHaptic(type)`
-- `loadGameState()`
-- `saveGameState(state)`
-- `flushGameState()`
-- `shareRoomCode(code)`
-- `onPause(callback)`
-- `onResume(callback)`
-- `oasis.gameId`, `oasis.roomCode`, `oasis.playerName`, `oasis.playerAvatar`
+No crashes, no special setup required for local dev.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,9 +28,22 @@
   "release": {
     "branches": [
       "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/github",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "npm version ${nextRelease.version} --no-git-tag-version --allow-same-version --no-workspaces",
+          "publishCmd": "npm publish --access public --no-workspaces"
+        }
+      ]
     ]
   },
   "devDependencies": {
+    "@semantic-release/exec": "^7.1.0",
     "@types/node": "^25.3.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",