@oasiz/sdk 1.0.1 → 1.1.0

package/README.md

@@ -1,11 +1,11 @@
 # @oasiz/sdk
 
-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.
+Typed SDK for integrating games with the Oasiz platform. Handles score submission, haptic feedback, cross-session state persistence, multiplayer room codes, navigation hooks, and app lifecycle events for local development.
 
 ## Install
 
 ```bash
-npm install @oasiz/sdk
+npm install @oasiz/sdk@^0.1.0
 ```
 
 ## Quick start
@@ -13,17 +13,27 @@ npm install @oasiz/sdk
 ```ts
 import { oasiz } from "@oasiz/sdk";
 
-// 1. Load persisted state at the start of each session
+// 1. Emit score normalization config once on init
+oasiz.emitScoreConfig({
+  anchors: [
+    { raw: 30, normalized: 100 },
+    { raw: 60, normalized: 300 },
+    { raw: 120, normalized: 600 },
+    { raw: 300, normalized: 950 },
+  ],
+});
+
+// 2. Load persisted state at the start of each session
 const state = oasiz.loadGameState();
 let level = typeof state.level === "number" ? state.level : 1;
 
-// 2. Save state at checkpoints
+// 3. Save state at checkpoints
 oasiz.saveGameState({ level, coins: 42 });
 
-// 3. Trigger haptics on key events
+// 4. Trigger haptics on key events
 oasiz.triggerHaptic("medium");
 
-// 4. Submit score when the game ends
+// 5. Submit score when the game ends
 oasiz.submitScore(score);
 ```
 
@@ -33,14 +43,44 @@ oasiz.submitScore(score);
 
 ### `oasiz.submitScore(score: number)`
 
-Submit the player's score. The platform handles leaderboard persistence — do not track high scores locally.
+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
-oasiz.submitScore(this.score);
+private onGameOver(): void {
+  oasiz.submitScore(Math.floor(this.score));
+}
 ```
 
 - `score` must be a non-negative integer. Floats are floored automatically.
-- When and how often you call this depends on your game type (once at game over, end of each level, or throttled for long sessions).
+- 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`
 
 ---
 
@@ -59,14 +99,23 @@ type HapticType = "light" | "medium" | "heavy" | "success" | "error";
 | `"light"` | UI button taps, menu navigation, D-pad press |
 | `"medium"` | Collecting items, standard collisions, scoring |
 | `"heavy"` | Explosions, major impacts, screen shake |
-| `"success"` | Level complete, achievement unlocked |
+| `"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) {
@@ -75,54 +124,75 @@ private onGameOver(): void {
 }
 ```
 
+Haptics are throttled internally (50ms cooldown) to prevent spam.
+
 ---
 
 ## Game state persistence
 
-Persist cross-session data such as unlocked levels, inventory, or lifetime stats. Available across devices and app reinstalls.
+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.
+Returns the player's saved state synchronously. Returns `{}` if no state has been saved yet. Call once at the start of the game.
 
 ```ts
-const state = oasiz.loadGameState();
-this.level = typeof state.level === "number" ? state.level : 1;
+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. Call freely at checkpoints.
+Queues a debounced save. Saves are batched automatically — call freely at checkpoints without worrying about request spam.
 
 ```ts
-oasiz.saveGameState({ level: this.level, unlockedSkins: this.unlockedSkins });
+// Save after each level completion
+private onLevelComplete(): void {
+  this.level += 1;
+  oasiz.saveGameState({
+    level: this.level,
+    lifetimeHits: this.lifetimeHits,
+    unlockedSkins: this.unlockedSkins,
+  });
+}
 ```
 
+**Rules:**
 - State must be a plain JSON object (not an array or primitive).
-- Use `saveGameState` instead of `localStorage` for cross-session progress.
-- Do not store scores here — use `submitScore`.
+- 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 game over or before page unload.
+Forces an immediate write, bypassing the debounce. Use at important checkpoints like game over or before the page unloads.
 
 ```ts
