roblox-box-animal

Animales con rig de cajas para Roblox

Escribes un pequeño archivo de datos para cada animal: paleta, huesos, cajas y clips. scripts/boxrig.py convierte ese archivo en la malla, los studs, el rig, las animaciones, las mutaciones, los renders y las exportaciones.

Ejemplos, con previsualizaciones en examples/previews/:

• examples/penguin.py: un bípedo.
• examples/dragon.py: un dragón de tamaño completo: cuerpo voxel suave/cuello en S/cola + cabeza construida con cajas, cuernos, placas y alas de murciélago, con mandíbula y una animación de inactividad con aliento de fuego.
• examples/lion.py: un león de anatomía correcta con aspecto macizo: cuerpo voxel suave, studs grandes, cara pixel-art dibujada en la rejilla voxel. examples/lion_chibi.py es el león chibi antiguo, conservado como ejemplo de la API de cajas.

Requisitos

• Blender 4.2 o posterior, ejecutado en modo headless. En Windows busca en C:\Program Files\Blender Foundation\Blender */blender.exe; en Mac, /Applications/Blender.app/Contents/MacOS/Blender. Probado en 5.1.
• Python 3 con Pillow y numpy: py -m pip install --user pillow numpy. No ejecutes los scripts con py -I.
• Marcadores de posición abajo: <B> = el ejecutable de Blender, <S> = la carpeta de este skill.

Flujo de trabajo

1. Especificación, anatomía primero (regla de usuario). Cada animal obtiene la estructura del animal real: su plan corporal real, proporciones y silueta, construido a partir de bloques. Nunca un personaje cúbico con características pegadas.
   • Lee reference/anatomy.md. Busca el animal real, o usa la referencia del usuario.
   • Escribe sus proporciones en alturas de los hombros como comentarios en el archivo de datos: longitud del cuerpo, cabeza, cuello, patas, cola.
   • Bosqueja la silueta lateral con formas grandes, y ajústala antes de añadir detalles.
   • Las proporciones chibi o "mascota linda" (cabeza grande, patas rechonchas) solo cuando el usuario las pida.
   • Anota de 2 a 4 rasgos distintivos y los clips (por defecto Caminar, Correr, Inactivo). Una imagen de referencia o modelo del usuario es la especificación.
   • Decide la escala: un personaje de Roblox mide unas 5 studs de alto; las mascotas miden de 4 a 8 studs; las criaturas de tamaño real son a escala real (un dragón mide unas 40 studs de largo). No reduzcas animales grandes.
2. Copia el ejemplo más cercano en la carpeta del usuario, o ejecuta py <S>/scripts/new_animal.py <Nombre> quad|biped <carpeta>. Nunca edites dentro del skill.
3. Edita los datos. Lee primero reference/design_guide.md.
4. Construye y renderiza:

   <B> -b --factory-startup --python <S>/scripts/boxrig.py -- <animal.py> all
   py <S>/scripts/make_sheet.py <dir_salida> _v1
   

   • <dir_salida> es out_<Nombre> junto al archivo.
   • Los modos son views (rápido, para dar forma), gif, export, mutations (vistas, exportación y mutaciones) y all.
5. Revisa <Nombre>_sheet_vN.png, review_<Clip>_vN.png y <Nombre>_mutations_vN.png. Corrige los datos y reconstruye con una nueva etiqueta, porque la herramienta Read guarda imágenes en caché por ruta. Normalmente de 3 a 5 rondas.
6. Verifica: <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <dir_salida> debe imprimir VERIFY_OK.
7. Entrega la hoja, la hoja de mutaciones y los GIFs.
8. Studio, si el Roblox Studio MCP está conectado. Sigue reference/roblox_studio.md: importar, arreglar, BoxRigAnim más <Nombre>Clips para poses y KeyframeSequences, MutationFX, luego un playtest medido.

Hoja de trucos del archivo de datos

• Unidades y ejes: studs, Z hacia arriba, frente = -Y, la izquierda del animal = +X.
• Cajas: box(x0,x1, y0,y1, z0,z1, color, hueso). sym(...) refleja la caja al lado derecho, con % convirtiéndose en L o R en el nombre del hueso; box con % en el hueso hace lo mismo. Una caja posterior gana donde las cajas se superponen.
• Escultura voxel (el valor por defecto para cuerpos de criaturas): establece VOXEL lo suficientemente pequeño para curvas suaves (aproximadamente 1/90 de la longitud del cuerpo: 0.5 en un dragón grande, 0.2 en un león) y STUD_SIZE más grande (2–4 celdas, p.ej. 1.0 / 0.8) para que los studs sigan siendo macizos y legibles. Luego:
  • vell(cx,cy,cz, rx,ry,rz, col, hueso): elipsoide.
  • vcap(p0, p1, r0, r1, col, hueso): cápsula cónica, para cuellos, patas, colas, cuernos y hocicos.
  • vbox(...): caja.
  • vsheet(origen, u, v, pts, grosor, col, hueso): polígono plano, para alas, aletas y crestas; hueso ('a', split, bajo, alto) lo divide entre dos huesos.
  • Opciones: paint=True recolorea solo los voxels existentes (raya del vientre, ojos, marcas); paint='belly' recolorea solo las celdas de ese color (bandas a través de una raya); '%' en el hueso refleja a L y R; mirror=True refleja en el mismo hueso (cuernos, dientes).
  • Todo se voxeliza en una sola rejilla y se mallado de manera codiciosa. Mantén los radios al menos en un voxel, o las partes delgadas se rompen. Lee "El estilo por defecto = FORMA suave + ASPECTO macizo" en reference/design_guide.md.
