Supported Format

• VRM 1.0 (preferred) — loaded via @pixiv/three-vrm
• VRM 0.x — supported with automatic conversion by the loader
• GLB — supported with PBR materials for best HDRI lighting interaction. Use VRM for spring bone physics
• Other 3D formats (FBX, OBJ) are not directly supported — convert to VRM or GLB first

Required: ARKit Blendshapes

Your model's mesh must include morph targets (blend shapes) using the ARKit naming convention. AStack uses the standard 52 ARKit blendshape names used by Apple, Meta, and NVIDIA Audio2Face.

Critical blendshapes (required for basic animation):

• jawOpen — mouth open/close
• eyeBlinkLeft, eyeBlinkRight — eye blinking

Required: Humanoid Bone Structure

VRM models must include a humanoid bone rig for idle animations (breathing, head bob, body sway). The following bones are used:

• Spine, Chest — breathing animation
• Neck, Head — head bob and sway
• LeftShoulder, RightShoulder — shoulder movement with breathing
• LeftUpperArm, RightUpperArm — natural arm rest pose

Recommended: VRM Expressions

For best results, your VRM should include an ExpressionManager with these expressions:

• aa — mouth open (mapped from jawOpen)
• happy — smile (mapped from mouthSmileLeft/Right)
• blink — both eyes blink
• blinkLeft, blinkRight — individual eye blinks
• ou — mouth funnel shape

Performance Guidelines

PBR vs MToon Materials

Models using PBR materials (MeshStandardMaterial) respond to HDRI environment lighting — skin picks up warm/cool tinting, hair shows soft specular, and clothing reflects the scene. MToon (toon shader) materials ignore environment maps entirely. For best visual quality with HDRI backgrounds, use PBR materials.

Mobile vs Desktop

• Mobile: Target <5MB file size, 1024px textures, <50K vertices
• Desktop: Up to 15MB, 2048px textures, <100K vertices

Compressing Custom Models

Use gltf-transform to optimize models before upload:

# Install gltf-transform CLI
npm install -g @gltf-transform/cli

# Compress textures to WebP and apply Draco mesh compression
gltf-transform optimize input.vrm output.glb \
  --texture-compress webp \
  --compress draco

# Resize oversized textures to max 2048px
gltf-transform resize input.glb output.glb --width 2048 --height 2048

Testing Compatibility

Use the onModelLoadcallback to check your model's compatibility:

<VRMAvatar
  blendshapes={blendshapes}
  modelUrl="/your-model.vrm"
  onModelLoad={(report) => {
    console.log('Supported:', report.supported, '/ 52');
    console.log('Missing:', report.missing);
    console.log('Warnings:', report.warnings);
    console.log('Stats:', report.modelStats);
  }}
/>

You can also use the Demo page character selector to test your model with a live connection.

Custom Blendshape Mapping

If your model uses non-standard blendshape names, provide a mapping from ARKit names to your model's names:

import { VROID_BLENDSHAPE_MAP } from '@aether-stack-dev/client-sdk';

<VRMAvatar
  blendshapes={blendshapes}
  modelUrl="/vroid-model.vrm"
  blendshapeMap={VROID_BLENDSHAPE_MAP}
/>

A preset VROID_BLENDSHAPE_MAP is included for VRoid Studio models. You can also provide your own custom mapping.

Template Characters

AStack provides 11 ready-to-use characters hosted on Supabase Storage. These are available to all SDK consumers without needing to bundle any files locally. Try them on the Demo page.

Where to Find Characters

• VRoid Hub — Largest free VRM library (10,000+ models)
• VRoid Studio — Free character creator with VRM export
• Mixamo + UniVRM — Convert FBX characters to VRM via UniVRM Blender plugin