scenario-roblox-assets

Roblox 资产管线与 UGC

目标：在 macOS 上使用 scenario-roblox-expert 工具包，面向 Roblox Studio（2026 年 10 月版本）。

这里的专家级标准意味着：每个网格导入 Studio 时都已设置为正确的尺寸（以 stud 为单位）、朝向 -Z、符合三角形预算、在需要时为封闭网格，贴图尺寸和拆分方式也符合 Roblox 的要求，并且有数据证明。先在 Blender 中修复，再在 Studio 中预览和审核，无需上传；在本地验证通过后，恰好在 Roblox 需要上传资产的环节停止。

如果你可用的技能中缺少此处提到的同级技能，请让用户安装该技能 （npx skills add scenario-labs/skills --skill <name>）；若无人值守，请根据工具架构继续操作，并指出缺失项。

必需背景知识： scenario-roblox-expert（频道、审核流程、工具包、当前 Roblox 的注意事项）。

立场（专家级的差异）

1. 将 AI GLB 视为存在已知缺陷的原始输入。 图像转 3D 输出的尺寸约为 0.95 个单位，正面朝向 +Z，每个材质的 doubleSided 都为 true，metallicFactor 为 1.0 且绘制了部分金属度，贴图为 2048 px JPEG，并存在针孔[新增，基于两份生成结果测量]。原始网格需要重新网格化、调整轴心和缩放（CallMeDogey）。
2. 在 Blender 中确定以 stud 为单位的尺寸，而非在 Studio 中确定。 一个 Blender 单位等于一个 stud；因此 glTF 不需要设置 Importer 缩放（Creator 文档，Importer；KatsBits [00:02:56]）。道具的轴心设在底部中心（Common Sense Machines [00:02:39]）；配饰的轴心设在网格中心（验证 #173）。
3. 导出前将正面转向 -Z。 glTF 正面朝向 +Z；Roblox 的 LookVector 为 -Z。在 Blender 中将偏航旋转 180 度即可一劳永逸地修正[新增]。
4. 配饰看其包围盒，帽子看其帽冠。 包围盒按 AccessoryType 划分，以附件点为中心测量，旋转会使包围盒增大（KatsBits [00:10:34]）。包围盒遵循 AvatarPartScaleType：none 或 Classic 使用 GetValidationRules() 的包围盒（Hat 为 3 x 4 x 3），ProportionsNormal 使用文档中的数值（1.87 x 2.5 x 1.87）[新增，基于实时测试]。调整帽子尺寸，使帽冠高于头部，然后检查包围盒：测试帽的帽檐填满 Normal 包围盒时，帽冠比默认头部更窄[新增]。
5. 测量水密性；不要相信填充操作符。 在测试帽上，bmesh.ops.holes_fill 只封住了 9 个针孔中的 2 个，而减面后又产生了拥有三个面的边[新增]。逐个封住边界环，减面后修复，再次统计边界边。切勿使用 Make Double Sided 来掩盖孔洞（Creator 文档，Importer）。
6. 无需上传即可预览。 EditableMesh 和 EditableImage 可在体验中重建处理好的网格及其 PBR 贴图，用于审核、穿戴测试和截图[新增]。这些内容仅在会话期间存在，在试玩副本中为空[新增]；迭代时通过 Importer 导入，并关闭 Upload to Roblox（Creator 文档；Templates [00:02:31]）。
7. 在本地验证通过后停止。 ValidateUGCAccessoryAsync 会在试玩期间运行 Roblox 验证器。修复所有与几何、架构、材质或包围盒有关的字符串错误；与所有权和审核相关的错误需要上传资产，应在此处结束 Agent 的工作（Creator 文档，验证系统）。
8. 贴图遵循纹理密度，而非源图尺寸。 每 2 x 2 x 2 stud 使用 256 px，尺寸为 2 的幂；法线贴图使用 OpenGL；除非设计为缎面，否则金属度设为 0 或 1；配饰使用不透明的 ColorMap（Creator 文档，纹理规格和 SurfaceAppearance）。

预先确定

