@react-shimeji/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,511 @@
+/** A two-dimensional point in work-area coordinates. */
+interface Point {
+    /** Horizontal coordinate in CSS pixels. */
+    x: number;
+    /** Vertical coordinate in CSS pixels. */
+    y: number;
+}
+/** A rectangular region in a spritesheet or work area. */
+interface Rectangle extends Point {
+    /** Rectangle width in CSS pixels. */
+    width: number;
+    /** Rectangle height in CSS pixels. */
+    height: number;
+}
+/** A sprite cropped from the character's atlas. */
+interface SpriteRectangle extends Rectangle {
+    /** Optional URL overriding the character-level spritesheet for this sprite. */
+    url?: string;
+}
+/** A standalone sprite image rather than an atlas crop. */
+interface IndividualSprite {
+    /** Image URL or data URI. */
+    url: string;
+    /** Optional known image width. */
+    width?: number;
+    /** Optional known image height. */
+    height?: number;
+}
+/** Sprite definitions keyed by the legacy image path, such as `/shime1.png`. */
+type SpriteMap = Record<string, SpriteRectangle | IndividualSprite | string>;
+/** One legacy animation pose. Durations use the traditional 40 ms unit. */
+interface Pose {
+    /** Sprite key from the character's sprite map, or an image URL. */
+    sprite: string;
+    /** Point within the sprite that occupies the mascot's world position. */
+    anchor: Point;
+    /** Per-legacy-frame movement encoded by the character pack. */
+    velocity: Point;
+    /** Number of 40 ms units for which the pose remains active. */
+    duration: number;
+}
+/** A conditional collection of poses used by an action. */
+interface AnimationDefinition {
+    /** Optional Shimeji expression controlling whether this animation applies. */
+    condition?: string;
+    /** Ordered pose frames. */
+    poses: Pose[];
+}
+/** Kind of action understood by the action executor. */
+type ActionType = "Sequence" | "Select" | "Reference" | "Stay" | "Animate" | "Move" | "Embedded";
+/** Boundary on which an action is allowed to begin. */
+type BorderType = "Floor" | "Wall" | "Ceiling";
+/** A normalized action from a compiled or XML character definition. */
+interface ActionDefinition {
+    /** Action implementation kind. */
+    type: ActionType;
+    /** Stable action name used by behaviors and references. */
+    name?: string;
+    /** Embedded action class name such as `Fall`, `Dragged`, or `Look`. */
+    embedType?: string;
+    /** Optional expression that must evaluate truthfully. */
+    condition?: string;
+    /** Optional boundary prerequisite. */
+    borderType?: BorderType;
+    /** Nested actions for sequence and selection nodes. */
+    actions?: ActionDefinition[];
+    /** Conditional pose alternatives for leaf actions. */
+    animations?: AnimationDefinition[];
+    /** Whether a sequence should repeat. */
+    loop?: boolean;
+    /** Duration expression measured in legacy frames. */
+    duration?: string | number;
+    /** Legacy expression gap made available while evaluating other properties. */
+    gap?: string | number;
+    /** Horizontal target expression. */
+    targetX?: string | number;
+    /** Vertical target expression. */
+    targetY?: string | number;
+    /** Movement speed expression. */
+    velocity?: string | number;
+    /** Horizontal offset expression. */
+    x?: string | number;
+    /** Vertical offset expression. */
+    y?: string | number;
+    /** Initial horizontal velocity expression. */
+    initialVx?: string | number;
+    /** Initial vertical velocity expression. */
+    initialVy?: string | number;
+    /** Horizontal air-resistance expression. */
+    resistanceX?: string | number;
+    /** Vertical air-resistance expression. */
+    resistanceY?: string | number;
+    /** Gravity expression. */
+    gravity?: string | number;
+    /** Child spawn horizontal offset expression. */
+    bornX?: string | number;
+    /** Child spawn vertical offset expression. */
+    bornY?: string | number;
+    /** Behavior assigned to a spawned child. */
+    bornBehavior?: string;
+    /** Carried-element horizontal offset expression. */
+    ieOffsetX?: string | number;
+    /** Carried-element vertical offset expression. */
+    ieOffsetY?: string | number;
+    /** Facing expression used by Look actions. */
+    lookRight?: string | boolean;
+}
+/** Kind of behavior node stored in a character specification. */
+type BehaviorType = "Behavior" | "Reference";
+/** One weighted behavior and its possible transitions. */
+interface BehaviorDefinition {
+    /** Whether this is a complete behavior or a reference to one. */
+    type: BehaviorType;
+    /** Name of the behavior and its same-named action. */
+    name: string;
+    /** Relative random-selection weight. */
+    frequency: number;
+    /** Conditions that must all be true. */
+    conditions: string[];
+    /** Candidates considered after this behavior completes. */
+    nextBehaviors: BehaviorDefinition[];
+    /** Menu grouping value retained from legacy packs. */
+    groupIndex: number;
+    /** Whether user interfaces should hide the behavior. */
+    hidden: boolean;
+}
+/** Free-form character attribution and directory metadata. */
+interface CharacterMetadata {
+    /** Character display name. */
+    shimejiName?: string;
+    /** Character group identifier. */
+    group?: string;
+    /** Character group display name. */
+    groupName?: string;
+    /** Original artist name. */
+    artistName?: string | null;
+    /** Upstream source URL. */
+    sourceUrl?: string;
+    /** Any additional pack-specific metadata. */
+    [key: string]: unknown;
+}
+/** Fully parsed character data consumed by the engine. */
+interface CharacterSpec {
+    /** Stable identifier used when spawning the character. */
+    id: string;
+    /** Optional human-readable name. */
+    name?: string;
+    /** Character attribution metadata. */
+    metadata?: CharacterMetadata;
+    /** Spritesheet URL, data URI, or Blob owned by spawned mascots. */
+    spritesheet: string | Blob;
+    /** Atlas rectangles or individual sprite URLs. */
+    sprites: SpriteMap;
+    /** Parsed action tree definitions. */
+    actions: ActionDefinition[];
+    /** Parsed behavior state-machine definitions. */
+    behaviors: BehaviorDefinition[];
+}
+/** Legacy bundle whose XML and JSON fields have not necessarily been parsed. */
+interface LegacyCharacterPack {
+    /** Stable character identifier; inferred from metadata when omitted. */
+    id?: string;
+    /** Optional human-readable name. */
+    name?: string;
+    /** Optional wrapper object used by some pack exporters. */
+    configuration?: unknown;
+    /** Parsed actions or raw `actions.xml` text. */
+    actions: ActionDefinition[] | string;
+    /** Parsed behaviors or raw `behaviors.xml` text. */
+    behaviors: BehaviorDefinition[] | string;
+    /** Parsed sprite map or raw `sprites.json` text. */
+    sprites: SpriteMap | string;
+    /** Spritesheet URL, data URI, or Blob. */
+    spritesheet: string | Blob;
+    /** Optional character metadata. */
+    metadata?: CharacterMetadata;
+}
+/** Supported input accepted by the character loader. */
+type CharacterSource = CharacterSpec | LegacyCharacterPack | string | URL;
+/** Initial placement and state for a newly spawned mascot. */
+interface SpawnOptions extends Partial<Point> {
+    /** Initial horizontal velocity. */
+    vx?: number;
+    /** Initial vertical velocity. */
+    vy?: number;
+    /** Initial facing direction. */
+    lookRight?: boolean;
+    /** Behavior to run first. */
+    behaviorName?: string;
+}
+/** Public immutable snapshot of a mascot. */
+interface MascotState extends Point {
+    /** Unique mascot instance identifier. */
+    id: string;
+    /** Registered character identifier. */
+    characterId: string;
+    /** Current horizontal velocity. */
+    vx: number;
+    /** Current vertical velocity. */
+    vy: number;
+    /** Current sprite key. */
+    sprite: string;
+    /** Current horizontal sprite anchor. */
+    anchorX: number;
+    /** Current vertical sprite anchor. */
+    anchorY: number;
+    /** Whether the sprite faces right. */
+    lookRight: boolean;
+    /** Name of the current behavior. */
+    behaviorName: string;
+    /** Whether the mascot is currently being dragged. */
+    dragging: boolean;
+}
+/** Runtime options for a Shimeji engine. */
+interface ShimejiEngineOptions {
+    /** Legacy frame duration in milliseconds. Defaults to 40. */
+    frameDuration?: number;
+    /** Default gravity in legacy pixels per frame squared. Defaults to 2. */
+    gravity?: number;
+    /** Maximum elapsed time applied to one animation update. Defaults to 100 ms. */
+    maxDeltaTime?: number;
+    /** CSS class added to the generated work area. */
+    workAreaClassName?: string;
+    /** CSS class added to each generated mascot element. */
+    mascotClassName?: string;
+    /** Optional deterministic random-number source. */
+    random?: () => number;
+}
+/** Events emitted by {@link ShimejiEngine}. */
+interface ShimejiEngineEventMap {
+    /** Emitted after a mascot is created. */
+    spawn: MascotState;
+    /** Emitted immediately before a mascot is discarded. */
+    remove: MascotState;
+    /** Emitted when the state collection changes during a frame. */
+    statechange: MascotState[];
+    /** Emitted when a mascot is clicked without being dragged. */
+    click: MascotState;
+    /** Emitted when a recoverable pack or runtime error occurs. */
+    error: Error;
+}
+/** Typed callback for one engine event. */
+type ShimejiEventListener<K extends keyof ShimejiEngineEventMap> = (payload: ShimejiEngineEventMap[K]) => void;
+/** Read-only environment supplied to expression and action evaluation. */
+interface MascotEnvironment {
+    /** Current mascot snapshot. */
+    mascot: {
+        /** Current number of live mascots. */
+        totalCount: number;
+        /** Current anchor position. */
+        anchor: Point;
+        /** Current facing direction. */
+        lookRight: boolean;
+        /** Browser and work-area values exposed to legacy expressions. */
+        environment: {
+            /** Latest pointer position and velocity. */
+            cursor: Point & {
+                dx: number;
+                dy: number;
+            };
+            /** Current viewport dimensions. */
+            screen: {
+                width: number;
+                height: number;
+            };
+            /** Current work-area bounds and edge predicates. */
+            workArea: EnvironmentRectangle;
+            /** Alias for the work-area bottom edge. */
+            floor: EnvironmentEdge;
+            /** Alias for the work-area top edge. */
+            ceiling: EnvironmentEdge;
+            /** Inactive compatibility rectangle for page-element actions. */
+            activeIE: EnvironmentRectangle & {
+                visible: boolean;
+            };
+        };
+    };
+    /** Legacy expression gap variable. */
+    gap: number;
+    /** Configured upper mascot count. */
+    maxCount: number;
+    /** Current action target x-coordinate. */
+    targetX?: number;
+    /** Current action target y-coordinate. */
+    targetY?: number;
+    /** Dragging animation foot x-coordinate. */
+    footX?: number;
+    /** Dragging animation foot y-coordinate. */
+    footY?: number;
+}
+/** Edge predicate exposed to legacy expressions. */
+interface EnvironmentEdge {
+    /** Returns whether a point is on this edge. */
+    isOn(point: Point): boolean;
+}
+/** Rectangle and edge predicates exposed to legacy expressions. */
+interface EnvironmentRectangle extends Rectangle {
+    /** Left edge coordinate. */
+    left: number;
+    /** Right edge coordinate. */
+    right: number;
+    /** Top edge coordinate. */
+    top: number;
+    /** Bottom edge coordinate. */
+    bottom: number;
+    /** Top edge predicate. */
+    topBorder: EnvironmentEdge;
+    /** Left edge predicate. */
+    leftBorder: EnvironmentEdge;
+    /** Right edge predicate. */
+    rightBorder: EnvironmentEdge;
+    /** Bottom edge predicate. */
+    bottomBorder: EnvironmentEdge;
+}
+
+/** Framework-agnostic manager for character registration and live Shimeji mascots. */
+declare class ShimejiEngine {
+    private readonly container;
+    private readonly specs;
+    private readonly mascots;
+    private readonly sprites;
+    private readonly dom;
+    private readonly events;
+    private readonly disposers;
+    private readonly intervals;
+    private readonly options;
+    private readonly originalContainerPosition;
+    private readonly adjustedContainerPosition;
+    private pointer;
+    private animationFrame;
+    private lastFrameTime;
+    private nextMascotId;
+    private destroyed;
+    private initialized;
+    /** Creates and initializes an engine inside a host DOM element. */
+    constructor(container: HTMLElement, options?: ShimejiEngineOptions);
+    /** Starts the clock and global listeners. Calling this method more than once is harmless. */
+    initialize(): void;
+    /** Registers or replaces a parsed or legacy character specification. */
+    registerCharacter(spec: CharacterSpec | unknown): string;
+    /** Unregisters a character and optionally removes all of its live mascots. */
+    unregisterCharacter(characterId: string, removeMascots?: boolean): boolean;
+    /** Returns identifiers for all currently registered characters. */
+    getCharacterIds(): string[];
+    /** Creates a mascot from a registered character and returns its instance id. */
+    spawn(characterId: string, position?: SpawnOptions): string;
+    /** Removes one mascot and all resources associated with it. */
+    remove(mascotId: string): boolean;
+    /** Removes every live mascot while leaving registered character specs available. */
+    removeAll(): void;
+    /** Returns detached snapshots of every live mascot. */
+    getState(): MascotState[];
+    /** Subscribes to a typed engine event and returns an unsubscribe function. */
+    on<K extends keyof ShimejiEngineEventMap>(event: K, listener: ShimejiEventListener<K>): () => void;
+    /** Stops animation and timers, removes listeners and DOM, and revokes all object URLs. */
+    destroy(): void;
+    /** Returns whether this engine has completed permanent teardown. */
+    isDestroyed(): boolean;
+    private readonly onAnimationFrame;
+    private renderAll;
+    private emitState;
+    private listen;
+    private assertAlive;
+}
+
+/** Parses a legacy `actions.xml` document into normalized action definitions. */
+declare function parseActionsXml(xml: string): ActionDefinition[];
+/** Parses a legacy `behaviors.xml` document into normalized behavior definitions. */
+declare function parseBehaviorsXml(xml: string): BehaviorDefinition[];
+/** Converts a pre-parsed definition or raw XML/JSON legacy bundle to a character specification. */
+declare function normalizeCharacterSpec(input: CharacterSpec | LegacyCharacterPack | unknown): CharacterSpec;
+/** Loads character JSON from a URL or normalizes an already available character bundle. */
+declare function loadCharacter(source: CharacterSource): Promise<CharacterSpec>;
+
+/** Safely evaluates a legacy Shimeji expression without using `eval` or `Function`. */
+declare function evaluateExpression(expression: string | number | boolean | undefined, environment: MascotEnvironment, fallback: number): number;
+/** Safely evaluates a legacy Shimeji expression without using `eval` or `Function`. */
+declare function evaluateExpression(expression: string | number | boolean | undefined, environment: MascotEnvironment, fallback: boolean): boolean;
+/** Returns true when every condition in a behavior or action is satisfied. */
+declare function conditionsMatch(conditions: readonly string[], environment: MascotEnvironment): boolean;
+/** Chooses one item with probability proportional to its non-negative weight. */
+declare function selectWeighted<T>(items: readonly T[], weight: (item: T) => number, random?: () => number): T | undefined;
+/** Selects applicable behaviors and resolves legacy behavior references. */
+declare class BehaviorController {
+    private readonly spec;
+    private readonly random;
+    private previous;
+    /** Creates a behavior selector for a normalized character specification. */
+    constructor(spec: CharacterSpec, random?: () => number);
+    /** Selects an initial behavior, honoring an explicit requested name when possible. */
+    selectInitial(environment: MascotEnvironment, requestedName?: string): BehaviorDefinition | undefined;
+    /** Selects the weighted transition following the current behavior. */
+    selectNext(environment: MascotEnvironment): BehaviorDefinition | undefined;
+    /** Replaces selection history so an external interaction can force a behavior. */
+    force(name: string): BehaviorDefinition | undefined;
+    private choose;
+    private resolve;
+    private findFallBehavior;
+    private isOnAnyBoundary;
+}
+
+/** Callbacks through which embedded actions request engine-level operations. */
+interface ActionExecutorCallbacks {
+    /** Spawns another mascot from the same character. */
+    spawn(position: {
+        x: number;
+        y: number;
+        behaviorName?: string;
+    }): void;
+    /** Removes the mascot owning this executor. */
+    remove(): void;
+}
+/** Settings used while interpreting actions. */
+interface ActionExecutorOptions {
+    /** Duration of one legacy animation unit in milliseconds. */
+    frameDuration: number;
+    /** Gravity used when a Fall action does not define one. */
+    gravity: number;
+}
+/** Executes normalized action trees independently from DOM rendering. */
+declare class ActionExecutor {
+    private readonly spec;
+    private readonly state;
+    private readonly options;
+    private readonly callbacks;
+    private runtime;
+    /** Creates an executor bound to one mascot's mutable internal state. */
+    constructor(spec: CharacterSpec, state: MascotState, options: ActionExecutorOptions, callbacks: ActionExecutorCallbacks);
+    /** Starts the action whose name matches a selected behavior. */
+    start(actionName: string, environment: MascotEnvironment): boolean;
+    /** Advances the current action and returns true when it has completed. */
+    tick(deltaMs: number, environment: MascotEnvironment, bounds: Rectangle): boolean;
+    /** Cancels the current action tree. */
+    cancel(): void;
+    private createRuntime;
+}
+
+/** Clamps a number to an inclusive range. */
+declare function clamp(value: number, minimum: number, maximum: number): number;
+/** Returns whether a point lies on the top edge of a rectangle. */
+declare function isOnTop(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
+/** Returns whether a point lies on the bottom edge of a rectangle. */
+declare function isOnBottom(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
+/** Returns whether a point lies on the left edge of a rectangle. */
+declare function isOnLeft(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
+/** Returns whether a point lies on the right edge of a rectangle. */
+declare function isOnRight(point: Point, rectangle: Rectangle, tolerance?: number): boolean;
+/** Returns whether an anchor satisfies an action's boundary requirement. */
+declare function isOnBorder(state: MascotState, bounds: Rectangle, border: "Floor" | "Wall" | "Ceiling" | undefined): boolean;
+/** Advances ballistic motion and clamps the mascot to the work-area boundaries. */
+declare function applyGravity(state: MascotState, bounds: Rectangle, frameScale: number, gravity: number, resistanceX?: number, resistanceY?: number): boolean;
+/** Moves a mascot toward a target without overshooting it. */
+declare function moveToward(state: MascotState, target: Point, speed: number, frameScale: number): boolean;
+
+/** A resolved image and optional atlas crop for one sprite frame. */
+interface ResolvedSprite {
+    /** Browser-loadable image URL. */
+    url: string;
+    /** Optional atlas crop. */
+    rectangle?: SpriteRectangle;
+}
+/** A per-mascot spritesheet resource whose temporary URL can be released. */
+interface SpriteLease {
+    /** URL used to render atlas-backed frames. */
+    url: string;
+    /** Releases any object URL owned by this lease. */
+    release(): void;
+}
+/** Owns temporary sprite URLs and resolves atlas or individual image frames. */
+declare class SpriteManager {
+    private readonly leases;
+    /** Creates a separately releasable spritesheet lease for a mascot. */
+    acquire(source: string | Blob): SpriteLease;
+    /** Resolves a sprite key using a lease and the character's sprite map. */
+    resolve(spec: CharacterSpec, lease: SpriteLease, spriteName: string): ResolvedSprite | undefined;
+    /** Revokes every object URL that has not already been released. */
+    destroy(): void;
+}
+/** Returns whether a sprite definition is a standalone image object. */
+declare function isIndividualSprite(sprite: SpriteRectangle | IndividualSprite | string): sprite is IndividualSprite;
+
+/** DOM nodes and resources owned by one mascot. */
+interface MascotDomHandle {
+    /** Pointer-interactive mascot wrapper. */
+    element: HTMLDivElement;
+    /** Child element on which sprite images are painted. */
+    spriteElement: HTMLDivElement;
+    /** Per-mascot spritesheet URL lease. */
+    spriteLease: SpriteLease;
+}
+
+/** Callbacks through which a mascot communicates with its owning engine. */
+interface MascotCallbacks {
+    /** Returns the latest pointer position and velocity in work-area coordinates. */
+    pointer(): Point & {
+        dx: number;
+        dy: number;
+    };
+    /** Returns the current number of live mascots. */
+    count(): number;
+    /** Requests a sibling mascot. */
+    spawn(characterId: string, options: SpawnOptions): void;
+    /** Requests removal of this mascot. */
+    remove(id: string): void;
+    /** Reports a click without a drag gesture. */
+    click(state: MascotState): void;
+    /** Reports a recoverable runtime failure. */
+    error(error: Error): void;
+}
+
+export { type ActionDefinition, ActionExecutor, type ActionExecutorCallbacks, type ActionExecutorOptions, type ActionType, type AnimationDefinition, BehaviorController, type BehaviorDefinition, type BehaviorType, type BorderType, type CharacterMetadata, type CharacterSource, type CharacterSpec, type EnvironmentEdge, type EnvironmentRectangle, type IndividualSprite, type LegacyCharacterPack, type MascotCallbacks, type MascotDomHandle, type MascotEnvironment, type MascotState, type Point, type Pose, type Rectangle, type ResolvedSprite, ShimejiEngine, type ShimejiEngineEventMap, type ShimejiEngineOptions, type ShimejiEventListener, type SpawnOptions, type SpriteLease, SpriteManager, type SpriteMap, type SpriteRectangle, applyGravity, clamp, conditionsMatch, evaluateExpression, isIndividualSprite, isOnBorder, isOnBottom, isOnLeft, isOnRight, isOnTop, loadCharacter, moveToward, normalizeCharacterSpec, parseActionsXml, parseBehaviorsXml, selectWeighted };