robô-animais-bloco-roblox

Animais box-rig para Roblox

Você escreve um pequeno arquivo de dados para cada animal: paleta, ossos, caixas e clipes. O scripts/boxrig.py transforma esse arquivo na malha, studs, rig, animações, mutações, renders e exportações.

Exemplos, com prévias em examples/previews/:

• examples/penguin.py: um bípede.
• examples/dragon.py: um dragão em tamanho real: corpo voxel suave/pescoço-S/cauda + cabeça construída com caixas, chifres, placas e asas de morcego, com mandíbula e um idle de sopro de fogo.
• examples/lion.py: um leão com anatomia correta e aparência encorpada: corpo voxel suave, studs grandes, rosto pixel art desenhado na grade de voxels. examples/lion_chibi.py é o leão chibi antigo, mantido como exemplo de API de caixas.

Requisitos

• Blender 4.2 ou superior, executado headless. No Windows, procure em C:\Program Files\Blender Foundation\Blender */blender.exe; no Mac, /Applications/Blender.app/Contents/MacOS/Blender. Testado na versão 5.1.
• Python 3 com Pillow e numpy: py -m pip install --user pillow numpy. Não execute os scripts com py -I.
• Placeholders abaixo: <B> = o executável do Blender, <S> = a pasta desta skill.

Fluxo de trabalho

1. Especificação, anatomia primeiro (regra do usuário). Cada animal recebe a estrutura do animal real: seu plano corporal real, proporções e silhueta, construídos a partir de blocos. Nunca um personagem cúbico com recursos colados.
   • Leia reference/anatomy.md. Pesquise o animal real ou use a referência do usuário.
   • Escreva suas proporções em alturas de ombro como comentários no arquivo de dados: comprimento do corpo, cabeça, pescoço, pernas, cauda.
   • Bloqueie a silhueta lateral com formas grandes e ajuste antes de adicionar detalhes.
   • Proporções chibi ou "pet fofo" (cabeça grande, pernas curtas) apenas quando o usuário pedir.
   • Anote 2 a 4 características marcantes e os clipes (padrão Walk, Run, Idle). Uma imagem de referência ou modelo do usuário é a especificação.
   • Decida a escala: um personagem Roblox tem cerca de 5 studs de altura; pets têm 4 a 8 studs; criaturas de tamanho real são em escala real (um dragão tem cerca de 40 studs de comprimento). Não encolha animais grandes.
2. Copie o exemplo mais próximo para a pasta do usuário ou execute py <S>/scripts/new_animal.py <Nome> quad|biped <pasta>. Nunca edite dentro da skill.
3. Edite os dados. Leia primeiro reference/design_guide.md.
4. Construa e renderize:

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

   • <out_dir> é out_<Nome> ao lado do arquivo.
   • Os modos são views (rápido, para modelagem), gif, export, mutations (visualizações, exportação e mutações) e all.
5. Revise <Nome>_sheet_vN.png, review_<Clip>_vN.png e <Nome>_mutations_vN.png. Corrija os dados e reconstrua com uma nova tag, pois a ferramenta Read armazena imagens em cache por caminho. Geralmente 3 a 5 rodadas.
6. Verifique: <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <out_dir> deve imprimir VERIFY_OK.
7. Entregue a planilha, a planilha de mutações e os GIFs.
8. Studio, se o MCP do Roblox Studio estiver conectado. Siga reference/roblox_studio.md: importe, corrija, BoxRigAnim mais <Nome>Clips para poses e KeyframeSequences, MutationFX e, em seguida, um playtest medido.

Folha de dicas do arquivo de dados

• Unidades e eixos: studs, Z para cima, frente = -Y, esquerda do animal = +X.
• Caixas: box(x0,x1, y0,y1, z0,z1, cor, osso). sym(...) espelha a caixa para o lado direito, com % tornando-se L ou R no nome do osso; box com % no osso faz o mesmo. Uma caixa posterior vence onde as caixas se sobrepõem.
• Escultura voxel (padrão para corpos de criaturas): defina VOXEL pequeno o suficiente para curvas suaves (cerca de 1/90 do comprimento do corpo: 0.5 em um dragão grande, 0.2 em um leão) e STUD_SIZE maior (2–4 células, ex.: 1.0 / 0.8) para que os studs permaneçam encorpados e legíveis. Então:
  • vell(cx,cy,cz, rx,ry,rz, col, osso): elipsóide.
  • vcap(p0, p1, r0, r1, col, osso): cápsula cônica, para pescoços, pernas, caudas, chifres e focinhos.
  • vbox(...): caixa.
  • vsheet(origem, u, v, pts, espessura, col, osso): polígono plano, para asas, nadadeiras e babados; osso ('a', split, low, high) divide entre dois ossos.
  • Opções: paint=True recolor apenas voxels existentes (listra na barriga, olhos, marcações); paint='barriga' recolor apenas células dessa cor (faixas em uma listra); '%' no osso espelha para L e R; mirror=True espelha no mesmo osso (chifres, dentes).
  • Tudo é voxelizado em uma grade e mesclado vorazmente (greedy mesh). Mantenha raios em ou acima de um voxel, ou partes finas se quebrarão. Leia "O estilo padrão = FORMA suave + APARÊNCIA encorpada" em reference/design_guide.md.