• 目标：体验内道具，或 Marketplace 头像物品。只有第二种必须通过验证，并且网格必须封闭。
• 每个资产的尺寸（单位为 studs；R15 角色身高约为 5 到 6 studs），以及配件要使用的 AccessoryType 和将声明的 AvatarPartScaleType（Classic、ProportionsNormal、ProportionsSlender）。
• 预算类别：主打道具、杂物或配件（4,000 个三角形）。
• 来源：scenario-3d 中的 GLB（首选）、FBX（需要 FBX Unit Scale）或 OBJ（仅网格）。
• 导入后，将已绑定骨架或蒙皮的输入交给 scenario-roblox-animation。
• 未指定时的默认值：道具、底部枢轴、最长边按概念图的比例确定、纹理边长取自 texture_side、帽冠开口为 1.35 studs、不使用缩放类型（Classic 方框）。

流程

完整代码和记录结果见：procedures.md。设置： import rbx_assets as ra（它会查找主工具包）。除注明尚未运行的内容外，每段代码均于 2026-10-19 在 Studio 0.743 或 Blender 5.2 中运行。Edit 和 Playtest 截图确认了贴合度（被遮挡的窗口会返回暗色帧：请先依据数值判断）。

1. 分类检查。 目标：了解缺陷。方法：离线运行 ra.glb_info(path)。关卡：记录每个资产的三角形数量、尺寸、贴图尺寸、doubleSided、蒙皮和扩展。
2. 在 Blender 中修复。 目标：尺寸、朝向、枢轴、预算、封闭网格、Roblox 贴图。方法：运行 ra.blender_prep({**ra.PROP_PREP or ra.ACCESSORY_PREP, "input", "out_dir", "yaw": 180, "scale": ...})；帽子使用 {"opening": 1.35, "band": [0.08, 0.2], "cap": [3, 4, 3]}。该命令会等待机器防护程序，运行 blender -b，并生成报告和四张 Workbench 视图。关卡：ra.gates(report["after"], kind, type) 全部通过，且正视图显示正面。
3. 读取实时规则。 目标：获取当前限制。方法：运行 ra.run(studio, "return AssetAudit.rules()", kit=["AssetAudit"])。关卡：记录 AccessoryMaxTriangles、MaxTextureSize 以及该类型附件的 Size 和 Offset；离线关卡会使用这些值。
4. 在 Studio 中预览并审核。 目标：在场景中测量资产。方法：通过 ra.stage 暂存打包后的网格和贴图，然后运行 MeshBuild.build 和 AssetAudit.prop。关卡：Size 与 Blender 尺寸相差不超过 0.01 stud，三角形数量一致，没有审核错误，正面截图显示正面。
5. 构建配件。 目标：创建一个包含 Accessory、Handle 和一个按类型命名的附件的配件。方法：运行 MeshBuild.accessory，然后运行 AssetAudit.accessory(acc, rules)。关卡：错误数为零；AvatarPartScaleType 是唯一警告（Accessory Fitting Tool 会添加它）。
6. 试戴。 目标：确保配件佩戴合适。方法：在 Edit 中运行 UGCCheck.rig 和 UGCCheck.wear，然后拍摄正面和侧面截图。关卡：存在关节，附件误差小于 0.01 stud，opening.clears（帽冠在头顶处至少与头部一样宽），且截图中帽檐贴合头部。
7. 在本地验证。 目标：只剩下上传时才会检查的字符串。方法：在 Playtest 中，运行 ra.stage(..., dm="Server") 和 UGCCheck.validate(acc, Enum.AccessoryType.Hat)；使用单一故障副本作为负向对照，每 60 秒最多调用 10 次。关卡：物品返回有效，且没有字符串；每个故障副本均验证失败。
8. 移交导入。 目标：按正式发布流程操作。方法：由人工或计算机操作 Agent 按照 gui-paths.md 中的设置导入 <name>_roblox.glb；Accessory Fitting Tool 会生成最终配件。关卡：导入的 MeshPart 的 Size 与预览一致；P7 会再次审核。

数值

