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.mdindex 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 lintnpm testnpm run build+npm run build:runtimenpm run e2euv run --with numpy --with pillow --with opencv-python-headless tools/test_build_layers.pyuv run tools/test_agent_tools.pydiff --git a/package.json b/package.jsonindex 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.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.jsonindex 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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*/` } },+ },+});