• Formas orgânicas, baseadas em caixas (estilo encorpado antigo):
  • ell(cx,cy,cz, rx,ry,rz, cor, osso) é uma massa arredondada em degraus feita de 3 caixas. Use para corpos, peitos, quadris, segmentos de pescoço, coxas e segmentos de cauda.
  • poly([(x,y),...], z0, z1, cor, osso, passo=1.0) preenche um contorno em vista superior. Use para membranas de asas, nadadeiras, babados e pás de cauda. osso pode ser uma função de x, para dividir uma membrana entre Wing e WingTip.
  • beam(p0, p1, largura, z0, z1, cor, osso) é uma barra reta, para ossos de braço, dedos de asa e chifres.
• Animais alados: modele as asas espalhadas e planas, depois dobre-as nos clipes com wing_rest=(levantar, ponta_cair, varrer); o dragão usa (58, 24, 22). Defina VIEW_POSE = ('Idle', 0) para que a planilha mostre o animal em pé com as asas dobradas.
• Ossos: BONES[nome] = (pai, cabeça, cauda). Exatamente uma raiz em (0,0,0), que não possui caixas. O ponto da cabeça é o pivô.
  • Clipes de quadrúpedes precisam de Body, Head, FrontUpper/Lower_L/R e BackUpper/Lower_L/R. Opcionais: uma cadeia de cauda, uma cadeia de neck (pescoço), wings=('Wing','WingTip') e uma jaw (mandíbula).
  • Clipes de bípedes precisam de Body, Head e Leg_L/R. Opcionais: Foot_L/R, Wing_L/R e uma cauda.
• Clipes: CLIPS = {'Walk': (fn, quadros), ...} a 30 fps, sem interrupções, no lugar.
  • Fábricas prontas (apenas argumentos nomeados):
    • quad_walk, quad_run, quad_idle(jaw=, yawn=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • Animais que voam (dragões, pássaros, grifos, morcegos, qualquer coisa com asas funcionais), uma regra do usuário:
    • Walk é uma caminhada no chão: as pernas se movem e as asas ficam paradas. Use quad_walk(..., wings=..., wing_flap=0) ou biped_walk(..., wing_flap=0).
    • Run é voar: as asas batem e as pernas não correm; elas ficam dobradas e paradas. Use quad_fly(...) ou biped_fly(...), nunca quad_run ou biped_run.
    • Nunca bata as asas enquanto as pernas correm.
  • Sopro de fogo (dragões e outros que sopram fogo): quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) mais MOUTH = (x, y, z) e MOUTH_BONE = 'Head' no arquivo de dados.
    • O clipe recua e inspira, depois empurra para frente com a mandíbula aberta de t0 a t1.
    • Os GIFs mostram uma chama provisória. No Studio, assets/FireBreath.lua gera chamas reais a partir dos marcadores FireStart e FireStop do clipe, coloridos por mutação.
    • O fogo nunca aparece no Animation Editor, que reproduz apenas ossos. Para mostrá-lo no modo Edit, use assets/BoxRigPreview.lua.
    • Uma mandíbula apontando para frente abre para baixo com rx +. rx - balança para cima no crânio, onde parece que desapareceu.
  • Comprimentos típicos: walk de 32 a 40 quadros, run de 18 a 24, idle de 90 a 150.
  • Animais grandes se movem mais devagar e mais pesados: mais quadros, maior bob e bounce em studs, e um pitch mais baixo.
  • Um clipe personalizado é fn(t) -> {osso: ((rx,ry,rz) graus em torno dos eixos mundiais na junta, (tx,ty,tz) studs)}. Sinais: rx + balança um pé para trás, acena uma cabeça para baixo e levanta uma cauda.
• Mutações (Gold, Diamond e Shadow por padrão) vêm de MUTATIONS em boxrig.py.
  • Cada uma mapeia o brilho da paleta para uma rampa de cores suave.
  • ROLES nomeia as partes dos olhos (iris, eye, shine, blush) para que recebam as cores de olhos complementares da mutação. keep deixa chaves como dentes inalteradas.
  • Substitua com MUTATIONS = {...} e escolha um subconjunto com MUTATIONS_USE.

Amigável ao Roblox por construção (não quebre estas regras)

• Uma chamada de desenho (draw call): uma malha, um material e uma textura de studs de 512 px com repetição (tiling) compartilhada. As cores são cores de vértice, que o Roblox multiplica pelo TextureID.
• Skinning rígida (pesos 1.0) e remoção de faces ocultas por outra caixa no mesmo osso.
• Tamanho: cerca de 800 triângulos para um pet e cerca de 1.600 para um dragão. Mantenha mobs abaixo de cerca de 3k; o limite máximo é 20k.
• Mutações são malhas separadas no mesmo rig: toda animação funciona em todas as variantes. Os efeitos vêm de um emissor e no máximo uma luz por modelo.
• Exportação: FBX sem ossos folha, escala unitária do FBX, -Z para frente e Y para cima, raiz na origem, um clipe por FBX.

Mais detalhes: reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md e reference/pitfalls.md.