cute-cube 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,264 @@
+import { C as CharacterPlayerOptions, a as CharacterPose, L as LegacyCharacterManifest, b as LayeredCharacterManifest, A as AnimationStateConfig, c as CharacterManifest } from './types-D7Q7Ycer.js';
+export { d as AnimationStateFramesConfig, e as AnimationStateGridSheetConfig, G as GridSheetConfig, f as GridSheetOrder, i as isGridSheetAnimation, g as isLayeredManifest } from './types-D7Q7Ycer.js';
+
+declare class CharacterPlayer {
+    readonly container: HTMLElement;
+    private readonly manifest;
+    private readonly flatStates;
+    private readonly layered;
+    private readonly transitionMap;
+    private readonly baseUrl;
+    private readonly transitionMs;
+    private readonly fitPadding;
+    private characterWidth;
+    private characterHeight;
+    private readonly queueStateUntilCycleEnd;
+    private readonly debug;
+    private app;
+    private root;
+    private resizeObserver;
+    private currentSprite;
+    /** Current clip key: legacy `idle` / `talk`, layered `neutral/idle`, or internal `__tr__/a/b`. */
+    private currentFlatKey;
+    /** Logical pose when `layered`; unchanged while a transition clip plays. */
+    private currentPose;
+    private transitioning;
+    private fromSprite;
+    private toSprite;
+    private transitionProgress;
+    private transitionTargetFlatKey;
+    private pendingFlatKey;
+    private transitionUpdateBound;
+    private deferredTargetFlatKey;
+    private waitingForCycleEnd;
+    /** After a one-shot transition clip mounts, crossfade into this pose key. */
+    private pendingAfterTransitionClip;
+    private textureWidth;
+    private textureHeight;
+    /** Invalidates in-flight `playOneShotAction` completion handlers after a new one-shot or `destroy()`. */
+    private oneShotCompletionToken;
+    private destroyed;
+    constructor(options: CharacterPlayerOptions);
+    /** Create Pixi app, load first clip, append canvas. Call once. */
+    init(): Promise<void>;
+    /**
+     * Current clip key. Layered manifests use `characterState/action` (e.g. `neutral/idle`);
+     * during a character-state transition the internal `__tr__/from/to` key may be returned.
+     */
+    getState(): string | null;
+    /** Logical pose for layered manifests; `null` for legacy flat manifests. */
+    getPose(): CharacterPose | null;
+    /**
+     * Set explicit character size in CSS pixels (see `CharacterPlayerOptions.characterWidth` /
+     * `characterHeight`). Pass no arguments or `undefined` for both dimensions to restore
+     * scaling that fits the container (still multiplied by `fitPadding`).
+     */
+    setCharacterSize(width?: number, height?: number): void;
+    /** Switch pose (layered manifests only). */
+    setPose(pose: CharacterPose): Promise<void>;
+    /** Switch animation clip; crossfades when `transitionMs` > 0. */
+    setState(name: string): Promise<void>;
+    /**
+     * Play a one-shot action clip immediately: aborts crossfades, cycle queues, and transition clips,
+     * then returns to `{ characterState, action: "idle" }` when the clip ends. Layered manifests only;
+     * requires a matching clip and playback context for that character state (including a
+     * `from`→… transition clip when `from` matches).
+     */
+    playOneShotAction(pose: CharacterPose): Promise<void>;
+    /**
+     * Play the neutral `click` clip (see {@link playOneShotAction}).
+     */
+    playNeutralClick(): Promise<void>;
+    private resolveSetStateName;
+    /** True when the current clip is for `characterState` or a transition clip leaving that state. */
+    private isCharacterStatePlaybackContext;
+    /**
+     * Stops and tears down active playback so a one-shot (e.g. click) can start immediately.
+     * Clears crossfade ticker, transition sprites, cycle/queue state, and the current sprite.
+     */
+    private abortImmediatePlayback;
+    private validatePose;
+    private logDebug;
+    private logWarn;
+    /** True while a one-shot character-state transition clip is playing (after crossfade onto it). */
+    private isPlayingTransitionClip;
+    private applySetFlatKey;
+    private syncPoseFromFlatKey;
+    private applyTransitionNow;
+    private applyCharacterStateChange;
+    private clearCycleWait;
+    private attachCycleEndListener;
+    private finishDeferredAndTransition;
+    /** Returns true if we scheduled waiting for a transition clip to finish (skip processing crossfade queue). */
+    private maybeAttachTransitionClipCompletion;
+    private attachTransitionClipCompletion;
+    private finishCharacterTransitionChain;
+    private swapInstant;
+    private beginCrossfade;
+    private onTransitionTick;
+    private finishCrossfade;
+    private mountState;
+    private attachSprite;
+    private createSpriteForState;
+    private layout;
+    destroy(): void;
+}
+
+/** Separator for flat keys: `characterState/action` (e.g. `neutral/idle`). */
+declare const POSE_KEY_SEPARATOR = "/";
+/** `frame_001.png` … `frame_181.png` */
+declare function idleFrameNames(count?: number): string[];
+/** `idle/frame_001.png` … when `subdir` is `idle`; use with `baseUrl` at the assets root. */
+declare function framePaths(subdir: string, count: number): string[];
+declare function poseToKey(pose: CharacterPose): string;
+/** Parse `neutral/idle` into a pose; returns null if not a layered key. */
+declare function keyToPose(key: string): CharacterPose | null;
+/** Internal flat key for a one-shot character-state transition clip. */
+declare function transitionFlatKey(fromCharacterState: string, toCharacterState: string): string;
+declare function isTransitionFlatKey(key: string): boolean;
+/**
+ * Merge layered character actions and transition clips into one flat `states` map for the player.
+ */
+declare function flattenLayeredManifest(manifest: LayeredCharacterManifest): Record<string, AnimationStateConfig>;
+/** Resolve default pose for a layered manifest (deterministic: first entry keys). */
+declare function defaultPoseForLayered(manifest: LayeredCharacterManifest): CharacterPose;
+/** Build a single flat `states` map for CharacterPlayer from any manifest shape. */
+declare function manifestToFlatStates(manifest: CharacterManifest): Record<string, AnimationStateConfig>;
+/** Default manifest: `idle` and `talk` under distinct asset folders (legacy flat). */
+declare function createDefaultManifest(): LegacyCharacterManifest;
+/** Frame counts for packaged sad demo assets under `assets/sheets/` (must match PNG layout). */
+declare const SAD_DEMO_FRAMES: {
+    /**
+     * `neutral_to_sad.png` is 5120×3830 → 10×10 cells @ 512×383; only **91** frames are drawn
+     * (9 full rows + 1 cell in row 10). The last 9 cells in the bottom row are empty—do not play them.
+     */
+    readonly transitionNeutralToSad: 91;
+    /** `sad_to_neutral.png` is 4608×3064 → 9×8 cells @ 512×383 (66 frames; last row partial). */
+    readonly transitionSadToNeutral: 66;
+    readonly sadIdle: 149;
+    readonly sadTalk: 126;
+    /** `neutral_click_512.png` is 3072×2298 → 6×6 cells @ 512×383 (36 frames). */
+    readonly neutralClick: 36;
+    /**
+     * `sad_click_512.png` is 4608×3447 → 9×9 grid @ 512×383; only **75** frames have content
+     * (last 6 cells in row-major order are empty padding—do not play them).
+     */
+    readonly sadClick: 75;
+    /**
+     * `sad_thinking_512.png` is 5632×3830 → 11×10 grid @ 512×383; **105** frames drawn
+     * (last 5 cells empty—avoids blink when looping).
+     */
+    readonly sadThinking: 105;
+    /**
+     * `neutral_thinking_512.png` is 6144×4213 → 12×11 grid @ 512×383; **122** frames drawn
+     * (last 10 cells empty—avoids blink when looping).
+     */
+    readonly neutralThinking: 122;
+    /**
+     * `sad_celebrating_512.png` is 6144×4213 → 12×11 grid @ 512×383; **122** frames drawn
+     * (last 10 cells empty).
+     */
+    readonly sadCelebrating: 122;
+    /**
+     * `neutral_celebrating_512.png` is 6656×4596 → 13×12 grid @ 512×383; **150** frames drawn
+     * (last 6 cells empty).
+     */
+    readonly neutralCelebrating: 150;
+};
+/**
+ * Uniform grid parameters per `assets/sheets/*.png`, derived from image pixel size and
+ * {@link SAD_DEMO_FRAMES} (row-major cells; unused trailing cells are allowed).
+ */
+declare const SAD_DEMO_GRID_SHEETS: {
+    readonly neutralIdle: {
+        readonly image: "sheets/neutral_idle_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 14;
+        readonly frameCount: 181;
+    };
+    readonly neutralTalk: {
+        readonly image: "sheets/neutral_talk_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 10;
+        readonly frameCount: 93;
+    };
+    readonly neutralClick: {
+        readonly image: "sheets/neutral_click_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 6;
+        readonly frameCount: 36;
+    };
+    readonly sadIdle: {
+        readonly image: "sheets/sad_idle_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 13;
+        readonly frameCount: 149;
+    };
+    readonly sadTalk: {
+        readonly image: "sheets/sad_talk_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 12;
+        readonly frameCount: 126;
+    };
+    readonly neutralToSad: {
+        readonly image: "sheets/neutral_to_sad.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 10;
+        readonly frameCount: 91;
+    };
+    readonly sadToNeutral: {
+        readonly image: "sheets/sad_to_neutral.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 9;
+        readonly frameCount: 66;
+    };
+    readonly sadClick: {
+        readonly image: "sheets/sad_click_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 9;
+        readonly frameCount: 75;
+    };
+    readonly sadThinking: {
+        readonly image: "sheets/sad_thinking_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 11;
+        readonly frameCount: 105;
+    };
+    readonly neutralThinking: {
+        readonly image: "sheets/neutral_thinking_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 12;
+        readonly frameCount: 122;
+    };
+    readonly sadCelebrating: {
+        readonly image: "sheets/sad_celebrating_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 12;
+        readonly frameCount: 122;
+    };
+    readonly neutralCelebrating: {
+        readonly image: "sheets/neutral_celebrating_512.png";
+        readonly frameWidth: 512;
+        readonly frameHeight: 383;
+        readonly columns: 13;
+        readonly frameCount: 150;
+    };
+};
+/**
+ * Layered manifest: neutral, sad, and one-shot transitions using one PNG grid sheet per clip
+ * under `assets/sheets/` (see {@link SAD_DEMO_GRID_SHEETS}).
+ */
+declare function createSadDemoManifest(): LayeredCharacterManifest;
+
+export { AnimationStateConfig, CharacterManifest, CharacterPlayer, CharacterPlayerOptions, CharacterPose, LayeredCharacterManifest, LegacyCharacterManifest, POSE_KEY_SEPARATOR, SAD_DEMO_FRAMES, SAD_DEMO_GRID_SHEETS, createDefaultManifest, createSadDemoManifest, defaultPoseForLayered, flattenLayeredManifest, framePaths, idleFrameNames, isTransitionFlatKey, keyToPose, manifestToFlatStates, poseToKey, transitionFlatKey };