@remix-gg/sdk 0.8.0 → 0.8.1

package/dist/index.d.mts

@@ -42,15 +42,31 @@ type GameInfo = {
         id: string;
         gameState: GameState;
     } | null;
+    /**
+     * Present only when the host has level progression enabled for this session.
+     * Games must key level mode off this block's presence, not their own level
+     * content — the platform can disable it (e.g. feature gating) at any time.
+     */
     levelBased?: {
+        /** Canonical level total configured on the platform at upload. */
         levelCount: number;
-        /**
-         * Score-derived level progression for this player. Platform-owned and kept
-         * fully separate from `gameState` — never read progression out of gameState.
-         */
+        /** Score-derived, platform-owned progression — never read from gameState. */
         progress: LevelProgressState;
     };
 };
+type LevelStars = 1 | 2 | 3;
+/** Stars for one level attempt: 0 = failed, 1–3 = completed with that rating. */
+type LevelAttemptStars = 0 | LevelStars;
+/**
+ * One level attempt reported with game_over. Games report only what happened
+ * in the attempt; the host owns and derives all cumulative progression.
+ */
+type LevelAttempt = {
+    /** 1-based index of the level that was just played. */
+    levelIndex: number;
+    /** Stars earned this attempt; 0 means the level was failed. */
+    stars: LevelAttemptStars;
+};
 /** Score-derived, platform-owned progression for a level-based game. */
 type LevelProgressState = {
     currentLevelIndex: number;
@@ -59,9 +75,7 @@ type LevelProgressState = {
 };
 type ReadyEvent = {
     type: 'ready';
-    data: {
-        instanceId: string;
-    } | undefined;
+    data: undefined;
 };
 type PlayAgainEvent = {
     type: 'play_again';
@@ -69,20 +83,6 @@ type PlayAgainEvent = {
         levelIndex?: number;
     };
 };
-type LevelStars = 1 | 2 | 3;
-type LevelOutcome = 'level_complete' | 'level_failed' | 'all_complete';
-/**
- * One level attempt reported with game_over. Games report only what happened
- * in the attempt; the host owns and derives all cumulative progression
- * (star maps, unlock state) — see `LevelProgressState` for the host→game snapshot.
- */
-type LevelAttempt = {
-    /** 1-based index of the level that was just played. */
-    levelIndex: number;
-    /** Stars earned this attempt. Omit for star-less games; a completion counts as 1. */
-    stars?: LevelStars;
-    outcome: LevelOutcome;
-};
 type SinglePlayerGameOverEvent = {
     type: 'game_over';
     data: {
@@ -120,7 +120,6 @@ type GameErrorEvent = {
         lineno?: number;
         colno?: number;
         error?: Error;
-        stack?: string;
     };
 };
 type GameInfoEvent = {
@@ -173,56 +172,41 @@ type GameEventMessage<T extends GameEvent['type']> = {
         type: T;
     }>;
 };
-/**
- * Build a game_event envelope for sending over postMessage. Hosts and the SDK
- * share this so the wire format is defined in one place.
- */
-declare const createGameEventMessage: <T extends GameEvent["type"]>(type: T, data: Extract<GameEvent, {
-    type: T;
-}>["data"]) => GameEventMessage<T>;
-/**
- * Parse an unknown postMessage payload into a GameEvent, or null when the
- * payload is not a well-formed game_event envelope.
- */
-declare const parseGameEventMessage: (value: unknown) => GameEvent | null;
 /**
  * Messages from the game host to the game client
  */
 type IncomingGameEvent = GameEventMessage<'play_again' | 'toggle_mute' | 'game_info' | 'game_state_updated' | 'purchase_complete'>;
 type OutgoingGameEvent = GameEventMessage<'game_over' | 'ready' | 'haptic_feedback' | 'error' | 'save_game_state' | 'refute_game_state' | 'multiplayer_game_over' | 'multiplayer_save_game_state' | 'purchase'>;
-type IncomingGameEventType = IncomingGameEvent['event']['type'];
-type IncomingGameEventData<T extends IncomingGameEventType> = Extract<GameEvent, {
-    type: T;
-}>['data'];
+type EventCallback = (data: unknown) => void;
 declare class RemixSDK {
+    /**
+     * The published version of this bundle. The host compares it against the
+     * version it asked the browser to load, so a cached bundle from a previous
+     * release can be detected before any game code runs.
+     */
+    readonly version: string;
     private isClient;
     private target;
     private eventListeners;
-    private readyPromise;
     private readyPromiseResolve;
-    private purchasePromiseResolvers;
-    private readyResendTimer;
-    private readonly instanceId;
+    private purchasePromiseResolve;
     private _gameInfo?;
     private _gameState?;
-    private _levelStars;
     constructor();
-    private scheduleReadyResend;
-    private cancelReadyResend;
-    on<T extends IncomingGameEventType>(eventType: T, callback: (data: IncomingGameEventData<T>) => void): () => void;
-    off<T extends IncomingGameEventType>(eventType: T, callback: (data: IncomingGameEventData<T>) => void): void;
+    on(eventType: IncomingGameEvent['event']['type'], callback: EventCallback): void;
+    off(eventType: IncomingGameEvent['event']['type'], callback: EventCallback): void;
     /**
      * Listen for the host starting play: a replay after game over, or — for level
-     * games — a host-directed level via `data.levelIndex` (Studio continue/jump or
-     * the production next-level button). `data` may be omitted for a plain restart.
+     * games — a host-directed level via `data.levelIndex`. `data` may be omitted
+     * for a plain restart.
      */
-    onPlay(callback: (data?: PlayAgainEvent['data']) => void): () => void;
-    /** @deprecated Use {@link onPlay}. Retained for backward compatibility. */
-    onPlayAgain(callback: (data?: PlayAgainEvent['data']) => void): () => void;
-    onToggleMute(callback: (data: ToggleMuteEvent['data']) => void): () => void;
-    onGameStateUpdated(callback: (data: GameStateUpdatedEvent['data']) => void): () => void;
-    onGameInfo(callback: (data: GameInfoEvent['data']) => void): () => void;
-    onPurchaseComplete(callback: (data: PurchaseCompleteEvent['data']) => void): () => void;
+    onPlay(callback: (data?: PlayAgainEvent['data']) => void): void;
+    /** Alias of {@link onPlay}. */
+    onPlayAgain(callback: (data?: PlayAgainEvent['data']) => void): void;
+    onToggleMute(callback: (data: ToggleMuteEvent['data']) => void): void;
+    onGameStateUpdated(callback: (data: GameStateUpdatedEvent['data']) => void): void;
+    onGameInfo(callback: (data: GameInfoEvent['data']) => void): void;
+    onPurchaseComplete(callback: (data: PurchaseCompleteEvent['data']) => void): void;
     setTarget(target: Window): void;
     get purchasedItems(): string[];
     get inventory(): InventoryItem[];
@@ -238,7 +222,7 @@ declare class RemixSDK {
     get levelCount(): number | undefined;
     /** 1-based level index from score-derived progression, defaulting to 1. */
     get currentLevelIndex(): number;
-    /** Best stars earned per level from score-derived progression. Keys are 1-based level indices. */
+    /** Best stars per level from score-derived progression. Keys are 1-based level indices. */
     get levelStars(): Record<string, LevelStars>;
     /** Highest unlocked level from score-derived progression, defaulting to 1. */
     get highestUnlockedLevel(): number;
@@ -281,4 +265,4 @@ declare class RemixSDK {
 }
 declare const sdk: RemixSDK;
 
-export { type GameErrorEvent, type GameEvent, type GameEventMessage, type GameInfo, type GameInfoEvent, type GameState, type GameStateUpdatedEvent, type HapticFeedbackEvent, type HapticFeedbackType, type IncomingGameEvent, type IncomingGameEventData, type IncomingGameEventType, type InventoryItem, type LevelAttempt, type LevelOutcome, type LevelProgressState, type LevelStars, type MultiplayerGameOverEvent, type MultiplayerSaveGameStateEvent, type OutgoingGameEvent, type PlayAgainEvent, type Player, type PurchaseCompleteEvent, type PurchaseEvent, type ReadyEvent, type RefuteGameStateEvent, RemixSDK, type SafeAreaInset, type SaveGameStateEvent, type ShopItem, type SinglePlayerGameOverEvent, type ToggleMuteEvent, type ViewContext, ZERO_SAFE_AREA_INSET, createGameEventMessage, parseGameEventMessage, sdk };
+export { type GameErrorEvent, type GameEvent, type GameEventMessage, type GameInfo, type GameInfoEvent, type GameState, type GameStateUpdatedEvent, type HapticFeedbackEvent, type HapticFeedbackType, type IncomingGameEvent, type InventoryItem, type LevelAttempt, type LevelAttemptStars, type LevelProgressState, type LevelStars, type MultiplayerGameOverEvent, type MultiplayerSaveGameStateEvent, type OutgoingGameEvent, type PlayAgainEvent, type Player, type PurchaseCompleteEvent, type PurchaseEvent, type ReadyEvent, type RefuteGameStateEvent, RemixSDK, type SafeAreaInset, type SaveGameStateEvent, type ShopItem, type SinglePlayerGameOverEvent, type ToggleMuteEvent, type ViewContext, ZERO_SAFE_AREA_INSET, sdk };

package/dist/index.d.ts

@@ -42,6 +42,36 @@ type GameInfo = {
         id: string;
         gameState: GameState;
     } | null;
+    /**
+     * Present only when the host has level progression enabled for this session.
+     * Games must key level mode off this block's presence, not their own level
+     * content — the platform can disable it (e.g. feature gating) at any time.
+     */
+    levelBased?: {
+        /** Canonical level total configured on the platform at upload. */
+        levelCount: number;
+        /** Score-derived, platform-owned progression — never read from gameState. */
+        progress: LevelProgressState;
+    };
+};
+type LevelStars = 1 | 2 | 3;
+/** Stars for one level attempt: 0 = failed, 1–3 = completed with that rating. */
+type LevelAttemptStars = 0 | LevelStars;
+/**
+ * One level attempt reported with game_over. Games report only what happened
+ * in the attempt; the host owns and derives all cumulative progression.
+ */
+type LevelAttempt = {
+    /** 1-based index of the level that was just played. */
+    levelIndex: number;
+    /** Stars earned this attempt; 0 means the level was failed. */
+    stars: LevelAttemptStars;
+};
+/** Score-derived, platform-owned progression for a level-based game. */
+type LevelProgressState = {
+    currentLevelIndex: number;
+    highestUnlockedLevel: number;
+    levelStars: Record<string, LevelStars>;
 };
 type ReadyEvent = {
     type: 'ready';
@@ -49,12 +79,15 @@ type ReadyEvent = {
 };
 type PlayAgainEvent = {
     type: 'play_again';
-    data: undefined;
+    data?: {
+        levelIndex?: number;
+    };
 };
 type SinglePlayerGameOverEvent = {
     type: 'game_over';
     data: {
         score: number;
+        levelAttempt?: LevelAttempt;
     };
 };
 type MultiplayerGameOverEvent = {
@@ -146,6 +179,12 @@ type IncomingGameEvent = GameEventMessage<'play_again' | 'toggle_mute' | 'game_i
 type OutgoingGameEvent = GameEventMessage<'game_over' | 'ready' | 'haptic_feedback' | 'error' | 'save_game_state' | 'refute_game_state' | 'multiplayer_game_over' | 'multiplayer_save_game_state' | 'purchase'>;
 type EventCallback = (data: unknown) => void;
 declare class RemixSDK {
+    /**
+     * The published version of this bundle. The host compares it against the
+     * version it asked the browser to load, so a cached bundle from a previous
+     * release can be detected before any game code runs.
+     */
+    readonly version: string;
     private isClient;
     private target;
     private eventListeners;
@@ -156,7 +195,14 @@ declare class RemixSDK {
     constructor();
     on(eventType: IncomingGameEvent['event']['type'], callback: EventCallback): void;
     off(eventType: IncomingGameEvent['event']['type'], callback: EventCallback): void;
-    onPlayAgain(callback: () => void): void;
+    /**
+     * Listen for the host starting play: a replay after game over, or — for level
+     * games — a host-directed level via `data.levelIndex`. `data` may be omitted
+     * for a plain restart.
+     */
+    onPlay(callback: (data?: PlayAgainEvent['data']) => void): void;
+    /** Alias of {@link onPlay}. */
+    onPlayAgain(callback: (data?: PlayAgainEvent['data']) => void): void;
     onToggleMute(callback: (data: ToggleMuteEvent['data']) => void): void;
     onGameStateUpdated(callback: (data: GameStateUpdatedEvent['data']) => void): void;
     onGameInfo(callback: (data: GameInfoEvent['data']) => void): void;
@@ -170,6 +216,18 @@ declare class RemixSDK {
     get players(): Player[] | undefined;
     get player(): Player | undefined;
     get isReady(): boolean;
+    /** True when the host configured this game with a fixed level count. */
+    get isLevelBased(): boolean;
+    /** Total levels for level-based games (from host metadata). */
+    get levelCount(): number | undefined;
+    /** 1-based level index from score-derived progression, defaulting to 1. */
+    get currentLevelIndex(): number;
+    /** Best stars per level from score-derived progression. Keys are 1-based level indices. */
+    get levelStars(): Record<string, LevelStars>;
+    /** Highest unlocked level from score-derived progression, defaulting to 1. */
+    get highestUnlockedLevel(): number;
+    /** Sum of best stars across all completed levels. */
+    get totalStars(): number;
     ready: () => Promise<GameInfo>;
     purchase: (data: PurchaseEvent["data"]) => Promise<PurchaseCompleteEvent["data"]>;
     reportError: (data: GameErrorEvent["data"]) => void;
@@ -207,4 +265,4 @@ declare class RemixSDK {
 }
 declare const sdk: RemixSDK;
 
-export { type GameErrorEvent, type GameEvent, type GameEventMessage, type GameInfo, type GameInfoEvent, type GameState, type GameStateUpdatedEvent, type HapticFeedbackEvent, type HapticFeedbackType, type IncomingGameEvent, type InventoryItem, type MultiplayerGameOverEvent, type MultiplayerSaveGameStateEvent, type OutgoingGameEvent, type PlayAgainEvent, type Player, type PurchaseCompleteEvent, type PurchaseEvent, type ReadyEvent, type RefuteGameStateEvent, RemixSDK, type SafeAreaInset, type SaveGameStateEvent, type ShopItem, type SinglePlayerGameOverEvent, type ToggleMuteEvent, type ViewContext, ZERO_SAFE_AREA_INSET, sdk };
+export { type GameErrorEvent, type GameEvent, type GameEventMessage, type GameInfo, type GameInfoEvent, type GameState, type GameStateUpdatedEvent, type HapticFeedbackEvent, type HapticFeedbackType, type IncomingGameEvent, type InventoryItem, type LevelAttempt, type LevelAttemptStars, type LevelProgressState, type LevelStars, type MultiplayerGameOverEvent, type MultiplayerSaveGameStateEvent, type OutgoingGameEvent, type PlayAgainEvent, type Player, type PurchaseCompleteEvent, type PurchaseEvent, type ReadyEvent, type RefuteGameStateEvent, RemixSDK, type SafeAreaInset, type SaveGameStateEvent, type ShopItem, type SinglePlayerGameOverEvent, type ToggleMuteEvent, type ViewContext, ZERO_SAFE_AREA_INSET, sdk };