/material

name: unity-material
description: Edit material and shader properties across Built-in/URP/HDRP

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Changing how a surface looks
• Tweaking material parameters
• Swapping shaders
• 调整物体外观、修改材质参数、切换 Shader

Unity Material Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ objects/materials.

Operating Mode

• **Approval** (default): all mutating skills (`material_create`, `material_create_batch`, `material_assign`, `material_assign_batch`, `material_duplicate`, `material_set_color` / `_emission` / `_texture` / `_float` / `_int` / `_vector` / `_keyword` / `_render_queue` / `_shader` / `_texture_offset` / `_texture_scale` / `_gi_flags`, and the `*_batch` variants) need user grant; grant triggers a single server-side execution that returns the result.
• **Auto / Bypass**: those skills execute directly.
• Query skills (`material_get_properties`, `material_get_keywords`) are `SkillMode.SemiAuto` — they run in all three modes without grant.
• This module contains **no** Delete / PlayMode / Reload / high-risk skills (no NeverInSemi); to delete a material asset, call the `asset` module.

Guardrails

**DO NOT** (common hallucinations):

• `material_set_metallic` / `material_set_smoothness` do not exist → use `material_set_float` with `propertyName="_Metallic"` or `"_Glossiness"` (Standard) / `"_Smoothness"` (URP)
• `material_set_color` r/g/b/a range is **0–1**, not 0–255
• `material_set_property` does not exist → use the specific setter: `material_set_float`, `material_set_int`, `material_set_vector`, `material_set_color`
• `material_get_color` does not exist → use `material_get_properties` (returns all properties including colors)

**Routing**:

• For shader changes → `material_set_shader` (this module)
• For texture tiling → `material_set_texture_scale` / `material_set_texture_offset`
• Pipeline-specific property names differ: check Render Pipeline Compatibility table in this doc

> ⚠️ **Targeting a GameObject edits the material asset, not that one object.** There is no per-object material instance here: every `material_set_*` resolves a GameObject to `renderer.sharedMaterial` and writes **the asset on disk** — an asset mutation, not a scene edit, whatever the individual skill's declared flags say. A freshly created primitive carries Unity's built-in `Default-Material`, so `material_set_color(name="Cube")` recolours *every* object in the project still using it — the classic "I coloured one cube and the whole scene changed" bug. Target by GameObject name only after confirming that object owns a material nobody else shares (`material_get_properties` → `materialPath` names the asset that would be written).

**Safe route for "make this object red"** — create, colour the asset by path, then assign:

unity_skills.call_skill("material_create", name="Red", savePath="Assets/Materials")
unity_skills.call_skill("material_set_color", path="Assets/Materials/Red.mat", r=1, g=0, b=0)
unity_skills.call_skill("material_assign", name="Cube", materialPath="Assets/Materials/Red.mat")

> **Object Targeting**: Most single-object skills accept `name` (GameObject name) **or** `path`. Behaviour of `path`: > - In `material_set_*` / `material_get_*` (color/emission/texture/float/int/vector/keyword/shader/render_queue/gi_flags/properties), `path` may be either a **GameObject hierarchy path** *or* a **material asset path** like `Assets/Materials/X.mat` — the skill auto-detects (paths starting with `Assets/` or ending with `.mat` are treated as material assets). > - In `material_assign`, `path` is a **GameObject hierarchy path only**; the material to assign goes in the separate `materialPath` parameter.

Skills Overview

| Single Object | Batch Version | Use Batch When | |---------------|---------------|----------------| | `material_create` | `material_create_batch` | Creating 2+ materials | | `material_assign` | `material_assign_batch` | Assigning to 2+ objects | | `material_set_color` | `material_set_colors_batch` | Setting colors on 2+ objects | | `material_set_emission` | `material_set_emission_batch` | Setting emission on 2+ objects |

**No batch needed**:

• `material_set_texture` - Set texture
• `material_set_texture_offset` / `material_set_texture_scale` - Texture tiling
• `material_set_float` / `material_set_int` / `material_set_vector` - Set properties
• `material_set_keyword` - Enable/disable shader keywords
• `material_set_render_queue` - Set render queue
• `material_set_shader` - Change shader
• `material_set_gi_flags` - Set global illumination flags
• `material_get_properties` / `material_get_keywords` - Query properties
• `material_duplicate` - Duplicate material

---

Skills

material_create

Create a new material (auto-detects render pipeline).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | Yes | - | Material name | | `shaderName` | string | No | auto-detect | Shader (auto-detects URP/HDRP/Standard) | | `savePath` | string | No | null | Save path (folder or full path) |

material_create_batch

Create multiple materials. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `items` | json string | Yes | - | JSON array of per-item objects (see example below) |

**Returns**: `{success, totalItems, successCount, failCount, results: [{success, name, path}]}`

unity_skills.call_skill("material_create_batch", items=[
    {"name": "Red", "savePath": "Assets/Materials"},
    {"name": "Blue", "savePath": "Assets/Materials"},
    {"name": "Green", "savePath": "Assets/