Imported from Lin20051019-code/SheNicest (game/.codely-cli/extensions/TJGenerators/skills/generate_material/SKILL.md). Install upstream with npx skills add Lin20051019-code/SheNicest --skill generate_material. Copyright stays with the author.

⚠️ 执行约束

• 主 agent：无 execute_custom_tool 权限，必须 task(subagent_name="material-generator", ...) 委托，不要 activate_skill 后自己调。
• 子代理（本文档主要读者）：有权限，按下方 execute_custom_tool(...) 示例执行。

⛔ place_assets_in_scene 调用规则

• 调用方式：activate_skill("unity-place-assets-in-scene") → 按 §4e Material 模板用 execute_csharp_script 赋给 Renderer.sharedMaterial（不是 execute_custom_tool）。
• 子代理：提交后立即调一次把占位 .mat 赋给目标 Renderer；收到 <bg_task_done> 后不再调（已赋上的 Renderer.sharedMaterial 自动显示真实贴图）。
• 主 agent：报告里的 material_path 是"已放置"的证据，不是"请你放置"的指示，不要再调。
• 例外：用户明确要"换 Renderer / 再赋一个对象"时才再次调用。详见 async-pattern §5.1。

Generate Surface Material in Unity 🪨

Generate PBR surface material assets in Unity using Huoshan SeeDream AI, from text prompts, reference images, or built-in texture pattern templates. Output: seamless PNG texture (imported as Default Texture) + a ready-to-use Unity .mat Material asset, auto-saved to Assets/TJGenerators/History/.

支持 material type preset（金属/木头/石头等）、texture pattern 模板（条纹/蜂窝/裂纹等）、surface state 风格（崭新/做旧/脏污/潮湿/风化）共同引导生成方向。

🚦 执行四步（不要跳读外链）

1. 调 generate_material → 拿 task_id + placeholder_path（PNG）+ placeholder_material_path（.mat）
2. 立即 place_assets_in_scene（资产类型 Material，路径用 placeholder_material_path）→ 赋给目标 Renderer
3. END RESPONSE TURN — 不要 poll、不要 query_material_status、不要继续操作
4. 下一轮收到 <bg_task_done> → 读 material_path / texture_path（PNG 已原地覆盖，.mat.mainTexture 自动更新，已绑定的 Renderer 不需要重赋值，不要再 place）

档位：短任务 60–180 秒；120 秒内无通知才允许 query_material_status 一次。最多 5 个并发。完整 async 规则见 generator-async-pattern。

⚠️ Skill 独有约束

1. 并发上限 5——同时运行的 material 任务最多 5 个，超过会被拒绝。
2. pattern_id 依赖本地模板——pattern 模板是本地图片文件，必须先在 Unity Editor 通过菜单 AI生成 → 开发 → 材质模板生成器 预生成。模板不存在时 pattern_id 会被忽略，回退使用 image_path。
3. 至少要给一个输入——prompt、preset_id、pattern_id、image_path 至少提供一个，否则会被拒绝；只给 preset_id 就够了。

When to Use / NOT to Use

适用：3D 物体表面材质、环境纹理、建筑材质、可平铺贴图。

不适用：

• 2D sprite / 图标 / UI 图片 → generate_sprite / generate_image
• 通用纹理（无需 PBR .mat） → generate_image
• 天空盒 → generate_skybox

工具

所有工具通过 execute_custom_tool 调用。

generate_material

execute_custom_tool(
  tool_name="generate_material",
  parameters={
    "prompt": "rough iron plate with surface rust",   # 可选：自由文本
    "generator_id": "huoshan_seedream_material",      # 唯一可用 generator（默认）
    "image_path": "Assets/References/ref.png",        # 可选：参考图
    "preset_id": "metal",                             # 可选：材质类型预设（见表）
    "pattern_id": "horizontal_lines",                 # 可选：纹理图案模板（见表）
    "style_id": "aged",                               # 可选：表面状态风格（见表）
    "size": "2048x2048",                              # 可选：1K / 2K / 4K
    # output_path: 不建议指定，默认 Assets/TJGenerators/History/
  }
)

Prompt 拼接公式（重要）：发给 AI 的 prompt 由系统按以下顺序拼接

preset.prompt + ", " + style.prompt + ", " + your prompt

