Roblox-Box-Tiere

Roblox Box-Rig Tiere

Du schreibst eine kleine Datendatei für jedes Tier: Palette, Knochen, Boxen und Clips. scripts/boxrig.py verwandelt diese Datei in das Mesh, die Studs, das Rig, die Animationen, Mutationen, Renderings und Exporte.

Beispiele mit Vorschauen in examples/previews/:

• examples/penguin.py: ein Zweibeiner (Biped).
• examples/dragon.py: ein Drache in voller Größe: glatter Voxel-Körper/S-förmiger Hals/Schwanz + box-basierter Kopf, Hörner, Platten und Fledermausflügel, mit einem Kiefer und einer Feueratem-Leerlaufanimation.
• examples/lion.py: ein anatomisch korrekter Löwe mit klobigem Look: glatter Voxel-Körper, große Studs, Pixel-Art-Gesicht, das auf das Voxel-Gitter gezeichnet wird. examples/lion_chibi.py ist der alte Chibi-Löwe, der als Box-API-Beispiel erhalten bleibt.

Anforderungen

• Blender 4.2 oder neuer, headless ausgeführt. Unter Windows in C:\Programme\Blender Foundation\Blender */blender.exe; auf dem Mac /Applications/Blender.app/Contents/MacOS/Blender. Getestet mit 5.1.
• Python 3 mit Pillow und numpy: py -m pip install --user pillow numpy. Führe die Skripte nicht mit py -I aus.
• Platzhalter unten: <B> = die Blender-ausführbare Datei, <S> = der Ordner dieser Fähigkeit.

Workflow

1. Spezifikation, Anatomie zuerst (Benutzerregel). Jedes Tier bekommt die Struktur des echten Tieres: seinen realen Körperbau, Proportionen und Silhouette, gebaut aus Blöcken. Niemals eine Würzelfigur mit aufgesetzten Merkmalen.
   • Lies reference/anatomy.md. Schlage das echte Tier nach oder verwende die Referenz des Benutzers.
   • Schreibe seine Proportionen in Schulterhöhen als Kommentare in der Datendatei: Körperlänge, Kopf, Hals, Beine, Schwanz.
   • Baue die seitliche Silhouette mit großen Formen und gleiche sie an, bevor du Details hinzufügst.
   • Chibi- oder „süße Haustier“-Proportionen (großer Kopf, stummelige Beine) nur, wenn der Benutzer danach fragt.
   • Notiere 2–4 charakteristische Merkmale und die Clips (Standard: Walk, Run, Idle). Ein Referenzbild oder -modell des Benutzers ist die Spezifikation.
   • Entscheide den Maßstab: Eine Roblox-Figur ist etwa 5 Studs groß; Haustiere sind 4–8 Studs; realistisch große Kreaturen sind lebensgroß (ein Drache ist etwa 40 Studs lang). Schrumpfe keine großen Tiere.
2. Kopiere das nächstgelegene Beispiel in den Benutzerordner oder führe py <S>/scripts/new_animal.py <Name> quad|biped <folder> aus. Bearbeite niemals innerhalb der Fähigkeit.
3. Bearbeite die Daten. Lies zuerst reference/design_guide.md.
4. Baue und rendere:

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

   • <out_dir> ist out_<Name> neben der Datei.
   • Die Modi sind views (schnell, zum Formen), gif, export, mutations (Ansichten, Exporte und Mutationen) und all.
5. Überprüfe <Name>_sheet_vN.png, review_<Clip>_vN.png und <Name>_mutations_vN.png. Korrigiere die Daten und baue mit einem neuen Tag neu, da das Lese-Werkzeug Bilder nach Pfad zwischenspeichert. Normalerweise 3–5 Runden.
6. Verifiziere: <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <out_dir> muss VERIFY_OK ausgeben.
7. Liefere das Blatt, das Mutationsblatt und die GIFs aus.
8. Studio, falls das Roblox Studio MCP verbunden ist. Folge reference/roblox_studio.md: importieren, reparieren, BoxRigAnim plus <Name>Clips für Posen und KeyframeSequences, MutationFX, dann einen gemessenen Spieltest.