数值	相对于	来源
20,000 个三角形	场景中的一个网格	Creator Docs
4,000 个三角形	刚性或分层配饰	Creator Docs；实时 AccessoryMaxTriangles
60,000 个顶点，20,000 个三角形	一个 EditableMesh；一个四边形计为 2 个三角形	EditableMesh reference
每 2 x 2 x 2 studs 为 256 px	纹理边长，取下一个 2 的幂	Texture specifications
4096 px	场景纹理（自 2026-01-30 起）	DevForum
1024 px	Avatar ColorMap，实时 MaxTextureSize；其他 avatar 映射为 256	Validation system；实时
1024 px	EditableImage 边长	AssetService reference
帽子 3 x 4 x 3 studs	无 AvatarPartScaleType 或 Classic；ProportionsNormal 为 1.87 x 2.5 x 1.87	实时规则和验证器；配饰规格
10 个部件	每个配饰 MeshPart 中不相连的组件数	Validation #187
0.05 至 4.0 studs	avatar 部件的 MeshPart 各轴尺寸	Validation #176、#177
0.02	AlphaMode 为 Transparency 时，柔和 alpha 对应的最低 MeshPart.Transparency 值	SurfaceAppearance
0 至 40	Marketplace 商品的 EmissiveStrength 值	SurfaceAppearance
1.35 studs	帽冠开口尺寸，适用于默认头部尺寸为 1.16 studs 的 R15 头部	[新增，佩戴测试]
0.3 stud	帽子在网格底部上方的配饰点位置：帽檐位于头部顶部下方四分之一头高处	[新增，佩戴测试和贴合渲染]
每 60 s 调用 10 次	ValidateUGCAccessoryAsync 速率限制	实时错误字符串

质量门槛

可测量项：

• Blender 报告：每个 ra.gates 条目都通过；原始输入未通过其应失败的检查（负向对照）。
• Studio：AssetAudit 未返回错误；Size 和三角形数量与报告一致。
• 佩戴效果：关节存在，配饰点误差小于 0.01 stud。
• 验证器：不再有无需上传即可修复的字符串。

视觉检查（使用一张不超过 1,600 px 的联系表，并打开查看）：

• 每个素材正面朝向 -Z 方向的相机；道具放在地面上；没有黑色或内外翻转的部分。
• 从正面和侧面看，帽子都贴合头部，既不悬空，也没有陷入帽檐以下。
• 纹理符合概念设计：细节位置正确，没有模糊的纹理图集。

在宣布完成前，使用 critique.md 对结果评分。

常见错误

错误	症状	修复
直接导入单位尺寸的 GLB	物件只有一个砖块那么大	在 Blender 中按 studs 缩放；Scale Unit Studs
glTF 输入没有设置偏航角	锁或正面朝向背面	导出前设置 yaw: 180
使用 Make Double Sided 隐藏孔洞	验证时报边界边错误；出现双重三角形	在 Blender 中封闭孔洞
信任 holes_fill	修复后仍显示“Not watertight”	封闭环线，在简化后修复，并重新统计
在 Studio 中直接简化模型	上传时超过 4,000 个三角形	在 Blender 中简化到 3,800 个
将打包的金属度-粗糙度贴图用作单张贴图	金属效果无处不在或完全没有	将 G 和 B 通道拆分为灰度贴图
保留部分金属度	金属呈现着色效果，像塑料	读取遮罩后，将值设为 0 或 1
配件上的 ColorMap 带有透明度	验证错误 #145，出现透明区域	使用 opaque_color
同时设置 TextureID 和 SurfaceAppearance	验证错误 #146	只设置其中一个
配件上保留了属性或标签	验证错误 #191	验证前清除
配件的枢轴位于脚部	“Mesh data is not centered”	将枢轴居中
在 fitting box 内旋转帽子	虽然网格看起来在盒内，但盒子显示红色	在 Blender 中重新居中并调整朝向
根据帽檐调整帽子尺寸	头部从帽冠处穿出	设置 scale.opening，然后设置 opening.clears
Massless 在 Handle 上设为 true	验证器提示：“Expected to be = false”	保留默认值
从客户端对自己的角色调用 AddAccessory	没有关节；帽子掉落	在服务端附加；通过 CFrame 为本地预览定位
帽子网格和贴图由服务端上的 Editable 内容构建	客户端在 Handle 处绘制一个小棋盘格方块	在服务端保留关节；在每个客户端上应用本地构建的网格（ApplyMesh）和 SurfaceAppearance（流程 P8）
以为 EditableMesh 预览会保存	重新打开后 Part 为空	仅限当前会话；要实际使用请导入
以为游戏测试中会显示 Edit 预览	复制的部件保留 Size，但没有网格	在该数据模型中暂存并构建

