Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

Build the mesh-avatar package for npm

shinshin8619ca82fee986
diff --git a/AGENTS.md b/AGENTS.md
index 9927f05..9641570 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,6 +17,7 @@ Use Node.js 22.17+ and Python 3.10+ with `uv`. Run:
npm run lint
npm test
npm run build
+npm run build:runtime
npm run e2e
uv run --with numpy --with pillow --with opencv-python-headless tools/test_build_layers.py
uv run tools/test_agent_tools.py
diff --git a/package.json b/package.json
index d3748f3..fb119fe 100644
--- a/package.json
+++ b/package.json
@@ -8,8 +8,9 @@
"dev": "vite --host 127.0.0.1",
"screenshots": "node tools/capture-readme-screenshots.mjs",
"test": "vitest run",
- "lint": "eslint src tests e2e tools/*.mjs packages/runtime/src packages/runtime/tests",
+ "lint": "eslint src tests e2e tools/*.mjs packages/runtime/src packages/runtime/tests packages/runtime/vite.config.ts packages/runtime/*.mjs",
"build": "tsc --noEmit && vite build",
+ "build:runtime": "npm run build -w mesh-avatar",
"e2e": "playwright test",
"validate-rig": "node --experimental-strip-types tools/validate-rig.mjs",
"validate-avatar": "node --experimental-strip-types tools/validate-avatar.mjs",
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
new file mode 100644
index 0000000..ce125a6
--- /dev/null
+++ b/packages/runtime/README.md
@@ -0,0 +1,77 @@
+# mesh-avatar
+
+A WebGL runtime for 2D mesh avatars created with [Mesh Avatar Studio](https://github.com/shinshin86/mesh-avatar-studio). Load a `.mavatar` archive or an avatar folder into a canvas, then control its motion, voice level and expressions.
+
+## Install
+
+```sh
+npm install mesh-avatar
+```
+
+The package is ESM and includes TypeScript declarations. Rendering requires a browser with WebGL. It has no React dependency; the animation loop starts automatically after loading.
+
+## Load an avatar
+
+Place an exported `.mavatar` file in your app's public assets and provide a canvas:
+
+```html
+<canvas id="avatar" width="720" height="960"></canvas>
+```
+
+```js
+import { loadMeshAvatar } from 'mesh-avatar';
+
+const canvas = document.querySelector('#avatar');
+const avatar = await loadMeshAvatar(canvas, '/avatars/character.mavatar');
+```
+
+To load the unpacked folder instead, serve its `rig.json`, `built/` assets and optional `avatar.json` under a folder URL:
+
+```js
+import { loadMeshAvatar } from 'mesh-avatar';
+
+const canvas = document.querySelector('#avatar');
+const avatar = await loadMeshAvatar(canvas, '/avatars/character/');
+```
+
+Use one loading example per canvas. Asset URLs must be reachable by the browser; cross-origin hosting needs the appropriate CORS headers. You can also pass a `URL`, `Blob`, `ArrayBuffer` or `Uint8Array` to `loadMeshAvatar` for an archive.
+
+## Drive the avatar
+
+```js
+// Idle motion and blinking are enabled by default.
+avatar.setAutoIdle(true);
+
+// While your app plays voice audio, feed its normalized loudness (0–1).
+avatar.setSpeaking(true);
+avatar.setVoiceLevel(0.6);
+
+// Set an emotion for the spoken line, or a persistent expression overlay.
+avatar.setEmotion('happy', { playMotion: false });
+avatar.setExpression('smile');
+
+// Apply tracked or posed parameters. Each call replaces the supplied overrides.
+avatar.setParameters({ angleX: 10, gazeX: 0.25 }, 1);
+
+// When the line finishes, return to idle and clear overrides.
+avatar.setVoiceLevel(0);
+avatar.setSpeaking(false);
+avatar.setEmotion(null);
+avatar.setExpression('neutral');
+avatar.setParameters({});
+
+// When removing the canvas or replacing the avatar:
+avatar.destroy();
+```
+
+Emotion tags are `happy`, `sad`, `angry`, `surprised`, `relaxed` and `neutral` (or `null` to reset). Expressions are `neutral`, `smile`, `shy`, `surprise`, `halfLidded`, `angry`, `sad` and `wink`; `LIVE_EXPRESSIONS` exports that list. `PARAMS` exports the parameter IDs, ranges and defaults. Voice methods animate the avatar; your app handles audio playback.
+
+`loadMeshAvatar` releases archives it opens on `destroy()` or load failure; when passed an existing `AvatarPackage` from `openAvatar`, the caller owns it and must call `release()` after its last user is destroyed.
+
+For custom loading or tooling, the package also exports `createMeshAvatar`, `openAvatar`, `packAvatar`, `unpackAvatar`, `validateAvatarFiles`, `parseManifest`, `parseRig`, `validateRig` and lighting settings. See the [avatar format reference](https://github.com/shinshin86/mesh-avatar-studio/blob/main/docs/format.md) for archive contents, validation and compatibility rules.
+
+## License
+
+The runtime is MIT licensed; see [LICENSE](./LICENSE). The browser bundle includes [fflate](https://github.com/101arrowz/fflate), with its MIT notice retained in the bundle.
+
+Avatar artwork has its own license. Miko images and other sample artwork are **not included** in this npm package, and the runtime license does not grant rights to that artwork.
diff --git a/packages/runtime/fix-declarations.mjs b/packages/runtime/fix-declarations.mjs
new file mode 100644
index 0000000..0131d5f
--- /dev/null
+++ b/packages/runtime/fix-declarations.mjs
@@ -0,0 +1,30 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+
+const dist = fileURLToPath(new URL('./dist/', import.meta.url));
+// tsc preserves source module specifiers. Make declaration references valid in NodeNext
+// as well as bundlers, without changing the source imports used by the local tools.
+for (const name of readdirSync(dist, { recursive: true }).filter(name => name.endsWith('.d.ts'))) {
+ const file = resolve(dist, name), text = readFileSync(file, 'utf8');
+ const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+ const edits = [];
+ function visit(node) {
+ if (ts.isStringLiteral(node) && node.text.startsWith('.') && (
+ ((ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) && node.parent.moduleSpecifier === node)
+ || (ts.isLiteralTypeNode(node.parent) && ts.isImportTypeNode(node.parent.parent))
+ )) {
+ const base = resolve(dirname(file), node.text.replace(/\.(?:js|ts)$/, ''));
+ const target = [`${base}.d.ts`, resolve(base, 'index.d.ts')].find(existsSync);
+ if (!target) throw new Error(`Unresolved declaration import in ${name}: ${node.text}`);
+ const path = relative(dirname(file), target).split(sep).join('/').replace(/\.d\.ts$/, '.js');
+ edits.push({ start: node.getStart(source) + 1, end: node.end - 1, path: path.startsWith('.') ? path : `./${path}` });
+ }
+ ts.forEachChild(node, visit);
+ }
+ visit(source);
+ let result = text;
+ for (const edit of edits.sort((a, b) => b.start - a.start)) result = result.slice(0, edit.start) + edit.path + result.slice(edit.end);
+ writeFileSync(file, result);
+}
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
index 3e52ef9..31d3a83 100644
--- a/packages/runtime/package.json
+++ b/packages/runtime/package.json
@@ -3,7 +3,21 @@
"version": "0.1.0",
"type": "module",
"license": "MIT",
+ "description": "A browser WebGL runtime for 2D mesh avatars, with .mavatar archive and folder loading.",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/shinshin86/mesh-avatar-studio.git",
+ "directory": "packages/runtime"
+ },
+ "homepage": "https://github.com/shinshin86/mesh-avatar-studio/tree/main/packages/runtime",
+ "keywords": ["avatar", "2d", "webgl", "animation", "vtuber", "mesh-avatar"],
+ "sideEffects": false,
+ "types": "./dist/index.d.ts",
"files": ["dist", "README.md", "LICENSE"],
+ "scripts": {
+ "build": "vite build && tsc -p tsconfig.build.json && node fix-declarations.mjs",
+ "prepack": "npm run build"
+ },
"exports": {
".": {
"types": "./dist/index.d.ts",
diff --git a/packages/runtime/tsconfig.build.json b/packages/runtime/tsconfig.build.json
new file mode 100644
index 0000000..2c57d8d
--- /dev/null
+++ b/packages/runtime/tsconfig.build.json
@@ -0,0 +1,19 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "allowJs": true,
+ "checkJs": false,
+ "allowImportingTsExtensions": true,
+ "declaration": true,
+ "emitDeclarationOnly": true,
+ "noEmitOnError": true,
+ "rootDir": "src",
+ "outDir": "dist",
+ "types": []
+ },
+ "include": ["src"]
+}
diff --git a/packages/runtime/vite.config.ts b/packages/runtime/vite.config.ts
new file mode 100644
index 0000000..12f6d3c
--- /dev/null
+++ b/packages/runtime/vite.config.ts
@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vite';
+
+const fromHere = (path: string) => fileURLToPath(new URL(path, import.meta.url));
+// The standalone browser bundle includes fflate, so retain its full MIT notice.
+const require = createRequire(import.meta.url);
+const fflateLicense = readFileSync(join(dirname(require.resolve('fflate/package.json')), 'LICENSE'), 'utf8');
+
+export default defineConfig({
+ publicDir: false,
+ esbuild: { legalComments: 'inline' },
+ build: {
+ target: 'es2022',
+ lib: { entry: fromHere('./src/index.ts'), formats: ['es'], fileName: () => 'index.js' },
+ rollupOptions: { output: { banner: `/*! fflate\n${fflateLicense}\n*/` } },
+ },
+});