humanforge 0.4.0 → 0.5.0

package/README.md

@@ -33,6 +33,7 @@ npm run build:human -- mpfb2/src/mpfb/data mh_assets \
   --extra mh_hair01 --extra mh_dress01 --extra mh_suits01  # -> assets/human (~26 MB, all options)
 npm run build:garments                                     # + modest wear and dresses (below)
 npm run build:previews                                     # thumbnails + swatches for every option (needs Chrome)
+npm run build:mobile -- --skin-2k                          # JPEG/PNG texture pack for Expo (no WebP in expo-gl)
 ```
 
 Leave out the `--extra` packs for the system set only (~14 MB). Every item loads on demand, so
@@ -63,24 +64,83 @@ npx expo install expo-gl expo-file-system three fflate
 ```tsx
 import { HumanView, useHumanPackage } from 'humanforge';
 
-const { pkg } = useHumanPackage('https://cdn.example.com/human');
-if (!pkg) return <Loading />;
+const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.5.0/assets/human';
+
+function Avatar({ config }) {
+  // ready = the first textured frame can be painted (manifest, body, and this look's
+  // hair/clothes/skin/eyes are on disk), not just "manifest loaded"
+  const { pkg, ready, progress } = useHumanPackage(ASSETS, { config, textureSize: '1k' });
+  if (!pkg || !ready) return <Loading progress={progress} />;
+  return (
+    <HumanView
+      pkg={pkg}
+      config={config}
+      framing="face"                 // or "body"
+      textureSize="1k"               // see the table below
+      expressions={{ mouthSmile: 0.6 }}
+      onReady={() => SplashScreen.hideAsync()}   // fires once, after the first textured frame
+      style={{ width: 240, height: 240, borderRadius: 120 }}
+    />
+  );
+}
+```
 
-<HumanView
-  pkg={pkg}
-  framing="face"                     // or "body"
-  textureSize="1k"                   // "2k" for the editor screen
-  config={{ gender: 0.1, age: 0.2, african: 1, asian: 0, caucasian: 0,
-            skin: 'young_african_female', hair: 'afro01', hairColor: '#1a120c',
-            detail: { noseWidth: 0.3, eyeSize: 0.2 },
-            clothes: ['female_casualsuit01', 'shoes01'] }}
-  expressions={{ mouthSmile: 0.6 }}
-  style={{ width: 240, height: 240, borderRadius: 120 }}
-/>
+A ref gives you `avatar` (bones, `setExpression`), `render()` and `snapshot()` (PNG file URI).
+
+#### Textures on Expo: the mobile pack
+
+expo-gl uploads images through stb_image, which **can't decode WebP**: a WebP texture leaves the
+mesh black with only the lights showing. The asset package therefore ships a **mobile texture
+pack** with the same textures as baseline JPEG (opaque) and paletted PNG (hair, lashes, lace),
+in three tiers. `useHumanPackage`, `preloadHumanPackage` and `expoLoadOptions` select it
+automatically (`textureFormat: 'mobile'`); the web keeps using WebP. Nothing is converted on the
+device, and nothing large goes into your app or the npm package: files download from the CDN
+on demand and stay in the app's cache directory (offline on later launches).
+
+| `textureSize` | Max edge | Use for | First-look download* |
+| --- | --- | --- | --- |
+| `'512'` | 512 px | lists, chat bubbles, avatars under ~120 pt | ~0.8 MB |
+| `'1k'` (default) | 1024 px | profile, bust/face framing; at phone sizes this matches web 2k | ~1.2 MB |
+| `'2k'` | 2048 px (skins) | full-screen face close-ups, tablets | ~1.3 MB |
+
+\* meshes + textures of a default look (hair, outfit, shoes, skin, eyes, brows, lashes); the
+shared body and shape data add ~1.45 MB once. Brows, lashes and eye textures are small at every
+tier; textures are never upscaled.
+
+On the jsDelivr setup the pack lives on its own git tag (`mobile-v0.5.0`), because jsDelivr serves
+GitHub versions only up to 50 MB; `manifest.mobileTextures.baseUrl` points there, so you only pass
+the main URL. Self-hosting: run `npm run build:mobile` and upload `assets/human/mobile/` next to
+`manifest.json` (or pass `mobileBaseUrl`).
+
+#### Preload during the splash screen
+
+```tsx
+import { preloadHumanPackage } from 'humanforge';
+
+// resolves when the files are on disk, so the first <HumanView> paints textured at once
+await preloadHumanPackage(ASSETS, { config: savedAvatar, textureSize: '1k', onProgress: (done, total) => {} });
 ```
 
-Files are cached in the app's cache directory, so later launches work offline. A ref gives you
-`avatar` (bones, `setExpression`), `render()` and `snapshot()` (PNG file URI).
+It shares its cache with `useHumanPackage` (same URL = same package, no second download).
+
+#### Performance knobs
+
+| `HumanView` prop | Default | Notes |
+| --- | --- | --- |
+| `textureSize` | `'1k'` | tiers above |
+| `pixelRatio` | device (max 3) | `2` on 3x phones renders ~55% fewer pixels and still looks sharp |
+| `antialias` | `true` | MSAA (expo-gl `msaaSamples` on iOS) |
+| `maxTextureAnisotropy` | `2` | `1` turns it off |
+| `normalMaps` | `true` | `false` skips clothing normal maps (lighter, slightly flatter fabric) |
+
+Slider, color and expression changes reuse the textures already on the GPU: only a new item
+(hair, outfit, skin tone) or a new tier loads files. `onReady` fires once per avatar, after the
+first frame with all textures; it does not fire again on later edits.
+
+Recommended: editor screen `textureSize="1k"` (or `'2k'` on tablets), lists and thumbnails
+`'512'` with `pixelRatio={2}`. For option pickers, use the static preview images and swatches
+(`getHumanCatalog`, below) rather than live 3D views: they are small WebP files shown with
+`<Image>`, which uses the platform decoder (WebP is fine there).
 
 ### 3. React / web
 
@@ -111,7 +171,7 @@ import { HumanEditor, useHumanPackage } from 'humanforge/web';
 // React Native (Expo)
 import { HumanEditor, useHumanPackage } from 'humanforge/native';
 
-const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.4.0/assets/human';
+const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.5.0/assets/human';
 const { pkg } = useHumanPackage(ASSETS);
 
 <HumanEditor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanforge",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Open-source avatar SDK for React and React Native: realistic MakeHuman-based humans (CC0) plus a tiny procedural low-poly mode.",
   "license": "MIT",
   "author": "abdulrehman043",
@@ -52,7 +52,8 @@
     "typecheck": "tsc --noEmit",
     "test": "tsx scripts/smoke.ts && tsx scripts/human-smoke.mts && tsx scripts/fit-test.mts && tsx scripts/editor-test.mts",
     "build:facemap": "tsx tools/build-facemap.mts",
-    "build:previews": "tsx tools/build-previews.mts"
+    "build:previews": "tsx tools/build-previews.mts",
+    "build:mobile": "tsx tools/build-mobile-textures.mts"
   },
   "peerDependencies": {
     "@gltf-transform/core": ">=4",

package/src/human/runtime.ts

@@ -82,6 +82,17 @@ export interface HumanManifest {
   /** Iris color and round iris thumbnail per eye color (tools/build-previews.mts). */
   eyeOptions?: Record<string, { swatch: string; preview: string }>;
   textureSizes: { skin1k: number; skin2k: number; eyes: number };
+  /**
+   * JPEG/PNG copies of every WebP texture for decoders without WebP (expo-gl's stb_image),
+   * from tools/build-mobile-textures.mts. Files: `<baseUrl or dir>/<key>_<tier>.<ext>`.
+   */
+  mobileTextures?: {
+    dir: string;
+    /** Absolute URL of the pack when it is hosted apart from the manifest (e.g. a separate CDN tag). */
+    baseUrl?: string;
+    tiers: Record<TextureTier, number>;
+    files: Record<string, { ext: 'jpg' | 'png'; max: number }>;
+  };
   expressions: Record<string, string>;
 }
 interface Morph { idx: Uint16Array; d: Int16Array; scale: number }
@@ -89,6 +100,13 @@ interface Morph { idx: Uint16Array; d: Int16Array; scale: number }
 /** Loads a texture from a URL. `size` is the known square size (React Native needs it up front). */
 export type HumanTextureLoader = (url: string, size: number) => Promise<Texture>;
 
+/** Texture quality tier: max texture edge 512 / 1024 / 2048 px (smaller sources are never upscaled). */
+export type TextureTier = '512' | '1k' | '2k';
+/** 'webp': the web files. 'mobile': the JPEG/PNG pack (needed by expo-gl, which can't decode WebP). */
+export type TextureFormat = 'webp' | 'mobile';
+const TIER_PX: Record<TextureTier, number> = { '512': 512, '1k': 1024, '2k': 2048 };
+const tierFor = (px: number): TextureTier => (px >= 2048 ? '2k' : px >= 1024 ? '1k' : '512');
+
 export const webTextureLoader: HumanTextureLoader = async (url) => new TextureLoader().loadAsync(url);
 
 export interface HumanPackage {
@@ -101,12 +119,21 @@ export interface HumanPackage {
   fetchBinary: (url: string) => Promise<ArrayBuffer>;
   proxyCache: Map<string, Promise<GlbPrimitive>>;
   textureCache: Map<string, Promise<Texture>>;
+  textureFormat: TextureFormat;
+  /** URL and pixel size of a texture key ('skins/<id>', 'eyes/<id>', 'textures/<name>') at a tier. */
+  resolveTexture(key: string, tier: TextureTier, nativeSize: number): { url: string; size: number };
+  /** Load (once per URL) a texture by key and tier. */
+  getTexture(key: string, tier: TextureTier, nativeSize: number): Promise<Texture>;
 }
 
 export interface LoadOptions {
   loadTexture?: HumanTextureLoader;
   /** Override fetching (e.g. for an offline cache). Must return the raw (still gzipped) bytes. */
   fetch?: (url: string) => Promise<ArrayBuffer>;
+  /** Texture files to use. Default 'webp'; the Expo loaders use 'mobile' (falls back to WebP if the pack is missing). */
+  textureFormat?: TextureFormat;
+  /** Where the mobile pack lives. Default: manifest.mobileTextures.baseUrl, else `<baseUrl>/mobile`. */
+  mobileBaseUrl?: string;
 }
 
 /** Undo build-human's wrapping delta coding + byte planes. */
@@ -157,12 +184,109 @@ export async function loadHumanPackage(baseUrl: string, opts: LoadOptions = {}):
     }
     morphs.set(m.name, { idx, d, scale: m.scale });
   }
+  const loadTexture = opts.loadTexture ?? webTextureLoader;
+  const mobile = manifest.mobileTextures;
+  const textureFormat: TextureFormat = opts.textureFormat === 'mobile' && mobile ? 'mobile' : 'webp';
+  if (opts.textureFormat === 'mobile' && !mobile) console.warn('humanforge: this asset package has no mobile texture pack (npm run build:mobile); using WebP');
+  const mobileBase = (opts.mobileBaseUrl ?? mobile?.baseUrl ?? `${root}/${mobile?.dir ?? 'mobile'}`).replace(/\/$/, '');
+  const textureCache = new Map<string, Promise<Texture>>();
+  const resolveTexture = (key: string, tier: TextureTier, nativeSize: number) => {
+    const entry = textureFormat === 'mobile' ? mobile!.files[key] : undefined;
+    if (entry) {
+      const px = Math.min(TIER_PX[tier], entry.max, nativeSize);
+      return { url: `${mobileBase}/${key}_${tierFor(px)}.${entry.ext}`, size: px };
+    }
+    // WebP: skins come in 1k and 2k; everything else at its native size
+    if (key.startsWith('skins/')) return tier === '2k' ? { url: `${root}/${key}_2k.webp`, size: manifest.textureSizes.skin2k } : { url: `${root}/${key}_1k.webp`, size: manifest.textureSizes.skin1k };
+    return { url: `${root}/${key}.webp`, size: nativeSize };
+  };
+  const getTexture = (key: string, tier: TextureTier, nativeSize: number) => {
+    const { url, size } = resolveTexture(key, tier, nativeSize);
+    let t = textureCache.get(url);
+    if (!t) {
+      t = loadTexture(url, size).then((tex) => {
+        tex.colorSpace = key.endsWith('_n') ? '' : SRGBColorSpace;
+        tex.flipY = false;
+        tex.needsUpdate = true;
+        return tex;
+      });
+      textureCache.set(url, t);
+      t.catch(() => textureCache.delete(url));
+    }
+    return t;
+  };
+  return {
+    baseUrl: root, manifest, base, morphs, body: readGlb(bodyBuf), loadTexture,
+    fetchBinary, proxyCache: new Map(), textureCache, textureFormat, resolveTexture, getTexture,
+  };
+}
+
+/** Texture key of a proxy texture path ('textures/hair-bob02.webp' -> 'textures/hair-bob02'). */
+const keyOf = (file: string) => file.replace(/\.(webp|png|jpe?g)$/, '');
+
+/**
+ * Every file a config needs for its first textured frame (proxy meshes + textures), so apps can
+ * download them ahead of time. Used by preloadHumanPackage.
+ */
+export function humanAssetsFor(pkg: HumanPackage, config: Partial<HumanConfig>, opts: { textureSize?: TextureTier; normalMaps?: boolean } = {}) {
+  const c = { ...DEFAULT_HUMAN, ...config } as HumanConfig;
+  const tier = opts.textureSize ?? '1k';
+  const ids = ['eyes-high-poly', 'teeth-teeth_base', 'tongue-tongue01'];
+  if (c.eyebrows) ids.push(`eyebrows-${c.eyebrows}`);
+  if (c.eyelashes) ids.push(`eyelashes-${c.eyelashes}`);
+  const metaOf = (id: string) => pkg.manifest.proxies.find((p) => `${p.kind}-${p.id}` === id);
+  const hidden = c.clothes.some((id) => metaOf(`clothes-${id}`)?.hidesHair);
+  if (c.hair && !hidden) ids.push(`hair-${c.hair}`);
+  for (const id of c.clothes) ids.push(`clothes-${id}`);
+  const proxies = ids.map(metaOf).filter((p): p is ProxyMeta => !!p);
+  const textures: { key: string; nativeSize: number }[] = [
+    { key: `skins/${c.skin}`, nativeSize: pkg.manifest.textureSizes.skin2k },
+    { key: `eyes/${c.eyes}`, nativeSize: pkg.manifest.textureSizes.eyes },
+  ];
+  for (const p of proxies) {
+    if (p.texture) textures.push({ key: keyOf(p.texture), nativeSize: p.textureSize });
+    if (p.normalTexture && opts.normalMaps !== false) textures.push({ key: keyOf(p.normalTexture), nativeSize: 1024 });
+  }
   return {
-    baseUrl: root, manifest, base, morphs, body: readGlb(bodyBuf), loadTexture: opts.loadTexture ?? webTextureLoader,
-    fetchBinary, proxyCache: new Map(), textureCache: new Map(),
+    meshes: proxies.map((p) => ({ id: `${p.kind}-${p.id}`, url: `${pkg.baseUrl}/${p.file}` })),
+    textures: textures.map((t) => ({ ...t, ...pkg.resolveTexture(t.key, tier, t.nativeSize) })),
   };
 }
 
+export interface PreloadOptions extends LoadOptions {
+  /** The look to warm up (default DEFAULT_HUMAN): its hair, clothes, skin and eyes are downloaded too. */
+  config?: Partial<HumanConfig>;
+  textureSize?: TextureTier;
+  normalMaps?: boolean;
+  onProgress?: (done: number, total: number) => void;
+}
+
+/**
+ * Load the package and download everything the first textured frame of `config` needs. Resolves
+ * when those files are fetched (and, with the Expo loaders, on disk), not just the manifest.
+ */
+export async function preloadHumanPackage(baseUrl: string, opts: PreloadOptions = {}): Promise<HumanPackage> {
+  const pkg = await loadHumanPackage(baseUrl, opts);
+  await warmHumanPackage(pkg, opts);
+  return pkg;
+}
+
+/** Download the meshes and textures for a config into the package caches (see preloadHumanPackage). */
+export async function warmHumanPackage(pkg: HumanPackage, opts: Omit<PreloadOptions, keyof LoadOptions> = {}) {
+  const { meshes, textures } = humanAssetsFor(pkg, opts.config ?? {}, opts);
+  const total = meshes.length + textures.length;
+  let done = 0;
+  const tick = () => opts.onProgress?.(++done, total);
+  await Promise.all([
+    ...meshes.map(async (m) => {
+      let p = pkg.proxyCache.get(m.id);
+      if (!p) { p = pkg.fetchBinary(m.url).then(readGlb); pkg.proxyCache.set(m.id, p); p.catch(() => pkg.proxyCache.delete(m.id)); }
+      await p; tick();
+    }),
+    ...textures.map(async (t) => { await pkg.getTexture(t.key, opts.textureSize ?? '1k', t.nativeSize); tick(); }),
+  ]);
+}
+
 // ---------------------------------------------------------------- shape evaluation
 const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
 
@@ -295,7 +419,12 @@ export class HumanAvatar {
   private exprDeltas: Float32Array[];
   private skinMat: MeshStandardMaterial;
   private version = 0;
-  textureSize: '1k' | '2k' = '2k';
+  /** Texture tier; set before the first setConfig (changing it later reloads textures). */
+  textureSize: TextureTier = '2k';
+  /** Anisotropic filtering for textures (1 = off). Lower is cheaper on phones. */
+  anisotropy = 4;
+  /** Load clothing normal maps. Turn off for lighter mobile materials. */
+  normalMaps = true;
 
   constructor(pkg: HumanPackage) {
     this.pkg = pkg;
@@ -358,8 +487,8 @@ export class HumanAvatar {
       return [slot, await this.loadProxy(id)] as const;
     });
     const sizes = this.pkg.manifest.textureSizes;
-    const skin = this.texture(`skins/${c.skin}_${this.textureSize}.webp`, this.textureSize === '2k' ? sizes.skin2k : sizes.skin1k);
-    const eyes = this.texture(`eyes/${c.eyes}.webp`, sizes.eyes);
+    const skin = this.texture(`skins/${c.skin}`, sizes.skin2k);
+    const eyes = this.texture(`eyes/${c.eyes}`, sizes.eyes);
     const loaded = await Promise.all(loads);
     const [skinTex, eyeTex] = await Promise.all([skin, eyes]);
     if (v !== this.version) return; // a newer setConfig superseded this one
@@ -371,14 +500,17 @@ export class HumanAvatar {
       this.group.add(entry[1].mesh);
       if (entry[1].soft) this.group.add(entry[1].soft);
     }
-    this.skinMat.map = skinTex;
+    // only touch the material when the texture really changed (slider edits keep the same one)
+    if (this.skinMat.map !== skinTex) {
+      if (!this.skinMat.map) this.skinMat.needsUpdate = true; // null -> texture changes the shader
+      this.skinMat.map = skinTex;
+    }
     this.skinMat.color.set(c.skinTint);
-    this.skinMat.needsUpdate = true;
     for (const [slot, p] of this.proxies) {
       const m = p.mesh.material as MeshStandardMaterial;
       if (slot === 'hair') { m.color.set(c.hairColor); (p.soft?.material as MeshStandardMaterial | undefined)?.color.set(c.hairColor); }
       if (slot === 'eyebrows') m.color.set(c.eyebrowColor);
-      if (slot === 'eyes' && m.map !== eyeTex) { m.map = eyeTex; m.needsUpdate = true; }
+      if (slot === 'eyes' && m.map !== eyeTex) { if (!m.map) m.needsUpdate = true; m.map = eyeTex; }
       if (p.meta.kind === 'clothes' && p.meta.tintable) m.color.set(c.garmentColors?.[clothingInfo(p.meta.id).slot] ?? p.meta.color ?? '#ffffff');
     }
     this.reshape();
@@ -386,6 +518,30 @@ export class HumanAvatar {
 
   getConfig(): HumanConfig { return this.config; }
 
+  /**
+   * Re-apply textures after changing textureSize, anisotropy or normalMaps (meshes stay as they
+   * are; already-loaded files come from the cache).
+   */
+  async reloadTextures() {
+    const c = this.config, sizes = this.pkg.manifest.textureSizes;
+    const v = this.version;
+    const [skin, eyes] = await Promise.all([this.texture(`skins/${c.skin}`, sizes.skin2k), this.texture(`eyes/${c.eyes}`, sizes.eyes)]);
+    const maps = await Promise.all([...this.proxies.values()].map(async (p) => [p,
+      p.meta.texture ? await this.texture(keyOf(p.meta.texture), p.meta.textureSize) : null,
+      p.meta.normalTexture && this.normalMaps ? await this.texture(keyOf(p.meta.normalTexture), 1024) : null] as const));
+    if (v !== this.version) return; // a setConfig happened meanwhile and used the new settings
+    this.skinMat.map = skin;
+    for (const [p, map, normal] of maps) {
+      for (const m of [p.mesh.material, p.soft?.material].filter(Boolean) as MeshStandardMaterial[]) {
+        const shaderChange = !!m.normalMap !== !!normal;
+        if (p.meta.tileable) for (const t of [map, normal]) if (t && t.wrapS !== RepeatWrapping) { t.wrapS = t.wrapT = RepeatWrapping; t.needsUpdate = true; }
+        if (p.meta.kind === 'eyes') m.map = eyes; else if (map) m.map = map;
+        m.normalMap = normal;
+        if (shaderChange) m.needsUpdate = true;
+      }
+    }
+  }
+
   /** Expression by ARKit-style name (e.g. 'jawOpen', 'mouthSmile') or MPFB unit name, weight 0..1. */
   setExpression(name: string, weight: number) {
     const unit = this.exprNames.findIndex((u) => u === name || this.alias(u) === name);
@@ -396,20 +552,11 @@ export class HumanAvatar {
   }
   get expressionNames() { return this.exprNames.map((u) => this.alias(u)); }
 
-  private texture(file: string, size: number): Promise<Texture> {
-    const url = `${this.pkg.baseUrl}/${file}`;
-    let t = this.pkg.textureCache.get(url);
-    if (!t) {
-      t = this.pkg.loadTexture(url, size).then((tex) => {
-        tex.colorSpace = file.endsWith('_n.webp') ? '' : SRGBColorSpace;
-        tex.flipY = false;
-        tex.anisotropy = 4;
-        tex.needsUpdate = true;
-        return tex;
-      });
-      this.pkg.textureCache.set(url, t);
-    }
-    return t;
+  private texture(key: string, nativeSize: number): Promise<Texture> {
+    return this.pkg.getTexture(key, this.textureSize, nativeSize).then((tex) => {
+      if (tex.anisotropy !== this.anisotropy) { tex.anisotropy = this.anisotropy; tex.needsUpdate = true; }
+      return tex;
+    });
   }
 
   private async loadProxy(fullId: string): Promise<ProxyInstance | null> {
@@ -422,8 +569,8 @@ export class HumanAvatar {
     }
     const [prim, map, normalMap] = await Promise.all([
       p,
-      meta.texture ? this.texture(meta.texture, meta.textureSize) : null,
-      meta.normalTexture ? this.texture(meta.normalTexture, 1024) : null,
+      meta.texture ? this.texture(keyOf(meta.texture), meta.textureSize) : null,
+      meta.normalTexture && this.normalMaps ? this.texture(keyOf(meta.normalTexture), 1024) : null,
     ]);
     const geo = geometryFrom(prim, '_JOINTS', '_WEIGHTS');
     const refs = asU16(prim.attributes._REFS), refw = toFloat(prim.attributes._REFW), offs = toFloat(prim.attributes._OFFS);

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from './core';
 export * from './human';
 export * from './native';
+// the root entry targets React Native: its preload uses the Expo disk cache and mobile textures
+export { preloadHumanPackage } from './native';

package/src/native/HumanView.tsx

@@ -1,31 +1,71 @@
 // <HumanView>: realistic MakeHuman-based avatar for React Native (expo-gl + three).
 // Renders on demand only; a static avatar costs no GPU after the first frame.
 import React, { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
-import { PanResponder, StyleProp, View, ViewStyle } from 'react-native';
+import { LayoutChangeEvent, PanResponder, PixelRatio, StyleProp, View, ViewStyle } from 'react-native';
 import { ExpoWebGLRenderingContext, GLView } from 'expo-gl';
 import {
   ACESFilmicToneMapping, Color, DirectionalLight, HemisphereLight, PerspectiveCamera, Scene, SRGBColorSpace, Vector3, WebGLRenderer,
 } from 'three';
-import { HumanAvatar, HumanConfig, HumanPackage, loadHumanPackage } from '../human/runtime';
+import {
+  HumanAvatar, HumanConfig, HumanPackage, LoadOptions, PreloadOptions, TextureTier, loadHumanPackage, warmHumanPackage,
+} from '../human/runtime';
 import { expoLoadOptions } from './humanExpo';
 
-/** Load (and disk-cache) the human package once per base URL. */
+export interface UseHumanPackageOptions extends Omit<PreloadOptions, keyof LoadOptions | 'onProgress'> {
+  /** Host of the mobile texture pack, if not next to the manifest or in manifest.mobileTextures.baseUrl. */
+  mobileBaseUrl?: string;
+  /** Also download this look's meshes and textures before `ready` (default: true, with DEFAULT_HUMAN). */
+  preload?: boolean;
+}
+
+/**
+ * Preload on Expo: loads the package with the disk cache and JPEG/PNG textures, then downloads
+ * everything `config` needs for its first textured frame. Resolves when those files are on disk.
+ *
+ *   await preloadHumanPackage(ASSETS, { config: savedAvatar, textureSize: '1k' });  // e.g. during splash
+ */
+export function preloadHumanPackage(baseUrl: string, opts: Omit<PreloadOptions, keyof LoadOptions> & { mobileBaseUrl?: string } = {}) {
+  return getPackage(baseUrl, opts.mobileBaseUrl).then(async (pkg) => { await warmHumanPackage(pkg, opts); return pkg; });
+}
+
 const packages = new Map<string, Promise<HumanPackage>>();
-export function useHumanPackage(baseUrl: string) {
+function getPackage(baseUrl: string, mobileBaseUrl?: string) {
+  let p = packages.get(baseUrl);
+  if (!p) {
+    p = loadHumanPackage(baseUrl, { ...expoLoadOptions, mobileBaseUrl });
+    packages.set(baseUrl, p);
+    p.catch(() => packages.delete(baseUrl));
+  }
+  return p;
+}
+
+/**
+ * Load (and disk-cache) the human package once per base URL. `ready` turns true when the first
+ * textured frame can be painted: manifest, base mesh, and (unless `preload: false`) the meshes and
+ * textures of `config`, all on disk. `progress` is 0..1 while preloading.
+ */
+export function useHumanPackage(baseUrl: string, opts: UseHumanPackageOptions = {}) {
   const [pkg, setPkg] = useState<HumanPackage | null>(null);
+  const [ready, setReady] = useState(false);
+  const [progress, setProgress] = useState(0);
   const [error, setError] = useState<Error | null>(null);
+  const key = JSON.stringify([opts.config ?? null, opts.textureSize ?? '1k', opts.normalMaps ?? true, opts.preload ?? true]);
   useEffect(() => {
-    let p = packages.get(baseUrl);
-    if (!p) {
-      p = loadHumanPackage(baseUrl, expoLoadOptions);
-      packages.set(baseUrl, p);
-      p.catch(() => packages.delete(baseUrl));
-    }
     let live = true;
-    p.then((v) => live && setPkg(v), (e) => live && setError(e));
+    setReady(false);
+    getPackage(baseUrl, opts.mobileBaseUrl)
+      .then(async (p) => {
+        if (!live) return;
+        setPkg(p);
+        if (opts.preload !== false) {
+          await warmHumanPackage(p, { ...opts, onProgress: (d, t) => live && setProgress(d / t) });
+        }
+        if (live) { setProgress(1); setReady(true); }
+      })
+      .catch((e) => live && setError(e));
     return () => { live = false; };
-  }, [baseUrl]);
-  return { pkg, error };
+  }, [baseUrl, key]);
+  return { pkg, ready, progress, error };
 }
 
 export interface HumanViewProps {
@@ -36,9 +76,21 @@ export interface HumanViewProps {
   expressions?: Record<string, number>;
   background?: string;
   rotatable?: boolean;
-  /** '1k' textures for lists/low-end devices, '2k' for the editor. */
-  textureSize?: '1k' | '2k';
+  /**
+   * Texture tier. Default '1k': at face/bust framing on a phone it looks like web '2k'.
+   * '512' for lists and avatars under ~120 pt; '2k' only for full-screen close-ups.
+   */
+  textureSize?: TextureTier;
+  /** Render resolution in pixels per point. Default: the device's (max 3). 2 is a good speed/quality balance. */
+  pixelRatio?: number;
+  /** MSAA. Default true (expo-gl multisampling on iOS, three's antialias elsewhere). */
+  antialias?: boolean;
+  /** Anisotropic texture filtering. Default 2; 1 turns it off. */
+  maxTextureAnisotropy?: number;
+  /** Clothing normal maps. Default true; false for lighter materials on low-end phones. */
+  normalMaps?: boolean;
   style?: StyleProp<ViewStyle>;
+  /** Called once, after the first frame with all textures has been drawn. */
   onReady?: (avatar: HumanAvatar) => void;
 }
 
@@ -49,12 +101,21 @@ export interface HumanViewHandle {
 }
 
 export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function HumanView(
-  { pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '2k', style, onReady }, ref,
+  {
+    pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '1k',
+    pixelRatio, antialias = true, maxTextureAnisotropy = 2, normalMaps = true, style, onReady,
+  }, ref,
 ) {
   const gl = useRef<ExpoWebGLRenderingContext | null>(null);
   const renderer = useRef<WebGLRenderer | null>(null);
   const yaw = useRef(0);
   const pending = useRef(false);
+  const textured = useRef(false); // config applied with all textures loaded
+  const readyFired = useRef(false);
+  const readyCb = useRef(onReady);
+  readyCb.current = onReady;
+  const [layout, setLayout] = useState<{ w: number; h: number } | null>(null);
+
   const stage = useMemo(() => {
     const scene = new Scene();
     scene.background = new Color(background);
@@ -65,21 +126,39 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     scene.add(key, rim, new HemisphereLight('#ffffff', '#b9a99a', 1.1));
     const avatar = new HumanAvatar(pkg);
     avatar.textureSize = textureSize;
+    avatar.anisotropy = maxTextureAnisotropy;
+    avatar.normalMaps = normalMaps;
     scene.add(avatar.group);
+    textured.current = false;
+    readyFired.current = false;
     return { scene, camera: new PerspectiveCamera(24, 1, 0.05, 50), avatar };
   }, [pkg]);
 
+  useEffect(() => { (stage.scene.background as Color).set(background); requestRender(); }, [background]);
+
   const draw = () => {
-    if (!gl.current || !renderer.current) return;
+    const ctx = gl.current, r = renderer.current;
+    if (!ctx || !r) return;
     const { camera, avatar } = stage;
+    const w = ctx.drawingBufferWidth, h = ctx.drawingBufferHeight;
+    if (r.domElement.width !== w || r.domElement.height !== h) {
+      r.domElement.width = w; r.domElement.height = h;
+      r.setSize(w, h, false);
+      camera.aspect = w / h;
+      camera.updateProjectionMatrix();
+    }
     const m = avatar.metrics();
     const target = framing === 'face' ? new Vector3(0, m.headY - 0.08, 0) : new Vector3(0, m.height * 0.52, 0);
-    const h = framing === 'face' ? 0.42 : m.height * 1.12;
-    const dist = h / 2 / Math.tan((camera.fov * Math.PI) / 360) / Math.min(1, camera.aspect * 1.1);
+    const vh = framing === 'face' ? 0.42 : m.height * 1.12;
+    const dist = vh / 2 / Math.tan((camera.fov * Math.PI) / 360) / Math.min(1, camera.aspect * 1.1);
     camera.position.set(Math.sin(yaw.current) * dist, target.y + dist * 0.03, Math.cos(yaw.current) * dist);
     camera.lookAt(target);
-    renderer.current.render(stage.scene, camera);
-    gl.current.endFrameEXP();
+    r.render(stage.scene, camera);
+    ctx.endFrameEXP();
+    if (textured.current && !readyFired.current) {
+      readyFired.current = true;
+      readyCb.current?.(avatar);
+    }
   };
   const requestRender = () => {
     if (pending.current) return;
@@ -90,7 +169,7 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
   const onContextCreate = (ctx: ExpoWebGLRenderingContext) => {
     const w = ctx.drawingBufferWidth, h = ctx.drawingBufferHeight;
     const canvas = { width: w, height: h, style: {}, clientWidth: w, clientHeight: h, addEventListener: () => {}, removeEventListener: () => {}, getContext: () => ctx };
-    const r = new WebGLRenderer({ canvas: canvas as any, context: ctx as any, antialias: true });
+    const r = new WebGLRenderer({ canvas: canvas as any, context: ctx as any, antialias });
     r.setPixelRatio(1);
     r.setSize(w, h, false);
     r.outputColorSpace = SRGBColorSpace;
@@ -102,17 +181,28 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     requestRender();
   };
 
+  // Shape/color changes reuse the cached textures; only a new item or tier loads files.
   const key = JSON.stringify(config);
   useEffect(() => {
     let live = true;
     stage.avatar.setConfig(config).then(() => {
       if (!live) return;
+      textured.current = true;
       requestRender();
-      onReady?.(stage.avatar);
     });
     return () => { live = false; };
   }, [key, stage]);
 
+  // quality knobs that need the textures reapplied
+  useEffect(() => {
+    const a = stage.avatar;
+    if (a.textureSize === textureSize && a.anisotropy === maxTextureAnisotropy && a.normalMaps === normalMaps) return;
+    a.textureSize = textureSize;
+    a.anisotropy = maxTextureAnisotropy;
+    a.normalMaps = normalMaps;
+    a.reloadTextures().then(requestRender);
+  }, [textureSize, maxTextureAnisotropy, normalMaps, stage]);
+
   useEffect(() => {
     for (const [k, v] of Object.entries(expressions ?? {})) stage.avatar.setExpression(k, v);
     requestRender();
@@ -141,9 +231,23 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     },
   }));
 
+  // expo-gl sizes its buffer to (view size x device scale). For a lower pixelRatio, render a
+  // smaller GLView and scale it up to fill the box.
+  const device = Math.min(3, PixelRatio.get());
+  const k = pixelRatio && pixelRatio < device ? pixelRatio / device : 1;
+  const onLayout = (e: LayoutChangeEvent) => setLayout({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height });
+  const glStyle: StyleProp<ViewStyle> = k === 1 || !layout
+    ? { flex: 1 }
+    : {
+      position: 'absolute', width: layout.w * k, height: layout.h * k,
+      left: (layout.w - layout.w * k) / 2, top: (layout.h - layout.h * k) / 2, transform: [{ scale: 1 / k }],
+    };
+
   return (
-    <View style={[{ overflow: 'hidden' }, style]} {...(rotatable ? pan.panHandlers : null)}>
-      <GLView style={{ flex: 1 }} onContextCreate={onContextCreate} />
+    <View style={[{ overflow: 'hidden' }, style]} onLayout={onLayout} {...(rotatable ? pan.panHandlers : null)}>
+      {k === 1 || layout ? (
+        <GLView style={glStyle} msaaSamples={antialias ? 4 : 0} onContextCreate={onContextCreate} />
+      ) : null}
     </View>
   );
 });

package/src/native/humanExpo.ts

@@ -1,5 +1,9 @@
 // React Native (Expo) adapters for the realistic human: a disk-cached fetcher and an
-// expo-gl texture loader. Pass both to loadHumanPackage (useHumanPackage does it for you).
+// expo-gl texture loader. Pass expoLoadOptions to loadHumanPackage / preloadHumanPackage
+// (useHumanPackage does it for you).
+//
+// expo-gl decodes images with stb_image, which has no WebP support, so these options select the
+// JPEG/PNG mobile texture pack (manifest.mobileTextures, built by `npm run build:mobile`).
 import * as FileSystem from 'expo-file-system/legacy';
 import { Texture } from 'three';
 import type { HumanTextureLoader, LoadOptions } from '../human/runtime';
@@ -7,20 +11,34 @@ import type { HumanTextureLoader, LoadOptions } from '../human/runtime';
 const DIR = `${FileSystem.cacheDirectory ?? ''}humanforge/`;
 let dirReady: Promise<void> | null = null;
 
-/** Download once into the cache directory; later sessions load offline. */
-async function cached(url: string): Promise<string> {
-  dirReady ??= FileSystem.makeDirectoryAsync(DIR, { intermediates: true }).catch(() => {});
-  await dirReady;
-  const file = DIR + url.replace(/^https?:\/\//, '').replace(/[^a-zA-Z0-9._-]/g, '_');
-  const info = await FileSystem.getInfoAsync(file);
-  if (!info.exists) {
-    const res = await FileSystem.downloadAsync(url, file);
-    if (res.status !== 200) {
-      await FileSystem.deleteAsync(file, { idempotent: true });
-      throw new Error(`humanforge: ${res.status} for ${url}`);
-    }
+const inflight = new Map<string, Promise<string>>();
+
+/**
+ * Download once into the cache directory; later sessions load offline. Concurrent requests for
+ * the same URL share one download, and files are written to a temp name and moved into place, so
+ * an interrupted download never leaves a broken file in the cache.
+ */
+export function cached(url: string): Promise<string> {
+  let p = inflight.get(url);
+  if (!p) {
+    p = (async () => {
+      dirReady ??= FileSystem.makeDirectoryAsync(DIR, { intermediates: true }).catch(() => {});
+      await dirReady;
+      const file = DIR + url.replace(/^https?:\/\//, '').replace(/[^a-zA-Z0-9._-]/g, '_');
+      if ((await FileSystem.getInfoAsync(file)).exists) return file;
+      const tmp = `${file}.${Date.now()}.part`;
+      const res = await FileSystem.downloadAsync(url, tmp);
+      if (res.status !== 200) {
+        await FileSystem.deleteAsync(tmp, { idempotent: true });
+        throw new Error(`humanforge: ${res.status} for ${url}`);
+      }
+      await FileSystem.moveAsync({ from: tmp, to: file });
+      return file;
+    })();
+    inflight.set(url, p);
+    p.catch(() => {}).finally(() => inflight.delete(url));
   }
-  return file;
+  return p;
 }
 
 const B64 = new Uint8Array(128);
@@ -43,16 +61,20 @@ export const expoFetch = async (url: string): Promise<ArrayBuffer> =>
 
 /**
  * expo-gl decodes images natively when texImage2D receives `{ localUri }`, so we hand three
- * a "data texture" whose data is the cached file (same trick expo-three uses).
+ * a "data texture" whose data is the cached file (same trick expo-three uses). The file must be
+ * JPEG or PNG (stb_image); WebP uploads silently fail and the mesh renders black.
  */
 export const expoTextureLoader: HumanTextureLoader = async (url, size) => {
+  if (/\.webp$/i.test(url)) console.warn(`humanforge: expo-gl can't decode WebP (${url}); build/host the mobile texture pack`);
   const localUri = await cached(url);
   const tex = new Texture();
   tex.image = { data: { localUri }, width: size, height: size };
   (tex as any).isDataTexture = true;
