@oasiz/sdk 1.8.3 → 1.8.4

package/README.md

@@ -138,30 +138,97 @@ 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`.
+
+#### HTML5 / TypeScript
+
 ```ts
-import { JIBBLE_ANIMATION, getJibbleAnimationId, oasiz } from "@oasiz/sdk";
+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);
+  JibbleDirection.Back); // "walk_n"
 
-var idleFront = JibbleAnimations.Idle.South;
+var walkFrontRightId = JibbleAnimations.GetId(
+  JibbleAnimationAction.Walk,
+  JibbleDirection.FrontRight); // "walk_se"
+
+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

@@ -1514,6 +1514,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 +1593,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];
 }

package/dist/index.d.cts

@@ -251,7 +251,44 @@ 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: {

package/dist/index.d.ts

@@ -251,7 +251,44 @@ 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: {

package/dist/index.js

@@ -1455,6 +1455,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 +1534,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];
 }

package/package.json

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