Spickzettel für die Datendatei

• Einheiten und Achsen: Studs, Z nach oben, vorne = -Y, die linke Seite des Tieres = +X.
• Boxen: box(x0, x1, y0, y1, z0, z1, farbe, knochen). sym(...) spiegelt die Box auf die rechte Seite, wobei % im Knochennamen zu L oder R wird; box mit % im Knochen macht dasselbe. Eine spätere Box gewinnt, wo sich Boxen überlappen.
• Voxel-Skulpturieren (die Standardmethode für Kreaturenkörper): setze VOXEL klein genug für glatte Kurven (etwa 1/90 der Körperlänge: 0,5 bei einem großen Drachen, 0,2 bei einem Löwen) und STUD_SIZE größer (2–4 Zellen, z.B. 1,0 / 0,8), damit die Studs klobig und lesbar bleiben. Dann:
  • vell(cx, cy, cz, rx, ry, rz, col, bone): Ellipsoid.
  • vcap(p0, p1, r0, r1, col, bone): verjüngte Kapsel für Hälse, Beine, Schwänze, Hörner und Schnauzen.
  • vbox(...): Box.
  • vsheet(origin, u, v, pts, thick, col, bone): flaches Polygon für Flügel, Flossen und Kragen; bone ('a', split, low, high) teilt es zwischen zwei Knochen auf.
  • Optionen: paint=True färbt nur vorhandene Voxel um (Bauchstreifen, Augen, Markierungen); paint='belly' färbt nur Zellen dieser Farbe um (Bänder über einen Streifen); '%' im Knochen spiegelt nach L und R; mirror=True spiegelt auf demselben Knochen (Hörner, Zähne).
  • Alles wird auf einem Gitter vokalisiert und gierig vernetzt. Halte Radien bei einem Voxel oder darüber, sonst brechen dünne Teile auseinander. Lies „Der Standard-Stil = glatte FORM + klobiges AUSSEHEN“ in reference/design_guide.md.
• Organische Formen, box-basiert (älterer klobiger Stil):
  • ell(cx, cy, cz, rx, ry, rz, farbe, knochen) ist ein abgerundeter, gestufter Klecks aus 3 Boxen. Verwende ihn für Körper, Brust, Hüften, Halssegmente, Oberschenkel und Schwanzsegmente.
  • poly([(x,y),...], z0, z1, farbe, knochen, step=1.0) füllt eine Draufsicht-Kontur. Verwende es für Flügelmembranen, Flossen, Kragen und Schwanzspitzen. bone kann eine Funktion von x sein, um eine Membran auf Wing und WingTip aufzuteilen.
  • beam(p0, p1, breite, z0, z1, farbe, knochen) ist ein gerader Balken für Armknochen, Flügelfinger und Hörner.
• Geflügelte Tiere: Modelliere die Flügel flach ausgebreitet, falte sie dann in den Clips mit wing_rest=(raise, tip_droop, sweep); der Drache verwendet (58, 24, 22). Setze VIEW_POSE = ('Idle', 0), damit das Blatt das Tier mit gefalteten Flügeln stehend zeigt.
• Knochen: BONES[name] = (parent, head, tail). Genau eine Wurzel bei (0,0,0), die keine Boxen hat. Der head-Punkt ist der Gelenkpunkt.
  • Vierbeiner (Quad)-Clips benötigen Body, Head, FrontUpper/Lower_L/R und BackUpper/Lower_L/R. Optional: eine Schwanzkette, eine neck-Kette, wings=('Wing','WingTip') und ein jaw.
  • Zweibeiner (Biped)-Clips benötigen Body, Head und Leg_L/R. Optional: Foot_L/R, Wing_L/R und einen Schwanz.
• Clips: CLIPS = {'Walk': (fn, frames), ...} bei 30 fps, nahtlos, an Ort und Stelle.
  • Fertige Fabriken (nur Schlüsselwortargumente):
    • quad_walk, quad_run, quad_idle(jaw=, yawn=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • Tiere, die fliegen (Drachen, Vögel, Greife, Fledermäuse – alles mit funktionierenden Flügeln), eine Benutzerregel:
    • Walk ist ein Bodengang: Die Beine bewegen sich und die Flügel bleiben still. Verwende quad_walk(..., wings=..., wing_flap=0) oder biped_walk(..., wing_flap=0).
    • Run ist Fliegen: Die Flügel schlagen und die Beine rennen nicht; sie bleiben angelegt und still. Verwende quad_fly(...) oder biped_fly(...), niemals quad_run oder biped_run.
    • Lasse die Flügel niemals schlagen, während die Beine rennen.
  • Feueratem (Drachen und andere Atmer): quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) plus MOUTH = (x, y, z) und MOUTH_BONE = 'Head' in der Datendatei.
    • Der Clip lehnt sich zurück und atmet ein, stößt dann mit offenem Kiefer von t0 bis t1 nach vorne.
    • Die GIFs zeigen eine Ersatzflamme. In Studio steuert assets/FireBreath.lua echte Flammen von den Markern FireStart und FireStop des Clips, farblich pro Mutation.
    • Feuer wird niemals im Animations-Editor angezeigt, der nur Knochen abspielt. Um es im Bearbeitungsmodus anzuzeigen, verwende assets/BoxRigPreview.lua.
    • Ein nach vorne zeigender Kiefer öffnet sich nach unten mit rx +. rx - schwingt ihn nach oben in den Schädel, wo es aussieht, als wäre er verschwunden.
  • Typische Längen: Walk 32–40 Frames, Run 18–24, Idle 90–150.
  • Große Tiere bewegen sich langsamer und schwerer: mehr Frames, größere bob- und bounce-Werte in Studs und eine niedrigere pitch.
  • Ein benutzerdefinierter Clip ist fn(t) -> {bone: ((rx, ry, rz) Grad um Weltachsen am Gelenk, (tx, ty, tz) Studs)}. Vorzeichen: rx + schwingt einen Fuß nach hinten, nickt einen Kopf nach unten und hebt einen Schwanz.
• Mutationen (standardmäßig Gold, Diamond und Shadow) stammen von MUTATIONS in boxrig.py.
  • Jede bildet die Helligkeit der Palette auf eine glatte Farbrampe ab.
  • ROLES benennt die Augenteile (iris, eye, shine, blush), damit sie die komplementären Augenfarben der Mutation erhalten. keep lässt Schlüssel wie Zähne unverändert.
  • Überschreibe sie mit MUTATIONS = {...} und wähle eine Teilmenge mit MUTATIONS_USE aus.

Roblox-freundlich durch Konstruktion (diese nicht brechen)

• Ein Zeichenaufruf: ein Mesh, ein Material und eine gemeinsame 512 Pixel große, sich wiederholende Stud-Struktur. Farben sind Vertex-Farben, die Roblox mit der TextureID multipliziert.
• Starres Skinning (1.0 Gewichte) und Ausblenden von Flächen, die durch eine andere Box auf demselben Knochen verdeckt werden.
• Größe: etwa 800 Dreiecke für ein Haustier und etwa 1.600 für einen Drachen. Halte Mobs unter etwa 3k; die harte Grenze ist 20k.
• Mutationen sind separate Meshes auf demselben Rig: jede Animation funktioniert auf jeder Variante. Die Effekte stammen von einem Emitter und höchstens einem Licht pro Modell.
• Export: FBX ohne Blattknochen, FBX-Einheitsskalierung, -Z nach vorne und Y nach oben, die Wurzel im Ursprung, ein Clip pro FBX.

Mehr Details: reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md und reference/pitfalls.md.