Avatar Configurator 🎭

Configuratore 3D interattivo per personalizzare avatar con accessori e esportarli in formato GLB.

🚀 Quick Start

Prerequisiti

Questo progetto usa Bun come package manager e runtime. Installalo se non è già presente:

curl -fsSL https://bun.sh/install | bash

Installazione

bun install

Avvio Sviluppo

bun run dev

L'applicazione sarà disponibile su http://localhost:5173

Build Produzione

bun run build

Assets (consumatore)

Dopo npm install @memori.ai/avatar-configurator, gli asset 3D sono in node_modules/@memori.ai/avatar-configurator/dist/assets.
Copiali una volta nel public della tua app:

npx avatar-configurator-copy-assets public/avatar-assets

Poi usa il componente:

import "@memori.ai/ui/styles.css";
import "@memori.ai/avatar-configurator/dist/avatar-configurator.css";
import { AvatarConfigurator } from "@memori.ai/avatar-configurator";

<AvatarConfigurator />;

Stili e font: il configurator usa i componenti Button di @memori.ai/ui. Importa sempre @memori.ai/ui/styles.css prima del CSS del configurator. La libreria UI non include il font: carica Lexend Deca nell'app host (es. Google Fonts) oppure imposta --memori-font-family in CSS.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link
  href="https://fonts.googleapis.com/css2?family=Lexend+Deca:[email protected]&display=swap"
  rel="stylesheet"
/>

Il browser caricherà i modelli da /avatar-assets. Per un path diverso:

<AvatarConfigurator assetsBaseUrl="/my-custom-path" />

Sviluppo in questo repo: bun run dev — nessuna copia necessaria, gli asset sono serviti da src/assets.

Release (maintainer)

Prerequisiti una tantum:

# npm registry (Bun usa le credenziali npm)
bun pm whoami          # verifica login, altrimenti: npm login
gh auth status         # per creare la GitHub Release

Pubblica una nuova versione (da main, working tree pulito):

bun run release

release-it esegue in ordine: lint + typecheck → bump versione → build → commit + tag → GitHub Release → bun publish.

Per la prima release alla versione corrente (1.0.0) senza bump:

bun run release -- --no-increment

Solo patch/minor/major senza prompt interattivo:

bun run release -- patch
bun run release -- minor
bun run release -- major

Dry-run (nessuna modifica pubblicata):

bun run release -- --dry-run

🎮 Come Usare

1. Configurazione Avatar

• Usa i checkbox nel pannello laterale per aggiungere/rimuovere accessori:
  • 👓 Occhiali (Glasses)
  • 🧔 Barba (Beard)
  • 🎩 Cappello (Hat)
  • 🦋 Ali (Wings)

2. Visualizzazione

• Trascina per ruotare l'avatar
• Scroll per zoom in/out
• Click destro + trascina per pan

3. Export

Opzione A: GLB Multi-Mesh (Completo)

Usa: "Scarica GLB (Multi-Mesh)"

✅ Include:

• Skeleton (67 bones)
• Blendshapes (67 morph targets)
• Materiali separati (5 materiali)
• Mesh separate per ogni componente

📊 Metriche:

• Material Count: 5
• Draw Call Count: 5
• Mesh Count: 5 (corpo + accessori separati)

📦 Dimensione: ~4-5 MB
🎯 Uso: Editing avanzato in Blender, modifiche post-export

Opzione B: GLB Ottimizzato (Performance) ⭐ CONSIGLIATO

Usa: "GLB Ottimizzato (1 Mesh)"

✅ Include:

• Skeleton (67 bones): ✅ Pronto per animazioni
• Blendshapes (67 morph targets): ✅ Espressioni facciali e lip-sync
• Pivot centrato: ✅ Allineamento perfetto
• Unico Atlas Texture: ✅ Tutte le texture unificate
• 1 solo Materiale: Ottimizzazione massima
• 1 Draw Call: Performance GPU eccellenti

📊 Metriche Performance:

• Material Count: 1
• Draw Call Count: 1 (riduzione ~80% rispetto a multi-mesh)
• Texture Images: 1 (atlas unificato)
• Has Skins: true (skeleton completo)
• Has Morph Targets: true (espressioni complete)

