gltf-instanced-world
Patrón completo para cargar assets GLTF en un mundo tile-based con Three.js, usando InstancedMesh para objetos repetidos (Layer 0 y Layer 1) y Mesh clone para ocupantes únicos (Layer 2). Cubre cache-f
SKILL.mdskills/mnt/user-data/outputs/skills/gltf-instanced-world/SKILL.md
GitHubgltf-instanced-world
Principio fundamental
Un mundo tile-based tiene dos clases de objetos:
- Repetidos (tiles del suelo, props de ambiente): InstancedMesh → 1 draw call por tipo
- Únicos (edificios, personajes): Mesh clone → 1 draw call por instancia
La decisión InstancedMesh vs Mesh clone no es estética — es aritmética de draw calls. Con 200 tiles de hierba y 3 tipos de tile: 3 draw calls con InstancedMesh, 200 sin él.
Paso 1 — Cache-first loading
Nunca cargues el mismo archivo dos veces. Deduplica el set de archivos necesarios antes de lanzar las peticiones.
const loader = new GLTFLoader();
const cache = new Map(); // filename → gltf
async function loadAssets(worldCells, tileFiles) {
// Derivar set mínimo de archivos desde los datos del mundo
const needed = new Set();
worldCells.forEach(cell => {
needed.add(tileFiles[cell.tileType]);
if (cell.occupant) needed.add(cell.occupant + '.gltf');
cell.environment?.forEach(id => needed.add(id + '.gltf'));
});
// Carga en paralelo — Promise.allSettled nunca interrumpe por un fallo individual
await Promise.allSettled(
[...needed].map(file =>
new Promise(res =>
loader.load(
file,
gltf => { cache.set(file, gltf); res(); },
undefined,
err => { console.warn('[skip]', file, err.message); res(); }
// res() siempre, incluso en error — el mundo carga sin ese asset
)
)
)
);
return cache;
}
Paso 2 — Extracción de geometría y material
Los GLTF de KayKit tienen 1 sub-mesh por tile hex (confirmado en PoC). Para assets con múltiples sub-meshes, crea un InstancedMesh por sub-mesh.
function extractMeshes(gltf) {
const meshes = [];
gltf.scene.traverse(child => {
if (child.isMesh) meshes.push(child);
});
if (!meshes.length) throw new Error('0 meshes en la escena GLTF');
return meshes;
}
Paso 3 — Construir InstancedMesh (Layer 0 y Layer 1)
function buildInstancedLayer(gltf, positions, assetKey) {
const srcMeshes = extractMeshes(gltf);
const group = new THREE.Group();
const dummy = new THREE.Object3D();
srcMeshes.forEach(src => {
const inst = new THREE.InstancedMesh(
src.geometry, // NO clonar — compartir la misma geometría
src.material, // NO clonar — compartir el mismo material
positions.length
);
inst.userData.assetKey = assetKey; // para raycasting
inst.castShadow = true;
inst.receiveShadow = true;
positions.forEach((pos, i) => {
dummy.position.copy(pos);
dummy.rotation.y = ((i * 7) % 6) * (Math.PI / 3); // rotación hex discreta
dummy.updateMatrix();
inst.setMatrixAt(i, dummy.matrix);
});
inst.instanceMatrix.needsUpdate = true; // OBLIGATORIO después de setMatrixAt
group.add(inst);
});
return group;
}
Por qué no clonar geometría ni material en InstancedMesh
Clonar crea buffers duplicados en GPU. InstancedMesh está diseñado para compartirlos. Solo clona si necesitas modificar la geometría de una instancia concreta (raro).
Paso 4 — Mesh clone para ocupantes únicos (Layer 2)
function placeOccupant(gltf, position, assetKey) {
const obj = gltf.scene.clone(true); // true = deep clone con materiales
obj.position.copy(position);
// Propagar assetKey a TODOS los nodos del árbol
// El raycaster puede impactar cualquier hijo — todos deben tener la clave
obj.traverse(node => {
node.userData.assetKey = assetKey;
});
return obj;
}
Paso 5 — Raycasting con InstancedMesh y Mesh clone
function handleClick(event, camera, scene) {
const mouse = new THREE.Vector2(
(event.clientX / innerWidth) * 2 - 1,
-(event.clientY / innerHeight) * 2 + 1
);
raycaster.setFromCamera(mouse, camera);
const intersects = raycaster.intersectObjects(scene.children, true);
if (!intersects.length) return null;
let node = intersects[0].object;
// Caso InstancedMesh: el objeto ES el nodo con assetKey
// Caso Mesh clone: puede ser un hijo — subimos hasta encontrar assetKey
while (node && node.parent && !node.userData.assetKey) {
node = node.parent;
}
return node?.userData?.assetKey ?? null;
}
Medición de peso real de carga
Para GLTF partidos en .gltf + .bin, medir ambos archivos.
El .gltf es JSON liviano; el .bin es el volumen real de datos geométricos.
async function measureAssetWeight(gltfPath, binPath) {
try {
const [gRes, bRes] = await Promise.all([fetch(gltfPath), fetch(binPath)]);
const [gBuf, bBuf] = await Promise.all([gRes.arrayBuffer(), bRes.arrayBuffer()]);
return {
gltfKB: (gBuf.byteLength / 1024).toFixed(1),
binKB: (bBuf.byteLength / 1024).toFixed(1),
totalKB: ((gBuf.byteLength + bBuf.byteLength) / 1024).toFixed(1),
};
} catch (e) {
return { gltfKB: 0, binKB: 0, totalKB: 0 };
}
}
Umbrales de referencia (calibrados con KayKit Medieval Hexagon Pack)
| Asset tipo | Peso típico .gltf+.bin | Sub-meshes | Draw calls con instancing |
|---|---|---|---|
| Hex tile (L0) | 80-150 KB | 1 | 1 por tipo de tile |
| Prop ambiente (L1) | 50-200 KB | 1-3 | 1-3 por tipo de prop |
| Building (L2) | 150-400 KB | 2-6 | 1 por building único |
Pitfalls críticos
1. instanceMatrix.needsUpdate = true es obligatorio.
Sin esta línea, Three.js no sube la matriz al shader y todos los objetos aparecen en (0,0,0).
2. No usar Object.assign para setear propiedades de Three.js.
position, rotation, scale son getters en Object3D. Asignar con set() o .copy().
3. Promise.allSettled, no Promise.all.
Un asset roto no debe tumbar el mundo entero. Con allSettled, el mundo carga sin ese archivo.
4. Propagar userData.assetKey por traverse en clones. Si no lo haces, el raycaster impacta un hijo sin clave y el click no registra nada.
5. No medir solo el .gltf.
El .gltf JSON pesa pocos KB. El .bin es el 90% del peso real. Medir ambos.