@oasiz/sdk 1.8.3 → 1.8.5

package/README.md

@@ -138,30 +138,129 @@ Supported `device` presets:
 
 Use the Jibble animation constants when wiring a player character atlas so you can reference known animation IDs during local development instead of publishing first and reading logs.
 
+The atlas animation IDs are stable strings. Directional animations use the pattern
+`<action>_<direction>`, where the direction suffix is one of `n`, `ne`, `e`, `se`,
+`s`, `sw`, `w`, or `nw`.
+
+| Player-facing direction | Compass direction | Suffix |
+| --- | --- | --- |
+| `front`, `forward`, `forth` | South | `s` |
+| `front-right`, `forward-right` | SouthEast | `se` |
+| `right` | East | `e` |
+| `back-right`, `backward-right` | NorthEast | `ne` |
+| `back`, `backward` | North | `n` |
+| `back-left`, `backward-left` | NorthWest | `nw` |
+| `left` | West | `w` |
+| `front-left`, `forward-left` | SouthWest | `sw` |
+
+You can also pass compass names directly, such as `north`, `south`, `north-east`,
+or `southwest`.
+
+#### Animation catalog
+
+| Action | Constant | Animation IDs |
+| --- | --- | --- |
+| Idle | `JIBBLE_ANIMATION.Idle` | `idle_n`, `idle_ne`, `idle_e`, `idle_se`, `idle_s`, `idle_sw`, `idle_w`, `idle_nw` |
+| Walk | `JIBBLE_ANIMATION.Walk` | `walk_n`, `walk_ne`, `walk_e`, `walk_se`, `walk_s`, `walk_sw`, `walk_w`, `walk_nw` |
+| Backflip | `JIBBLE_ANIMATION.Backflip` | `backflip` |
+
+`backflip` is not directional, so `getJibbleAnimationId("backflip", "left")`
+still returns `backflip`.
+
+#### Local browser sample atlas
+
+Inside the Oasiz app, `oasiz.getPlayerCharacter()` returns the authenticated
+player's real character atlas. On `localhost` or `file://` without the app
+bridge, it returns a bundled sample Jibble atlas instead, so browser games can
+test sprite loading, atlas slicing, and animation lookup before publishing.
+
+The sample atlas includes every catalog ID above, and its `imageUrl` is an
+inline `data:image/svg+xml` URL. It does not make a network request and it is
+only used when the app bridge is missing.
+
+```ts
+const character = await oasiz.getPlayerCharacter();
+
+// In Oasiz app: the real signed-in player's character.
+// On localhost without the app bridge: "SDK Sample Jibble".
+// On non-local pages without the app bridge: null.
+```
+
+Use the options when you need explicit behavior:
+
 ```ts
-import { JIBBLE_ANIMATION, getJibbleAnimationId, oasiz } from "@oasiz/sdk";
+// Keep the old "missing bridge means null" behavior.
+const characterOrNull = await oasiz.getPlayerCharacter({ localFallback: false });
+
+// Force the sample atlas in a browser test harness.
+const sampleCharacter = await oasiz.getPlayerCharacter({ localFallback: true });
+
+// Or fetch the sample directly without checking the bridge.
+const directSample = oasiz.getSamplePlayerCharacter();
+```
+
+#### HTML5 / TypeScript
+
+```ts
+import {
+  JIBBLE_ANIMATION,
+  JIBBLE_ANIMATION_IDS,
+  getJibbleAnimationId,
+  oasiz,
+} from "@oasiz/sdk";
 
 const character = await oasiz.getPlayerCharacter();
 if (!character) return;
 
 const atlas = character.textureAtlas;
+
+// Print the full SDK catalog while debugging.
+console.table(JIBBLE_ANIMATION_IDS);
+
 const walkBack = getJibbleAnimationId("walk", "back"); // "walk_n"
 const walkBackAnimation = atlas.animations.find((anim) => anim.animationId === walkBack);
+
 const idleFrontAnimation = atlas.animations.find(
   (anim) => anim.animationId === JIBBLE_ANIMATION.Idle.South,
 );
+
+const backflipAnimation = atlas.animations.find(
+  (anim) => anim.animationId === JIBBLE_ANIMATION.Backflip,
+);
+
+const availableAnimations = new Set(atlas.animations.map((anim) => anim.animationId));
+const animationToPlay = availableAnimations.has(walkBack)
+  ? walkBack
+  : JIBBLE_ANIMATION.Idle.South;
 ```
 
