@laplace.live/pixijs-live2d 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 GuangChen2333
+Copyright (c) 2026 LAPLACE Live!
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @laplace.live/pixijs-live2d
+
+PixiJS v8 Live2D engine for Cubism 3/4/5 models — motions, expressions, physics, pose, lip
+sync with motion sounds, parallel motions, and hit-area picking. The 2D-object engine of
+[LAPLACE Persona](https://github.com/laplace-live/persona); its WebGPU sibling for three.js is
+[`@laplace.live/three-live2d`](https://www.npmjs.com/package/@laplace.live/three-live2d).
+
+Forked from
+[untitled-pixi-live2d-engine](https://github.com/Untitled-Story/untitled-pixi-live2d-engine)
+`v1.3.5` (itself a PixiJS v8 continuation of the pixi-live2d-display line). Diverges
+deliberately: Cubism 2 support removed, the CubismWebFramework mirrored pristine at tag
+`5-r.5`, and moc3 v6 (Cubism 5.3 offscreens + new blend modes) rendering verified.
+
+## Install
+
+```sh
+npm i @laplace.live/pixijs-live2d pixi.js
+npm i @pixi/sound   # optional — motion sounds / audio lip sync
+```
+
+`pixi.js` ≥ 8.13 is a peer dependency. `@pixi/sound` is an optional peer, dynamic-imported the
+first time audio is used.
+
+## Cubism Core
+
+Live2D Cubism Core (`live2dcubismcore.js`) is Live2D's proprietary runtime and is **not
+bundled**. Download it with the
+[Cubism SDK for Web](https://www.live2d.com/en/sdk/download/web/), serve it yourself, and load
+it **before this package is imported** — the entry throws immediately when
+`window.Live2DCubismCore` is missing. A `<script>` tag ahead of your bundle works; so does
+evaluating Core first and pulling the engine in with a dynamic `import()`. Adding the SDK's
+`live2dcubismcore.d.ts` to your project completes the typings.
+
+## Usage
+
+```ts
+import { Live2DModel } from '@laplace.live/pixijs-live2d'
+import { Application, Ticker } from 'pixi.js'
+
+const app = new Application()
+await app.init({ backgroundAlpha: 0 })
+
+Live2DModel.registerTicker(Ticker) // drive motion updates from pixi's shared ticker
+
+const model = await Live2DModel.from('https://example.com/hiyori/hiyori.model3.json')
+app.stage.addChild(model)
+model.scale.set(0.25)
+
+model.on('hit', (hitAreas) => {
+  if (hitAreas.includes('Body')) model.motion('TapBody')
+})
+```
+
+`@laplace.live/pixijs-live2d/extra` ships `HitAreaFrames`, a debug overlay that draws the
+model's hit areas.
+
+## License
+
+The engine (`src/`) is [MIT](./LICENSE), carrying the upstream fork's copyright alongside ours.
+It compiles in a pristine mirror of
+[Live2D/CubismWebFramework](https://github.com/Live2D/CubismWebFramework), covered by the
+[Live2D Open Software License](https://www.live2d.com/eula/live2d-open-software-license-agreement_en.html)
+— its license text ships in this package at `vendor/cubism/LICENSE.md`. Live2D Cubism Core is
+not included; it is distributed by Live2D under the
+[Live2D Proprietary Software License](https://www.live2d.com/eula/live2d-proprietary-software-license-agreement_en.html),
+and businesses above the revenue threshold also need a
+[Cubism SDK Release License](https://www.live2d.com/en/sdk/license/). Review Live2D's terms
+before shipping a product.

package/dist/extra.d.ts

@@ -0,0 +1,16 @@
+import { Graphics, Renderer, Text } from "pixi.js";
+//#region src/tools/HitAreaFrames.d.ts
+declare class HitAreaFrames extends Graphics {
+  initialized: boolean;
+  texts: Text[];
+  strokeWidth: number;
+  normalColor: number;
+  activeColor: number;
+  constructor();
+  private readonly handleInit;
+  private readonly handlePointerMove;
+  protected _render(renderer: Renderer): void;
+}
+//#endregion
+export { HitAreaFrames };
+//# sourceMappingURL=extra.d.ts.map

package/dist/extra.js

@@ -0,0 +1,75 @@
+import { Graphics, Rectangle, Text, TextStyle } from "pixi.js";
+//#region src/tools/HitAreaFrames.ts
+const tempBounds = new Rectangle();
+var HitAreaFrames = class extends Graphics {
+	initialized = false;
+	texts = [];
+	strokeWidth = 4;
+	normalColor = 14883354;
+	activeColor = 2017330;
+	constructor() {
+		super();
+		this.eventMode = "static";
+		this.on("added", this.handleInit).on("globalpointermove", this.handlePointerMove);
+	}
+	handleInit = () => {
+		const internalModel = this.parent.internalModel;
+		const textStyle = new TextStyle({
+			fontSize: 24,
+			fill: "#ffffff",
+			stroke: {
+				color: "#000000",
+				width: 4
+			}
+		});
+		this.texts = Object.keys(internalModel.hitAreas).map((hitAreaName) => {
+			const text = new Text({
+				text: hitAreaName,
+				style: textStyle
+			});
+			text.visible = false;
+			this.addChild(text);
+			return text;
+		});
+	};
+	handlePointerMove = (e) => {
+		const hitAreaNames = this.parent.hitTest(e.global.x, e.global.y);
+		this.texts.forEach((text) => {
+			text.visible = hitAreaNames.includes(text.text);
+		});
+	};
+	_render(renderer) {
+		const internalModel = this.parent.internalModel;
+		const matrix = this.worldTransform;
+		const scale = 1 / Math.sqrt(matrix.a ** 2 + matrix.b ** 2);
+		this.texts.forEach((text) => {
+			const hitArea = internalModel.hitAreas[text.text];
+			if (!hitArea) return;
+			let drawIndex = hitArea.index;
+			if (drawIndex < 0) {
+				drawIndex = internalModel.getDrawableIndex(hitArea.id);
+				if (drawIndex < 0) return;
+				hitArea.index = drawIndex;
+			}
+			const bounds = internalModel.getDrawableBounds(drawIndex, tempBounds);
+			const transform = internalModel.localTransform;
+			bounds.x = bounds.x * transform.a + transform.tx;
+			bounds.y = bounds.y * transform.d + transform.ty;
+			bounds.width = bounds.width * transform.a;
+			bounds.height = bounds.height * transform.d;
+			this.setStrokeStyle({
+				width: this.strokeWidth * scale,
+				color: text.visible ? this.activeColor : this.normalColor
+			}).rect(bounds.x, bounds.y, bounds.width, bounds.height);
+			text.x = bounds.x + this.strokeWidth * scale;
+			text.y = bounds.y + this.strokeWidth * scale;
+			text.scale.set(scale);
+		});
+		Graphics.prototype._render.call(this, renderer);
+		this.clear();
+	}
+};
+//#endregion
+export { HitAreaFrames };
+
+//# sourceMappingURL=extra.js.map

package/dist/extra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra.js","names":[],"sources":["../src/tools/HitAreaFrames.ts"],"sourcesContent":["// noinspection JSUnusedGlobalSymbols\n\nimport type { Renderer } from 'pixi.js'\nimport { type FederatedPointerEvent, Graphics, Rectangle, Text, TextStyle } from 'pixi.js'\n\nimport type { Live2DModel } from '@/Live2DModel'\n\nconst tempBounds = new Rectangle()\n\nexport class HitAreaFrames extends Graphics {\n  initialized = false\n\n  texts: Text[] = []\n\n  strokeWidth = 4\n  normalColor = 0xe31a1a\n  activeColor = 0x1ec832\n\n  constructor() {\n    super()\n\n    this.eventMode = 'static'\n\n    this.on('added', this.handleInit).on('globalpointermove', this.handlePointerMove)\n  }\n\n  private readonly handleInit = () => {\n    const internalModel = (this.parent as Live2DModel).internalModel\n\n    const textStyle = new TextStyle({\n      fontSize: 24,\n      fill: '#ffffff',\n      stroke: { color: '#000000', width: 4 },\n    })\n\n    this.texts = Object.keys(internalModel.hitAreas).map(hitAreaName => {\n      const text = new Text({\n        text: hitAreaName,\n        style: textStyle,\n      })\n\n      text.visible = false\n\n      this.addChild(text)\n\n      return text\n    })\n  }\n\n  private readonly handlePointerMove = (e: FederatedPointerEvent) => {\n    const hitAreaNames = (this.parent as Live2DModel).hitTest(e.global.x, e.global.y)\n\n    this.texts.forEach(text => {\n      text.visible = hitAreaNames.includes(text.text)\n    })\n  }\n\n  protected _render(renderer: Renderer): void {\n    const internalModel = (this.parent as Live2DModel).internalModel\n\n    // extract scale from the transform matrix, and invert it to ease following calculation\n    // https://math.stackexchange.com/a/13165\n    const matrix = this.worldTransform\n    const scale = 1 / Math.sqrt(matrix.a ** 2 + matrix.b ** 2)\n\n    this.texts.forEach(text => {\n      const hitArea = internalModel.hitAreas[text.text]\n\n      if (!hitArea) {\n        return\n      }\n\n      let drawIndex = hitArea.index\n\n      if (drawIndex < 0) {\n        drawIndex = internalModel.getDrawableIndex(hitArea.id)\n\n        if (drawIndex < 0) {\n          return\n        }\n\n        hitArea.index = drawIndex\n      }\n\n      const bounds = internalModel.getDrawableBounds(drawIndex, tempBounds)\n      const transform = internalModel.localTransform\n\n      bounds.x = bounds.x * transform.a + transform.tx\n      bounds.y = bounds.y * transform.d + transform.ty\n      bounds.width = bounds.width * transform.a\n      bounds.height = bounds.height * transform.d\n\n      this.setStrokeStyle({\n        width: this.strokeWidth * scale,\n        color: text.visible ? this.activeColor : this.normalColor,\n      }).rect(bounds.x, bounds.y, bounds.width, bounds.height)\n\n      text.x = bounds.x + this.strokeWidth * scale\n      text.y = bounds.y + this.strokeWidth * scale\n      text.scale.set(scale)\n    })\n\n    const render = (\n      Graphics.prototype as unknown as {\n        _render: (renderer: Renderer) => void\n      }\n    )._render\n    render.call(this, renderer)\n\n    this.clear()\n  }\n}\n"],"mappings":";;AAOA,MAAM,aAAa,IAAI,UAAU;AAEjC,IAAa,gBAAb,cAAmC,SAAS;CAC1C,cAAc;CAEd,QAAgB,CAAC;CAEjB,cAAc;CACd,cAAc;CACd,cAAc;CAEd,cAAc;EACZ,MAAM;EAEN,KAAK,YAAY;EAEjB,KAAK,GAAG,SAAS,KAAK,UAAU,CAAC,CAAC,GAAG,qBAAqB,KAAK,iBAAiB;CAClF;CAEA,mBAAoC;EAClC,MAAM,gBAAiB,KAAK,OAAuB;EAEnD,MAAM,YAAY,IAAI,UAAU;GAC9B,UAAU;GACV,MAAM;GACN,QAAQ;IAAE,OAAO;IAAW,OAAO;GAAE;EACvC,CAAC;EAED,KAAK,QAAQ,OAAO,KAAK,cAAc,QAAQ,CAAC,CAAC,KAAI,gBAAe;GAClE,MAAM,OAAO,IAAI,KAAK;IACpB,MAAM;IACN,OAAO;GACT,CAAC;GAED,KAAK,UAAU;GAEf,KAAK,SAAS,IAAI;GAElB,OAAO;EACT,CAAC;CACH;CAEA,qBAAsC,MAA6B;EACjE,MAAM,eAAgB,KAAK,OAAuB,QAAQ,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC;EAEhF,KAAK,MAAM,SAAQ,SAAQ;GACzB,KAAK,UAAU,aAAa,SAAS,KAAK,IAAI;EAChD,CAAC;CACH;CAEA,QAAkB,UAA0B;EAC1C,MAAM,gBAAiB,KAAK,OAAuB;EAInD,MAAM,SAAS,KAAK;EACpB,MAAM,QAAQ,IAAI,KAAK,KAAK,OAAO,KAAK,IAAI,OAAO,KAAK,CAAC;EAEzD,KAAK,MAAM,SAAQ,SAAQ;GACzB,MAAM,UAAU,cAAc,SAAS,KAAK;GAE5C,IAAI,CAAC,SACH;GAGF,IAAI,YAAY,QAAQ;GAExB,IAAI,YAAY,GAAG;IACjB,YAAY,cAAc,iBAAiB,QAAQ,EAAE;IAErD,IAAI,YAAY,GACd;IAGF,QAAQ,QAAQ;GAClB;GAEA,MAAM,SAAS,cAAc,kBAAkB,WAAW,UAAU;GACpE,MAAM,YAAY,cAAc;GAEhC,OAAO,IAAI,OAAO,IAAI,UAAU,IAAI,UAAU;GAC9C,OAAO,IAAI,OAAO,IAAI,UAAU,IAAI,UAAU;GAC9C,OAAO,QAAQ,OAAO,QAAQ,UAAU;GACxC,OAAO,SAAS,OAAO,SAAS,UAAU;GAE1C,KAAK,eAAe;IAClB,OAAO,KAAK,cAAc;IAC1B,OAAO,KAAK,UAAU,KAAK,cAAc,KAAK;GAChD,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,GAAG,OAAO,OAAO,OAAO,MAAM;GAEvD,KAAK,IAAI,OAAO,IAAI,KAAK,cAAc;GACvC,KAAK,IAAI,OAAO,IAAI,KAAK,cAAc;GACvC,KAAK,MAAM,IAAI,KAAK;EACtB,CAAC;EAOD,SAJW,UAGT,QACK,KAAK,MAAM,QAAQ;EAE1B,KAAK,MAAM;CACb;AACF"}