Skip to content

AVATAR_DEBUG_GUIDE.md

Latest commit

 

History

History
200 lines (159 loc) · 5.57 KB

AVATAR_DEBUG_GUIDE.md

File metadata and controls

200 lines (159 loc) · 5.57 KB
Raw

Avatar Model Loading Debug Guide

🔍 Debugging Avatar Model Issues

Problem Description

  • avatar.glb loads correctly
  • avatar_thinking.glb and avatar_talking.glb don't load/display
  • Models exist in the same directory but behave differently

🧪 Test Pages Created

1. Model Tester (/test-avatar-models)

Tests all three models side by side:

  • Red cube = Loading error
  • Yellow cube = No scene data
  • 3D model = Success

2. Avatar Comparison (/test-avatar-comparison)

Compares two approaches:

  • Multi-Model Avatar: Uses different .glb files for each state
  • Single Model Avatar: Uses only avatar.glb with procedural animations

🔧 Possible Causes & Solutions

1. Model File Issues

Symptoms: Models don't load at all Causes:

  • Corrupted .glb files
  • Different export settings
  • Missing textures/materials
  • File size issues

Debug Steps:

# Check file sizes
ls -la public/models/avatars/

# Verify files are valid GLB format
file public/models/avatars/*.glb

Solutions:

  • Re-export all models with identical settings
  • Use same 3D software and export parameters
  • Ensure all models have same scale/orientation
  • Check for embedded vs external textures

2. Model Structure Differences

Symptoms: Some models load but don't display correctly Causes:

  • Different scene hierarchy
  • Missing or renamed nodes
  • Different material setups
  • Animation data conflicts

Debug Steps:

  1. Open models in 3D viewer (Blender, Three.js Editor)
  2. Compare scene structure between working and non-working models
  3. Check material names and properties
  4. Verify mesh names and hierarchy

Solutions:

  • Ensure all models have identical scene structure
  • Use same naming conventions for meshes/materials
  • Remove unnecessary animation data
  • Standardize material properties

3. React Three Fiber Loading Issues

Symptoms: Models exist but React components fail to load them Causes:

  • useGLTF caching issues
  • Component re-rendering problems
  • Memory management issues
  • Suspense boundary problems

Debug Steps:

  1. Check browser console for errors
  2. Monitor network requests for model files
  3. Use React DevTools to inspect component state
  4. Check Three.js scene graph in browser

Solutions:

  • Clear useGLTF cache: useGLTF.clear()
  • Add proper error boundaries
  • Use Suspense correctly
  • Implement fallback mechanisms

4. File Path & Caching Issues

Symptoms: Models load inconsistently Causes:

  • Browser caching old versions
  • Incorrect file paths
  • Server-side rendering conflicts
  • Build process issues

Debug Steps:

# Verify files exist
curl -I http://localhost:3000/models/avatars/avatar_thinking.glb
curl -I http://localhost:3000/models/avatars/avatar_talking.glb

# Check network tab in browser DevTools

Solutions:

  • Hard refresh browser (Ctrl+Shift+R)
  • Clear browser cache
  • Restart development server
  • Check Next.js static file serving

🛠️ Immediate Fixes to Try

Option 1: Use Single Model Approach

If the other models have issues, use the SingleModelAvatar component:

// In Scene.js, replace:
import Avatar from "./models/Avatar";
// With:
import Avatar from "./models/SingleModelAvatar";

This uses only avatar.glb with procedural animations.

Option 2: Fix Model Loading

Enhanced Avatar component with better error handling:

// The updated Avatar.js includes:
- Fallback to default model on load errors
- Better error logging
- Proper model cloning
- Suspense boundaries

Option 3: Regenerate Models

If models are corrupted:

  1. Open original avatar model in 3D software
  2. Create thinking animation (head movements, pose changes)
  3. Create talking animation (mouth movements, gestures)
  4. Export all three with identical settings:
    • Same scale and orientation
    • Same material setup
    • Same export format (GLB)
    • Same compression settings

🔍 Debug Commands

Check Model Files

# File sizes (should be reasonable, not 0 bytes)
ls -lh public/models/avatars/

# File types (should all be GLB)
file public/models/avatars/*.glb

# Test HTTP access
curl -I http://localhost:3000/models/avatars/avatar.glb
curl -I http://localhost:3000/models/avatars/avatar_thinking.glb  
curl -I http://localhost:3000/models/avatars/avatar_talking.glb

Browser Console Debugging

// Check useGLTF cache
console.log(useGLTF.cache);

// Clear cache if needed
useGLTF.clear();

// Test manual loading
import { useGLTF } from '@react-three/drei';
const gltf = useGLTF('/models/avatars/avatar_thinking.glb');
console.log(gltf);

📊 Expected Results

Working System:

  • All three models load successfully in /test-avatar-models
  • Avatar changes models smoothly in /test-avatar-comparison
  • Console shows successful model loading logs
  • No red/yellow cubes in model tester

Fallback System:

  • SingleModelAvatar works with procedural animations
  • Smooth transitions between animation states
  • Visual indicators show current state
  • No model loading errors

🎯 Next Steps

  1. Test Model Loading: Visit /test-avatar-models to see which models load
  2. Compare Approaches: Visit /test-avatar-comparison to test both systems
  3. Check Console: Look for error messages about model loading
  4. Verify Files: Ensure all .glb files are valid and accessible
  5. Choose Approach: Use multi-model if working, or single-model as fallback

The system now has robust fallbacks and debugging tools to identify and resolve avatar model loading issues.