设了 preset_id 和 style_id 后，prompt 字段通常只需补充细节（特定颜色、特定纹理细节），不必从头写。

返回字段

• task_id
• placeholder_path：占位 PNG（1×1 灰色），立即可用
• placeholder_material_path：占位 .mat（Standard shader），立即可用——直接应用到物体
• expected_texture_path / expected_material_path：最终路径（与 placeholder 同路径）
• prompt：实际拼接发给 AI 的 prompt
• estimated_wait_seconds ≈ 90
• notification_mode: "bg_task_done"

提交失败时 result["success"] == false，读 error_code / message，不要poll。

<bg_task_done> 独有字段

通用字段见模板。本 skill 额外字段：

query_material_status / list_material_tasks

query_material_status 仅作 fallback（120 秒后单次）。返回字段同 <bg_task_done> payload，外加 placeholder_path / placeholder_material_path（仅 generating 时）。

list_material_tasks 返回当前 session 的所有 material 任务。

参数速查

材质类型预设 (preset_id)

Preset 同时设置生成的 .mat 上的 Metallic / Smoothness 数值，无需手动调。

纹理图案模板 (pattern_id)

⚠️ 必须先在 Unity Editor 用 AI生成 → 开发 → 材质模板生成器 预生成模板图。模板不存在时 pattern_id 被忽略。

表面状态风格 (style_id)

输出尺寸 (size)

使用示例

按材质类型生成

result = execute_custom_tool(
    tool_name="generate_material",
    parameters={
        "preset_id": "metal",
        "style_id": "aged",
        "prompt": "iron plate with surface rust"
    }
)
if not result.get("success", True):
    raise RuntimeError(f"[{result['error_code']}] {result['message']}")

task_id = result["task_id"]
placeholder_material_path = result["placeholder_material_path"]

# ✅ 立即用 place_assets_in_scene 把 .mat 应用到目标物体
# 然后 END RESPONSE TURN，等 bg_task_done 通知

按纹理图案生成

parameters={
    "preset_id": "wood",
    "pattern_id": "horizontal_lines",   # 使用模板图控制结构
    "style_id": "new"
}

从参考图生成

parameters={
    "image_path": "Assets/References/brick_photo.jpg",
    "preset_id": "brick",
    "style_id": "weathered"
}

并发批量（最多 5 个）

task_ids = []
materials = [
    ("metal", "aged", "rusty iron"),
    ("wood",  "new",  "clean oak planks"),
    ("stone", "weathered", "mossy cobblestone"),
]
for preset, style, prompt in materials:
    result = execute_custom_tool(
        tool_name="generate_material",
        parameters={"preset_id": preset, "style_id": style, "prompt": prompt}
    )
    task_ids.append(result["task_id"])
    # ✅ 直接继续，不 poll

# END RESPONSE TURN — 每个 task 都会单独发 bg_task_done

放入场景

资产类型 Material，路径用 placeholder_material_path / material_path。placement_instruction 例："赋给 Floor 的材质"、"应用到 Wall_001"。

规则见 async-pattern §5 / §5.1。

Prompt 写作指南

preset_id + style_id 通常已经覆盖大部分语义。prompt 字段只补充细节。

技巧：

• 优先让 preset_id + style_id 工作；prompt 只补 preset/style 表达不出的细节
• 平铺表面要明确加 "seamless tileable"
• pattern_id + preset_id 组合可同时控制结构与材质类型
• 不要描述物体（如 "a sword"），只描述表面本身

故障排查

通用故障（配置缺失 / 任务卡住 / 状态异常 / 未登录）见 generator-async-pattern §10。

Skill 独有问题

Domain reload 后 task 丢失

通用恢复流程见 generator-async-pattern §6。本 skill 完成态阈值：

• PNG ≥ 100 KB → 真实纹理已就绪
• .mat 文件本身较小（约几 KB）——通过对应 PNG 大小判定即可

可用 glob("Assets/TJGenerators/History/*.png") + 文件大小恢复。

Task ID Format：material_{counter}_{timestamp}

Notes：

• PNG 自动导入为 TextureImporterType.Default；.mat 的 shader 默认为 Standard
• 自动应用 TuanjieAI 标签
• 并发上限 5——批量生成超过 5 个时分批做
• 需 Unity Editor 在线运行；消耗 AI 服务额度