📦 Dimensione: ~3-4 MB
🎯 Uso: Applicazioni real-time, mobile, VR/AR, performance critiche

📁 Struttura Assets

public/assets/
├── male.glb              # Base avatar maschile
├── glasses.glb           # Accessorio occhiali
├── beard.glb             # Accessorio barba
├── hat.glb               # Accessorio cappello
└── wings.glb             # Accessorio ali

Requisiti GLB Assets

• Formato: GLTF 2.0 Binary (.glb)
• Coordinate: Y-up, Right-handed
• Unità: Metri
• Skeleton: Humanoid rig standard
• Texture: Embedded nel GLB

🔧 Configurazione Tecnica

Tecnologie Utilizzate

• Three.js (r182): Rendering 3D
• React Three Fiber: React renderer per Three.js
• React (17 / 18 / 19): UI framework
• TypeScript (5.9): Type safety
• Vite (7): Build tool e dev server
• Bun (1.2): Package manager e runtime

File Principali

• src/components/AvatarConfigurator.tsx: Componente principale
• src/utils/AvatarModelGenerator.ts: Caricamento e gestione modelli
• src/utils/MeshMerger.ts: Merge geometrie per export ottimizzato
• src/utils/AvatarManager.ts: Orchestrazione avatar e export
• src/utils/GLBExporter.ts: Export GLB con texture embedding

⚙️ Caratteristiche Tecniche Avatar Ottimizzato

✅ Funzionalità Complete

• Skeleton Completo: 67 bones pronti per animazioni complete
• Morph Targets Preservati: 67 blendshapes per espressioni facciali
• Pivot Centrato: Allineamento corretto per tutte le trasformazioni
• Texture Atlas: Tutte le texture unificate in un singolo file
• Performance GPU: 1 draw call invece di 5+ (riduzione ~80%)

📊 Ottimizzazioni

• Material Batching: Da 5 materiali a 1 materiale unificato
• Texture Packing: Da 5+ texture a 1 texture atlas
• Mesh Merging: Da 5+ mesh a 1 SkinnedMesh
• Memory Footprint: Riduzione ~25% rispetto a multi-mesh

⚠️ Note

1. Struttura Blender
   • Possibile presenza di oggetto glTF_not_exported dopo import
   • Non influisce sulla funzionalità
   • Può essere rimosso manualmente in Blender

Compatibilità

• ✅ Blender: 3.x, 4.x
• ✅ Unity: 2020.3+
• ✅ Unreal Engine: 5.x
• ✅ Three.js Viewer: Tutti i viewer standard

📚 Documentazione Tecnica

Per dettagli tecnici approfonditi, problemi di Three.js e architettura del codice:

👉 TECHNICAL_REPORT.md

Include:

• Criticità di Three.js (SkinnedMesh, morph targets, etc.)
• Soluzioni implementate
• Comparazione modalità export
• Raccomandazioni future

🐛 Troubleshooting

Avatar nero dopo export

Causa: Texture non embedded
Soluzione: ✅ Già risolto - tutte le texture vengono convertite in Data URLs

Avatar sollevato dal pavimento in Blender

Causa: World matrix non applicato
Soluzione: In Blender: Select Armature > Object > Apply > All Transforms

glTF_not_exported in Blender

Causa: GLTFExporter riorganizza la scena
Soluzione: Eliminare manualmente, non influisce sulla funzionalità

Performance in browser mobile

Causa: Draw calls eccessivi con multi-mesh
Soluzione: ✅ Usare export ottimizzato (1 draw call)

🤝 Contribuire

Questo è un progetto personalizzato. Per modifiche:

1. Crea un branch per la feature
2. Testa le modifiche con tutti gli accessori (bun run dev)
3. Verifica export in Blender
4. Aggiorna documentazione se necessario

🙏 Credits

• Three.js: Rendering engine 3D
• Ready Player Me: Ispirazione per sistema avatar
• Khronos Group: Specifiche GLTF 2.0

Versione: 1.0.0
Data: Gennaio 2026