roblox-box-animal

Animaux box-rig Roblox

Vous écrivez un petit fichier de données pour chaque animal : palette, os, boîtes et clips. scripts/boxrig.py transforme ce fichier en maillage, studs, rig, animations, mutations, rendus et exports.

Exemples, avec aperçus dans examples/previews/ :

• examples/penguin.py : un bipède.
• examples/dragon.py : un dragon pleine taille : corps voxel lisse encolure en S/queue + tête construite en boîtes, cornes, plaques et ailes de chauve-souris, avec une mâchoire et un repos cracheur de feu.
• examples/lion.py : un lion anatomiquement correct avec un look massif : corps voxel lisse, gros studs, visage pixel art dessiné sur la grille de voxels. examples/lion_chibi.py est l'ancien lion chibi, conservé comme exemple d'API boîte.

Prérequis

• Blender 4.2 ou ultérieur, exécuté sans interface graphique. Sur Windows, cherchez dans C:\Program Files\Blender Foundation\Blender */blender.exe ; sur Mac, /Applications/Blender.app/Contents/MacOS/Blender. Testé avec la version 5.1.
• Python 3 avec Pillow et numpy : py -m pip install --user pillow numpy. N'exécutez pas les scripts avec py -I.
• Espaces réservés ci-dessous : <B> = l'exécutable Blender, <S> = le dossier de cette compétence.

Flux de travail

1. Spécifications, anatomie d'abord (règle utilisateur). Chaque animal reçoit la structure de l'animal réel : son plan corporel réel, ses proportions et sa silhouette, construits à partir de blocs. Jamais un personnage cube avec des éléments collés dessus.
   • Lisez reference/anatomy.md. Recherchez l'animal réel, ou utilisez la référence de l'utilisateur.
   • Écrivez ses proportions en hauteurs d'épaule sous forme de commentaires dans le fichier de données : longueur du corps, tête, cou, pattes, queue.
   • Esquissez la silhouette de côté avec de grandes formes, et faites correspondre avant d'ajouter des détails.
   • Les proportions chibi ou « animal mignon » (grosse tête, pattes courtes) uniquement lorsque l'utilisateur les demande.
   • Notez 2 à 4 traits distinctifs et les clips (par défaut Marche, Course, Repos). Une image de référence ou un modèle de l'utilisateur fait office de spécification.
   • Déterminez l'échelle : un personnage Roblox mesure environ 5 studs ; les animaux de compagnie 4 à 8 studs ; les créatures grandeur nature sont à taille réelle (un dragon fait environ 40 studs de long). Ne réduisez pas les grands animaux.
2. Copiez l'exemple le plus proche dans le dossier de l'utilisateur, ou exécutez py <S>/scripts/new_animal.py <Nom> quad|bipede <dossier>. Ne modifiez jamais l'intérieur de la compétence.
3. Modifiez les données. Lisez reference/design_guide.md d'abord.
4. Construisez et rendez :

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

   • <dossier_sortie> est out_<Nom> à côté du fichier.
   • Les modes sont views (rapide, pour le modelage), gif, export, mutations (vues, export et mutations) et all.
5. Révisez <Nom>_sheet_vN.png, review_<Clip>_vN.png et <Nom>_mutations_vN.png. Corrigez les données et reconstruisez avec un nouveau tag, car l'outil de lecture met en cache les images par chemin. Généralement 3 à 5 cycles.
6. Vérifiez : <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <dossier_sortie> doit afficher VERIFY_OK.
7. Livrez la fiche, la fiche de mutation et les GIFs.
8. Studio, si le MCP Roblox Studio est connecté. Suivez reference/roblox_studio.md : importez, corrigez, BoxRigAnim plus <Nom>Clips pour les poses et KeyframeSequences, MutationFX, puis un test de jeu mesuré.

Aide-mémoire du fichier de données

• Unités et axes : studs, Z vers le haut, avant = -Y, la gauche de l'animal = +X.
• Boîtes : box(x0,x1, y0,y1, z0,z1, couleur, os). sym(...) reflète la boîte sur le côté droit, avec % devenant L ou R dans le nom de l'os ; box avec % dans l'os fait de même. Une boîte ultérieure l'emporte là où les boîtes se chevauchent.
• Sculpture voxel (par défaut pour les corps de créatures) : définissez VOXEL suffisamment petit pour des courbes lisses (environ 1/90 de la longueur du corps : 0.5 sur un grand dragon, 0.2 sur un lion) et STUD_SIZE plus grand (2 à 4 cellules, par ex. 1.0 / 0.8) pour que les studs restent massifs et lisibles. Ensuite :
  • vell(cx,cy,cz, rx,ry,rz, col, os) : ellipsoïde.
  • vcap(p0, p1, r0, r1, col, os) : capsule effilée, pour cous, pattes, queues, cornes et museaux.
  • vbox(...) : boîte.
  • vsheet(origine, u, v, pts, epaisseur, col, os) : polygone plat, pour ailes, nageoires et fanons ; os ('a', split, bas, haut) le divise entre deux os.
  • Options : paint=True recolore uniquement les voxels existants (bande ventrale, yeux, marques) ; paint='ventre' recolore uniquement les cellules de cette couleur (bandes à travers une rayure) ; '%' dans l'os se reflète à gauche et à droite ; mirror=True se reflète sur le même os (cornes, dents).
  • Tout est voxélisé sur une grille unique et maillé de manière gloutonne. Gardez les rayons à au moins un voxel, sinon les parties fines se brisent. Lisez « Le style par défaut = FORME lisse + ASPECT massif » dans reference/design_guide.md.