-oasiz.saveGameState({ level: this.level });
-oasiz.flushGameState();
-oasiz.submitScore(this.score);
+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(() => {
+const offPause  = oasiz.onPause(() => {
   this.gameLoop.stop();
   this.bgMusic.pause();
 });
@@ -132,39 +202,126 @@ const offResume = oasiz.onResume(() => {
   this.bgMusic.play();
 });
 
+// Clean up when the game is destroyed
 offPause();
 offResume();
 ```
 
 ---
 
+## Navigation
+
+Use navigation hooks when your game needs to control back behavior (Android back / web Escape) or participate in host-driven close events.
+
+### `oasiz.onBackButton(callback: () => void): Unsubscribe`
+
+Registers a callback for platform back actions. While at least one back listener is subscribed, back actions are routed to your game instead of immediately closing it.
+
+Use this for pause menus, in-game overlays, or custom back-stack behavior.
+
+```ts
+const offBack = oasiz.onBackButton(() => {
+  if (this.isPauseMenuOpen) {
+    this.closePauseMenu();
+    return;
+  }
+  this.openPauseMenu();
+});
+
+// Restore default host back behavior when no longer needed
+offBack();
+```
+
+### `oasiz.leaveGame(): void`
+
+Programmatically request the host to close the current game (for example, from a Quit button inside your game UI).
+
+```ts
+quitButton.addEventListener("click", () => {
+  oasiz.leaveGame();
+});
+```
+
+### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
+
+Registers a callback fired when the host initiates closing the game (for example, close button, gesture, or host navigation). Use this for lightweight cleanup.
+
+```ts
+const offLeave = oasiz.onLeaveGame(() => {
+  oasiz.flushGameState();
+  this.bgMusic.pause();
+});
+
+// Clean up listener when destroyed
+offLeave();
+```
+
+---
+
 ## Multiplayer
 
-### `oasiz.shareRoomCode(code: string | null)`
+### `oasiz.shareRoomCode(code: string | null, options?: { inviteOverride?: boolean })`
+
+Notify the platform of the active multiplayer room so friends can join via the invite system. Pass `null` when leaving a room.
 
-Notify the platform of the active multiplayer room. Pass `null` when leaving.
+Set `inviteOverride: true` when your game wants to hide the platform invite pill and render its own invite button/UI. The platform still tracks the room code, but your game owns the invite entry point.
 
 ```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 properties
+```ts
+// Game-owned invite UI: hide the platform pill, keep room tracking
+oasiz.shareRoomCode(getRoomCode(), { inviteOverride: true });
+```
+
+If you still want to use the platform invite sheet from your own in-game button, combine it with `openInviteModal()`:
+
+```ts
+import { openInviteModal, shareRoomCode } from "@oasiz/sdk";
+
+shareRoomCode("ABCD", { inviteOverride: true });
+
+inviteButton.addEventListener("click", () => {
+  openInviteModal();
+});
+```
 
-| Property | Type | Description |
-|---|---|---|
-| `oasiz.gameId` | string \| undefined | The platform's game ID |
-| `oasiz.roomCode` | string \| undefined | Pre-filled room code from invite |
-| `oasiz.playerName` | string \| undefined | Player's display name |
-| `oasiz.playerAvatar` | string \| undefined | Player's profile picture URL |
+### 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,
@@ -172,6 +329,9 @@ import {
   shareRoomCode,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   getGameId,
   getRoomCode,
   getPlayerName,
@@ -184,15 +344,17 @@ import {
 ## TypeScript types
 
 ```ts
-import type { HapticType, GameState } from "@oasiz/sdk";
+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:
+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.
 ```
+
+No crashes, no special setup required for local dev.

package/dist/index.cjs

@@ -20,15 +20,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  emitScoreConfig: () => emitScoreConfig,
   flushGameState: () => flushGameState,
   getGameId: () => getGameId,
   getPlayerAvatar: () => getPlayerAvatar,
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
+  leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
   oasiz: () => oasiz,
+  onBackButton: () => onBackButton,
+  onLeaveGame: () => onLeaveGame,
   onPause: () => onPause,
   onResume: () => onResume,
+  openInviteModal: () => openInviteModal,
   saveGameState: () => saveGameState,
   shareRoomCode: () => shareRoomCode,
   submitScore: () => submitScore,
@@ -71,10 +76,10 @@ function getBridgeWindow2() {
   }
   return window;
 }
-function shareRoomCode(roomCode) {
+function shareRoomCode(roomCode, options) {
   const bridge = getBridgeWindow2();
   if (typeof bridge?.shareRoomCode === "function") {
-    bridge.shareRoomCode(roomCode);
+    bridge.shareRoomCode(roomCode, options);
     return;
   }
   if (isDevelopment2()) {
@@ -83,6 +88,18 @@ function shareRoomCode(roomCode) {
     );
   }
 }
+function openInviteModal() {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.openInviteModal === "function") {
+    bridge.openInviteModal();
+    return;
+  }
+  if (isDevelopment2()) {
+    console.warn(
+      "[oasiz/sdk] openInviteModal bridge is unavailable. This is expected in local development."
+    );
+  }
+}
 function getGameId() {
   const bridge = getBridgeWindow2();
   return bridge?.__GAME_ID__;
@@ -133,6 +150,14 @@ function submitScore(score) {
   }
   warnMissingBridge("submitScore");
 }
+function emitScoreConfig(config) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.emitScoreConfig === "function") {
+    bridge.emitScoreConfig(config);
+    return;
+  }
+  warnMissingBridge("emitScoreConfig");
+}
 
 // src/state.ts
 function isDevelopment4() {
@@ -225,16 +250,90 @@ function onResume(callback) {
   return addLifecycleListener("oasiz:resume", callback);
 }
 
+// src/navigation.ts
+var activeBackListeners = 0;
+function isDevelopment6() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow5() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function warnMissingBridge3(methodName) {
+  if (isDevelopment6()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+function addNavigationListener(eventName, callback) {
+  if (typeof window === "undefined") {
+    if (isDevelopment6()) {
+      console.warn(
+        "[oasiz/sdk] " + eventName + " listener registered without a browser window. This is expected in local development."
+      );
+    }
+    return () => {
+    };
+  }
+  const handler = () => callback();
+  window.addEventListener(eventName, handler);
+  return () => window.removeEventListener(eventName, handler);
+}
+function onBackButton(callback) {
+  const off = addNavigationListener("oasiz:back", callback);
+  const bridge = getBridgeWindow5();
+  activeBackListeners += 1;
+  if (activeBackListeners === 1) {
+    if (typeof bridge?.__oasizSetBackOverride === "function") {
+      bridge.__oasizSetBackOverride(true);
+    } else {
+      warnMissingBridge3("__oasizSetBackOverride");
+    }
+  }
+  return () => {
+    off();
+    activeBackListeners = Math.max(0, activeBackListeners - 1);
+    if (activeBackListeners === 0) {
+      const currentBridge = getBridgeWindow5();
+      if (typeof currentBridge?.__oasizSetBackOverride === "function") {
+        currentBridge.__oasizSetBackOverride(false);
+      } else {
+        warnMissingBridge3("__oasizSetBackOverride");
+      }
+    }
+  };
+}
+function onLeaveGame(callback) {
+  return addNavigationListener("oasiz:leave", callback);
+}
+function leaveGame() {
+  const bridge = getBridgeWindow5();
+  if (typeof bridge?.__oasizLeaveGame === "function") {
+    bridge.__oasizLeaveGame();
+    return;
+  }
+  warnMissingBridge3("__oasizLeaveGame");
+}
+
 // src/index.ts
 var oasiz = {
   submitScore,
+  emitScoreConfig,
   triggerHaptic,
   loadGameState,
   saveGameState,
   flushGameState,
   shareRoomCode,
+  openInviteModal,
   onPause,
   onResume,
+  onBackButton,
+  onLeaveGame,
+  leaveGame,
   get gameId() {
     return getGameId();
   },
@@ -250,15 +349,20 @@ var oasiz = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  emitScoreConfig,
   flushGameState,
   getGameId,
   getPlayerAvatar,
   getPlayerName,
   getRoomCode,
+  leaveGame,
   loadGameState,
   oasiz,
+  onBackButton,
+  onLeaveGame,
   onPause,
   onResume,
+  openInviteModal,
   saveGameState,
   shareRoomCode,
   submitScore,