-Supported directional IDs use compass codes: `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`. The helper accepts gameplay-facing aliases too: `front` -> `s`, `back` -> `n`, `left` -> `w`, `right` -> `e`.
+Not every custom atlas is guaranteed to contain every catalog ID. Check
+`atlas.animations` before playing an animation and choose a fallback, usually
+`idle_s` or the closest available direction.
 
-Unity exposes the same IDs:
+#### Unity
 
 ```csharp
-var walkBack = JibbleAnimations.GetId(
+using Oasiz;
+
+var walkBackId = JibbleAnimations.GetId(
+  JibbleAnimationAction.Walk,
+  JibbleDirection.Back); // "walk_n"
+
+var walkFrontRightId = JibbleAnimations.GetId(
   JibbleAnimationAction.Walk,
-  JibbleDirection.Back);
+  JibbleDirection.FrontRight); // "walk_se"
 
-var idleFront = JibbleAnimations.Idle.South;
+var idleFrontId = JibbleAnimations.GetId(
+  JibbleAnimationAction.Idle,
+  JibbleDirection.Front); // "idle_s"
+
+var backflipId = JibbleAnimations.Backflip; // "backflip"
+
+foreach (var animationId in JibbleAnimations.All)
+{
+  Debug.Log(animationId);
+}
 ```
 
 ### Score

package/dist/index.cjs

