cocos-plugin-live2d 0.0.0 → 0.0.13

package/README.md

@@ -1,3 +1,41 @@
 # cocos-plugin-live2d
 
-Placeholder package (0.0.0). Reserved for doki-land/live2d.ts.
+One package, two host folders — session / evaluate / render stay in `@doki-land/live2d`:
+
+| Import | Folder | Status |
+| --- | --- | --- |
+| `cocos-plugin-live2d` or `…/creator3` | `src/creator3` | Creator **3.x** Web runtime |
+| `cocos-plugin-live2d/creator2` | `src/creator2` | Creator **2.4** scaffold (component shell only) |
+
+Check which entry resolved:
+
+```ts
+import { COCOS_CREATOR_API, Live2D } from "cocos-plugin-live2d/creator3";
+// → COCOS_CREATOR_API === 3
+
+import { COCOS_CREATOR_API, Live2D } from "cocos-plugin-live2d/creator2";
+// → COCOS_CREATOR_API === 2
+```
+
+## Creator 3
+
+```ts
+import { Live2D } from "cocos-plugin-live2d/creator3";
+
+const live2d = node.addComponent(Live2D);
+live2d.model = "https://example.com/model/model3.json";
+```
+
+## Creator 2 (scaffold)
+
+```ts
+import { Live2D } from "cocos-plugin-live2d/creator2";
+
+const live2d = this.addComponent(Live2D); // or node.addComponent(Live2D)
+```
+
+`creator2` currently mounts a `cc.Component` shell and logs a warning in `start()` —
+no offscreen canvas / `@doki-land/live2d` wiring yet. Use it to verify the project
+resolves this package and the `/creator2` export.
+
+Native Android / iOS are out of this slice. Tips / chrome stay in `@doki-land/live2d-widget`.

package/package.json

@@ -1,7 +1,44 @@
 {
   "name": "cocos-plugin-live2d",
-  "version": "0.0.0",
-  "description": "live2d.ts placeholder — not for production use.",
+  "version": "0.0.13",
+  "description": "Cocos Creator Live2D adaptor for @doki-land/live2d — one package, creator3 / creator2 entries",
+  "type": "module",
   "license": "MIT",
-  "private": false
+  "author": "Doki Land",
+  "keywords": [
+    "live2d",
+    "cocos",
+    "cocos-creator",
+    "cocos-creator-2",
+    "cocos-creator-3",
+    "plugin",
+    "doki-land"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./creator3": "./src/creator3/index.ts",
+    "./creator2": "./src/creator2/index.ts"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@doki-land/live2d": "0.0.13"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/live2d.ts.git"
+  }
 }

package/src/creator2/Live2D.ts

@@ -0,0 +1,56 @@
+import { COCOS_CREATOR_API } from "./api.js";
+
+/**
+ * Creator 2.4 entry — scaffold only.
+ *
+ * Same package / property surface as creator3 so you can verify both hosts
+ * resolve `cocos-plugin-live2d/creator2`. Runtime bridge lands later.
+ */
+
+export { COCOS_CREATOR_API };
+
+const { ccclass, property } = cc._decorator;
+
+@ccclass("Live2D")
+export class Live2D extends cc.Component {
+    @property
+    model = "";
+
+    @property
+    width = 320;
+
+    @property
+    height = 320;
+
+    /** Comma-separated prefer list in the editor; parsed at runtime later. */
+    @property
+    prefer = "canvas2d,webgl2,webgpu";
+
+    @property
+    autoplay = true;
+
+    @property
+    autoSway = true;
+
+    onLoad(): void {
+        if (!this.getComponent(cc.Sprite)) {
+            this.addComponent(cc.Sprite);
+        }
+        this.node.setContentSize(this.width, this.height);
+    }
+
+    start(): void {
+        console.warn(
+            "[cocos-plugin-live2d/creator2] scaffold only — Live2D runtime not wired yet. API=",
+            COCOS_CREATOR_API,
+        );
+    }
+
+    update(_dt: number): void {
+        // runtime later
+    }
+
+    onDestroy(): void {
+        // runtime later
+    }
+}

package/src/creator2/api.ts

@@ -0,0 +1,2 @@
+/** Discriminator for import checks (Creator 2 entry). */
+export const COCOS_CREATOR_API = 2 as const;

package/src/creator2/index.ts

@@ -0,0 +1,2 @@
+export { COCOS_CREATOR_API } from "./api.js";
+export { Live2D } from "./Live2D.js";