交接

• 接收来自 scenario-3d 的内容：带有 PBR 贴图的 GLB 或 FBX 网格（图像转 3D、重网格、重新贴图、绑定骨骼）。如果简化破坏了轮廓，请求执行重网格。
• 接收来自 scenario-textures 的内容：适用于单个网格的 PBR 贴图集，在此处转换为 SurfaceAppearance。可平铺的贴图集作为 MaterialVariants 交给 scenario-roblox-environment。
• 接收来自 scenario-game-assets 的内容：由 scenario-3d 转换为网格的概念图（一个居中的主体、纯色背景、正面视图）。图标、精灵图和 UI 美术资源交给 scenario-roblox-ui，贴花交给 scenario-roblox-environment。
• 交付给 scenario-roblox-environment：保持真实尺寸、底部设有枢轴的 MeshParts，并附上建议的 CollisionFidelity 和检查报告；由其负责放置、设置最终的保真度和 LevelOfDetail，并进行光照。
• 交付给 scenario-roblox-animation：已绑定骨骼或蒙皮的导入资源，并检查比例和朝向。
• 交付给 scenario-roblox-performance：每批导入资源，用于内存和批处理审计 （references/memory-and-crowds.md、PerfAudit.assets）；此技能不会重复进行这些审计。

当前 Roblox 说明

• EditableMesh 和 EditableImage 不能通过 Instance.new 创建；请使用 AssetService:CreateEditableMesh()、CreateEditableImage() 和 Content.fromObject。已发布的体验需要启用 Mesh 和 Image API 设置。
• CreateSurfaceAppearanceAsync 只接受 EditableImage 内容；之后无法替换贴图。
• Avatar Joint Upgrade 使用 RigidConstraint 连接刚性配件，而不是焊接。请使用 FindFirstChild(name, true) 查找附件。
• GenerateMeshAsync 计划弃用；使用 schema 为 Car5 或 Body1 的 GenerationService:GenerateModelAsync 替代。
• 自 2026-01-30 起，Places 支持 4096 px 贴图；Avatar 限制来自 GetValidationRules()。
• Studio MCP 以插件权限运行：在 Edit 模式下，它写入了 SurfaceAppearance.ColorMap、 ColorMapContent 和 MeshPart.CollisionFidelity，且未报错。游戏脚本的权限较少； 发布前请先在 Script 中测试代码片段。
• generate_mesh（Studio MCP）仅返回 {generationName, tag}，并插入一个由分段 MeshParts 组成的 Model，其中包含资源 ID 和 TextureID；请传入 size、maxTriangles 和 segmentation。

参考资料

• references/expert-notes.md：按来源整理的原则、分歧，以及实时运行新增的内容。
• references/procedures.md：P1 到 P11 的完整代码、测试 ID 和结果。
• references/avatar-item-checks.md：每个封装背后的引擎调用、多个身体上的动作、六视图不透明度、倾斜、Fitting Tool 残留项（Unknown type、TexturePack、MeshSize）。
• references/critique.md：检查你自己输出的阻断性问题和质量问题。
• references/gui-paths.md：Importer、Accessory Fitting Tool、验证插件和 Blender 路径。
• references/sources.md：所有文档和视频的凭据与时间戳。
• scripts/rbx_assets.py：GLB 分流、带机器防护的 Blender 运行器、检查门槛、贴图尺寸调整、负载、工具包运行器。
• scripts/blender_roblox_prep.py：无头 Blender 检查和预处理流程。
• scripts/agentkit/assets/：Payload、MeshBuild、AssetAudit、 UGCCheck。