Skip to content

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

Add native Rust workspace with avatar loading and grid building

shinshin86abcd8dba1ffe
diff --git a/.gitignore b/.gitignore
index 39509ca..d37478a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,4 +9,5 @@ playwright-report/
__pycache__/
projects/
work/
+native/target/
samples/**/review/
diff --git a/native/Cargo.lock b/native/Cargo.lock
new file mode 100644
index 0000000..671c1ee
--- /dev/null
+++ b/native/Cargo.lock
@@ -0,0 +1,280 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "arbitrary"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3bc62ac97cc33321f50863d514c3bc38a453947a8f9e781137e47c7401020aed"
+dependencies = [
+ "derive_arbitrary",
+]
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "crc32fast"
+version = "1.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ba106e844045ddc02c20768ac4b0b7cb45f2cc2ecbd833ac9f5dacb183c2055"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+
+[[package]]
+name = "derive_arbitrary"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b034bd7d5f032402a2479444dcc6f74e36a03f31854d41680fb240ef682a1ac"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "flate2"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide 0.9.1",
+ "zlib-rs",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "indexmap"
+version = "2.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "mesh-avatar-core"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "png",
+ "serde",
+ "serde_json",
+ "zip",
+]
+
+[[package]]
+name = "mesh-avatar-desktop"
+version = "0.1.0"
+
+[[package]]
+name = "mesh-avatar-wgpu"
+version = "0.1.0"
+dependencies = [
+ "mesh-avatar-core",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide 0.8.9",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "zip"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1dcb24d0152526ae49b9b96c1dcf71850ca1e0b882e4e28ed898a93c41334744"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "crossbeam-utils",
+ "indexmap",
+ "memchr",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/native/Cargo.toml b/native/Cargo.toml
new file mode 100644
index 0000000..e4db84c
--- /dev/null
+++ b/native/Cargo.toml
@@ -0,0 +1,17 @@
+[workspace]
+members = ["crates/mesh-avatar-core", "crates/mesh-avatar-wgpu", "apps/mesh-avatar-desktop"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.88"
+publish = false
+
+[workspace.dependencies]
+mesh-avatar-core = { path = "crates/mesh-avatar-core" }
+anyhow = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+png = "0.17"
+zip = { version = "2", default-features = false }
diff --git a/native/apps/mesh-avatar-desktop/Cargo.toml b/native/apps/mesh-avatar-desktop/Cargo.toml
new file mode 100644
index 0000000..cdc6d3e
--- /dev/null
+++ b/native/apps/mesh-avatar-desktop/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "mesh-avatar-desktop"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+publish.workspace = true
diff --git a/native/apps/mesh-avatar-desktop/src/main.rs b/native/apps/mesh-avatar-desktop/src/main.rs
new file mode 100644
index 0000000..e6ef620
--- /dev/null
+++ b/native/apps/mesh-avatar-desktop/src/main.rs
@@ -0,0 +1,3 @@
+fn main() {
+ eprintln!("The desktop avatar app is not implemented yet.");
+}
diff --git a/native/conformance/dump.mjs b/native/conformance/dump.mjs
new file mode 100644
index 0000000..884899f
--- /dev/null
+++ b/native/conformance/dump.mjs
@@ -0,0 +1,60 @@
+// Run with Node.js 22.17+ from any directory: node native/conformance/dump.mjs
+import { existsSync } from 'node:fs';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { registerHooks } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { PNG } from 'pngjs';
+
+// Match the runtime's bundler-style extensionless lighting imports in plain Node.
+const hooks = registerHooks({ resolve(specifier, context, next) {
+ if (specifier.startsWith('.') && !/\.[a-z]+$/i.test(specifier)) {
+ for (const extension of ['.ts', '.js']) {
+ const url = new URL(specifier + extension, context.parentURL);
+ if (existsSync(url)) return next(url.href, context);
+ }
+ }
+ return next(specifier, context);
+} });
+const { createRig } = await import('../../packages/runtime/src/engine/rig.js');
+const { createRenderer } = await import('../../packages/runtime/src/engine/renderer.js');
+const { parseRig } = await import('../../packages/runtime/src/rig/validate.ts');
+hooks.deregister();
+
+const sample = new URL('../../samples/miko-qipao/', import.meta.url);
+const json = async path => JSON.parse(await readFile(new URL(path, sample), 'utf8'));
+const rig = parseRig(await json('rig.json'));
+const metadata = await json('built/layers.json');
+const sprites = await json('built/sprites/sprites.json');
+const { buildGrid } = createRenderer(createRig(rig), rig);
+const plain = mesh => Object.fromEntries(Object.entries(mesh).map(([key, value]) =>
+ [key, ArrayBuffer.isView(value) ? Array.from(value) : value]));
+const grids = [];
+for (const [sprite, rectangles] of [[false, { base: [0, 0, rig.image.width, rig.image.height], ...metadata.layers }], [true, sprites.layers]]) {
+ for (const [name, rect] of Object.entries(rectangles)) {
+ const texture = `${sprite ? 'sprites/' : ''}${name}.png`;
+ const image = PNG.sync.read(await readFile(new URL(`built/${texture}`, sample)));
+ if (image.width !== rect[2] || image.height !== rect[3]) throw new Error(`PNG dimensions do not match ${texture}`);
+ const cell = sprite ? rig.mesh.spriteCell : name === 'base' ? rig.mesh.baseCell
+ : name === 'hand' ? rig.mesh.handCell : name.startsWith('tassel') ? rig.mesh.tasselCell
+ : name.endsWith('_ball') ? rig.mesh.eyeBallCell : rig.mesh.eyeCell;
+ const fine = name === 'base' ? rig.mesh.fine : null;
+ const alpha = Uint8Array.from({ length: image.width * image.height }, (_, i) => image.data[i * 4 + 3]);
+ grids.push({ name, texture, cell, fine, mesh: plain(buildGrid(rect, cell, alpha, image.width, fine)) });
+ }
+}
+
+// Exercise numerical edges independently of the installed sample's geometry/alpha.
+const cases = [
+ { name: 'opaque-standin', rect: [10, 20, 5, 7], cell: 2, alpha: [255], width: 1 },
+ { name: 'transparent', rect: [0, 0, 5, 4], cell: 2, alpha: Array(20).fill(3), width: 5 },
+ { name: 'alpha-border', rect: [2.25, -3.5, 5, 4], cell: 2, alpha: [4, ...Array(19).fill(0)], width: 5 },
+ { name: 'fine-boundary', rect: [1, 2, 12, 10], cell: 4, alpha: [255], width: 1,
+ fine: { x0: 4, x1: 10, y0: 3, y1: 9, cell: 2 } },
+ { name: 'fractional-tail', rect: [0, 0, 4.25, 2.5], cell: 2, alpha: [255], width: 1 },
+].map(input => ({ ...input, fine: input.fine ?? null,
+ mesh: plain(buildGrid(input.rect, input.cell, Uint8Array.from(input.alpha), input.width, input.fine ?? null)) }));
+
+const destination = new URL('../target/conformance/', import.meta.url);
+await mkdir(destination, { recursive: true });
+await writeFile(new URL('grids.json', destination), JSON.stringify({ version: 1, grids, cases }) + '\n');
+console.log(`Wrote ${grids.length} layer/sprite grids and ${cases.length} edge cases to ${fileURLToPath(new URL('grids.json', destination))}`);
diff --git a/native/crates/mesh-avatar-core/Cargo.toml b/native/crates/mesh-avatar-core/Cargo.toml
new file mode 100644
index 0000000..028fa55
--- /dev/null
+++ b/native/crates/mesh-avatar-core/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "mesh-avatar-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+png.workspace = true
+zip.workspace = true
diff --git a/native/crates/mesh-avatar-core/src/engine/grid.rs b/native/crates/mesh-avatar-core/src/engine/grid.rs
new file mode 100644
index 0000000..0e3b2b9
--- /dev/null
+++ b/native/crates/mesh-avatar-core/src/engine/grid.rs
@@ -0,0 +1,163 @@
+//! Layer grids matching the JavaScript renderer's buildGrid.
+
+use crate::rig::FineGrid;
+use anyhow::{ensure, Result};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct Grid {
+ pub rect: [f64; 4],
+ pub cols: usize,
+ pub rows: usize,
+ pub rest: Vec<f32>,
+ pub uv: Vec<f32>,
+ pub pos: Vec<f32>,
+ pub tris: Vec<u32>,
+ pub lines: Vec<u32>,
+}
+
+fn axis(start: f64, len: f64, cell: f64, fine: Option<(f64, f64, f64)>) -> Result<Vec<f64>> {
+ let mut out = vec![start];
+ let mut v = start;
+ while v < start + len - 0.5 {
+ let c = fine
+ .filter(|&(from, to, _)| v >= from && v < to)
+ .map_or(cell, |(_, _, cell)| cell);
+ let next = (start + len).min(v + c);
+ ensure!(next > v, "grid step is below coordinate precision");
+ v = next;
+ out.push(v);
+ }
+ Ok(out)
+}
+
+pub fn build_grid(
+ rect: [f64; 4],
+ cell: f64,
+ alpha: &[u8],
+ alpha_width: usize,
+ fine: Option<&FineGrid>,
+) -> Result<Grid> {
+ let [rx, ry, rw, rh] = rect;
+ ensure!(
+ rect.iter().all(|v| v.is_finite()) && rw > 0.0 && rh > 0.0,
+ "invalid grid rectangle"
+ );
+ ensure!(
+ cell.is_finite() && cell >= 1.0,
+ "grid cell must be at least one pixel"
+ );
+ ensure!(
+ alpha_width > 0 && !alpha.is_empty() && alpha.len().is_multiple_of(alpha_width),
+ "invalid alpha dimensions"
+ );
+ if let Some(fine) = fine {
+ ensure!(fine.cell > 0, "fine cell must be positive");
+ }
+ // Bound allocation and ensure every index fits the JS Uint32Array representation.
+ ensure!(
+ rw <= 65535.0 && rh <= 65535.0,
+ "grid dimensions exceed limits"
+ );
+ let xs = axis(
+ rx,
+ rw,
+ cell,
+ fine.map(|f| (f.x0 as f64, f.x1 as f64, f.cell as f64)),
+ )?;
+ let ys = axis(
+ ry,
+ rh,
+ cell,
+ fine.map(|f| (f.y0 as f64, f.y1 as f64, f.cell as f64)),
+ )?;
+ let cols = xs.len() - 1;
+ let rows = ys.len() - 1;
+ let count = xs
+ .len()
+ .checked_mul(ys.len())
+ .filter(|&n| n <= 4_000_000)
+ .ok_or_else(|| anyhow::anyhow!("grid has too many vertices"))?;
+ let mut rest = Vec::with_capacity(count * 2);
+ let mut uv = Vec::with_capacity(count * 2);
+ for &y in &ys {
+ for &x in &xs {
+ rest.extend([x as f32, y as f32]);
+ uv.extend([((x - rx) / rw) as f32, ((y - ry) / rh) as f32]);
+ }
+ }
+ let mut tris = Vec::new();
+ let mut lines = Vec::new();
+ let alpha_height = alpha.len() / alpha_width;
+ let ax = if alpha_width == 1 { 0.0 } else { 1.0 };
+ for j in 0..rows {
+ for i in 0..cols {
+ let x0 = (((xs[i] - rx).floor() * ax - 2.0).max(0.0) as usize).min(alpha_width);
+ let x1 = (((xs[i + 1] - rx).ceil() * ax + 2.0).max(0.0) as usize).min(alpha_width);
+ let y0 = (((ys[j] - ry).floor() * ax - 2.0).max(0.0) as usize).min(alpha_height);
+ let y1 = (((ys[j + 1] - ry).ceil() * ax + 2.0).max(0.0) as usize).min(alpha_height);
+ let any = (y0..y1).any(|y| {
+ alpha[y * alpha_width + x0..y * alpha_width + x1]
+ .iter()
+ .any(|&a| a > 3)
+ });
+ if !any {
+ continue;
+ }
+ let a = (j * (cols + 1) + i) as u32;
+ let b = a + 1;
+ let c = a + cols as u32 + 1;
+ let d = c + 1;
+ tris.extend([a, b, c, b, d, c]);
+ lines.extend([a, b, a, c, b, c]);
+ if i == cols - 1 {
+ lines.extend([b, d]);
+ }
+ if j == rows - 1 {
+ lines.extend([c, d]);
+ }
+ }
+ }
+ Ok(Grid {
+ rect,
+ cols,
+ rows,
+ pos: rest.clone(),
+ rest,
+ uv,
+ tris,
+ lines,
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn opaque_standin_and_alpha_threshold() {
+ let grid = build_grid([10.0, 20.0, 4.0, 4.0], 2.0, &[255], 1, None).unwrap();
+ assert_eq!((grid.cols, grid.rows), (2, 2));
+ assert_eq!(grid.tris.len(), 24);
+ assert_eq!(&grid.tris[..6], &[0, 1, 3, 1, 4, 3]);
+ assert_eq!(grid.pos, grid.rest);
+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[3], 1, None)
+ .unwrap()
+ .tris
+ .is_empty());
+ assert_eq!(
+ build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[4], 1, None)
+ .unwrap()
+ .tris
+ .len(),
+ 24
+ );
+ }
+
+ #[test]
+ fn rejects_invalid_input() {
+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 0.0, &[255], 1, None).is_err());
+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[255], 0, None).is_err());
+ assert!(build_grid([1e16, 0.0, 4.0, 4.0], 1.0, &[255], 1, None).is_err());
+ }
+}
diff --git a/native/crates/mesh-avatar-core/src/engine/mod.rs b/native/crates/mesh-avatar-core/src/engine/mod.rs
new file mode 100644
index 0000000..f7a1b46
--- /dev/null
+++ b/native/crates/mesh-avatar-core/src/engine/mod.rs
@@ -0,0 +1 @@
+pub mod grid;
diff --git a/native/crates/mesh-avatar-core/src/format.rs b/native/crates/mesh-avatar-core/src/format.rs
new file mode 100644
index 0000000..b4b15dc
--- /dev/null
+++ b/native/crates/mesh-avatar-core/src/format.rs
@@ -0,0 +1,826 @@
+//! Load a built project directory or a stored ZIP .mavatar archive.
+
+use crate::rig::{Eye, Rig};
+use anyhow::{bail, ensure, Context, Result};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::{
+ collections::{BTreeMap, BTreeSet},
+ fs,
+ io::{Cursor, Read, Seek, SeekFrom},
+ path::Path,
+};
+
+const MAX_ENTRIES: usize = 200;
+const MAX_SIZE: u64 = 64 * 1024 * 1024;
+pub type Rect = [u32; 4];
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Manifest {
+ pub format: String,
+ pub version: u32,
+ pub name: String,
+ pub author: Option<String>,
+ pub license: Option<String>,
+ pub thumbnail: Option<String>,
+ pub source: Option<String>,
+ pub studio: Option<Studio>,
+ #[serde(rename = "lipSync")]
+ pub lip_sync: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Studio {
+ pub version: String,
+}
+
+impl Manifest {
+ fn parse(bytes: &[u8]) -> Result<Self> {
+ let m: Self =
+ serde_json::from_slice(bytes).context("avatar.json: invalid manifest JSON")?;
+ ensure!(
+ m.format == "mesh-avatar" && m.version == 1,
+ "avatar.json: unsupported format or version"
+ );
+ ensure!(
+ !m.name.trim().is_empty(),
+ "avatar.json.name must not be empty"
+ );
+ if let Some(studio) = &m.studio {
+ ensure!(
+ !studio.version.trim().is_empty(),
+ "avatar.json.studio.version must not be empty"
+ );
+ }
+ Ok(m)
+ }
+
+ fn default_named(name: String) -> Self {
+ Self {
+ format: "mesh-avatar".into(),
+ version: 1,
+ name,
+ author: None,
+ license: None,
+ thumbnail: None,
+ source: None,
+ studio: None,
+ lip_sync: None,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EyeCurves {
+ pub x0: f64,
+ pub x1: f64,
+ pub top: [f64; 24],
+ pub bot: [f64; 24],
+}
+
+impl EyeCurves {
+ fn matches(&self, eye: &Eye) -> bool {
+ self.x0 == eye.x0 && self.x1 == eye.x1 && self.top == eye.top && self.bot == eye.bot
+ }
+}
+
+fn legacy_version() -> u32 {
+ 1
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LayerMetadata {
+ #[serde(default = "legacy_version")]
+ pub version: u32,
+ pub build: String,
+ pub size: [u32; 2],
+ pub layers: BTreeMap<String, Rect>,
+ pub eyes: [EyeCurves; 2],
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SpriteMetadata {
+ #[serde(default = "legacy_version")]
+ pub version: u32,
+ pub build: String,
+ pub layers: BTreeMap<String, Rect>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Texture {
+ pub width: u32,
+ pub height: u32,
+ /// Straight RGBA, retaining original red/alpha channels for CPU masks.
+ pub rgba: Vec<u8>,
+}
+
+impl Texture {
+ pub fn alpha(&self) -> Vec<u8> {
+ self.rgba.as_chunks::<4>().0.iter().map(|p| p[3]).collect()
+ }
+
+ /// RGBA upload data matching WebGL's premultiplied-alpha texture convention.
+ pub fn premultiplied_rgba(&self) -> Vec<u8> {
+ let mut pixels = self.rgba.clone();
+ for p in pixels.as_chunks_mut::<4>().0 {
+ let alpha = u32::from(p[3]);
+ for c in &mut p[..3] {
+ *c = ((u32::from(*c) * alpha + 127) / 255) as u8;
+ }
+ }
+ pixels
+ }
+
+ pub fn decode(bytes: &[u8]) -> Result<Self> {
+ let mut decoder = png::Decoder::new(Cursor::new(bytes));
+ decoder.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);
+ decoder.set_limits(png::Limits {
+ bytes: MAX_SIZE as usize,
+ });
+ let mut reader = decoder.read_info().context("invalid PNG header")?;
+ let info = reader.info();
+ let rgba_size = u64::from(info.width)
+ .checked_mul(u64::from(info.height))
+ .and_then(|n| n.checked_mul(4))
+ .context("PNG dimensions overflow")?;
+ ensure!(rgba_size <= MAX_SIZE, "decoded PNG exceeds 64 MB");
+ let mut bytes = vec![0; reader.output_buffer_size()];
+ let output = reader
+ .next_frame(&mut bytes)
+ .context("invalid PNG pixels")?;
+ let bytes = &bytes[..output.buffer_size()];
+ let mut rgba = Vec::with_capacity(rgba_size as usize);
+ match output.color_type {
+ png::ColorType::Rgba => rgba.extend_from_slice(bytes),
+ png::ColorType::Rgb => {
+ for p in bytes.as_chunks::<3>().0 {
+ rgba.extend([p[0], p[1], p[2], 255]);
+ }
+ }
+ png::ColorType::Grayscale => {
+ for &v in bytes {
+ rgba.extend([v, v, v, 255]);
+ }
+ }
+ png::ColorType::GrayscaleAlpha => {
+ for p in bytes.as_chunks::<2>().0 {
+ rgba.extend([p[0], p[0], p[0], p[1]]);
+ }
+ }
+ png::ColorType::Indexed => bail!("PNG palette was not expanded"),
+ }
+ Ok(Self {
+ width: output.width,
+ height: output.height,
+ rgba,
+ })
+ }
+}
+
+#[derive(Debug)]
+pub struct AvatarPackage {
+ pub manifest: Manifest,
+ pub rig: Rig,
+ pub layers: LayerMetadata,
+ pub sprites: Option<SpriteMetadata>,
+ /// Keys relative to built/, for example base.png or sprites/mouth_a.png.
+ pub textures: BTreeMap<String, Texture>,
+}
+
+fn check_entry_name(name: &str) -> Result<()> {
+ let b = name.as_bytes();
+ ensure!(
+ !name.is_empty()
+ && !name.starts_with('/')
+ && !name.contains(['\\', '\0'])
+ && !(b.len() >= 2 && b[0].is_ascii_alphabetic() && b[1] == b':')
+ && !name.split('/').any(|s| s == ".."),
+ "unsafe asset path: {name}"
+ );
+ Ok(())
+}
+
+fn bounded_read(reader: impl Read) -> Result<Vec<u8>> {
+ let mut bytes = Vec::new();
+ reader.take(MAX_SIZE + 1).read_to_end(&mut bytes)?;
+ ensure!(bytes.len() as u64 <= MAX_SIZE, "file exceeds 64 MB");
+ Ok(bytes)
+}
+
+// zip's filename map deduplicates names. Check the raw directory first so duplicate
+// entries and inconsistent local headers cannot silently change the loaded avatar.
+fn check_zip_directory(reader: &mut (impl Read + Seek)) -> Result<()> {
+ fn read_at(reader: &mut (impl Read + Seek), offset: u64, size: usize) -> Result<Vec<u8>> {
+ reader.seek(SeekFrom::Start(offset))?;
+ let mut bytes = vec![0; size];
+ reader.read_exact(&mut bytes).context("truncated ZIP")?;
+ Ok(bytes)
+ }
+ let u16_at = |b: &[u8], i| u16::from_le_bytes([b[i], b[i + 1]]);
+ let u32_at = |b: &[u8], i| u32::from_le_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]);
+ let size = reader.seek(SeekFrom::End(0))?;
+ let tail_size = size.min(65557) as usize;
+ ensure!(tail_size >= 22, "truncated ZIP end record");
+ let tail = read_at(reader, size - tail_size as u64, tail_size)?;
+ let end = (0..=tail_size - 22)
+ .rev()
+ .find(|&i| {
+ u32_at(&tail, i) == 0x06054b50 && i + 22 + u16_at(&tail, i + 20) as usize == tail_size
+ })
+ .context("invalid ZIP end record")?;
+ ensure!(
+ u16_at(&tail, end + 4) == 0
+ && u16_at(&tail, end + 6) == 0
+ && u16_at(&tail, end + 8) == u16_at(&tail, end + 10),
+ "multi-disk ZIP is unsupported"
+ );
+ let count = u16_at(&tail, end + 10) as usize;
+ ensure!(
+ count <= MAX_ENTRIES,
+ "archive exceeds {MAX_ENTRIES} entries"
+ );
+ let directory = u64::from(u32_at(&tail, end + 16));
+ let directory_end = directory + u64::from(u32_at(&tail, end + 12));
+ ensure!(
+ directory_end == size - tail_size as u64 + end as u64,
+ "invalid ZIP directory size"
+ );
+ let mut position = directory;
+ let mut seen = BTreeSet::new();
+ for _ in 0..count {
+ ensure!(position + 46 <= directory_end, "truncated ZIP directory");
+ let header = read_at(reader, position, 46)?;
+ ensure!(
+ u32_at(&header, 0) == 0x02014b50,
+ "invalid ZIP directory header"
+ );
+ let name_len = u16_at(&header, 28) as usize;
+ let next = position
+ + 46
+ + name_len as u64
+ + u64::from(u16_at(&header, 30))
+ + u64::from(u16_at(&header, 32));
+ ensure!(next <= directory_end, "truncated ZIP directory entry");
+ let name_bytes = read_at(reader, position + 46, name_len)?;
+ let name = std::str::from_utf8(&name_bytes).context("ZIP filename must be UTF-8")?;
+ check_entry_name(name)?;
+ ensure!(seen.insert(name.to_owned()), "duplicate ZIP entry: {name}");
+ let compressed = u64::from(u32_at(&header, 20));
+ let uncompressed = u64::from(u32_at(&header, 24));
+ let flags = u16_at(&header, 8);
+ ensure!(
+ compressed <= MAX_SIZE && uncompressed <= MAX_SIZE,
+ "ZIP entry {name}: exceeds 64 MB"
+ );
+ ensure!(
+ u16_at(&header, 10) == 0 && compressed == uncompressed,
+ "ZIP entry {name}: expected stored compression"
+ );
+ ensure!(
+ flags & 1 == 0,
+ "ZIP entry {name}: encryption is unsupported"
+ );
+ let offset = u64::from(u32_at(&header, 42));
+ ensure!(offset + 30 <= directory, "invalid local ZIP offset");
+ let local = read_at(reader, offset, 30)?;
+ ensure!(
+ u32_at(&local, 0) == 0x04034b50 && u16_at(&local, 8) == 0 && u16_at(&local, 6) == flags,
+ "inconsistent local ZIP header"
+ );
+ let local_name_len = u16_at(&local, 26) as usize;
+ let start = offset + 30 + local_name_len as u64 + u64::from(u16_at(&local, 28));
+ ensure!(start + uncompressed <= directory, "truncated ZIP payload");
+ ensure!(
+ read_at(reader, offset + 30, local_name_len)? == name_bytes,
+ "inconsistent local ZIP filename"
+ );
+ position = next;
+ }
+ ensure!(position == directory_end, "invalid ZIP entry count");
+ reader.rewind()?;
+ Ok(())
+}
+
+fn unpack(mut reader: impl Read + Seek) -> Result<BTreeMap<String, Vec<u8>>> {
+ check_zip_directory(&mut reader)?;
+ let mut zip = zip::ZipArchive::new(reader).context("invalid .mavatar ZIP")?;
+ ensure!(
+ zip.len() <= MAX_ENTRIES,
+ "archive exceeds {MAX_ENTRIES} entries"
+ );
+ let mut files = BTreeMap::new();
+ for i in 0..zip.len() {
+ let file = zip.by_index(i).context("unreadable ZIP entry")?;
+ let name = std::str::from_utf8(file.name_raw())
+ .context("ZIP filename must be UTF-8")?
+ .to_owned();
+ check_entry_name(&name)?;
+ ensure!(!files.contains_key(&name), "duplicate ZIP entry: {name}");
+ ensure!(
+ file.compression() == zip::CompressionMethod::Stored,
+ "ZIP entry {name}: expected stored compression"
+ );
+ ensure!(
+ file.size() <= MAX_SIZE && file.compressed_size() <= MAX_SIZE,
+ "ZIP entry {name}: exceeds 64 MB"
+ );
+ files.insert(
+ name.clone(),
+ bounded_read(file).with_context(|| format!("ZIP entry {name}"))?,
+ );
+ }
+ ensure!(
+ files.contains_key("avatar.json"),
+ "avatar.json: missing file in .mavatar archive"
+ );
+ Ok(files)
+}
+
+fn validate_rectangles(layers: &BTreeMap<String, Rect>, size: [u32; 2]) -> Result<()> {
+ for (name, &[x, y, w, h]) in layers {
+ ensure!(
+ !name.is_empty()
+ && name
+ .bytes()
+ .all(|c| c.is_ascii_alphanumeric() || c == b'_' || c == b'-'),
+ "unsafe layer name: {name}"
+ );
+ ensure!(
+ w > 0
+ && h > 0
+ && u64::from(x) + u64::from(w) <= u64::from(size[0])
+ && u64::from(y) + u64::from(h) <= u64::from(size[1]),
+ "layer {name}: rectangle must stay inside image"
+ );
+ }
+ Ok(())
+}
+
+impl AvatarPackage {
+ pub fn open(path: impl AsRef<Path>) -> Result<Self> {
+ let path = path.as_ref();
+ if !path.is_dir() {
+ return Self::from_archive(
+ fs::File::open(path).context("could not open avatar archive")?,
+ );
+ }
+ let root = path
+ .canonicalize()
+ .context("could not open avatar folder")?;
+ let read = |name: &str| -> Result<Option<Vec<u8>>> {
+ check_entry_name(name)?;
+ let resolved = match root.join(name).canonicalize() {
+ Ok(path) => path,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+ Err(e) => return Err(e).with_context(|| format!("could not resolve {name}")),
+ };
+ ensure!(
+ resolved.starts_with(&root),
+ "asset escapes project folder: {name}"
+ );
+ Ok(Some(
+ bounded_read(fs::File::open(resolved)?)
+ .with_context(|| format!("could not read {name}"))?,
+ ))
+ };
+ let name = root
+ .file_name()
+ .and_then(|v| v.to_str())
+ .unwrap_or("Avatar")
+ .to_owned();
+ Self::load(read, Some(name))
+ }
+
+ pub fn from_archive(reader: impl Read + Seek) -> Result<Self> {
+ let files = unpack(reader)?;
+ Self::load(|name| Ok(files.get(name).cloned()), None)
+ }
+
+ fn load(
+ read: impl Fn(&str) -> Result<Option<Vec<u8>>>,
+ folder_name: Option<String>,
+ ) -> Result<Self> {
+ let required = |name: &str| read(name)?.with_context(|| format!("{name}: missing file"));
+ let layers: LayerMetadata = serde_json::from_slice(&required("built/layers.json")?)
+ .context("built/layers.json: invalid metadata")?;
+ ensure!(
+ layers.version == 1 && !layers.build.trim().is_empty(),
+ "built/layers.json: unsupported version or empty build"
+ );
+ let mut raw: Value =
+ serde_json::from_slice(&required("rig.json")?).context("rig.json: invalid JSON")?;
+ // Legacy folder rigs can get baked eye curves from layer metadata; archives must contain them.
+ if folder_name.is_some() {
+ if let Some(eyes) = raw.get_mut("eyes").and_then(Value::as_array_mut) {
+ for (eye, curves) in eyes.iter_mut().zip(&layers.eyes) {
+ if let Some(eye) = eye.as_object_mut() {
+ for (key, value) in serde_json::to_value(curves)?.as_object().unwrap() {
+ eye.entry(key.clone()).or_insert_with(|| value.clone());
+ }
+ }
+ }
+ }
+ }
+ let rig = Rig::parse(&serde_json::to_vec(&raw)?)?;
+ ensure!(
+ layers.size == [rig.image.width, rig.image.height],
+ "built/layers.json.size must match rig image dimensions"
+ );
+ validate_rectangles(&layers.layers, layers.size)?;
+ for (curves, eye) in layers.eyes.iter().zip(&rig.eyes) {
+ ensure!(
+ curves.matches(eye),
+ "built/layers.json eyes must match rig eye curves"
+ );
+ }
+ for i in 0..2 {
+ for part in ["ball", "low", "crease", "lash"] {
+ let name = format!("eye{i}_{part}");
+ ensure!(
+ layers.layers.contains_key(&name),
+ "missing required layer: {name}"
+ );
+ }
+ }
+ if rig.hand.is_some() {
+ ensure!(
+ layers.layers.contains_key("hand"),
+ "missing required hand layer"
+ );
+ }
+ for accessory in &rig.accessories {
+ ensure!(
+ layers.layers.contains_key(&accessory.name),
+ "missing accessory layer: {}",
+ accessory.name
+ );
+ }
+ let manifest = match read("avatar.json")? {
+ Some(bytes) => Manifest::parse(&bytes)?,
+ None => Manifest::default_named(folder_name.context("avatar.json: missing manifest")?),
+ };
+ let sprites: Option<SpriteMetadata> = read("built/sprites/sprites.json")?
+ .map(|bytes| {
+ serde_json::from_slice(&bytes)
+ .context("built/sprites/sprites.json: invalid metadata")
+ })
+ .transpose()?;
+ if let Some(sprites) = &sprites {
+ ensure!(
+ sprites.version == 1 && !sprites.build.trim().is_empty(),
+ "sprites metadata: unsupported version or empty build"
+ );
+ validate_rectangles(&sprites.layers, layers.size)?;
+ }
+ let mut image_rects = BTreeMap::from([
+ (
+ "base.png".to_owned(),
+ [0, 0, rig.image.width, rig.image.height],
+ ),
+ (
+ "hairmask.png".to_owned(),
+ [0, 0, rig.image.width, rig.image.height],
+ ),
+ ]);
+ for (name, rect) in &layers.layers {
+ image_rects.insert(format!("{name}.png"), *rect);
+ }
+ if let Some(sprites) = &sprites {
+ for (name, rect) in &sprites.layers {
+ image_rects.insert(format!("sprites/{name}.png"), *rect);
+ }
+ }
+ let mut textures = BTreeMap::new();
+ for (name, rect) in image_rects {
+ let texture = Texture::decode(&required(&format!("built/{name}"))?)
+ .with_context(|| format!("built/{name}"))?;
+ ensure!(
+ [texture.width, texture.height] == [rect[2], rect[3]],
+ "built/{name}: PNG dimensions must match rectangle"
+ );
+ textures.insert(name, texture);
+ }
+ Ok(Self {
+ manifest,
+ rig,
+ layers,
+ sprites,
+ textures,
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::{
+ io::Write,
+ sync::{
+ atomic::{AtomicUsize, Ordering},
+ OnceLock,
+ },
+ };
+
+ fn png_bytes(width: u32, height: u32, color: png::ColorType, pixels: &[u8]) -> Vec<u8> {
+ let mut bytes = Vec::new();
+ {
+ let mut encoder = png::Encoder::new(&mut bytes, width, height);
+ encoder.set_color(color);
+ encoder.set_depth(png::BitDepth::Eight);
+ encoder
+ .write_header()
+ .unwrap()
+ .write_image_data(pixels)
+ .unwrap();
+ }
+ bytes
+ }
+
+ fn fixture() -> BTreeMap<String, Vec<u8>> {
+ static FILES: OnceLock<BTreeMap<String, Vec<u8>>> = OnceLock::new();
+ FILES
+ .get_or_init(|| {
+ let mut files = BTreeMap::from([
+ (
+ "avatar.json".into(),
+ include_bytes!("../../../../samples/miko-qipao/avatar.json").to_vec(),
+ ),
+ (
+ "rig.json".into(),
+ include_bytes!("../../../../samples/miko-qipao/rig.json").to_vec(),
+ ),
+ (
+ "built/layers.json".into(),
+ include_bytes!("../../../../samples/miko-qipao/built/layers.json").to_vec(),
+ ),
+ (
+ "built/sprites/sprites.json".into(),
+ include_bytes!("../../../../samples/miko-qipao/built/sprites/sprites.json")
+ .to_vec(),
+ ),
+ ]);
+ let layers: LayerMetadata =
+ serde_json::from_slice(&files["built/layers.json"]).unwrap();
+ let sprites: SpriteMetadata =
+ serde_json::from_slice(&files["built/sprites/sprites.json"]).unwrap();
+ let mut rects = BTreeMap::from([
+ ("base".to_owned(), [0, 0, layers.size[0], layers.size[1]]),
+ (
+ "hairmask".to_owned(),
+ [0, 0, layers.size[0], layers.size[1]],
+ ),
+ ]);
+ rects.extend(layers.layers);
+ rects.extend(
+ sprites
+ .layers
+ .into_iter()
+ .map(|(n, r)| (format!("sprites/{n}"), r)),
+ );
+ for (name, [_, _, w, h]) in rects {
+ // Synthetic opaque images; the loader tests do not depend on sample PNGs.
+ files.insert(
+ format!("built/{name}.png"),
+ png_bytes(
+ w,
+ h,
+ png::ColorType::Grayscale,
+ &vec![255; (w * h) as usize],
+ ),
+ );
+ }
+ files
+ })
+ .clone()
+ }
+
+ fn archive(files: &BTreeMap<String, Vec<u8>>) -> Vec<u8> {
+ let mut writer = zip::ZipWriter::new(Cursor::new(Vec::new()));
+ for (name, bytes) in files {
+ writer
+ .start_file(
+ name,
+ zip::write::SimpleFileOptions::default()
+ .compression_method(zip::CompressionMethod::Stored),
+ )
+ .unwrap();
+ writer.write_all(bytes).unwrap();
+ }
+ writer.finish().unwrap().into_inner()
+ }
+
+ fn load(files: &BTreeMap<String, Vec<u8>>, folder: bool) -> Result<AvatarPackage> {
+ AvatarPackage::load(
+ |name| Ok(files.get(name).cloned()),
+ folder.then(|| "Test Avatar".to_owned()),
+ )
+ }
+
+ fn edit_json(files: &mut BTreeMap<String, Vec<u8>>, name: &str, edit: impl FnOnce(&mut Value)) {
+ let mut value = serde_json::from_slice(&files[name]).unwrap();
+ edit(&mut value);
+ files.insert(name.into(), serde_json::to_vec(&value).unwrap());
+ }
+
+ struct TestFolder(std::path::PathBuf);
+ impl TestFolder {
+ fn new(files: &BTreeMap<String, Vec<u8>>) -> Self {
+ static NEXT: AtomicUsize = AtomicUsize::new(0);
+ let path = Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("../../target/test-fixtures")
+ .join(format!(
+ "{}-{}",
+ std::process::id(),
+ NEXT.fetch_add(1, Ordering::Relaxed)
+ ));
+ fs::create_dir_all(&path).unwrap();
+ for (name, bytes) in files {
+ let file = path.join(name);
+ fs::create_dir_all(file.parent().unwrap()).unwrap();
+ fs::write(file, bytes).unwrap();
+ }
+ Self(path)
+ }
+ }
+ impl Drop for TestFolder {
+ fn drop(&mut self) {
+ let _ = fs::remove_dir_all(&self.0);
+ }
+ }
+
+ #[test]
+ fn opens_archive_and_folder_with_all_assets() {
+ let files = fixture();
+ let folder = TestFolder::new(&files);
+ let folder_avatar = AvatarPackage::open(&folder.0).unwrap();
+ let archive_path = folder.0.join("avatar.mavatar");
+ fs::write(&archive_path, archive(&files)).unwrap();
+ let packed = AvatarPackage::open(archive_path).unwrap();
+ assert_eq!(packed.manifest.name, folder_avatar.manifest.name);
+ assert_eq!(packed.textures.len(), 29);
+ assert_eq!(packed.textures.len(), folder_avatar.textures.len());
+ for (name, texture) in &packed.textures {
+ assert_eq!(texture.rgba, folder_avatar.textures[name].rgba);
+ }
+ }
+
+ #[test]
+ fn folder_defaults_and_legacy_curves_are_not_archive_defaults() {
+ let mut files = fixture();
+ files.remove("avatar.json");
+ edit_json(&mut files, "rig.json", |v| {
+ for eye in v["eyes"].as_array_mut().unwrap() {
+ for field in ["x0", "x1", "top", "bot"] {
+ eye.as_object_mut().unwrap().remove(field);
+ }
+ }
+ });
+ let avatar = load(&files, true).unwrap();
+ assert_eq!(avatar.manifest.name, "Test Avatar");
+ assert!(avatar.layers.eyes[0].matches(&avatar.rig.eyes[0]));
+ assert!(AvatarPackage::from_archive(Cursor::new(archive(&files))).is_err());
+ files.insert("avatar.json".into(), fixture()["avatar.json"].clone());
+ assert!(load(&files, false).is_err());
+ }
+
+ #[test]
+ fn optional_features_and_unknown_fields_remain_compatible() {
+ let mut files = fixture();
+ files.remove("built/sprites/sprites.json");
+ edit_json(&mut files, "rig.json", |v| {
+ let object = v.as_object_mut().unwrap();
+ for field in ["buns", "strands", "accessories", "hand"] {
+ object.remove(field);
+ }
+ object.insert("futureFeature".into(), serde_json::json!({"enabled": true}));
+ });
+ let avatar = load(&files, false).unwrap();
+ assert!(avatar.sprites.is_none());
+ assert!(avatar.rig.strands.is_empty());
+ assert!(avatar.rig.hand.is_none());
+ }
+
+ #[test]
+ fn rejects_bad_rigs_metadata_and_images() {
+ type Mutation = (&'static str, fn(&mut Value));
+ let mutations: &[Mutation] = &[
+ ("rig.json", |v| v["version"] = 2.into()),
+ ("rig.json", |v| v["head"]["rx"] = 0.into()),
+ ("rig.json", |v| v["mesh"]["baseCell"] = 0.into()),
+ ("rig.json", |v| v["mesh"]["eyeCell"] = 1.5.into()),
+ ("rig.json", |v| v["eyes"][0]["top"] = serde_json::json!([1])),
+ ("rig.json", |v| v["view"]["padSide"] = (-0.5).into()),
+ ("built/layers.json", |v| v["version"] = 2.into()),
+ ("built/layers.json", |v| v["size"][0] = 1.into()),
+ ("built/layers.json", |v| v["eyes"][0]["top"][0] = 0.into()),
+ ("built/layers.json", |v| {
+ v["layers"].as_object_mut().unwrap().remove("eye0_ball");
+ }),
+ ("built/sprites/sprites.json", |v| {
+ v["layers"]["../escape"] = serde_json::json!([0, 0, 1, 1])
+ }),
+ ];
+ for &(name, edit) in mutations {
+ let mut files = fixture();
+ edit_json(&mut files, name, edit);
+ assert!(load(&files, true).is_err(), "accepted invalid {name}");
+ }
+ for name in [
+ "built/base.png",
+ "built/hairmask.png",
+ "built/sprites/mouth_a.png",
+ ] {
+ let mut files = fixture();
+ files.remove(name);
+ assert!(load(&files, true).is_err(), "accepted missing {name}");
+ files.insert(name.into(), vec![1, 2, 3]);
+ assert!(load(&files, true).is_err(), "accepted corrupt {name}");
+ files.insert(
+ name.into(),
+ png_bytes(1, 1, png::ColorType::Grayscale, &[255]),
+ );
+ assert!(
+ load(&files, true).is_err(),
+ "accepted wrong dimensions for {name}"
+ );
+ }
+ }
+
+ #[test]
+ fn rejects_unsafe_archive_entries_and_inconsistent_headers() {
+ for name in ["../evil", "/evil", "C:evil", "built\\evil"] {
+ let files = BTreeMap::from([(name.to_owned(), vec![1])]);
+ assert!(unpack(Cursor::new(archive(&files))).is_err());
+ }
+ let mut data = archive(&BTreeMap::from([
+ ("one".into(), vec![1]),
+ ("two".into(), vec![2]),
+ ]));
+ // Rewrite both occurrences of a same-length filename to create a duplicate.
+ for i in 0..data.len() - 2 {
+ if &data[i..i + 3] == b"two" {
+ data[i..i + 3].copy_from_slice(b"one");
+ }
+ }
+ assert!(unpack(Cursor::new(data))
+ .unwrap_err()
+ .to_string()
+ .contains("duplicate"));
+ let good = archive(&BTreeMap::from([("one".into(), vec![1])]));
+ let mut bad = good.clone();
+ bad[30] = b'x';
+ assert!(unpack(Cursor::new(bad)).is_err());
+ assert!(unpack(Cursor::new(&good[..good.len() - 1])).is_err());
+ let mut too_many = good;
+ let end = too_many.len() - 22;
+ too_many[end + 8..end + 12].copy_from_slice(&[201, 0, 201, 0]);
+ assert!(unpack(Cursor::new(too_many))
+ .unwrap_err()
+ .to_string()
+ .contains("entries"));
+ }
+
+ #[test]
+ fn decodes_png_channels_and_premultiplies_for_upload() {
+ for (color, pixels, expected) in [
+ (
+ png::ColorType::Grayscale,
+ vec![100],
+ vec![100, 100, 100, 255],
+ ),
+ (
+ png::ColorType::GrayscaleAlpha,
+ vec![100, 128],
+ vec![100, 100, 100, 128],
+ ),
+ (png::ColorType::Rgb, vec![20, 40, 60], vec![20, 40, 60, 255]),
+ (
+ png::ColorType::Rgba,
+ vec![20, 40, 60, 128],
+ vec![20, 40, 60, 128],
+ ),
+ ] {
+ let texture = Texture::decode(&png_bytes(1, 1, color, &pixels)).unwrap();
+ assert_eq!(texture.rgba, expected);
+ assert_eq!(texture.alpha(), [expected[3]]);
+ }
+ let texture =
+ Texture::decode(&png_bytes(1, 1, png::ColorType::Rgba, &[20, 40, 60, 128])).unwrap();
+ assert_eq!(texture.premultiplied_rgba(), [10, 20, 30, 128]);
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn rejects_folder_symlinks_outside_project() {
+ let folder = TestFolder::new(&fixture());
+ let outside = TestFolder::new(&BTreeMap::from([("base.png".into(), vec![1])]));
+ fs::remove_file(folder.0.join("built/base.png")).unwrap();
+ std::os::unix::fs::symlink(
+ outside.0.canonicalize().unwrap().join("base.png"),
+ folder.0.join("built/base.png"),
+ )
+ .unwrap();
+ let error = AvatarPackage::open(&folder.0).unwrap_err();
+ assert!(error.to_string().contains("escapes project"));
+ }
+}
diff --git a/native/crates/mesh-avatar-core/src/lib.rs b/native/crates/mesh-avatar-core/src/lib.rs
new file mode 100644
index 0000000..6ba75e5
--- /dev/null
+++ b/native/crates/mesh-avatar-core/src/lib.rs
@@ -0,0 +1,5 @@
+//! Data loading and CPU geometry for mesh avatars.
+
+pub mod engine;
+pub mod format;
+pub mod rig;
diff --git a/native/crates/mesh-avatar-core/src/rig.rs b/native/crates/mesh-avatar-core/src/rig.rs
new file mode 100644
index 0000000..e7c84c0
--- /dev/null
+++ b/native/crates/mesh-avatar-core/src/rig.rs
@@ -0,0 +1,346 @@
+//! Typed rig data. Unknown JSON fields are ignored for forward compatibility.
+
+use anyhow::{ensure, Context, Result};
+use serde::{Deserialize, Serialize};
+
+pub type Point = [f64; 2];
+pub type Band = [f64; 2];
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Ellipse {
+ pub cx: f64,
+ pub cy: f64,
+ pub rx: f64,
+ pub ry: f64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Eye {
+ pub opening: Vec<Point>,
+ pub roi: Vec<Point>,
+ pub x0: f64,
+ pub x1: f64,
+ pub top: [f64; 24],
+ pub bot: [f64; 24],
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Strand {
+ pub name: String,
+ pub nodes: Vec<Point>,
+ pub sigma: f64,
+ pub k: f64,
+ pub max: f64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Accessory {
+ pub name: String,
+ pub pivot: Point,
+ pub tip: Point,
+ pub split: f64,
+ pub r#box: [i64; 4],
+ pub color: AccessoryColor,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AccessoryColor {
+ pub redness: f64,
+ pub min_red: f64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Hand {
+ pub outline: Vec<Point>,
+ pub jaw: Vec<Point>,
+ pub jaw_range: Band,
+ pub background: Vec<Point>,
+ pub elbow: Point,
+ pub wrist: Point,
+ pub knuckle: Point,
+ pub contact: Point,
+ pub forearm_share: f64,
+ pub arm_band: Band,
+ pub wrist_band: Band,
+ pub hand_band: Band,
+ pub finger_x_band: Band,
+ pub finger_y_band: Band,
+ pub pin_band: Band,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ImageSize {
+ pub width: u32,
+ pub height: u32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Head {
+ #[serde(flatten)]
+ pub ellipse: Ellipse,
+ pub shift_x: f64,
+ pub shift_y: f64,
+ pub pivot_x: f64,
+ pub pivot_y: f64,
+ pub max_roll: f64,
+ pub weight_band: Band,
+ pub turn_band: Band,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Body {
+ pub pivot_x: f64,
+ pub pivot_y: f64,
+ pub max_roll: f64,
+ pub breath_band: Band,
+ pub roll_band: Band,
+ pub chest: Ellipse,
+ pub shoulders: Vec<Ellipse>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BandedEllipse {
+ #[serde(flatten)]
+ pub ellipse: Ellipse,
+ pub band: Band,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Face {
+ pub nose: Ellipse,
+ pub mouth: Ellipse,
+ pub eye_a: Ellipse,
+ pub eye_b: Ellipse,
+ pub ear_l: Ellipse,
+ pub ear_r: Ellipse,
+ pub brow: BandedEllipse,
+ pub jaw: BandedEllipse,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Buns {
+ pub bun_l: Option<Ellipse>,
+ pub bun_r: Option<Ellipse>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MouthArea {
+ #[serde(flatten)]
+ pub ellipse: Ellipse,
+ pub angle: f64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Mouth {
+ pub cx: f64,
+ pub cy: f64,
+ pub angle: f64,
+ pub half_len: f64,
+ pub bow: f64,
+ pub area: MouthArea,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FineGrid {
+ pub x0: i64,
+ pub x1: i64,
+ pub y0: i64,
+ pub y1: i64,
+ pub cell: u32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Mesh {
+ pub base_cell: u32,
+ pub fine: FineGrid,
+ pub hand_cell: u32,
+ pub tassel_cell: u32,
+ pub eye_ball_cell: u32,
+ pub eye_cell: u32,
+ pub sprite_cell: u32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct View {
+ pub pad_top: f64,
+ pub pad_side: f64,
+ pub gaze_center: Option<Point>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Rig {
+ pub version: u32,
+ pub image: ImageSize,
+ pub head: Head,
+ pub body: Body,
+ pub face: Face,
+ pub buns: Option<Buns>,
+ pub eyes: [Eye; 2],
+ pub mouth: Mouth,
+ pub cheeks: [Point; 2],
+ #[serde(default)]
+ pub strands: Vec<Strand>,
+ #[serde(default)]
+ pub accessories: Vec<Accessory>,
+ pub hand: Option<Hand>,
+ pub mesh: Mesh,
+ pub view: View,
+}
+
+fn ellipse(e: &Ellipse) -> Result<()> {
+ ensure!(e.rx > 0.0 && e.ry > 0.0, "ellipse radii must be positive");
+ Ok(())
+}
+
+fn band(b: Band) -> Result<()> {
+ ensure!(b[0] < b[1], "band start must be less than end");
+ Ok(())
+}
+
+impl Rig {
+ pub fn parse(bytes: &[u8]) -> Result<Self> {
+ let rig: Self = serde_json::from_slice(bytes).context("rig.json: invalid rig JSON")?;
+ rig.validate().context("rig.json: invalid rig")?;
+ Ok(rig)
+ }
+
+ pub fn validate(&self) -> Result<()> {
+ ensure!(self.version == 1, "only rig version 1 is supported");
+ ensure!(
+ self.image.width > 0 && self.image.height > 0,
+ "image dimensions must be positive"
+ );
+ ellipse(&self.head.ellipse)?;
+ band(self.head.weight_band)?;
+ band(self.head.turn_band)?;
+ band(self.body.breath_band)?;
+ band(self.body.roll_band)?;
+ let f = &self.face;
+ for e in [
+ &self.body.chest,
+ &f.nose,
+ &f.mouth,
+ &f.eye_a,
+ &f.eye_b,
+ &f.ear_l,
+ &f.ear_r,
+ &f.brow.ellipse,
+ &f.jaw.ellipse,
+ &self.mouth.area.ellipse,
+ ]
+ .into_iter()
+ .chain(self.body.shoulders.iter())
+ {
+ ellipse(e)?;
+ }
+ band(f.brow.band)?;
+ band(f.jaw.band)?;
+ if let Some(buns) = &self.buns {
+ for e in [&buns.bun_l, &buns.bun_r].into_iter().flatten() {
+ ellipse(e)?;
+ }
+ }
+ for (i, eye) in self.eyes.iter().enumerate() {
+ ensure!(
+ eye.opening.len() >= 3 && eye.roi.len() >= 3,
+ "eyes[{i}]: polygons need at least three points"
+ );
+ ensure!(eye.x0 < eye.x1, "eyes[{i}]: x1 must exceed x0");
+ ensure!(
+ eye.top.iter().zip(eye.bot).all(|(&a, b)| a <= b),
+ "eyes[{i}]: top must not exceed bottom curve"
+ );
+ }
+ ensure!(self.mouth.half_len > 0.0, "mouth.halfLen must be positive");
+ for s in &self.strands {
+ ensure!(!s.name.trim().is_empty(), "strand name must not be empty");
+ ensure!(
+ s.nodes.len() >= 2 && s.nodes.windows(2).all(|p| p[0] != p[1]),
+ "strand needs distinct consecutive nodes"
+ );
+ ensure!(
+ s.sigma > 0.0 && s.k > 0.0 && s.max > 0.0,
+ "strand sigma/k/max must be positive"
+ );
+ }
+ for a in &self.accessories {
+ ensure!(
+ !a.name.trim().is_empty(),
+ "accessory name must not be empty"
+ );
+ ensure!(
+ a.split > 0.0 && a.split < 1.0,
+ "accessory split must be between zero and one"
+ );
+ ensure!(a.pivot != a.tip, "accessory tip must differ from pivot");
+ let [x0, y0, x1, y1] = a.r#box;
+ ensure!(
+ x0 >= 0
+ && y0 >= 0
+ && x0 < x1
+ && y0 < y1
+ && x1 <= self.image.width as i64
+ && y1 <= self.image.height as i64,
+ "accessory rectangle must stay inside image"
+ );
+ ensure!(
+ (0.0..=1.0).contains(&a.color.redness),
+ "accessory redness must be between zero and one"
+ );
+ }
+ if let Some(h) = &self.hand {
+ ensure!(
+ h.outline.len() >= 3 && h.background.len() >= 3 && h.jaw.len() >= 2,
+ "invalid hand polygons or jaw"
+ );
+ ensure!(
+ (0.0..=1.0).contains(&h.forearm_share),
+ "hand forearmShare must be between zero and one"
+ );
+ for b in [
+ h.jaw_range,
+ h.arm_band,
+ h.wrist_band,
+ h.hand_band,
+ h.finger_x_band,
+ h.finger_y_band,
+ h.pin_band,
+ ] {
+ band(b)?;
+ }
+ }
+ let m = &self.mesh;
+ ensure!(
+ [
+ m.base_cell,
+ m.fine.cell,
+ m.hand_cell,
+ m.tassel_cell,
+ m.eye_ball_cell,
+ m.eye_cell,
+ m.sprite_cell
+ ]
+ .iter()
+ .all(|&n| n > 0),
+ "mesh cells must be positive"
+ );
+ ensure!(
+ m.fine.x0 < m.fine.x1 && m.fine.y0 < m.fine.y1,
+ "fine rectangle must have positive area"
+ );
+ ensure!(
+ self.view.pad_top > -1.0 && self.view.pad_top < 1.0 && self.view.pad_side > -0.5,
+ "view margins must leave a positive viewport"
+ );
+ Ok(())
+ }
+}
diff --git a/native/crates/mesh-avatar-core/tests/conformance.rs b/native/crates/mesh-avatar-core/tests/conformance.rs
new file mode 100644
index 0000000..7c2c310
--- /dev/null
+++ b/native/crates/mesh-avatar-core/tests/conformance.rs
@@ -0,0 +1,78 @@
+use mesh_avatar_core::{
+ engine::grid::{build_grid, Grid},
+ format::AvatarPackage,
+ rig::FineGrid,
+};
+use serde::Deserialize;
+use std::{fs, path::Path};
+
+#[derive(Deserialize)]
+struct Golden {
+ version: u32,
+ grids: Vec<Layer>,
+ cases: Vec<Case>,
+}
+
+#[derive(Deserialize)]
+struct Layer {
+ name: String,
+ texture: String,
+ cell: f64,
+ fine: Option<FineGrid>,
+ mesh: Grid,
+}
+
+#[derive(Deserialize)]
+struct Case {
+ name: String,
+ rect: [f64; 4],
+ cell: f64,
+ alpha: Vec<u8>,
+ width: usize,
+ fine: Option<FineGrid>,
+ mesh: Grid,
+}
+
+#[test]
+fn every_sample_grid_matches_javascript_exactly() {
+ let native = Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
+ let golden_path = native.join("target/conformance/grids.json");
+ let bytes = match fs::read(&golden_path) {
+ Ok(bytes) => bytes,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+ eprintln!("Grid goldens absent; skipping. Run node native/conformance/dump.mjs first.");
+ return;
+ }
+ Err(e) => panic!("could not read grid goldens: {e}"),
+ };
+ let golden: Golden = serde_json::from_slice(&bytes).unwrap();
+ assert_eq!(golden.version, 1);
+ let avatar = AvatarPackage::open(native.join("../samples/miko-qipao")).unwrap();
+ assert_eq!(
+ golden.grids.len(),
+ 1 + avatar.layers.layers.len() + avatar.sprites.as_ref().unwrap().layers.len()
+ );
+ for layer in golden.grids {
+ let texture = &avatar.textures[&layer.texture];
+ let actual = build_grid(
+ layer.mesh.rect,
+ layer.cell,
+ &texture.alpha(),
+ texture.width as usize,
+ layer.fine.as_ref(),
+ )
+ .unwrap();
+ assert_eq!(actual, layer.mesh, "grid mismatch for {}", layer.name);
+ }
+ for case in golden.cases {
+ let actual = build_grid(
+ case.rect,
+ case.cell,
+ &case.alpha,
+ case.width,
+ case.fine.as_ref(),
+ )
+ .unwrap();
+ assert_eq!(actual, case.mesh, "grid mismatch for {}", case.name);
+ }
+}
diff --git a/native/crates/mesh-avatar-wgpu/Cargo.toml b/native/crates/mesh-avatar-wgpu/Cargo.toml
new file mode 100644
index 0000000..fab5168
--- /dev/null
+++ b/native/crates/mesh-avatar-wgpu/Cargo.toml
@@ -0,0 +1,9 @@
+[package]
+name = "mesh-avatar-wgpu"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+[dependencies]
+mesh-avatar-core.workspace = true
diff --git a/native/crates/mesh-avatar-wgpu/src/lib.rs b/native/crates/mesh-avatar-wgpu/src/lib.rs
new file mode 100644
index 0000000..bf7c711
--- /dev/null
+++ b/native/crates/mesh-avatar-wgpu/src/lib.rs
@@ -0,0 +1,3 @@
+//! GPU rendering support for mesh avatars.
+//!
+//! The renderer is not implemented yet.