-  tex.generateMipmaps = false;
+  // all pack textures are power-of-two squares, so mipmaps work and avoid shimmer at bust framing
+  tex.generateMipmaps = true;
   tex.needsUpdate = true;
   return tex;
 };
 
-export const expoLoadOptions: LoadOptions = { fetch: expoFetch, loadTexture: expoTextureLoader };
+/** Options for loadHumanPackage / preloadHumanPackage on Expo: disk cache + JPEG/PNG textures. */
+export const expoLoadOptions: LoadOptions = { fetch: expoFetch, loadTexture: expoTextureLoader, textureFormat: 'mobile' };

package/src/native/index.ts

@@ -2,8 +2,8 @@ export { AvatarView } from './AvatarView';
 export type { AvatarViewHandle, AvatarViewProps } from './AvatarView';
 export { AvatarCreator } from './AvatarCreator';
 export type { AvatarCreatorProps } from './AvatarCreator';
-export { HumanView, useHumanPackage } from './HumanView';
-export type { HumanViewHandle, HumanViewProps } from './HumanView';
-export { expoFetch, expoLoadOptions, expoTextureLoader } from './humanExpo';
+export { HumanView, preloadHumanPackage, useHumanPackage } from './HumanView';
+export type { HumanViewHandle, HumanViewProps, UseHumanPackageOptions } from './HumanView';
+export { cached as cachedFile, expoFetch, expoLoadOptions, expoTextureLoader } from './humanExpo';
 export { HumanEditor } from './HumanEditor';
 export type { HumanEditorProps } from './HumanEditor';

package/src/web/HumanCanvas.tsx

@@ -5,7 +5,7 @@ import {
   Vector3, WebGLRenderer,
 } from 'three';
 import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
-import { HumanAvatar, HumanConfig, HumanPackage } from '../human/runtime';
+import { HumanAvatar, HumanConfig, HumanPackage, TextureTier } from '../human/runtime';
 
 export interface HumanCanvasProps {
   pkg: HumanPackage;
@@ -16,7 +16,8 @@ export interface HumanCanvasProps {
   background?: string;
   /** Drag to turn the avatar. Default true. */
   rotatable?: boolean;
-  textureSize?: '1k' | '2k';
+  /** Texture tier: '512' | '1k' | '2k' (default '2k'). */
+  textureSize?: TextureTier;
   className?: string;
   style?: React.CSSProperties;
   onReady?: (avatar: HumanAvatar) => void;