babylonjs-engine (índice Senzu, ES)

Documentación completa upstream (inglés): SKILL.upstream.md (1233 líneas). No la leas entera: usa el mapa y lee solo la sección que necesites (Read con offset/limit o Grep).

Cuándo usar / cuándo NO

• Usar: el proyecto ya usa @babylonjs/core o pide juego/visualización 3D con física (Havok), GUI 2D integrada, WebXR o Node Material.
• Usar: cargar modelos glTF/GLB con PBR, sombras y post-procesado en un canvas propio.
• NO usar: si el proyecto usa Three.js o React Three Fiber → threejs-webgl / react-three-fiber; decoración 3D ligera (tilt, Zdog, Vanta) → lightweight-3d-effects.
• NO usar: escenas exportadas de Spline o PlayCanvas → spline-interactive / playcanvas-engine.

Lectura mínima por tarea

Tarea	Lee solo
Empezar un proyecto/starter	SKILL.upstream.md L16-84 (§1 Engine and Scene Initialization) + assets/starter_babylon/ (Vite)
Cámaras, luces, materiales, cargar glTF	L85-188, L299-367, L368-424
Física Havok / animaciones	L425-493 (§7 Physics), L494-569 (§8 Animations)
Post-procesado, GUI, sombras, partículas	L652-768 (Patterns 4-7)
Integrar en React / WebXR	L771-825, L826-863
Depurar / rendimiento	L884-997 (§Performance), L998-1134 (§Pitfalls), L1200-1222 (§Debugging)

Mapa de SKILL.upstream.md

Líneas	Sección	Para qué
8-13	Related Skills	Alternativas (threejs, r3f, gsap, motion)
16-84	1. Engine and Scene Initialization (§Core Concepts 14-569)	Engine, Scene, render loop, resize, setup ES6/TS
85-132	2. Camera Systems	FreeCamera, ArcRotateCamera (órbita + límites), UniversalCamera
133-188	3. Lighting Systems	Hemispheric, Directional, Point, Spot, includedOnlyMeshes
189-298	4. Mesh Creation	MeshBuilder, transformaciones, propiedades
299-367	5. Materials	StandardMaterial, PBRMaterial, MultiMaterial
368-424	6. Model Loading	SceneLoader (Append/ImportMeshAsync), AssetsManager
425-493	7. Physics Engine	Havok, PhysicsAggregate, shapes, fuerzas
494-569	8. Animations	Animation, keyframes, AnimationGroup, esqueletos
570-768	Common Patterns	Entorno por defecto, carga async, picking, post-proceso, GUI, sombras, partículas
769-883	Integration Patterns	React (useEffect + dispose), WebXR, Node Material
884-997	Performance Optimization	Merge/instances/thin instances, SceneOptimizer, hardware scaling, texturas KTX2
998-1134	Common Pitfalls	Leaks, draw calls, bloqueo del hilo, attachControl, async, física sin habilitar
1135-1199	Advanced Topics	Shaders custom, compute shaders (WebGPU), texturas procedurales
1200-1233	Debugging / Resources / Version Notes	Inspector, bounding boxes, FPS, SceneInstrumentation; enlaces; basado en Babylon.js 7.x

Recursos

• references/api_reference.md — referencia de clases, métodos y propiedades de Babylon.js 7.x.
• scripts/scene_generator.py — genera escena base: py -3 scripts/scene_generator.py --type basic|physics --camera arc-rotate --typescript --output scene.js (o --interactive).
• scripts/mesh_builder.py — genera código de mallas: py -3 scripts/mesh_builder.py --shape sphere --params '{"size":2}' --output meshes.js.
• assets/starter_babylon/ — starter Vite (index.html, src/main.js, style.css, package.json); assets/examples/README.md — ejemplos por tema (carga, PBR, física, GUI, XR, rendimiento).

Reglas duras

• Libera siempre recursos: mesh.dispose(), scene.dispose(), engine.dispose(); en React en el cleanup de useEffect junto al listener de resize.
• Muchas copias del mismo mesh → createInstance o thin instances, nunca un mesh por copia (un draw call cada uno).
• Carga de modelos y física son async: usa ImportMeshAsync/await HavokPhysics() y habilita scene.enablePhysics antes de crear PhysicsAggregate.
• Llama a camera.attachControl(canvas, true); sin ello la cámara no responde.
• Solo en cliente: Babylon toca window/canvas; en Next.js/Astro usa componentes client-only o dynamic(..., { ssr: false }).

Integración con el stack del proyecto

• Detecta el stack como indica la skill front-activation/skill-router (senzu/senzu.json → package.json). Librería agnóstica: vanilla/Vite (usa el starter), React (patrón L771-825 con refs), Vue/Astro (mismo patrón en onMounted/client:only).
• Si package.json ya trae three o @react-three/fiber, no introduzcas Babylon: usa threejs-webgl / react-three-fiber.