@oasiz/sdk 1.5.3 → 1.5.5

package/dist/index.d.cts

@@ -25,6 +25,107 @@ interface ShareRequest {
     score?: number;
     text?: string;
 }
+/**
+ * One frame in a texture atlas. Coordinates are in pixels, top-left origin
+ * (matches HTML canvas / WebGL texture coordinates after Y-flip).
+ */
+interface TextureAtlasFrame {
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Per-direction frame indexes inside an animation. `left` is either an
+ * integer index or the literal string `"mirror"`, indicating the renderer
+ * should mirror the right-facing frame instead of using a dedicated one.
+ */
+interface FacingFrameMap {
+    front: number;
+    back: number;
+    right: number;
+    left: number | "mirror";
+}
+/**
+ * One named animation in a texture atlas. `frames` is the playback-ordered
+ * list of frame names; resolve each name against the parent atlas's
+ * `frames` array to get pixel coordinates.
+ */
+interface TextureAtlasAnimation {
+    animationId: string;
+    role: string | null;
+    group: string | null;
+    direction: string | null;
+    frameRate: number;
+    frames: string[];
+    facingFrameMap: FacingFrameMap | null;
+}
+/**
+ * TexturePacker / Phaser-style texture atlas describing a baked sprite
+ * image. Drop-in compatible with Phaser via `addAtlas(key, img, atlas)`
+ * after a tiny shape transform; usable directly in custom GL renderers.
+ */
+interface TextureAtlas {
+    imageUrl: string;
+    imageWidth: number;
+    imageHeight: number;
+    frames: TextureAtlasFrame[];
+    animations: TextureAtlasAnimation[];
+}
+/**
+ * The authenticated player's character, returned by `getPlayerCharacter()`.
+ * `editorTextureAtlas` is the higher-detail variant intended for character
+ * previews / customizer UI and may be `null`.
+ */
+interface PlayerCharacter {
+    characterName: string | null;
+    baseCharacterId: string;
+    compositionCode: string;
+    textureAtlas: TextureAtlas;
+    editorTextureAtlas: TextureAtlas | null;
+}
+/**
+ * Result of `addScore(delta)` / `setScore(score)`. Returns `null` when the
+ * host bridge is unavailable (e.g. local development) or when the backend
+ * refused the request; production code should treat `null` as "no change
+ * was persisted, do not update local UI".
+ */
+interface ScoreEditResult {
+    playerId: string;
+    previousScore: number;
+    newScore: number;
+    previousWeeklyScore: number;
+    newWeeklyScore: number;
+    normalizedScore: number | null;
+}
+
+/**
+ * Fetch the authenticated player's character, including a TexturePacker /
+ * Phaser-style texture atlas describing the baked sprite image.
+ *
+ * Returns:
+ *   - `null` when the user has no character composition yet, OR
+ *   - `null` when the host bridge is unavailable (local dev / unauthenticated)
+ *
+ * The host transparently caches and proxies to `GET /api/sdk/me/character`,
+ * so calling this multiple times in a session is cheap. The returned
+ * `imageUrl` is content-addressed (R2 key derives from the composition
+ * hash), so games can safely cache the downloaded texture by `compositionCode`.
+ *
+ * Example (Phaser):
+ *
+ *   const character = await oasiz.getPlayerCharacter();
+ *   if (!character) return;
+ *   const atlas = character.textureAtlas;
+ *   scene.load.image("player-tex", atlas.imageUrl);
+ *   scene.load.atlas("player", atlas.imageUrl, {
+ *     frames: Object.fromEntries(
+ *       atlas.frames.map((f) => [f.name, { frame: { x: f.x, y: f.y, w: f.width, h: f.height } }]),
+ *     ),
+ *   });
+ */
+declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -47,11 +148,44 @@ declare function shareRoomCode(roomCode: string | null, options?: ShareRoomCodeO
 declare function openInviteModal(): void;
 declare function getGameId(): string | undefined;
 declare function getRoomCode(): string | undefined;
+/**
+ * Stable, unique, opaque identifier for the authenticated player, injected
+ * by the platform. Safe to use as a primary key for save slots, matchmaking,
+ * per-player analytics, or anywhere you need a reliable per-user key —
+ * unlike `getPlayerName()` (mutable, not unique).
+ *
+ * Mirrors the backend's `playerId` field returned by `GET /api/sdk/me`
+ * (= the Better Auth `user.id`). Returns `undefined` when the platform
+ * has not injected an identity (e.g. unauthenticated preview).
+ */
+declare function getPlayerId(): string | undefined;
 declare function getPlayerName(): string | undefined;
 declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
 
+/**
+ * Add (or subtract) `delta` from the player's current score for this game.
+ * The new score is clamped to >= 0 server-side.
+ *
+ * Unlike `submitScore()` (which is high-water and only ever raises the
+ * score), this endpoint always overwrites the row. Use it for game models
+ * where the leaderboard tracks an accumulator, balance, or persistent state
+ * instead of a single best-run value.
+ *
+ * Returns the resulting score values, or `null` when the bridge is
+ * unavailable. The integer must be a non-zero integer (positive or negative).
+ */
+declare function addScore(delta: number): Promise<ScoreEditResult | null>;
+/**
+ * Force the player's score to an absolute value (clamped to >= 0).
+ *
+ * Same overwrite semantics as `addScore`. Use when the game has computed
+ * the authoritative score locally (e.g. after offline play) and wants to
+ * sync it back to the leaderboard.
+ */
+declare function setScore(score: number): Promise<ScoreEditResult | null>;
+
 declare function share(options: ShareRequest): Promise<void>;
 
 declare function loadGameState(): GameState;
@@ -77,6 +211,9 @@ declare function leaveGame(): void;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
+    addScore: typeof addScore;
+    setScore: typeof setScore;
+    getPlayerCharacter: typeof getPlayerCharacter;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -94,9 +231,10 @@ declare const oasiz: {
     leaveGame: typeof leaveGame;
     readonly gameId: string | undefined;
     readonly roomCode: string | undefined;
+    readonly playerId: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
     readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRequest, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, share, shareRoomCode, submitScore, triggerHaptic };
+export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -25,6 +25,107 @@ interface ShareRequest {
     score?: number;
     text?: string;
 }
+/**
+ * One frame in a texture atlas. Coordinates are in pixels, top-left origin
+ * (matches HTML canvas / WebGL texture coordinates after Y-flip).
+ */
+interface TextureAtlasFrame {
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Per-direction frame indexes inside an animation. `left` is either an
+ * integer index or the literal string `"mirror"`, indicating the renderer
+ * should mirror the right-facing frame instead of using a dedicated one.
+ */
+interface FacingFrameMap {
+    front: number;
+    back: number;
+    right: number;
+    left: number | "mirror";
+}
+/**
+ * One named animation in a texture atlas. `frames` is the playback-ordered
+ * list of frame names; resolve each name against the parent atlas's
+ * `frames` array to get pixel coordinates.
+ */
+interface TextureAtlasAnimation {
+    animationId: string;
+    role: string | null;
+    group: string | null;
+    direction: string | null;
+    frameRate: number;
+    frames: string[];
+    facingFrameMap: FacingFrameMap | null;
+}
+/**
+ * TexturePacker / Phaser-style texture atlas describing a baked sprite
+ * image. Drop-in compatible with Phaser via `addAtlas(key, img, atlas)`
+ * after a tiny shape transform; usable directly in custom GL renderers.
+ */
+interface TextureAtlas {
+    imageUrl: string;
+    imageWidth: number;
+    imageHeight: number;
+    frames: TextureAtlasFrame[];
+    animations: TextureAtlasAnimation[];
+}
+/**
+ * The authenticated player's character, returned by `getPlayerCharacter()`.
+ * `editorTextureAtlas` is the higher-detail variant intended for character
+ * previews / customizer UI and may be `null`.
+ */
+interface PlayerCharacter {
+    characterName: string | null;
+    baseCharacterId: string;
+    compositionCode: string;
+    textureAtlas: TextureAtlas;
+    editorTextureAtlas: TextureAtlas | null;
+}
+/**
+ * Result of `addScore(delta)` / `setScore(score)`. Returns `null` when the
+ * host bridge is unavailable (e.g. local development) or when the backend
+ * refused the request; production code should treat `null` as "no change
+ * was persisted, do not update local UI".
+ */
+interface ScoreEditResult {
+    playerId: string;
+    previousScore: number;
+    newScore: number;
+    previousWeeklyScore: number;
+    newWeeklyScore: number;
+    normalizedScore: number | null;
+}
+
+/**
+ * Fetch the authenticated player's character, including a TexturePacker /
+ * Phaser-style texture atlas describing the baked sprite image.
+ *
+ * Returns:
+ *   - `null` when the user has no character composition yet, OR
+ *   - `null` when the host bridge is unavailable (local dev / unauthenticated)
+ *
+ * The host transparently caches and proxies to `GET /api/sdk/me/character`,
+ * so calling this multiple times in a session is cheap. The returned
+ * `imageUrl` is content-addressed (R2 key derives from the composition
+ * hash), so games can safely cache the downloaded texture by `compositionCode`.
+ *
+ * Example (Phaser):
+ *
+ *   const character = await oasiz.getPlayerCharacter();
+ *   if (!character) return;
+ *   const atlas = character.textureAtlas;
+ *   scene.load.image("player-tex", atlas.imageUrl);
+ *   scene.load.atlas("player", atlas.imageUrl, {
+ *     frames: Object.fromEntries(
+ *       atlas.frames.map((f) => [f.name, { frame: { x: f.x, y: f.y, w: f.width, h: f.height } }]),
+ *     ),
+ *   });
+ */
+declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -47,11 +148,44 @@ declare function shareRoomCode(roomCode: string | null, options?: ShareRoomCodeO
 declare function openInviteModal(): void;
 declare function getGameId(): string | undefined;
 declare function getRoomCode(): string | undefined;
+/**
+ * Stable, unique, opaque identifier for the authenticated player, injected
+ * by the platform. Safe to use as a primary key for save slots, matchmaking,
+ * per-player analytics, or anywhere you need a reliable per-user key —
+ * unlike `getPlayerName()` (mutable, not unique).
+ *
+ * Mirrors the backend's `playerId` field returned by `GET /api/sdk/me`
+ * (= the Better Auth `user.id`). Returns `undefined` when the platform
+ * has not injected an identity (e.g. unauthenticated preview).
+ */
+declare function getPlayerId(): string | undefined;
 declare function getPlayerName(): string | undefined;
 declare function getPlayerAvatar(): string | undefined;
 
 declare function submitScore(score: number): void;
 
+/**
+ * Add (or subtract) `delta` from the player's current score for this game.
+ * The new score is clamped to >= 0 server-side.
+ *
+ * Unlike `submitScore()` (which is high-water and only ever raises the
+ * score), this endpoint always overwrites the row. Use it for game models
+ * where the leaderboard tracks an accumulator, balance, or persistent state
+ * instead of a single best-run value.
+ *
+ * Returns the resulting score values, or `null` when the bridge is
+ * unavailable. The integer must be a non-zero integer (positive or negative).
+ */
+declare function addScore(delta: number): Promise<ScoreEditResult | null>;
+/**
+ * Force the player's score to an absolute value (clamped to >= 0).
+ *
+ * Same overwrite semantics as `addScore`. Use when the game has computed
+ * the authoritative score locally (e.g. after offline play) and wants to
+ * sync it back to the leaderboard.
+ */
+declare function setScore(score: number): Promise<ScoreEditResult | null>;
+
 declare function share(options: ShareRequest): Promise<void>;
 
 declare function loadGameState(): GameState;
@@ -77,6 +211,9 @@ declare function leaveGame(): void;
 
 declare const oasiz: {
     submitScore: typeof submitScore;
+    addScore: typeof addScore;
+    setScore: typeof setScore;
+    getPlayerCharacter: typeof getPlayerCharacter;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -94,9 +231,10 @@ declare const oasiz: {
     leaveGame: typeof leaveGame;
     readonly gameId: string | undefined;
     readonly roomCode: string | undefined;
+    readonly playerId: string | undefined;
     readonly playerName: string | undefined;
     readonly playerAvatar: string | undefined;
     readonly safeAreaTop: number;
 };
 
-export { type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type ShareRequest, type ShareRoomCodeOptions, type Unsubscribe, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, share, shareRoomCode, submitScore, triggerHaptic };
+export { type FacingFrameMap, type GameState, type HapticType, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, addScore, enableLogOverlay, flushGameState, getGameId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, leaveGame, loadGameState, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };