Troubleshooting
Avatar Problems
Fix 3D model rendering errors, bone animation clipping, texture loading failures, and layout shifting.
Overview
Asiyst avatars are real-time 3D models (glTF / GLB) rendered using WebGL with procedural skeletal animation.
Avatar Not Visible or Blank
- Verify avatar assignment: In the Asiyst dashboard under Projects > Your Project > Avatar, ensure an avatar model is selected and published.
- Inspect container clipping: Check if any ancestor CSS containers have
overflow: hiddenorclip-pathapplied.
- Verify asset download: In DevTools Network tab, look for
avatar.glb. If it returns404or403, republish the avatar model in Avatar Studio.
GLTF / Draco Compression Errors
If uploading custom 3D models to Avatar Studio:
- Maximum file size: 15 MB uncompressed, or 4 MB Draco-compressed.
- Supported format: Binary glTF (
.glb).
- Required bone hierarchy: Standard humanoid root bone naming (
Hips,Spine,Neck,Head).
Animation Stuttering & FPS Drops
- Ensure the 3D model polygon count is below 50,000 triangles.
- Limit texture map resolutions to 1024x1024 or 2048x2048.
- In low-power mobile modes, the SDK automatically throttles animation frame rates to 30 FPS to conserve battery.