package/src/creator2/shims-cc.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal Creator 2.4 ambient `cc` for typechecking this entry.
+ * Real Creator 2 projects use the engine's creator.d.ts.
+ */
+
+declare namespace cc {
+    type Constructor<T = unknown> = new (...args: never[]) => T;
+
+    class Vec2 {
+        x: number;
+        y: number;
+        constructor(x?: number, y?: number);
+    }
+
+    class Node {
+        static EventType: {
+            TOUCH_START: string;
+            TOUCH_MOVE: string;
+            TOUCH_END: string;
+            TOUCH_CANCEL: string;
+        };
+        name: string;
+        on(
+            type: string,
+            callback: (...args: never[]) => void,
+            target?: unknown,
+        ): void;
+        off(
+            type: string,
+            callback: (...args: never[]) => void,
+            target?: unknown,
+        ): void;
+        getComponent<T>(type: Constructor<T> | string): T | null;
+        addComponent<T>(type: Constructor<T> | string): T;
+        width: number;
+        height: number;
+        setContentSize(width: number, height: number): void;
+    }
+
+    class Component {
+        node: Node;
+        enabled: boolean;
+        getComponent<T>(type: Constructor<T> | string): T | null;
+        addComponent<T>(type: Constructor<T> | string): T;
+    }
+
+    class Sprite extends Component {
+        spriteFrame: SpriteFrame | null;
+    }
+
+    class SpriteFrame {
+        constructor();
+    }
+
+    class Texture2D {
+        initWithElement(element: HTMLCanvasElement | HTMLImageElement): void;
+        handleLoadedTexture(): void;
+    }
+
+    const _decorator: {
+        ccclass: (name?: string) => ClassDecorator;
+        property: ((options?: Record<string, unknown>) => PropertyDecorator) &
+            PropertyDecorator;
+    };
+}

package/src/creator3/Live2D.ts

