Roblox 箱形骨架動物模型

Roblox 箱形骨架動物模型 是做什麼的？

你要為每隻動物編寫一個小型數據檔案：色板、骨骼、方塊與片段。scripts/boxrig.py 會將該檔案轉換為網格、螺柱、骨架、動畫、突變、渲染與匯出。

範例（預覽圖位於 examples/previews/）：

• examples/penguin.py：二足步行動物。
• examples/dragon.py：全尺寸龍：平滑體素身體/S 型頸部/尾巴 + 方塊構建的頭部、角、板塊與蝙蝠翅膀，具有下顎與火焰吐息閒置動作。
• examples/lion.py：符合解剖學的獅子，帶有粗獷外觀：平滑體素身體、大螺柱、在體素網格上繪製的像素藝術臉孔。examples/lion_chibi.py 是舊版 Q 版獅子，保留作為方塊 API 範例。

需求

• Blender 4.2 或更新版本，以無頭模式執行。在 Windows 上請查閱 C:\Program Files\Blender Foundation\Blender */blender.exe；在 Mac 上請查閱 /Applications/Blender.app/Contents/MacOS/Blender。已於 5.1 版測試。
• Python 3 搭配 Pillow 與 numpy： py -m pip install --user pillow numpy。請勿使用 py -I 執行腳本。
• 下列佔位符： <B> = Blender 可執行檔，<S> = 此技能所在的資料夾。

工作流程

1. 規格，解剖學優先（使用者規則）。 每隻動物都要具備真實動物的結構：真實的身體規劃、比例與輪廓，由方塊構成。絕非只是附加特徵的立方體角色。
   • 閱讀 reference/anatomy.md。查閱真實動物，或使用使用者的參考資料。
   • 以肩高為單位，在數據檔案中以註解形式撰寫其比例：身體長度、頭部、頸部、腿部、尾巴。
   • 用大型形狀勾勒側面輪廓，在添加細節前先進行比對。
   • 只有在使用者要求時，才採用 Q 版或「可愛寵物」比例（大頭、短腿）。
   • 註明 2–4 個特徵與片段（預設為 Walk、Run、Idle）。使用者的參考圖片或模型即為規格。
   • 決定比例：Roblox 角色約 5 個螺柱高；寵物為 4–8 個螺柱；真實尺寸的生物為真實大小（龍約 40 個螺柱長）。不要縮小大型動物。
2. 將最接近的範例複製到使用者的資料夾，或執行 py <S>/scripts/new_animal.py <Name> quad|biped <folder>。切勿在技能資料夾內進行編輯。
3. 編輯數據。 先閱讀 reference/design_guide.md。
4. 建置與渲染：

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

   • <out_dir> 是檔案旁邊的 out_<Name>。
   • 模式包括 views（快速，用於塑形）、gif、export、mutations（檢視、匯出與突變）以及 all。
5. 檢視 <Name>_sheet_vN.png、review_<Clip>_vN.png 與 <Name>_mutations_vN.png。修正數據並使用新標籤重新建置，因為 Read 工具會按路徑快取圖片。通常需要 3–5 輪。
6. 驗證： <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <out_dir> 必須顯示 VERIFY_OK。
7. 交付 工作表、突變工作表與 GIF。
8. Studio（若已連接 Roblox Studio MCP）。遵循 reference/roblox_studio.md：匯入、修正、BoxRigAnim 加上 <Name>Clips（用於姿勢與 KeyframeSequence）、MutationFX，然後進行實地遊玩測試。

數據檔案速查表

• 單位與軸向： 螺柱，Z 軸向上，前方 = -Y，動物的左側 = +X。
• 方塊： box(x0,x1, y0,y1, z0,z1, colour， bone)。sym(...) 將方塊鏡射至右側，其中 % 在骨骼名稱中變為 L 或 R；bone 中包含 % 的 box 也具有相同效果。後續的方塊在重疊處優先。
• 體素雕刻（生物身體的預設方式）： 設定 VOXEL 足夠小以獲得平滑曲線（約身體長度的 1/90：大型龍為 0.5，獅子為 0.2），並將 STUD_SIZE 設定較大（2–4 個單元，例如 1.0 / 0.8），以保持螺柱粗獷且可讀。然後：
  • vell(cx,cy,cz, rx,ry,rz, col, bone)：橢球體。
  • vcap(p0, p1, r0, r1, col, bone)：錐形膠囊，用於頸部、腿部、尾巴、角與口鼻部。
  • vbox(...)：方塊。
  • vsheet(origin, u, v, pts, thick, col, bone)：扁平多邊形，用於翅膀、鰭與皺褶；bone 為 ('a', split, low, high) 可在兩個骨骼之間分割。
  • 選項：paint=True 僅重新著色現有體素（腹部條紋、眼睛、標記）；paint='belly' 僅重新著色該顏色的體素（條紋上的色帶）；骨骼中的 '%' 鏡射至 L 和 R；mirror=True 在同一骨骼上鏡射（角、牙齒）。
  • 所有物件都在一個網格上進行體素化並貪婪地生成網格。保持半徑至少為一個體素，否則薄的部分會斷裂。請閱讀 reference/design_guide.md 中的「預設風格 = 平滑形狀 + 粗獷外觀」。
