@doki-land/live2d-core 0.0.11 → 0.0.12

package/README.md

@@ -1,3 +1,3 @@
 # @doki-land/live2d-core
 
-live2d.ts package 0.0.11.
+live2d.ts package 0.0.12.

package/dist/index.d.ts

@@ -244,10 +244,103 @@ interface Live2DSession {
 }
 declare function createSessionStub(): Live2DSession;
 
+/** Normalized stage placement for one actor (0,0) top-left → (1,1) bottom-right. */
+interface ActorTransform {
+    /** Anchor point X in stage space. */
+    x: number;
+    /** Anchor point Y in stage space. */
+    y: number;
+    /** Uniform scale; ignored when `scaleX` / `scaleY` are set. */
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    /** Radians, counter-clockwise. */
+    rotation?: number;
+    /** Horizontal anchor within the model bounds (0 = left, 1 = right). */
+    anchorX?: number;
+    /** Vertical anchor within the model bounds (0 = top, 1 = bottom in stage space). */
+    anchorY?: number;
+}
+declare const DEFAULT_ACTOR_TRANSFORM: Readonly<ActorTransform>;
+type PointerTrackingMode = "all" | "focused" | "hovered" | "nearest" | "none" | "custom";
+interface PointerTrackingPolicy {
+    mode: PointerTrackingMode;
+    /** Used when `mode` is `custom`. */
+    targetActorId?: string;
+}
+interface CreateActorOptions {
+    id?: string;
+    transform?: Partial<ActorTransform>;
+    layer?: string;
+    order?: number;
+    visible?: boolean;
+    opacity?: number;
+}
+interface ActorHit {
+    readonly actor: Live2dActor;
+    readonly actorId: string;
+    readonly area: string;
+    readonly drawableIndex: number;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly localX: number;
+    readonly localY: number;
+}
+interface StagePointerEvent {
+    readonly actor: Live2dActor | null;
+    readonly actorId: string | null;
+    readonly area: string | null;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly hit: ActorHit | null;
+}
+type StageUpdateMode = "auto" | "manual";
+interface CreateLive2dStageOptions {
+    updateMode?: StageUpdateMode;
+}
+/** Read-only actor surface exposed by the stage. */
+interface Live2dActor {
+    readonly id: string;
+    readonly model: InternalModel | null;
+    readonly visible: boolean;
+    readonly opacity: number;
+    readonly layer: string;
+    readonly order: number;
+    readonly creationIndex: number;
+    getTransform(): ActorTransform;
+    setTransform(patch: Partial<ActorTransform>): void;
+    load(source: ModelSource, resolver?: AssetResolver): Promise<InternalModel>;
+    setParameter(id: string, value: number): void;
+    lookAt(stageX: number, stageY: number): void;
+    destroy(): void;
+}
+/** Multi-character stage owning one canvas surface and shared renderer. */
+interface Live2dStage {
+    readonly actors: readonly Live2dActor[];
+    mount(canvas: HTMLCanvasElement): Promise<void>;
+    createActor(options?: CreateActorOptions): Live2dActor;
+    removeActor(actor: Live2dActor | string): void;
+    defineLayers(layers: readonly string[]): void;
+    update(deltaTimeSeconds: number): void;
+    render(): void;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    hitTest(stageX: number, stageY: number): ActorHit | null;
+    hitTestAll(stageX: number, stageY: number): readonly ActorHit[];
+    addEventListener(type: "pointerdown" | "pointermove" | "pointerup", listener: (event: StagePointerEvent) => void): void;
+    removeEventListener(type: "pointerdown" | "pointermove" | "pointerup", listener: (event: StagePointerEvent) => void): void;
+    destroy(): void;
+    pointerTracking: PointerTrackingPolicy;
+}
+
 /**
  * `@doki-land/live2d-core` — types, events, session contracts.
  */
 
 declare const LIVE2D_CORE_VERSION: "0.0.0";
 
-export { type AssetKey, type AssetResolver, type DrawableProgram, EventEmitter, type ExpressionDefinition, FrameBlendMode, type FrameDrawable, type FrameProfile, type FrameSnapshot, type HitAreaDefinition, type InternalModel, LIVE2D_CORE_VERSION, type Live2DEventMap, type Live2DEventName, type Live2DListener, type Live2DSession, type LoadProgress, type LoadProgressStage, type ModelFormat, type ModelInstance, type ModelProgram, type ModelSettings, type ModelSource, type MotionDefinition, type ParameterProgram, type SessionPhase, type SessionState, createSessionStub, detectModelSettingsFormat, modelSourceUrl };
+export { type ActorHit, type ActorTransform, type AssetKey, type AssetResolver, type CreateActorOptions, type CreateLive2dStageOptions, DEFAULT_ACTOR_TRANSFORM, type DrawableProgram, EventEmitter, type ExpressionDefinition, FrameBlendMode, type FrameDrawable, type FrameProfile, type FrameSnapshot, type HitAreaDefinition, type InternalModel, LIVE2D_CORE_VERSION, type Live2DEventMap, type Live2DEventName, type Live2DListener, type Live2DSession, type Live2dActor, type Live2dStage, type LoadProgress, type LoadProgressStage, type ModelFormat, type ModelInstance, type ModelProgram, type ModelSettings, type ModelSource, type MotionDefinition, type ParameterProgram, type PointerTrackingMode, type PointerTrackingPolicy, type SessionPhase, type SessionState, type StagePointerEvent, type StageUpdateMode, createSessionStub, detectModelSettingsFormat, modelSourceUrl };

