@oasiz/sdk 1.4.0 → 1.5.0

package/README.md

@@ -1,47 +1,63 @@
-# @oasiz/sdk
+# Oasiz game SDKs
 
-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.
+Games on Oasiz can integrate using either of these official SDKs:
 
-## Install
+| Platform | Package | Use for |
+| --- | --- | --- |
+| **HTML5 / TypeScript** | [`@oasiz/sdk`](#html5--typescript-oasizsdk) (npm) | Canvas, Phaser, custom JS/TS, any browser game |
+| **Unity WebGL** | [Unity runtime](#unity-webgl-sdk) in this repo (`packages/OasizSDK/`) | Unity projects targeting WebGL |
+
+Both talk to the same host bridges (`window.submitScore`, `__oasizLeaveGame`, layout APIs, custom DOM events such as `oasiz:pause`, etc.). Unsupported hosts no-op safely; local dev usually logs warnings instead of crashing.
+
+---
+
+## HTML5 / TypeScript (`@oasiz/sdk`)
+
+Typed SDK for integrating browser games with the Oasiz platform: score, haptics, cross-session state, multiplayer hooks, layout (safe area, leaderboard visibility), navigation (back / leave), and lifecycle events.
+
+### Install
 
 ```bash
-npm install @oasiz/sdk@^0.1.0
+npm install @oasiz/sdk
 ```
 
-## Quick start
+### Quick start
 
 ```ts
 import { oasiz } from "@oasiz/sdk";
 
-// 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
+// 1. 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
+// 2. Save state at checkpoints
 oasiz.saveGameState({ level, coins: 42 });
 
-// 4. Trigger haptics on key events
+// 3. Trigger haptics on key events
 oasiz.triggerHaptic("medium");
 
+// 4. Respect the host's top safe area
+document.documentElement.style.setProperty(
+  "--safe-top",
+  `${oasiz.safeAreaTop}px`,
+);
+
 // 5. Submit score when the game ends
 oasiz.submitScore(score);
-```
 
----
+// 6. Optionally hide the leaderboard while a custom overlay is open
+oasiz.setLeaderboardVisible(false);
+
+// 7. Optionally surface console logs in-game while debugging
+oasiz.enableLogOverlay({
+  enabled: new URLSearchParams(window.location.search).has("oasizLogs"),
+  collapsed: true,
+});
+```
 
-## Score
+### Score
 
-### `oasiz.submitScore(score: number)`
+#### `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.
 
@@ -54,39 +70,9 @@ private onGameOver(): void {
 - `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
+### Haptics
 
-### `oasiz.triggerHaptic(type: HapticType)`
+#### `oasiz.triggerHaptic(type: HapticType)`
 
 Trigger native haptic feedback. Always guard with the user's haptics setting.
 
@@ -95,7 +81,7 @@ 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 |
@@ -126,20 +112,45 @@ private onGameOver(): void {
 
 Haptics are throttled internally (50ms cooldown) to prevent spam.
 
----
+### Debugging
+
+#### `oasiz.enableLogOverlay(options?: LogOverlayOptions)`
 
-## Game state persistence
+Mount an opt-in in-game console viewer for local debugging, QA sessions, or creator support. It mirrors `console.log`, `console.info`, `console.warn`, `console.error`, and `console.debug` into a floating overlay inside the game iframe. The overlay can be collapsed, repositioned by dragging the top bar, and resized from the bottom-right corner while the action buttons remain clickable.
+
+```ts
+const logOverlay = oasiz.enableLogOverlay({
+  enabled: new URLSearchParams(window.location.search).has("oasizLogs"),
+  collapsed: true,
+});
+
+console.log("[Boot] Scene ready");
+
+// Optional cleanup if your game tears down and remounts
+logOverlay.destroy();
+```
+
+Options:
+
+- `enabled`: defaults to `true`. Pass your own flag or query-param check here.
+- `collapsed`: start with only the toggle pill visible.
+- `maxEntries`: cap retained log lines. Defaults to `200`.
+- `title`: optional label shown at the top of the panel. Defaults to `SDK Logs`.
+
+The returned handle supports `show()`, `hide()`, `clear()`, `isVisible()`, and `destroy()`.
+
+### 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>`
+#### `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.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 : [];
 }
@@ -147,7 +158,7 @@ private initFromSavedState(): void {
 
 Always validate the shape of loaded data — it may be `{}` on first play.
 
-### `oasiz.saveGameState(state: Record<string, unknown>)`
+#### `oasiz.saveGameState(state: Record<string, unknown>)`
 
 Queues a debounced save. Saves are batched automatically — call freely at checkpoints without worrying about request spam.
 
@@ -164,11 +175,12 @@ private onLevelComplete(): void {
 ```
 
 **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()`
+#### `oasiz.flushGameState()`
 
 Forces an immediate write, bypassing the debounce. Use at important checkpoints like game over or before the page unloads.
 
@@ -180,19 +192,63 @@ private onGameOver(): void {
 }
 ```
 
----
+### Layout
+
+Use the runtime safe-area value instead of hardcoded top offsets. The host reports the current top inset in **CSS pixels** for persistent chrome such as the back button and top controls.
+
+#### `oasiz.getSafeAreaTop(): number`
+
+Returns the current top inset. The host may expose `window.getSafeAreaTop()` or `window.__OASIZ_SAFE_AREA_TOP__`. Unsupported hosts return `0`.
+
+```ts
+const safeTop = oasiz.getSafeAreaTop();
+document.documentElement.style.setProperty("--safe-top", `${safeTop}px`);
+```
 
-## Lifecycle
+#### `oasiz.safeAreaTop`
+
+Getter alias for `getSafeAreaTop()`.
+
+Recommended CSS pattern:
+
+```css
+:root {
+  --safe-top: 0px;
+}
+
+#top-bar {
+  padding-top: var(--safe-top);
+}
+```
+
+#### `oasiz.setLeaderboardVisible(visible: boolean): void`
+
+Show or hide the host leaderboard UI from inside the game. This only affects the leaderboard; back and social controls remain visible. Calls `window.__oasizSetLeaderboardVisible` when present.
+
+```ts
+function openCustomOverlay(): void {
+  oasiz.setLeaderboardVisible(false);
+}
+
+function closeCustomOverlay(): void {
+  oasiz.setLeaderboardVisible(true);
+}
+```
+
+Unsupported hosts safely no-op.
+
+### 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`
+#### `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();
 });
@@ -207,18 +263,18 @@ offPause();
 offResume();
 ```
 
----
-
-## Navigation
+### 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`
+#### `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.
 
+**If your callback throws**, the SDK calls `leaveGame()` (host close) and **rethrows** the error so you still see it in devtools or error reporting. Non-`Error` throws are normalized to an `Error` (strings become the message; otherwise `"Back button callback failed."`).
+
 ```ts
 const offBack = oasiz.onBackButton(() => {
   if (this.isPauseMenuOpen) {
@@ -232,7 +288,7 @@ const offBack = oasiz.onBackButton(() => {
 offBack();
 ```
 
-### `oasiz.leaveGame(): void`
+#### `oasiz.leaveGame(): void`
 
 Programmatically request the host to close the current game (for example, from a Quit button inside your game UI).
 
@@ -242,7 +298,7 @@ quitButton.addEventListener("click", () => {
 });
 ```
 
-### `oasiz.onLeaveGame(callback: () => void): Unsubscribe`
+#### `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.
 
@@ -256,14 +312,14 @@ const offLeave = oasiz.onLeaveGame(() => {
 offLeave();
 ```
 
----
-
-## Multiplayer
+### 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.
 
+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";
@@ -275,7 +331,26 @@ oasiz.shareRoomCode(getRoomCode());
 oasiz.shareRoomCode(null);
 ```
 
-### Read-only injected values
+```ts
+// Game-owned invite UI: hide the platform pill, keep room tracking
+oasiz.shareRoomCode(getRoomCode(), { inviteOverride: true });
+```
+
+#### `oasiz.openInviteModal(): void`
+
+Opens the platform invite-friends UI when the bridge is available. Typically used together with `shareRoomCode` (for example, your own invite button calls this).
+
+```ts
+import { openInviteModal, shareRoomCode } from "@oasiz/sdk";
+
+shareRoomCode("ABCD", { inviteOverride: true });
+
+inviteButton.addEventListener("click", () => {
+  openInviteModal();
+});
+```
+
+#### Read-only injected values
 
 These are populated by the platform before the game loads. Always check for `undefined` before using.
 
@@ -289,25 +364,26 @@ if (oasiz.roomCode) {
 }
 
 // Player identity for multiplayer games
-const name   = oasiz.playerName;
+const name = oasiz.playerName;
 const avatar = oasiz.playerAvatar;
 ```
 
----
-
-## Named exports
+### 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,
+  openInviteModal,
+  enableLogOverlay,
+  getSafeAreaTop,
+  setLeaderboardVisible,
   onPause,
   onResume,
   onBackButton,
@@ -320,18 +396,70 @@ import {
 } from "@oasiz/sdk";
 ```
 
----
-
-## TypeScript types
+### TypeScript types
 
 ```ts
-import type { HapticType, ScoreConfig, ScoreAnchor, GameState } from "@oasiz/sdk";
+import type {
+  GameState,
+  HapticType,
+  LogOverlayHandle,
+  LogOverlayOptions,
+  ShareRoomCodeOptions,
+  Unsubscribe,
+} from "@oasiz/sdk";
 ```
 
 ---
 
+## Unity WebGL SDK
+
+C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`packages/OasizSDK/`**. Copy the **`OasizSDK`** folder into your Unity project under **`Assets/`** (for example `Assets/OasizSDK`).
+
+### Setup
+
+1. Copy `packages/OasizSDK` from this repo into `Assets/OasizSDK`.
+2. Ensure the **WebGL** platform is selected for release builds; the `.jslib` under `Runtime/Plugins/WebGL/` is included automatically for WebGL.
+3. Add an **`OasizSDK`** component to a persistent GameObject early (for example a bootstrap scene), **or** rely on `OasizSDK.Instance` which creates a `DontDestroyOnLoad` object. The component registers listeners for `oasiz:pause`, `oasiz:resume`, `oasiz:back`, and `oasiz:leave` via `SendMessage`.
+
+### API parity (TypeScript → C#)
+
+| HTML5 (`@oasiz/sdk`) | Unity (`Oasiz` namespace) |
+| --- | --- |
+| `oasiz.submitScore(n)` | `OasizSDK.SubmitScore(int)` |
+| `oasiz.triggerHaptic(type)` | `OasizSDK.TriggerHaptic(HapticType)` |
+| `oasiz.loadGameState()` | `OasizSDK.LoadGameState()` → `Dictionary<string, object>` |
+| `oasiz.saveGameState(obj)` | `OasizSDK.SaveGameState(Dictionary<string, object>)` |
+| `oasiz.flushGameState()` | `OasizSDK.FlushGameState()` |
+| `oasiz.getSafeAreaTop()` / `safeAreaTop` | `OasizSDK.GetSafeAreaTop()` / `OasizSDK.SafeAreaTop` (`float`, CSS px) |
+| `oasiz.setLeaderboardVisible(v)` | `OasizSDK.SetLeaderboardVisible(bool)` |
+| `oasiz.onPause` / `onResume` | `OasizSDK.OnPause` / `OnResume` static events |
+| `oasiz.onBackButton` | `OasizSDK.OnBackButton` or `SubscribeBackButton(Action)` (reference-counts `__oasizSetBackOverride`) |
+| `oasiz.onLeaveGame` | `OasizSDK.OnLeaveGame` |
+| `oasiz.leaveGame()` | `OasizSDK.LeaveGame()` |
+| `oasiz.shareRoomCode` | `OasizSDK.ShareRoomCode(string, ShareRoomCodeOptions)` |
+| `oasiz.openInviteModal()` | `OasizSDK.OpenInviteModal()` |
+| `oasiz.gameId` / `roomCode` / … | `OasizSDK.GameId` / `RoomCode` / `PlayerName` / `PlayerAvatar` |
+| — | `OasizSDK.EmitScoreConfig(ScoreConfig)` → `window.emitScoreConfig` (Unity-only helper for normalized score UI) |
+| `oasiz.enableLogOverlay` | `OasizSDK.EnableLogOverlay(LogOverlayOptions)` (see note below) |
+
+### Back button and errors
+
+Matching the HTML5 SDK: if any **`OnBackButton`** handler throws, **`OasizSDK.LeaveGame()`** is invoked and the **original exception is rethrown** (`throw;` preserves the stack trace). Use **`SubscribeBackButton`** when you want an unsubscribe delegate; you can also use `OnBackButton +=` / `-=` directly.
+
+### Editor vs WebGL builds
+
+In the **Unity Editor**, bridge calls are mostly **logged** and return safe defaults (for example safe area `0`, `null` platform IDs). Real host integration applies to **WebGL player** builds running inside Oasiz.
+
+### Log overlay (Unity)
+
+The C# API for the log overlay exists for API compatibility, but the **default `OasizBridge.jslib` in this repo does not inject DOM UI** — `EnableLogOverlay` / `AppendLogOverlay` are no-ops at the JavaScript layer. Use Unity’s console and device logs for debugging unless you replace or extend the `.jslib` on your side.
+
+---
+
 ## Local development
 
+### HTML5 / TypeScript
+
 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:
 
 ```
@@ -339,3 +467,7 @@ All methods safely no-op when the platform bridges are not injected. In developm
 ```
 
 No crashes, no special setup required for local dev.
+
+### Unity WebGL
+
+The `.jslib` logs warnings when `window.*` bridges are missing (for example `submitScore`, `__oasizLeaveGame`). The Editor path avoids calling native plugins and prints `Debug.Log` for most operations instead.