@oasiz/sdk 1.5.0 → 1.5.1

package/README.md

@@ -402,7 +402,9 @@ import {
 import type {
   GameState,
   HapticType,
+  LogOverlayEntry,
   LogOverlayHandle,
+  LogOverlayLevel,
   LogOverlayOptions,
   ShareRoomCodeOptions,
   Unsubscribe,
@@ -421,6 +423,59 @@ C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`pack
 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`.
 
+### Quick start
+
+```csharp
+using Oasiz;
+using UnityEngine;
+
+public class GameManager : MonoBehaviour
+{
+    void Start()
+    {
+        // Ensure the singleton is initialized early
+        _ = OasizSDK.Instance;
+
+        // Subscribe to lifecycle events
+        OasizSDK.OnPause += OnPause;
+        OasizSDK.OnResume += OnResume;
+
+        // Offset UI for the host's top safe area
+        float safeTop = OasizSDK.SafeAreaTop;
+        Debug.Log($"Safe area top: {safeTop}px");
+
+        // Emit score normalization anchors
+        OasizSDK.EmitScoreConfig(new ScoreConfig(
+            new ScoreAnchor(10, 100),
+            new ScoreAnchor(30, 300),
+            new ScoreAnchor(75, 600),
+            new ScoreAnchor(200, 950)
+        ));
+    }
+
+    void OnGameOver(int finalScore)
+    {
+        OasizSDK.SubmitScore(finalScore);
+        OasizSDK.FlushGameState();
+        OasizSDK.SetLeaderboardVisible(true);
+    }
+
+    void OnGameplayStart()
+    {
+        OasizSDK.SetLeaderboardVisible(false);
+    }
+
+    void OnPause() => Time.timeScale = 0f;
+    void OnResume() => Time.timeScale = 1f;
+
+    void OnDestroy()
+    {
+        OasizSDK.OnPause -= OnPause;
+        OasizSDK.OnResume -= OnResume;
+    }
+}
+```
+
 ### API parity (TypeScript → C#)
 
 | HTML5 (`@oasiz/sdk`) | Unity (`Oasiz` namespace) |
@@ -438,21 +493,71 @@ C# API and **WebGL-only** `OasizBridge.jslib` live in this repository at **`pack
 | `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.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) |
+| -- | `OasizSDK.AppendLogOverlay(level, message, stackTrace)` (see note below) |
+
+### Types
+
+```csharp
+// Haptic feedback intensity
+public enum HapticType { Light, Medium, Heavy, Success, Error }
+
+// Score normalization (exactly 4 anchors required)
+public struct ScoreAnchor { public int raw; public int normalized; }
+public struct ScoreConfig { public ScoreAnchor[] anchors; }
+
+// Multiplayer invite options
+public class ShareRoomCodeOptions { public bool InviteOverride { get; set; } }
+
+// Log overlay configuration
+public class LogOverlayOptions
+{
+    public bool Enabled { get; set; } = true;
+    public bool Collapsed { get; set; } = false;
+    public int MaxEntries { get; set; } = 200;
+    public string Title { get; set; } = "SDK Logs";
+}
+
+// Log overlay lifecycle handle
+public class LogOverlayHandle
+{
+    public void Clear();
+    public void Hide();
+    public void Show();
+    public bool IsVisible();
+    public void Destroy();
+}
+```
 
 ### 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.
 
+```csharp
+// Subscribe with automatic unsubscribe support
+var offBack = OasizSDK.SubscribeBackButton(() =>
+{
+    if (isPaused)
+        Resume();
+    else
+        Pause();
+});
+
+// Unsubscribe when no longer needed
+offBack();
+```
+
 ### 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.
+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.
+
+`AppendLogOverlay(level, message, stackTrace)` lets you pipe `Debug.Log` output into the overlay manually, since many embedded WebViews do not route Unity player logs through `console.log`. Valid levels: `"debug"`, `"log"`, `"info"`, `"warn"`, `"error"`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",