package/dist/index.js

@@ -109,9 +109,19 @@ function createSessionStub() {
   };
 }
 
+// src/stage.ts
+var DEFAULT_ACTOR_TRANSFORM = {
+  x: 0.5,
+  y: 1,
+  scale: 1,
+  anchorX: 0.5,
+  anchorY: 1
+};
+
 // src/index.ts
 var LIVE2D_CORE_VERSION = "0.0.0";
 export {
+  DEFAULT_ACTOR_TRANSFORM,
   EventEmitter,
   FrameBlendMode,
   LIVE2D_CORE_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doki-land/live2d-core",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Live2D types, events, and session contracts",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -43,5 +43,18 @@ export {
     createSessionStub,
     type Live2DSession,
 } from "./session.js";
+export type {
+    ActorHit,
+    ActorTransform,
+    CreateActorOptions,
+    CreateLive2dStageOptions,
+    Live2dActor,
+    Live2dStage,
+    PointerTrackingMode,
+    PointerTrackingPolicy,
+    StagePointerEvent,
+    StageUpdateMode,
+} from "./stage.js";
+export { DEFAULT_ACTOR_TRANSFORM } from "./stage.js";
 
 export const LIVE2D_CORE_VERSION = "0.0.0" as const;

package/src/stage.ts

@@ -0,0 +1,147 @@
+import type { InternalModel } from "./model.js";
+
+/** Normalized stage placement for one actor (0,0) top-left → (1,1) bottom-right. */
+export interface ActorTransform {
+    /** Anchor point X in stage space. */
+    x: number;
+    /** Anchor point Y in stage space. */
+    y: number;
+    /** Uniform scale; ignored when `scaleX` / `scaleY` are set. */
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    /** Radians, counter-clockwise. */
+    rotation?: number;
+    /** Horizontal anchor within the model bounds (0 = left, 1 = right). */
+    anchorX?: number;
+    /** Vertical anchor within the model bounds (0 = top, 1 = bottom in stage space). */
+    anchorY?: number;
+}
+
+export const DEFAULT_ACTOR_TRANSFORM: Readonly<ActorTransform> = {
+    x: 0.5,
+    y: 1,
+    scale: 1,
+    anchorX: 0.5,
+    anchorY: 1,
+};
+
+export type PointerTrackingMode =
+    | "all"
+    | "focused"
+    | "hovered"
+    | "nearest"
+    | "none"
+    | "custom";
+
+export interface PointerTrackingPolicy {
+    mode: PointerTrackingMode;
+    /** Used when `mode` is `custom`. */
+    targetActorId?: string;
+}
+
+export interface CreateActorOptions {
+    id?: string;
+    transform?: Partial<ActorTransform>;
+    layer?: string;
+    order?: number;
+    visible?: boolean;
+    opacity?: number;
+}
+
+export interface ActorHit {
+    readonly actor: Live2dActor;
+    readonly actorId: string;
+    readonly area: string;
+    readonly drawableIndex: number;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly localX: number;
+    readonly localY: number;
+}
+
+export interface StagePointerEvent {
+    readonly actor: Live2dActor | null;
+    readonly actorId: string | null;
+    readonly area: string | null;
+    readonly stageX: number;
+    readonly stageY: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly hit: ActorHit | null;
+}
+
+export type StageUpdateMode = "auto" | "manual";
+
+export interface CreateLive2dStageOptions {
+    updateMode?: StageUpdateMode;
+}
+
+/** Read-only actor surface exposed by the stage. */
+export interface Live2dActor {
+    readonly id: string;
+    readonly model: InternalModel | null;
+    readonly visible: boolean;
+    readonly opacity: number;
+    readonly layer: string;
+    readonly order: number;
+    readonly creationIndex: number;
+
+    getTransform(): ActorTransform;
+
+    setTransform(patch: Partial<ActorTransform>): void;
+
+    load(
+        source: import("./contracts.js").ModelSource,
+        resolver?: import("./contracts.js").AssetResolver,
+    ): Promise<InternalModel>;
+
+    setParameter(id: string, value: number): void;
+
+    lookAt(stageX: number, stageY: number): void;
+
+    destroy(): void;
+}
+
+/** Multi-character stage owning one canvas surface and shared renderer. */
+export interface Live2dStage {
+    readonly actors: readonly Live2dActor[];
+
+    mount(canvas: HTMLCanvasElement): Promise<void>;
+
+    createActor(options?: CreateActorOptions): Live2dActor;
+
+    removeActor(actor: Live2dActor | string): void;
+
+    defineLayers(layers: readonly string[]): void;
+
+    update(deltaTimeSeconds: number): void;
+
+    render(): void;
+
+    start(): void;
+
+    pause(): void;
+
+    resume(): void;
+
+    stop(): void;
+
+    hitTest(stageX: number, stageY: number): ActorHit | null;
+
+    hitTestAll(stageX: number, stageY: number): readonly ActorHit[];
+
+    addEventListener(
+        type: "pointerdown" | "pointermove" | "pointerup",
+        listener: (event: StagePointerEvent) => void,
+    ): void;
+
+    removeEventListener(
+        type: "pointerdown" | "pointermove" | "pointerup",
+        listener: (event: StagePointerEvent) => void,
+    ): void;
+
+    destroy(): void;
+
+    pointerTracking: PointerTrackingPolicy;
+}