• Formes organiques, basées sur des boîtes (style massif plus ancien) :
  • ell(cx,cy,cz, rx,ry,rz, couleur, os) est une masse arrondie en escalier faite de 3 boîtes. Utilisez-la pour les corps, les poitrines, les hanches, les segments de cou, les cuisses et les segments de queue.
  • poly([(x,y),...], z0, z1, couleur, os, step=1.0) remplit un contour vu de dessus. Utilisez-le pour les membranes d'ailes, les nageoires, les fanons et les pelles de queue. os peut être une fonction de x, pour diviser une membrane entre Aile et BoutAile.
  • beam(p0, p1, largeur, z0, z1, couleur, os) est une barre droite, pour les os des bras, les doigts d'ailes et les cornes.
• Animaux ailés : modélisez les ailes à plat dépliées, puis pliez-les dans les clips avec wing_rest=(lever, affaissement_bout, balayage) ; le dragon utilise (58, 24, 22). Définissez VIEW_POSE = ('Idle', 0) pour que la fiche montre l'animal debout avec ses ailes repliées.
• Os : BONES[nom] = (parent, tête, queue). Exactement une racine à (0,0,0), qui n'a pas de boîtes. Le point de la tête est le pivot.
  • Les clips quadrupèdes ont besoin de Corps, Tête, AvantHaut/Bas_L/R et ArrièreHaut/Bas_L/R. Facultatif : une chaîne de queue, une chaîne cou, ailes=('Aile','BoutAile') et une mâchoire.
  • Les clips bipèdes ont besoin de Corps, Tête et Jambe_L/R. Facultatif : Pied_L/R, Aile_L/R et une queue.
• Clips : CLIPS = {'Walk': (fn, images), ...} à 30 ips, sans couture, sur place.
  • Usines prêtes à l'emploi (arguments mots-clés uniquement) :
    • quad_walk, quad_run, quad_idle(mâchoire=, bâillement=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • Animaux qui volent (dragons, oiseaux, griffons, chauves-souris, tout ce qui a des ailes fonctionnelles), une règle utilisateur :
    • Walking est une marche au sol : les pattes bougent et les ailes restent immobiles. Utilisez quad_walk(..., ailes=..., battement_aile=0), ou biped_walk(..., battement_aile=0).
    • Running est voler : les ailes battent et les pattes ne courent pas ; elles restent repliées et immobiles. Utilisez quad_fly(...) ou biped_fly(...), jamais quad_run ou biped_run.
    • Ne faites jamais battre les ailes pendant que les pattes courent.
  • Souffle de feu (dragons et autres cracheurs) : quad_idle(mâchoire='Jaw', bâillement=26, feu=(0.55, 0.75)) plus MOUTH = (x, y, z) et MOUTH_BONE = 'Head' dans le fichier de données.
    • Le clip recule et inspire, puis pousse en avant avec la mâchoire ouverte de t0 à t1.
    • Les GIFs montrent une flamme de substitution. Dans Studio, assets/FireBreath.lua génère de vraies flammes à partir des marqueurs FireStart et FireStop du clip, colorées par mutation.
    • Le feu n'apparaît jamais dans l'éditeur d'animations, qui ne joue que les os. Pour le montrer en mode Édition, utilisez assets/BoxRigPreview.lua.
    • Une mâchoire pointant vers l'avant s'ouvre vers le bas avec rx +. rx - la fait basculer vers le haut dans le crâne, où elle semble disparaître.
  • Longueurs typiques : marche 32 à 40 images, course 18 à 24, repos 90 à 150.
  • Les grands animaux se déplacent plus lentement et plus lourdement : plus d'images, bob et bounce plus grands en studs, et un pitch plus bas.
  • Un clip personnalisé est fn(t) -> {os: ((rx,ry,rz) degrés autour des axes du monde au niveau de l'articulation, (tx,ty,tz) studs)}. Signes : rx + balance une patte en arrière, fait hocher une tête vers le bas et soulève une queue.
• Mutations (Or, Diamant et Ombre par défaut) proviennent de MUTATIONS dans boxrig.py.
  • Chacune projette la luminosité de la palette sur une rampe de couleur lisse.
  • ROLES nomme les parties de l'œil (iris, œil, brillance, rougeur) pour qu'elles reçoivent les couleurs d'yeux complémentaires de la mutation. keep laisse des clés telles que les dents inchangées.
  • Remplacez-les avec MUTATIONS = {...} et choisissez un sous-ensemble avec MUTATIONS_USE.

Roblox-friendly par construction (ne cassez pas ces règles)

• Un seul appel de rendu : un maillage, un matériau et une texture de studs répétable unique de 512 px. Les couleurs sont des couleurs de sommets, que Roblox multiplie par le TextureID.
• Skinning rigide (poids 1.0) et élimination des faces cachées par une autre boîte sur le même os.
• Taille : environ 800 triangles pour un animal de compagnie et environ 1 600 pour un dragon. Gardez les monstres sous environ 3 000 ; la limite dure est 20 000.
• Mutations sont des maillages séparés sur le même rig : chaque animation fonctionne sur chaque variante. Les effets proviennent d'un seul émetteur et d'au plus une lumière par modèle.
• Export : FBX sans os feuilles, échelle unité FBX, -Z avant et Y vers le haut, la racine à l'origine, un clip par FBX.

Plus de détails : reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md et reference/pitfalls.md.