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 个标志性特征和动画片段（默认行走、奔跑、待机）。用户的参考图片或模型就是规格。
   • 决定比例：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 加上用于姿势和 KeyframeSequence 的 <Name>Clips、MutationFX，然后进行实测。

数据文件速查表

• 单位和轴向： 钉状单位，Z 向上，前方 = -Y，动物左侧 = +X。
• 方块： box(x0,x1, y0,y1, z0,z1, colour, bone)。sym(...) 将方块镜像到右侧，其中 % 会在骨骼名称中变为 L 或 R；在骨骼中使用 % 的 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)：平面多边形，用于翅膀、鳍和褶边；骨骼 ('a', split, low, high) 将其分裂到两根骨骼之间。
  • 选项：paint=True 仅重新着色现有体素（腹部条纹、眼睛、标记）；paint='belly' 仅重新着色该颜色的体素（条纹上的色带）；骨骼中的 '%' 镜像到左右；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
  • 会飞的动物（龙、鸟、狮鹫、蝙蝠，任何有功能性翅膀的），用户规则：
    • 行走 是地面行走：腿部移动，翅膀保持静止。使用 quad_walk(..., wings=..., wing_flap=0) 或 biped_walk(..., wing_flap=0)。
    • 奔跑 是飞行：翅膀扇动，腿部不奔跑；它们保持收起并静止。使用 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 - 会将其向上摆入头骨，看起来就像消失了一样。
  • 典型长度：行走 32-40 帧，奔跑 18-24，待机 90-150。
  • 大型动物移动更慢更重：更多帧，更大的 bob 和 bounce（以钉状单位计），以及更低的 pitch。
  • 自定义动画片段是 fn(t) -> {bone: ((rx,ry,rz) 以世界轴在关节处的度数, (tx,ty,tz) 钉状单位)}。符号：rx + 向后摆动脚，向下点头，抬起尾巴。
• 变异形态（默认为金色、钻石和暗影）来自 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。