roblox-avatar-appearance

Roblox 头像外观流程

如何为头像添加真实、多样、准确的服装／头发／肤色——这些细节并不显而易见。

核心问题

Studio 的 search_asset MCP 工具只能访问 Creator Store（开发资源：模型／图像／贴花），无法访问头像 Marketplace（服装／配饰）。而且它找到的足球／角色“球衣”模型是由 300 多个部件组成的 3D 网格，根本无法作为可穿戴服装使用。因此，你必须使用目录 Web API。

通过目录 Web API 获取资源（突破性方法）

使用 WebFetch 调用目录搜索端点——它会根据关键词和类别／子类别筛选条件返回资源 ID：

https://catalog.roblox.com/v1/search/items?category=Clothing&subcategory=ClassicShirts&keyword=<X>&limit=10

• limit 必须是 10 或 28。 6／20 会返回 HTTP 400。category=Accessories 和 creatorTargetId 也会返回 400。
• 可用的子类别：ClassicShirts、ClassicTShirts、ClassicPants。搜索头发时，使用 category=Clothing 没用——应按风格关键词搜索配饰（见下文）。
• 该端点只返回资源 ID；接下来需要解析详细信息。

衬衫／裤子：资源 ID → 可用的 ShirtTemplate ID

目录会提供 Shirt 资源 ID，但 Shirt 对象需要的是 ShirtTemplate 图像 ID（两者编号不同）。逐个解析：

1. InsertService:LoadAsset(assetId)——仅在 SERVER 数据模型中有效（客户端／编辑模式会被阻止）。
2. 读取已加载模型的子项 Shirt.ShirtTemplate → 这就是可用的模板 ID（:match("%d+")）。
3. 将其应用为真实对象：shirt.ShirtTemplate = "rbxassetid://<templateId>"（或 http://www.roblox.com/asset/?id=<id>），shirt.Parent = model。裤子也用同样的方法。

头发（及其他配饰）：验证后再手动挑选

1. 验证每个候选项是否是真正的头发： 在 HumanoidDescription 上设置 desc.HairAccessory = tostring(id)，然后调用 Players:CreateHumanoidModelFromDescription(desc, Enum.HumanoidRigType.R15)，并统计 Accessory 子项数量是否大于 0。很多“头发”搜索结果并不是有效的 HairAccessories。
2. 关键词很重要： 通用的 hair／classic hair 关键词返回的结果大多是尖刺造型的 ANIME UGC。按风格搜索：buzz cut hair、afro hair、man bun hair、curly fade、dreadlocks、slicked back hair、headband hair——这些会返回更写实的发型。真正经典的 Roblox 头发似乎已归档或无法搜索；写实风格的 UGC 是切实可行的替代方案。

渲染后手动挑选（不能盲目信任 ID）

• ViewportFrame 渲染效果很暗——在有灯光的 workspace 人形模型上渲染候选项，并添加带编号的 BillboardGui，然后使用 screen_capture 逐个查看，挑出合适／有代表性的选项。
• 空白 HumanoidDescription 会生成黑色身体。 生成模型前，先将颜色字段（desc.HeadColor、TorsoColor、LeftArmColor 等）设置为肤色，否则预览无法使用。
• 焊接配饰并锚定部件，确保拍摄时人形模型保持静止。之后清理临时人形模型文件夹并恢复相机（CameraType = Custom，重新启用 Freecam）。

按国家／身份加权的肤色和发色

要生成符合身份特征的外观（而不是随机选择），请使用按国家（或队伍／阵营）索引的小型加权分布表，并通过卡片／角色 ID 的稳定哈希值进行选择：

• SKIN = 约 8 种肤色的调色板（由浅到深）。NATION_SKIN[nation] = {weighted indices}（重复索引会增加被选中的概率）。skinFor(nation, hash) = SKIN[pool[(hash % #pool) + 1]]，未知国家使用覆盖完整范围的备用方案。
• HAIR_COLORS（由黑到金再到灰）+ NATION_HAIR[nation] = {weighted indices}，方法相同。将头发网格的 Handle.Color 染成选定的颜色，让数量不多的网格也能呈现多样发色。
• 实际验证：对应国家使用深色肤色；北欧角色使用金发；不同阵营的肤色应涵盖由浅到深的范围。

每张卡片／角色的标志性外观覆盖

要让主打角色始终容易辨认（而不是随机哈希选择），请添加一个按 ID 索引的覆盖映射，并优先检查它：

local CARD_HAIR: { [string]: string } = { ["some-star-id"] = "<hairAssetId>" }
-- in generate(): local hair = CARD_HAIR[id] or HAIR[(hash // k) % #HAIR + 1]

同样的方法也适用于标志性套装／皮肤。

⚠️ IP 注意事项

真实品牌套件／徽标存在商标风险。建议使用仿制或具有联想效果的品牌元素；只有在获得项目所有者明确许可后，才使用真实品牌元素。在 Roblox 上，真实球员的面孔无法还原——请使用少量通用的经典面孔来丰富表情，而非还原真人面貌。