/material

name: unity-material
description: Edit material and shader properties across Built-in/URP/HDRP. 编辑 Built-in/URP/HDRP 材质与 Shader 属性。

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

> **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/scale` - Texture tiling
• `material_set_float/int/vector` - Set properties
• `material_set_keyword` - Enable/disable shader keywords
• `material_set_render_queue` - Set render queue
• `material_set_shader` - Change shader
• `material_get_properties/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/Materials"}
])

material_assign

Assign material to object's renderer.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | GameObject name | | `instanceId` | int | No* | Instance ID | | `path` | string | No* | GameObject hierarchy path | | `materialPath` | string | Yes | Material asset to assign (e.g. `Assets/Materials/X.mat`) |

material_assign_batch

Assign materials to multiple objects. | 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, materialPath}]}`

unity_skills.call_skill("material_assign_batch", items=[
    {"name": "Cube1", "materialPath": "Assets/Materials/Red.mat"},
    {"name": "Cube2", "materialPath": "Assets/Materials/Blue.mat"}
])

material_set_color

Set material color with optional HDR intensity.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No* | GameObject name | | `path` | string | No* | Material asset path | | `r`, `g`, `b` | float | No | 1 | Color (0-1) | | `a` | float | No | 1 | Alpha | | `propertyName` | string | No | auto-detect | Color property | | `intensity` | float | No | 1.0 | HDR intensity (>1 for bloom) |

material_set_colors_batch

Set colors on multiple objects. Each item accepts