@@ -37,6 +37,8 @@ __export(index_exports, {
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   getSafeAreaTop: () => getSafeAreaTop,
+  getSamplePlayerCharacter: () => getSamplePlayerCharacter,
+  getSampleTextureAtlas: () => getSampleTextureAtlas,
   getViewportInsets: () => getViewportInsets,
   leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
@@ -1444,65 +1446,6 @@ function enableAppSimulator(options = {}) {
   return handle;
 }
 
-// src/character.ts
-function isDevelopment2() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow2() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function warnMissingBridge2(methodName) {
-  if (isDevelopment2()) {
-    console.warn(
-      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-async function getPlayerCharacter() {
-  const bridge = getBridgeWindow2();
-  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
-    warnMissingBridge2("getPlayerCharacter");
-    return null;
-  }
-  try {
-    const result = await bridge.__oasizGetPlayerCharacter();
-    return result ?? null;
-  } catch (error) {
-    if (isDevelopment2()) {
-      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
-    }
-    return null;
-  }
-}
-
-// src/haptics.ts
-function isDevelopment3() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow3() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function triggerHaptic(type) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.triggerHaptic === "function") {
-    bridge.triggerHaptic(type);
-    return;
-  }
-  if (isDevelopment3()) {
-    console.warn(
-      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-
 // src/jibble.ts
 var JIBBLE_DIRECTIONS = [
   "n",
@@ -1514,6 +1457,43 @@ var JIBBLE_DIRECTIONS = [
   "w",
   "nw"
 ];
+var JIBBLE_DIRECTION_ALIASES = {
+  n: "n",
+  ne: "ne",
+  e: "e",
+  se: "se",
+  s: "s",
+  sw: "sw",
+  w: "w",
+  nw: "nw",
+  north: "n",
+  "north-east": "ne",
+  northeast: "ne",
+  east: "e",
+  "south-east": "se",
+  southeast: "se",
+  south: "s",
+  "south-west": "sw",
+  southwest: "sw",
+  west: "w",
+  "north-west": "nw",
+  northwest: "nw",
+  front: "s",
+  forward: "s",
+  forth: "s",
+  back: "n",
+  backward: "n",
+  left: "w",
+  right: "e",
+  "front-right": "se",
+  "forward-right": "se",
+  "front-left": "sw",
+  "forward-left": "sw",
+  "back-right": "ne",
+  "backward-right": "ne",
+  "back-left": "nw",
+  "backward-left": "nw"
+};
 var JIBBLE_ANIMATION = {
   Idle: {
     North: "idle_n",
@@ -1556,20 +1536,6 @@ var JIBBLE_ANIMATION_IDS = [
   JIBBLE_ANIMATION.Walk.NorthWest,
   JIBBLE_ANIMATION.Backflip
 ];
-var JIBBLE_DIRECTION_ALIASES = {
-  n: "n",
-  ne: "ne",
-  e: "e",
-  se: "se",
-  s: "s",
-  sw: "sw",
-  w: "w",
-  nw: "nw",
-  front: "s",
-  back: "n",
-  left: "w",
-  right: "e"
-};
 function normalizeJibbleDirection(direction) {
   return JIBBLE_DIRECTION_ALIASES[direction];
 }
@@ -1580,6 +1546,223 @@ function getJibbleAnimationId(action, direction = "front") {
   return `${action}_${normalizeJibbleDirection(direction)}`;
 }
 
+// src/sample-character.ts
+var FRAME_SIZE = 32;
+var COLUMNS = 8;
+var WALK_FRAME_COUNT = 2;
+var BACKFLIP_FRAME_COUNT = 4;
+var COLORS = [
+  "#2563eb",
+  "#7c3aed",
+  "#db2777",
+  "#ea580c",
+  "#16a34a",
+  "#0891b2",
+  "#4f46e5",
+  "#be123c"
+];
+var IDLE_FRAME_NAMES = JIBBLE_DIRECTIONS.map((direction) => `idle_${direction}`);
+var WALK_FRAME_NAMES = JIBBLE_DIRECTIONS.flatMap(
+  (direction) => Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`)
+);
+var BACKFLIP_FRAME_NAMES = Array.from(
+  { length: BACKFLIP_FRAME_COUNT },
+  (_, index) => `backflip_${index}`
+);
+var SAMPLE_FRAME_NAMES = [
+  ...IDLE_FRAME_NAMES,
+  ...WALK_FRAME_NAMES,
+  ...BACKFLIP_FRAME_NAMES
+];
+var IMAGE_WIDTH = COLUMNS * FRAME_SIZE;
+var IMAGE_HEIGHT = Math.ceil(SAMPLE_FRAME_NAMES.length / COLUMNS) * FRAME_SIZE;
+function getFrameRect(index) {
+  return {
+    x: index % COLUMNS * FRAME_SIZE,
+    y: Math.floor(index / COLUMNS) * FRAME_SIZE,
+    width: FRAME_SIZE,
+    height: FRAME_SIZE
+  };
+}
+function createFrame(name, index) {
+  return {
+    name,
+    ...getFrameRect(index)
+  };
+}
+function getFrameLabel(name) {
+  return name.replace(/^idle_/, "i ").replace(/^walk_/, "w ").replace(/^backflip_/, "flip ");
+}
+function createSvgDataUrl() {
+  const cells = SAMPLE_FRAME_NAMES.map((name, index) => {
+    const { x, y } = getFrameRect(index);
+    const color = COLORS[index % COLORS.length];
+    const label = getFrameLabel(name);
+    return [
+      `<rect x="${x}" y="${y}" width="${FRAME_SIZE}" height="${FRAME_SIZE}" fill="${color}"/>`,
+      `<rect x="${x + 1}" y="${y + 1}" width="${FRAME_SIZE - 2}" height="${FRAME_SIZE - 2}" fill="none" stroke="#ffffff" stroke-opacity="0.35"/>`,
+      `<circle cx="${x + 16}" cy="${y + 11}" r="5" fill="#ffffff" fill-opacity="0.92"/>`,
+      `<rect x="${x + 12}" y="${y + 17}" width="8" height="7" rx="2" fill="#ffffff" fill-opacity="0.86"/>`,
+      `<text x="${x + 16}" y="${y + 30}" text-anchor="middle" font-family="monospace" font-size="5" fill="#ffffff">${label}</text>`
+    ].join("");
+  }).join("");
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" viewBox="0 0 ${IMAGE_WIDTH} ${IMAGE_HEIGHT}">`,
+    `<rect width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" fill="#111827"/>`,
+    cells,
+    "</svg>"
+  ].join("");
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+function createDirectionalAnimation(animationId, role, direction, frames, frameRate) {
+  return {
+    animationId,
+    role,
+    group: "jibble",
+    direction,
+    frameRate,
+    frames,
+    facingFrameMap: null
+  };
+}
+var SAMPLE_TEXTURE_ATLAS = {
+  imageUrl: createSvgDataUrl(),
+  imageWidth: IMAGE_WIDTH,
+  imageHeight: IMAGE_HEIGHT,
+  frames: SAMPLE_FRAME_NAMES.map(createFrame),
+  animations: [
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("idle", direction),
+        "idle",
+        direction,
+        [`idle_${direction}`],
+        1
+      )
+    ),
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("walk", direction),
+        "walk",
+        direction,
+        Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`),
+        8
+      )
+    ),
+    {
+      animationId: JIBBLE_ANIMATION.Backflip,
+      role: "action",
+      group: "jibble",
+      direction: null,
+      frameRate: 10,
+      frames: BACKFLIP_FRAME_NAMES,
+      facingFrameMap: null
+    }
+  ]
+};
+function cloneTextureAtlas(atlas) {
+  return {
+    ...atlas,
+    frames: atlas.frames.map((frame) => ({ ...frame })),
+    animations: atlas.animations.map((animation) => ({
+      ...animation,
+      frames: [...animation.frames],
+      facingFrameMap: animation.facingFrameMap ? { ...animation.facingFrameMap } : null
+    }))
+  };
+}
+function getSampleTextureAtlas() {
+  return cloneTextureAtlas(SAMPLE_TEXTURE_ATLAS);
+}
+function getSamplePlayerCharacter() {
+  return {
+    characterName: "SDK Sample Jibble",
+    baseCharacterId: "sdk-sample-jibble",
+    compositionCode: "sdk-sample-jibble-atlas-v1",
+    textureAtlas: getSampleTextureAtlas(),
+    editorTextureAtlas: getSampleTextureAtlas()
+  };
+}
+
+// src/character.ts
+function isDevelopment2() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow2() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function isLocalHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function shouldUseLocalFallback(bridge, localFallback) {
+  if (localFallback === true) {
+    return true;
+  }
+  if (localFallback === false) {
+    return false;
+  }
+  const location = bridge?.location;
+  if (!location) {
+    return false;
+  }
+  return location.protocol === "file:" || isLocalHostname(location.hostname);
+}
+function warnMissingBridge2(methodName, usingFallback) {
+  if (isDevelopment2()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. " + (usingFallback ? "Using the SDK sample character atlas for local development." : "This is expected in local development.")
+    );
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    return useLocalFallback ? getSamplePlayerCharacter() : null;
+  }
+  try {
+    const result = await bridge.__oasizGetPlayerCharacter();
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment2()) {
+      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
+    }
+    return null;
+  }
+}
+
+// src/haptics.ts
+function isDevelopment3() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow3() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function triggerHaptic(type) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.triggerHaptic === "function") {
+    bridge.triggerHaptic(type);
+    return;
+  }
+  if (isDevelopment3()) {
+    console.warn(
+      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+
 // src/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -3433,6 +3616,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3495,6 +3680,8 @@ var oasiz = {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   getViewportInsets,
   leaveGame,
   loadGameState,

package/dist/index.d.cts

@@ -220,13 +220,22 @@ interface ScoreEditResult {
     normalizedScore: number | null;
 }
 
+interface GetPlayerCharacterOptions {
+    /**
+     * Controls the SDK sample character returned when the Oasiz app bridge is
+     * missing. `"auto"` returns the sample on localhost/file URLs only.
+     */
+    localFallback?: boolean | "auto";
+}
 /**
  * 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)
+ *   - a sample character atlas when the host bridge is unavailable on a local
+ *     browser URL (`localhost` / `file://`), OR
+ *   - `null` when the host bridge is unavailable and local fallback is disabled
  *
  * The host transparently caches and proxies to `GET /api/sdk/me/character`,
  * so calling this multiple times in a session is cheap. The returned
@@ -245,13 +254,50 @@ interface ScoreEditResult {
  *     ),
  *   });
  */
-declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
+declare function getPlayerCharacter(options?: GetPlayerCharacterOptions): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
 declare const JIBBLE_DIRECTIONS: readonly ["n", "ne", "e", "se", "s", "sw", "w", "nw"];
 type JibbleDirectionCode = (typeof JIBBLE_DIRECTIONS)[number];
-type JibbleFacingDirection = JibbleDirectionCode | "front" | "back" | "left" | "right";
+declare const JIBBLE_DIRECTION_ALIASES: {
+    readonly n: "n";
+    readonly ne: "ne";
+    readonly e: "e";
+    readonly se: "se";
+    readonly s: "s";
+    readonly sw: "sw";
+    readonly w: "w";
+    readonly nw: "nw";
+    readonly north: "n";
+    readonly "north-east": "ne";
+    readonly northeast: "ne";
+    readonly east: "e";
+    readonly "south-east": "se";
+    readonly southeast: "se";
+    readonly south: "s";
+    readonly "south-west": "sw";
+    readonly southwest: "sw";
+    readonly west: "w";
+    readonly "north-west": "nw";
+    readonly northwest: "nw";
+    readonly front: "s";
+    readonly forward: "s";
+    readonly forth: "s";
+    readonly back: "n";
+    readonly backward: "n";
+    readonly left: "w";
+    readonly right: "e";
+    readonly "front-right": "se";
+    readonly "forward-right": "se";
+    readonly "front-left": "sw";
+    readonly "forward-left": "sw";
+    readonly "back-right": "ne";
+    readonly "backward-right": "ne";
+    readonly "back-left": "nw";
+    readonly "backward-left": "nw";
+};
+type JibbleFacingDirection = keyof typeof JIBBLE_DIRECTION_ALIASES;
 type JibbleAnimationAction = "idle" | "walk" | "backflip";
 declare const JIBBLE_ANIMATION: {
     readonly Idle: {
@@ -344,6 +390,9 @@ declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
 
+declare function getSampleTextureAtlas(): TextureAtlas;
+declare function getSamplePlayerCharacter(): PlayerCharacter;
+
 declare const oasiz: {
     submitScore: typeof submitScore;
     enableAppSimulator: typeof enableAppSimulator;
@@ -376,6 +425,8 @@ declare const oasiz: {
     addScore: typeof addScore;
     setScore: typeof setScore;
     getPlayerCharacter: typeof getPlayerCharacter;
+    getSamplePlayerCharacter: typeof getSamplePlayerCharacter;
+    getSampleTextureAtlas: typeof getSampleTextureAtlas;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -404,4 +455,4 @@ declare const oasiz: {
     readonly graphicsPerformance: GraphicsPerformanceMetric;
 };
 
-export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GetPlayerCharacterOptions, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getSamplePlayerCharacter, getSampleTextureAtlas, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -220,13 +220,22 @@ interface ScoreEditResult {
     normalizedScore: number | null;
 }
 
+interface GetPlayerCharacterOptions {
+    /**
+     * Controls the SDK sample character returned when the Oasiz app bridge is
+     * missing. `"auto"` returns the sample on localhost/file URLs only.
+     */
+    localFallback?: boolean | "auto";
+}
 /**
  * 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)
+ *   - a sample character atlas when the host bridge is unavailable on a local
+ *     browser URL (`localhost` / `file://`), OR
+ *   - `null` when the host bridge is unavailable and local fallback is disabled
  *
  * The host transparently caches and proxies to `GET /api/sdk/me/character`,
  * so calling this multiple times in a session is cheap. The returned
@@ -245,13 +254,50 @@ interface ScoreEditResult {
  *     ),
  *   });
  */
-declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
+declare function getPlayerCharacter(options?: GetPlayerCharacterOptions): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
 declare const JIBBLE_DIRECTIONS: readonly ["n", "ne", "e", "se", "s", "sw", "w", "nw"];
 type JibbleDirectionCode = (typeof JIBBLE_DIRECTIONS)[number];
-type JibbleFacingDirection = JibbleDirectionCode | "front" | "back" | "left" | "right";
+declare const JIBBLE_DIRECTION_ALIASES: {
+    readonly n: "n";
+    readonly ne: "ne";
+    readonly e: "e";
+    readonly se: "se";
+    readonly s: "s";
+    readonly sw: "sw";
+    readonly w: "w";
+    readonly nw: "nw";
+    readonly north: "n";
+    readonly "north-east": "ne";
+    readonly northeast: "ne";
+    readonly east: "e";
+    readonly "south-east": "se";
+    readonly southeast: "se";
+    readonly south: "s";
+    readonly "south-west": "sw";
+    readonly southwest: "sw";
+    readonly west: "w";
+    readonly "north-west": "nw";
+    readonly northwest: "nw";
+    readonly front: "s";
+    readonly forward: "s";
+    readonly forth: "s";
+    readonly back: "n";
+    readonly backward: "n";
+    readonly left: "w";
+    readonly right: "e";
+    readonly "front-right": "se";
+    readonly "forward-right": "se";
+    readonly "front-left": "sw";
+    readonly "forward-left": "sw";
+    readonly "back-right": "ne";
+    readonly "backward-right": "ne";
+    readonly "back-left": "nw";
+    readonly "backward-left": "nw";
+};
+type JibbleFacingDirection = keyof typeof JIBBLE_DIRECTION_ALIASES;
 type JibbleAnimationAction = "idle" | "walk" | "backflip";
 declare const JIBBLE_ANIMATION: {
     readonly Idle: {
@@ -344,6 +390,9 @@ declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
 
+declare function getSampleTextureAtlas(): TextureAtlas;
+declare function getSamplePlayerCharacter(): PlayerCharacter;
+
 declare const oasiz: {
     submitScore: typeof submitScore;
     enableAppSimulator: typeof enableAppSimulator;
@@ -376,6 +425,8 @@ declare const oasiz: {
     addScore: typeof addScore;
     setScore: typeof setScore;
     getPlayerCharacter: typeof getPlayerCharacter;
+    getSamplePlayerCharacter: typeof getSamplePlayerCharacter;
+    getSampleTextureAtlas: typeof getSampleTextureAtlas;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -404,4 +455,4 @@ declare const oasiz: {
     readonly graphicsPerformance: GraphicsPerformanceMetric;
 };
 
-export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GetPlayerCharacterOptions, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getSamplePlayerCharacter, getSampleTextureAtlas, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.js

@@ -1385,65 +1385,6 @@ function enableAppSimulator(options = {}) {
   return handle;
 }
 
-// src/character.ts
-function isDevelopment2() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow2() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function warnMissingBridge2(methodName) {
-  if (isDevelopment2()) {
-    console.warn(
-      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-async function getPlayerCharacter() {
-  const bridge = getBridgeWindow2();
-  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
-    warnMissingBridge2("getPlayerCharacter");
-    return null;
-  }
-  try {
-    const result = await bridge.__oasizGetPlayerCharacter();
-    return result ?? null;
-  } catch (error) {
-    if (isDevelopment2()) {
-      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
-    }
-    return null;
-  }
-}
-
-// src/haptics.ts
-function isDevelopment3() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow3() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function triggerHaptic(type) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.triggerHaptic === "function") {
-    bridge.triggerHaptic(type);
-    return;
-  }
-  if (isDevelopment3()) {
-    console.warn(
-      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-
 // src/jibble.ts
 var JIBBLE_DIRECTIONS = [
   "n",
@@ -1455,6 +1396,43 @@ var JIBBLE_DIRECTIONS = [
   "w",
   "nw"
 ];
+var JIBBLE_DIRECTION_ALIASES = {
+  n: "n",
+  ne: "ne",
+  e: "e",
+  se: "se",
+  s: "s",
+  sw: "sw",
+  w: "w",
+  nw: "nw",
+  north: "n",
+  "north-east": "ne",
+  northeast: "ne",
+  east: "e",
+  "south-east": "se",
+  southeast: "se",
+  south: "s",
+  "south-west": "sw",
+  southwest: "sw",
+  west: "w",
+  "north-west": "nw",
+  northwest: "nw",
+  front: "s",
+  forward: "s",
+  forth: "s",
+  back: "n",
+  backward: "n",
+  left: "w",
+  right: "e",
+  "front-right": "se",
+  "forward-right": "se",
+  "front-left": "sw",
+  "forward-left": "sw",
+  "back-right": "ne",
+  "backward-right": "ne",
+  "back-left": "nw",
+  "backward-left": "nw"
+};
 var JIBBLE_ANIMATION = {
   Idle: {
     North: "idle_n",
@@ -1497,20 +1475,6 @@ var JIBBLE_ANIMATION_IDS = [
   JIBBLE_ANIMATION.Walk.NorthWest,
   JIBBLE_ANIMATION.Backflip
 ];
-var JIBBLE_DIRECTION_ALIASES = {
-  n: "n",
-  ne: "ne",
-  e: "e",
-  se: "se",
-  s: "s",
-  sw: "sw",
-  w: "w",
-  nw: "nw",
-  front: "s",
-  back: "n",
-  left: "w",
-  right: "e"
-};
 function normalizeJibbleDirection(direction) {
   return JIBBLE_DIRECTION_ALIASES[direction];
 }
@@ -1521,6 +1485,223 @@ function getJibbleAnimationId(action, direction = "front") {
   return `${action}_${normalizeJibbleDirection(direction)}`;
 }
 
+// src/sample-character.ts
+var FRAME_SIZE = 32;
+var COLUMNS = 8;
+var WALK_FRAME_COUNT = 2;
+var BACKFLIP_FRAME_COUNT = 4;
+var COLORS = [
+  "#2563eb",
+  "#7c3aed",
+  "#db2777",
+  "#ea580c",
+  "#16a34a",
+  "#0891b2",
+  "#4f46e5",
+  "#be123c"
+];
+var IDLE_FRAME_NAMES = JIBBLE_DIRECTIONS.map((direction) => `idle_${direction}`);
+var WALK_FRAME_NAMES = JIBBLE_DIRECTIONS.flatMap(
+  (direction) => Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`)
+);
+var BACKFLIP_FRAME_NAMES = Array.from(
+  { length: BACKFLIP_FRAME_COUNT },
+  (_, index) => `backflip_${index}`
+);
+var SAMPLE_FRAME_NAMES = [
+  ...IDLE_FRAME_NAMES,
+  ...WALK_FRAME_NAMES,
+  ...BACKFLIP_FRAME_NAMES
+];
+var IMAGE_WIDTH = COLUMNS * FRAME_SIZE;
+var IMAGE_HEIGHT = Math.ceil(SAMPLE_FRAME_NAMES.length / COLUMNS) * FRAME_SIZE;
+function getFrameRect(index) {
+  return {
+    x: index % COLUMNS * FRAME_SIZE,
+    y: Math.floor(index / COLUMNS) * FRAME_SIZE,
+    width: FRAME_SIZE,
+    height: FRAME_SIZE
+  };
+}
+function createFrame(name, index) {
+  return {
+    name,
+    ...getFrameRect(index)
+  };
+}
+function getFrameLabel(name) {
+  return name.replace(/^idle_/, "i ").replace(/^walk_/, "w ").replace(/^backflip_/, "flip ");
+}
+function createSvgDataUrl() {
+  const cells = SAMPLE_FRAME_NAMES.map((name, index) => {
+    const { x, y } = getFrameRect(index);
+    const color = COLORS[index % COLORS.length];
+    const label = getFrameLabel(name);
+    return [
+      `<rect x="${x}" y="${y}" width="${FRAME_SIZE}" height="${FRAME_SIZE}" fill="${color}"/>`,
+      `<rect x="${x + 1}" y="${y + 1}" width="${FRAME_SIZE - 2}" height="${FRAME_SIZE - 2}" fill="none" stroke="#ffffff" stroke-opacity="0.35"/>`,
+      `<circle cx="${x + 16}" cy="${y + 11}" r="5" fill="#ffffff" fill-opacity="0.92"/>`,
+      `<rect x="${x + 12}" y="${y + 17}" width="8" height="7" rx="2" fill="#ffffff" fill-opacity="0.86"/>`,
+      `<text x="${x + 16}" y="${y + 30}" text-anchor="middle" font-family="monospace" font-size="5" fill="#ffffff">${label}</text>`
+    ].join("");
+  }).join("");
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" viewBox="0 0 ${IMAGE_WIDTH} ${IMAGE_HEIGHT}">`,
+    `<rect width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" fill="#111827"/>`,
+    cells,
+    "</svg>"
+  ].join("");
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+function createDirectionalAnimation(animationId, role, direction, frames, frameRate) {
+  return {
+    animationId,
+    role,
+    group: "jibble",
+    direction,
+    frameRate,
+    frames,
+    facingFrameMap: null
+  };
+}
+var SAMPLE_TEXTURE_ATLAS = {
+  imageUrl: createSvgDataUrl(),
+  imageWidth: IMAGE_WIDTH,
+  imageHeight: IMAGE_HEIGHT,
+  frames: SAMPLE_FRAME_NAMES.map(createFrame),
+  animations: [
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("idle", direction),
+        "idle",
+        direction,
+        [`idle_${direction}`],
+        1
+      )
+    ),
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("walk", direction),
+        "walk",
+        direction,
+        Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`),
+        8
+      )
+    ),
+    {
+      animationId: JIBBLE_ANIMATION.Backflip,
+      role: "action",
+      group: "jibble",
+      direction: null,
+      frameRate: 10,
+      frames: BACKFLIP_FRAME_NAMES,
+      facingFrameMap: null
+    }
+  ]
+};
+function cloneTextureAtlas(atlas) {
+  return {
+    ...atlas,
+    frames: atlas.frames.map((frame) => ({ ...frame })),
+    animations: atlas.animations.map((animation) => ({
+      ...animation,
+      frames: [...animation.frames],
+      facingFrameMap: animation.facingFrameMap ? { ...animation.facingFrameMap } : null
+    }))
+  };
+}
+function getSampleTextureAtlas() {
+  return cloneTextureAtlas(SAMPLE_TEXTURE_ATLAS);
+}
+function getSamplePlayerCharacter() {
+  return {
+    characterName: "SDK Sample Jibble",
+    baseCharacterId: "sdk-sample-jibble",
+    compositionCode: "sdk-sample-jibble-atlas-v1",
+    textureAtlas: getSampleTextureAtlas(),
+    editorTextureAtlas: getSampleTextureAtlas()
+  };
+}
+
+// src/character.ts
+function isDevelopment2() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow2() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function isLocalHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function shouldUseLocalFallback(bridge, localFallback) {
+  if (localFallback === true) {
+    return true;
+  }
+  if (localFallback === false) {
+    return false;
+  }
+  const location = bridge?.location;
+  if (!location) {
+    return false;
+  }
+  return location.protocol === "file:" || isLocalHostname(location.hostname);
+}
+function warnMissingBridge2(methodName, usingFallback) {
+  if (isDevelopment2()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. " + (usingFallback ? "Using the SDK sample character atlas for local development." : "This is expected in local development.")
+    );
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    return useLocalFallback ? getSamplePlayerCharacter() : null;
+  }
+  try {
+    const result = await bridge.__oasizGetPlayerCharacter();
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment2()) {
+      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
+    }
+    return null;
+  }
+}
+
+// src/haptics.ts
+function isDevelopment3() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow3() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function triggerHaptic(type) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.triggerHaptic === "function") {
+    bridge.triggerHaptic(type);
+    return;
+  }
+  if (isDevelopment3()) {
+    console.warn(
+      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+
 // src/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -3374,6 +3555,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3435,6 +3618,8 @@ export {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   getViewportInsets,
   leaveGame,
   loadGameState,

package/package.json

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