npm package: @oasiz/sdk
Description: Typed SDK for Oasiz game platform bridge APIs.
Latest version: 1.4.1

# @oasiz/sdk

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@^0.1.0
```

## 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
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,
  });
}
```

**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();
```

---

## 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.

If your callback throws, Oasiz falls back to closing the game and returning the player to Oasiz home before rethrowing the error for debugging/reporting.

```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.share(options: { text?: string; score?: number; image?: string }): Promise<void>`

Ask the host to open the same share flow Oasiz already uses today. Use `text` to customize the share message, `score` to trigger a challenge-style share, and `image` to share an `http(s)` URL or `data:image/...` payload.

```ts
await oasiz.share({
  text: "I made it to level 9!",
  score: 4200,
});
```

### `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)`

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,
  onBackButton,
  onLeaveGame,
  leaveGame,
  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.
```

No crashes, no special setup required for local dev.