@@ -0,0 +1,313 @@
+import {
+    createLive2D as createLive2DRuntime,
+    createRenderer,
+    focusParameterUpdates,
+    type Live2DRuntime,
+    type RendererKind,
+} from "@doki-land/live2d";
+import {
+    _decorator,
+    Component,
+    type EventTouch,
+    Node,
+    PixelFormat,
+    type Size,
+    Sprite,
+    SpriteFrame,
+    Texture2D,
+    UITransform,
+    Vec2,
+    Vec3,
+} from "cc";
+import { readCanvasRgba } from "./canvas-bridge.js";
+import { DEFAULT_COCOS_PREFER, normalizePrefer } from "./prefer.js";
+
+const { ccclass, property } = _decorator;
+
+/**
+ * Cocos Creator 3.x (Web) Live2D component.
+ *
+ * Draws via `@doki-land/live2d` into an offscreen canvas, then uploads pixels
+ * to a Sprite on the same node each frame. Native Android/iOS is out of scope.
+ */
+@ccclass("Live2D")
+export class Live2D extends Component {
+    /** Model settings URL, site path, or `npm:pkg[@ver]/path`. */
+    @property
+    model = "";
+
+    @property
+    width = 320;
+
+    @property
+    height = 320;
+
+    /**
+     * Renderer try order. Default prefers Canvas2D for Texture2D readback.
+     * Editor may leave this empty → {@link DEFAULT_COCOS_PREFER}.
+     */
+    @property({ type: [String] })
+    prefer: string[] = [...DEFAULT_COCOS_PREFER];
+
+    @property
+    autoplay = true;
+
+    @property
+    autoSway = true;
+
+    /** Optional touch hit callback (drawable id / area). */
+    onHit: ((payload: { area: string; x: number; y: number }) => void) | null =
+        null;
+
+    #canvas: HTMLCanvasElement | null = null;
+    #scratch: HTMLCanvasElement | null = null;
+    #runtime: Live2DRuntime | null = null;
+    #texture: Texture2D | null = null;
+    #spriteFrame: SpriteFrame | null = null;
+    #sprite: Sprite | null = null;
+    #mountGeneration = 0;
+    #elapsed = 0;
+    #autoSwayPausedByPointer = false;
+    #uiLoc = new Vec2();
+    #world = new Vec3();
+    #local = new Vec3();
+
+    onLoad(): void {
+        this.#sprite = this.getComponent(Sprite) ?? this.addComponent(Sprite);
+        const ui =
+            this.getComponent(UITransform) ?? this.addComponent(UITransform);
+        ui.setContentSize(this.width, this.height);
+
+        this.node.on(Node.EventType.TOUCH_MOVE, this.#onTouchMove, this);
+        this.node.on(Node.EventType.TOUCH_END, this.#onTouchEnd, this);
+        this.node.on(Node.EventType.TOUCH_CANCEL, this.#onTouchEnd, this);
+        this.node.on(Node.EventType.TOUCH_START, this.#onTouchStart, this);
+    }
+
+    start(): void {
+        void this.#remount();
+    }
+
+    update(dt: number): void {
+        const runtime = this.#runtime;
+        if (!runtime || !this.autoplay) return;
+
+        this.#elapsed += dt;
+        if (this.autoSway && !this.#autoSwayPausedByPointer) {
+            runtime.setParameter(
+                "PARAM_ANGLE_X",
+                this.#parameterFromNormalized(
+                    "PARAM_ANGLE_X",
+                    Math.sin(this.#elapsed) * 0.25,
+                ),
+            );
+        }
+        if (this.#autoSwayPausedByPointer) {
+            this.#autoSwayPausedByPointer = false;
+        }
+        runtime.update(dt);
+        this.#syncTexture();
+    }
+
+    onDestroy(): void {
+        this.#mountGeneration += 1;
+        this.node.off(Node.EventType.TOUCH_MOVE, this.#onTouchMove, this);
+        this.node.off(Node.EventType.TOUCH_END, this.#onTouchEnd, this);
+        this.node.off(Node.EventType.TOUCH_CANCEL, this.#onTouchEnd, this);
+        this.node.off(Node.EventType.TOUCH_START, this.#onTouchStart, this);
+        this.#teardownRuntime();
+        this.#texture?.destroy();
+        this.#texture = null;
+        this.#spriteFrame = null;
+    }
+
+    getRuntime(): Live2DRuntime | null {
+        return this.#runtime;
+    }
+
+    setParameter(id: string, value: number): void {
+        this.#runtime?.setParameter(id, value);
+        if (!this.autoplay) {
+            this.#runtime?.update(0);
+            this.#syncTexture();
+        }
+    }
+
+    listParameters() {
+        return this.#runtime?.listParameters() ?? [];
+    }
+
+    async reload(): Promise<void> {
+        if (!this.#runtime || !this.model) {
+            await this.#remount();
+            return;
+        }
+        const gen = this.#mountGeneration;
+        try {
+            await this.#runtime.loadModel(this.model);
+            if (gen !== this.#mountGeneration) return;
+            if (!this.autoplay) {
+                this.#runtime.update(0);
+                this.#syncTexture();
+            }
+        } catch {
+            // error emitted via runtime events
+        }
+    }
+
+    async #remount(): Promise<void> {
+        const gen = ++this.#mountGeneration;
+        this.#teardownRuntime();
+
+        if (typeof document === "undefined") {
+            console.warn(
+                "cocos-plugin-live2d: Live2D requires Creator Web (DOM canvas).",
+            );
+            return;
+        }
+
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.max(1, Math.round(this.width));
+        canvas.height = Math.max(1, Math.round(this.height));
+        this.#canvas = canvas;
+        this.#scratch = document.createElement("canvas");
+
+        const prefer = normalizePrefer(this.prefer);
+        const runtime = createLive2DRuntime({
+            renderer: createRenderer({ prefer }),
+        });
+        this.#runtime = runtime;
+        runtime.mount(canvas);
+
+        const ui = this.getComponent(UITransform);
+        ui?.setContentSize(this.width, this.height);
+
+        if (this.model) {
+            try {
+                await runtime.loadModel(this.model);
+                if (gen !== this.#mountGeneration) return;
+                if (!this.autoplay) {
+                    runtime.update(0);
+                }
+                this.#syncTexture();
+            } catch {
+                // error emitted via runtime events
+            }
+        }
+    }
+
+    #teardownRuntime(): void {
+        this.#runtime?.destroy();
+        this.#runtime = null;
+        this.#canvas = null;
+        this.#scratch = null;
+        this.#elapsed = 0;
+        this.#autoSwayPausedByPointer = false;
+    }
+
+    #syncTexture(): void {
+        const canvas = this.#canvas;
+        const sprite = this.#sprite;
+        if (!canvas || !sprite) return;
+
+        const pixels = readCanvasRgba(canvas, this.#scratch);
+        if (!pixels) {
+            // Last resort: let Cocos ingest the canvas directly when possible.
+            this.#ensureSpriteFrame(canvas.width, canvas.height);
+            try {
+                this.#texture?.uploadData(canvas);
+            } catch {
+                // ignore upload failure
+            }
+            return;
+        }
+
+        this.#ensureSpriteFrame(pixels.width, pixels.height);
+        this.#texture?.uploadData(pixels.data);
+    }
+
+    #ensureSpriteFrame(width: number, height: number): void {
+        if (!this.#texture) {
+            this.#texture = new Texture2D();
+        }
+        this.#texture.reset({
+            width,
+            height,
+            format: PixelFormat.RGBA8888,
+        });
+        if (!this.#spriteFrame) {
+            this.#spriteFrame = new SpriteFrame();
+        }
+        this.#spriteFrame.texture = this.#texture;
+        if (this.#sprite && this.#sprite.spriteFrame !== this.#spriteFrame) {
+            this.#sprite.spriteFrame = this.#spriteFrame;
+        }
+    }
+
+    #parameterFromNormalized(id: string, normalized: number): number {
+        const binding = this.#runtime
+            ?.listParameters()
+            .find((p) => p.id === id);
+        if (!binding) return normalized;
+        return normalized >= 0
+            ? binding.defaultValue +
+                  (binding.max - binding.defaultValue) * normalized
+            : binding.defaultValue +
+                  (binding.defaultValue - binding.min) * normalized;
+    }
+
+    #touchToModel(event: EventTouch): { x: number; y: number } | null {
+        const ui = this.getComponent(UITransform);
+        if (!ui) return null;
+        const loc = event.getUILocation(this.#uiLoc);
+        this.#world.set(loc.x, loc.y, 0);
+        ui.convertToNodeSpaceAR(this.#world, this.#local);
+        const size: Size = ui.contentSize;
+        const hw = size.width * 0.5;
+        const hh = size.height * 0.5;
+        if (hw <= 0 || hh <= 0) return null;
+        return {
+            x: this.#local.x / hw,
+            y: this.#local.y / hh,
+        };
+    }
+
+    #applyFocus(x: number, y: number): void {
+        const runtime = this.#runtime;
+        if (!runtime) return;
+        this.#autoSwayPausedByPointer = true;
+        for (const { id, value } of focusParameterUpdates(
+            runtime.listParameters(),
+            x,
+            y,
+        )) {
+            runtime.setParameter(id, value);
+        }
+        if (!this.autoplay) {
+            runtime.update(0);
+            this.#syncTexture();
+        }
+    }
+
+    #onTouchMove = (event: EventTouch): void => {
+        const p = this.#touchToModel(event);
+        if (!p) return;
+        this.#applyFocus(p.x, p.y);
+    };
+
+    #onTouchStart = (event: EventTouch): void => {
+        const p = this.#touchToModel(event);
+        if (!p) return;
+        this.#applyFocus(p.x, p.y);
+    };
+
+    #onTouchEnd = (event: EventTouch): void => {
+        const p = this.#touchToModel(event);
+        const runtime = this.#runtime;
+        if (!p || !runtime) return;
+        const area = runtime.hitTest(p.x, p.y);
+        if (area) this.onHit?.({ area, x: p.x, y: p.y });
+    };
+}
+
+export type { RendererKind };

package/src/creator3/api.ts

@@ -0,0 +1,2 @@
+/** Discriminator for import checks (Creator 3 entry). */
+export const COCOS_CREATOR_API = 3 as const;

package/src/creator3/canvas-bridge.ts

@@ -0,0 +1,49 @@
+export interface CanvasRgbaPixels {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8ClampedArray;
+}
+
+/**
+ * Read RGBA pixels from a canvas for Cocos Texture2D.uploadData.
+ * Prefers a 2D context on the source; otherwise blits through a scratch 2D canvas
+ * (needed when the Live2D backend used WebGL2 / WebGPU).
+ */
+export function readCanvasRgba(
+    source: HTMLCanvasElement,
+    scratch?: HTMLCanvasElement | null,
+): CanvasRgbaPixels | null {
+    const width = source.width | 0;
+    const height = source.height | 0;
+    if (width <= 0 || height <= 0) return null;
+
+    const direct = source.getContext("2d");
+    if (direct) {
+        try {
+            const img = direct.getImageData(0, 0, width, height);
+            return { width, height, data: img.data };
+        } catch {
+            // tainted or lost context — fall through
+        }
+    }
+
+    const blit =
+        scratch && scratch.width >= 0
+            ? scratch
+            : typeof document !== "undefined"
+              ? document.createElement("canvas")
+              : null;
+    if (!blit) return null;
+    if (blit.width !== width) blit.width = width;
+    if (blit.height !== height) blit.height = height;
+    const ctx = blit.getContext("2d");
+    if (!ctx) return null;
+    try {
+        ctx.clearRect(0, 0, width, height);
+        ctx.drawImage(source, 0, 0);
+        const img = ctx.getImageData(0, 0, width, height);
+        return { width, height, data: img.data };
+    } catch {
+        return null;
+    }
+}

package/src/creator3/index.ts

@@ -0,0 +1,7 @@
+export { COCOS_CREATOR_API } from "./api.js";
+export { type CanvasRgbaPixels, readCanvasRgba } from "./canvas-bridge.js";
+export { Live2D } from "./Live2D.js";
+export {
+    DEFAULT_COCOS_PREFER,
+    normalizePrefer,
+} from "./prefer.js";

package/src/creator3/prefer.ts

@@ -0,0 +1,23 @@
+import type { RendererKind } from "@doki-land/live2d";
+
+const ALLOWED = new Set<RendererKind>(["webgpu", "webgl2", "canvas2d"]);
+
+/** Default prefer order for Cocos Web: Canvas2D first so pixels can be read back. */
+export const DEFAULT_COCOS_PREFER: readonly RendererKind[] = [
+    "canvas2d",
+    "webgl2",
+    "webgpu",
+];
+
+/**
+ * Keep only known renderer kinds. Empty / invalid input → default Cocos order.
+ */
+export function normalizePrefer(
+    prefer: readonly string[] | undefined | null,
+): RendererKind[] {
+    if (!prefer?.length) return [...DEFAULT_COCOS_PREFER];
+    const out = prefer.filter((k): k is RendererKind =>
+        ALLOWED.has(k as RendererKind),
+    );
+    return out.length ? out : [...DEFAULT_COCOS_PREFER];
+}

package/src/creator3/shims-cc.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal Cocos Creator 3.x ambient types for typechecking this adaptor
+ * without vendoring the full engine. Creator projects use the real `cc`.
+ */
+
+declare module "cc" {
+    export type Constructor<T = unknown> = new (...args: never[]) => T;
+
+    export class Vec2 {
+        x: number;
+        y: number;
+        constructor(x?: number, y?: number);
+        set(x: number, y: number): this;
+    }
+
+    export class Vec3 {
+        x: number;
+        y: number;
+        z: number;
+        constructor(x?: number, y?: number, z?: number);
+        set(x: number, y: number, z?: number): this;
+    }
+
+    export class Size {
+        width: number;
+        height: number;
+        constructor(width?: number, height?: number);
+    }
+
+    export class Node {
+        static EventType: {
+            TOUCH_START: string;
+            TOUCH_MOVE: string;
+            TOUCH_END: string;
+            TOUCH_CANCEL: string;
+        };
+        name: string;
+        on(
+            type: string,
+            callback: (...args: never[]) => void,
+            target?: unknown,
+        ): void;
+        off(
+            type: string,
+            callback: (...args: never[]) => void,
+            target?: unknown,
+        ): void;
+        getComponent<T>(type: Constructor<T>): T | null;
+        addComponent<T>(type: Constructor<T>): T;
+    }
+
+    export class Component {
+        node: Node;
+        enabled: boolean;
+        getComponent<T>(type: Constructor<T>): T | null;
+        addComponent<T>(type: Constructor<T>): T;
+        scheduleOnce(callback: () => void, delay?: number): void;
+    }
+
+    export class UITransform extends Component {
+        contentSize: Size;
+        setContentSize(width: number, height: number): void;
+        convertToNodeSpaceAR(worldPoint: Vec3, out?: Vec3): Vec3;
+    }
+
+    export class ImageAsset {
+        constructor(data?: HTMLCanvasElement | HTMLImageElement | ImageBitmap);
+        reset(data: HTMLCanvasElement | HTMLImageElement | ImageBitmap): void;
+    }
+
+    export enum PixelFormat {
+        RGBA8888 = 35,
+    }
+
+    export class Texture2D {
+        reset(info: {
+            width: number;
+            height: number;
+            format?: PixelFormat;
+        }): void;
+        uploadData(
+            source:
+                | HTMLCanvasElement
+                | HTMLImageElement
+                | ArrayBufferView
+                | ImageBitmap,
+            level?: number,
+            arrayIndex?: number,
+        ): void;
+        destroy(): void;
+        image: ImageAsset | null;
+    }
+
+    export class SpriteFrame {
+        texture: Texture2D | null;
+        constructor();
+    }
+
+    export class Sprite extends Component {
+        spriteFrame: SpriteFrame | null;
+    }
+
+    export class EventTouch {
+        getUILocation(out?: Vec2): Vec2;
+    }
+
+    export const _decorator: {
+        ccclass: (name?: string) => ClassDecorator;
+        property: ((options?: Record<string, unknown>) => PropertyDecorator) &
+            PropertyDecorator;
+    };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+/** Default entry = Creator 3.x. Prefer `cocos-plugin-live2d/creator3` when explicit. */
+export * from "./creator3/index.js";