• 有機形狀，基於方塊（較舊的粗獷風格）：
  • ell(cx,cy,cz, rx,ry,rz, colour， bone) 是一個由 3 個方塊組成的圓角階梯狀團塊。用於身體、胸部、臀部、頸段、大腿與尾段。
  • poly([(x,y),...], z0, z1, colour， bone, step=1.0) 填充俯視輪廓。用於翼膜、鰭、皺褶與尾鏟。bone 可以是 x 的函數，用於將膜片分割到 Wing 與 WingTip 之間。
  • beam(p0, p1, width, z0, z1, colour, bone) 是一條直棒，用於臂骨、翼指與角。
• 有翼動物： 將翅膀建模為平展狀態，然後在片段中透過 wing_rest=(raise， tip_droop, sweep) 將其折疊；龍使用 (58, 24, 22)。設定 VIEW_POSE = ('Idle', 0)，使工作表顯示動物站立並折疊翅膀的姿態。
• 骨骼： BONES[name] = (parent, head, tail)。恰好一個根節點位於 (0,0,0)，且不帶任何方塊。頭點是樞紐。
  • 四足步行片段需要 Body、Head、FrontUpper/Lower_L/R 與 BackUpper/Lower_L/R。可選：尾巴鏈、neck 鏈、wings=('Wing','WingTip') 與 jaw。
  • 二足步行片段需要 Body、Head 與 Leg_L/R。可選：Foot_L/R、Wing_L/R 與尾巴。
• 片段： CLIPS = {'Walk': (fn， frames), ...} 以 30 fps 播放，循環播放，原地不動。
  • 現成的工廠函數（僅限關鍵字引數）：
    • quad_walk、quad_run、quad_idle(jaw=, yawn=)、quad_fly
    • biped_walk、biped_run、biped_idle、biped_fly
  • 會飛的動物（龍、鳥、獅鷲、蝙蝠，以及任何有功能翅膀的生物），使用者規則：
    • Walk 是地面行走：腿部移動，翅膀保持靜止。使用 quad_walk(..., wings=..., wing_flap=0) 或 biped_walk(..., wing_flap=0)。
    • Run 是飛行：翅膀拍動，腿部不跑步；它們保持收起且靜止。使用 quad_fly(...) 或 biped_fly(...)，絕不使用 quad_run 或 biped_run。
    • 絕不在腿部跑步時拍動翅膀。
  • 火焰吐息（龍與其他吐息生物）：quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) 加上數據檔案中的 MOUTH = (x, y, z) 與 MOUTH_BONE = 'Head'。
    • 片段會先向後仰並吸氣，然後在 t0 到 t1 期間張開下顎向前突進。
    • GIF 會顯示一個替代火焰。在 Studio 中，assets/FireBreath.lua 會根據片段中的 FireStart 與 FireStop 標記驅動真實火焰，並按突變著色。
    • 火焰絕不會在動畫編輯器中顯示，因為它只播放骨骼。若要在編輯模式下顯示，請使用 assets/BoxRigPreview.lua。
    • 向前的下顎以 rx + 向下張開。rx - 會使其向上擺動到頭骨中，看起來就像消失了。
  • 典型長度：Walk 32–40 幀，Run 18–24 幀，Idle 90–150 幀。
  • 大型動物移動更慢、更重：更多幀數，更大的 bob 與 bounce（單位為螺柱），以及更低的 pitch。
  • 自訂片段是 fn(t) -> {bone: ((rx,ry,rz) 度數，繞世界軸，位於關節處, (tx,ty,tz) 螺柱)}。符號：rx + 使腳向後擺，使頭向下點，使尾巴抬起。
• 突變（預設為 Gold、Diamond 與 Shadow）來自 boxrig.py 中的 MUTATIONS。
  • 每個突變都將色板的亮度對應到平滑的顏色漸層上。
  • ROLES 命名眼睛部分（iris、eye、shine、blush），使它們獲得突變的互補眼色。keep 使牙齒等鍵保持不變。
  • 透過 MUTATIONS = {...} 覆蓋它們，並使用 MUTATIONS_USE 挑選子集。

天生 Roblox 友善（請勿破壞以下規則）

• 一次繪製呼叫： 一個網格、一個材質與一個共用的 512 像素平舖螺柱紋理。顏色是頂點顏色，Roblox 會將其與 TextureID 相乘。
• 剛性蒙皮（權重 1.0）並隱藏被同一骨骼上其他方塊遮擋的面。
• 尺寸： 寵物約 800 個三角形，龍約 1,600 個。將生物控制在約 3k 以下；硬性限制為 20k。
• 突變 是同一骨架上的獨立網格：每個動畫都能在每個變體上運作。效果來自一個發射器與每個模型最多一個光源。
• 匯出： FBX，無葉子骨骼，FBX 單位比例，-Z 向前，Y 向上，根節點位於原點，每個 FBX 一個片段。

更多詳細資訊：reference/design_guide.md、reference/roblox_rules.md、reference/roblox_studio.md 與 reference/pitfalls.md。