用途:为 Roblox 虚拟形象和角色提供可穿戴的服装(衬衫/裤子)、发型、肤色发色,使其外观更真实、更多样。资料指出 Studio 的 search_asset MCP 只能访问 Creator Store 的开发资产,不能访问头像 Marketplace,因此需要走 catalog Web API。
主要能力:
- 通过 catalog 搜索接口按关键词检索资产 ID,例如 https://catalog.roblox.com/v1/search/items?category=Clothing&subcategory=ClassicShirts&keyword=<X>&limit=10。limit 必须为 10 或 28;category=Accessories、creatorTargetId 等会返回 HTTP 400。可用子类包括 ClassicShirts、ClassicTShirts、ClassicPants。
- 将服装资产 ID 解析为可用的模板 ID:在服务端使用 InsertService:LoadAsset(assetId) 加载模型,读取 Shirt.ShirtTemplate,再用 :match("%d+") 提取数字,最后设置 shirt.ShirtTemplate = "rbxassetid://<templateId>" 并设置 Parent。Pants 同理。
- 发型验证:对候选 ID 设置 HumanoidDescription.HairAccessory,调用 Players:CreateHumanoidModelFromDescription(desc, Enum.HumanoidRigType.R15),统计 Accessory 后代数量是否大于 0。关键词应使用风格词(如 buzz cut hair、afro hair、man bun hair、curly fade、dreadlocks、slicked back hair、headband hair),通用 hair 关键词多返回动漫风格 UGC。
- 人工挑选:ViewportFrame 渲染偏暗,建议在有光照的 workspace 骨架上渲染候选并加带编号的 BillboardGui,再 screen_capture 挑选。生成前需设置 HeadColor、TorsoColor、LeftArmColor 等肤色字段,否则预览为黑色身体。需焊接配件并锚定部件,完成后清理临时骨架并恢复相机与 Freecam。
- 按民族/身份加权:用 SKIN 约 8 色调色板、NATION_SKIN 加权索引、skinFor(nation, hash) 选取;HAIR_COLORS 与 NATION_HAIR 同理,并通过 Handle.Color 着色。
- 角色签名覆盖:用 CARD_HAIR 映射表按 id 优先指定发型,示例 local hair = CARD_HAIR[id] or HAIR[(hash // k) % #HAIR + 1]。
使用方式:以上步骤均在 Roblox Studio/服务端脚本中完成,涉及 WebFetch 调用 catalog 接口与 InsertService 加载资产。
适用场景:需要批量生成外观一致或按身份分布的角色、为球衣/服装项目制作可穿戴服装、为特定角色固定签名造型。
限制与风险:catalog 接口参数受限(limit 为 10 或 28,部分 category 返回 400);InsertService 仅服务端可用;真实品牌套件与标识存在商标风险;真人面孔在 Roblox 上不可实现,建议使用通用经典表情。