• Formas orgánicas, basadas en cajas (estilo macizo antiguo):
  • ell(cx,cy,cz, rx,ry,rz, color, hueso) es un blob redondeado escalonado hecho de 3 cajas. Úsalo para cuerpos, pechos, caderas, segmentos de cuello, muslos y segmentos de cola.
  • poly([(x,y),...], z0, z1, color, hueso, paso=1.0) rellena un contorno en vista superior. Úsalo para membranas de alas, aletas, crestas y espátulas de cola. hueso puede ser una función de x, para dividir una membrana entre Ala y PuntaAla.
  • beam(p0, p1, ancho, z0, z1, color, hueso) es una barra recta, para huesos de brazos, dedos de alas y cuernos.
• Animales alados: modela las alas extendidas planas, luego dóblalas en los clips con wing_rest=(levantar, caída_punta, barrido); el dragón usa (58, 24, 22). Establece VIEW_POSE = ('Idle', 0) para que la hoja muestre el animal de pie con las alas plegadas.
• Huesos: BONES[nombre] = (padre, cabeza, cola). Exactamente una raíz en (0,0,0), que no tiene cajas. El punto de la cabeza es el pivote.
  • Los clips de cuadrúpedos necesitan Cuerpo, Cabeza, DelanteroSup/Inf_L/R y TraseroSup/Inf_L/R. Opcional: una cadena de cola, una cadena de cuello, alas=('Ala','PuntaAla') y una mandíbula.
  • Los clips de bípedos necesitan Cuerpo, Cabeza y Pierna_L/R. Opcional: Pie_L/R, Ala_L/R y una cola.
• Clips: CLIPS = {'Walk': (fn, frames), ...} a 30 fps, sin costuras, en el lugar.
  • Fábricas preparadas (solo argumentos de palabra clave):
    • quad_walk, quad_run, quad_idle(jaw=, yawn=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • Animales que vuelan (dragones, pájaros, grifos, murciélagos, cualquier cosa con alas funcionales), una regla de usuario:
    • Caminar es caminar en tierra: las patas se mueven y las alas permanecen quietas. Usa quad_walk(..., wings=..., wing_flap=0), o biped_walk(..., wing_flap=0).
    • Correr es volar: las alas baten y las patas no corren; permanecen plegadas y quietas. Usa quad_fly(...) o biped_fly(...), nunca quad_run o biped_run.
    • Nunca bates las alas mientras las patas corren.
  • Aliento de fuego (dragones y otros que respiran fuego): quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) más MOUTH = (x, y, z) y MOUTH_BONE = 'Head' en el archivo de datos.
    • El clip se echa hacia atrás e inhala, luego se lanza hacia adelante con la mandíbula abierta de t0 a t1.
    • Los GIFs muestran una llama provisional. En Studio, assets/FireBreath.lua impulsa llamas reales desde los marcadores FireStart y FireStop del clip, coloreadas por mutación.
    • El fuego nunca se muestra en el Editor de Animaciones, que solo reproduce huesos. Para mostrarlo en modo Editar, usa assets/BoxRigPreview.lua.
    • Una mandíbula que apunta hacia adelante se abre hacia abajo con rx +. rx - la balancea hacia arriba dentro del cráneo, donde parece que desapareció.
  • Longitudes típicas: caminar 32–40 fotogramas, correr 18–24, inactivo 90–150.
  • Los animales grandes se mueven más lento y pesado: más fotogramas, mayor bob y bounce en studs, y un pitch más bajo.
  • Un clip personalizado es fn(t) -> {hueso: ((rx,ry,rz) grados alrededor de los ejes del mundo en la articulación, (tx,ty,tz) studs)}. Signos: rx + balancea un pie hacia atrás, asiente una cabeza hacia abajo y levanta una cola.
• Mutaciones (Oro, Diamante y Sombra por defecto) provienen de MUTATIONS en boxrig.py.
  • Cada una mapea el brillo de la paleta en una rampa de color suave.
  • ROLES nombra las partes del ojo (iris, eye, shine, blush) para que reciban los colores de ojos complementarios de la mutación. keep deja claves como dientes sin cambios.
  • Sobrescríbelas con MUTATIONS = {...} y elige un subconjunto con MUTATIONS_USE.

Amigable con Roblox por construcción (no rompas esto)

• Una llamada de dibujo: una malla, un material y una textura de stud compartida de 512 píxeles en mosaico. Los colores son colores de vértice, que Roblox multiplica por el TextureID.
• Skinning rígido (pesos 1.0) y eliminación de caras ocultas por otra caja en el mismo hueso.
• Tamaño: alrededor de 800 triángulos para una mascota y alrededor de 1,600 para un dragón. Mantén los enemigos por debajo de unos 3k; el límite duro es 20k.
• Las mutaciones son mallas separadas en el mismo rig: cada animación funciona en cada variante. Los efectos provienen de un emisor y como máximo una luz por modelo.
• Exportación: FBX sin huesos hoja, escala de unidad FBX, -Z hacia adelante e Y hacia arriba, la raíz en el origen, un clip por FBX.

Más detalles: reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md y reference/pitfalls.md.