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

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

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).

material_create_batch

Create multiple materials.

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.

material_assign_batch

Assign materials to multiple objects.

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.

material_set_colors_batch

Set colors on multiple objects. Each item accepts: identifier (name/instanceId/path) + r, g, b, a, optional per-item propertyName.

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

unity_skills.call_skill("material_set_colors_batch", items=[
    {"name": "Cube1", "r": 1, "g": 0, "b": 0},
    {"name": "Cube2", "r": 0, "g": 1, "b": 0},
    {"name": "Cube3", "r": 0, "g": 0, "b": 1}
])

material_set_emission

Set emission color with auto-enable keyword.

material_set_emission_batch

Set emission on multiple objects.

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

unity_skills.call_skill("material_set_emission_batch", items=[
    {"name": "Neon1", "r": 1, "g": 0, "b": 1, "intensity": 5.0},
    {"name": "Neon2", "r": 0, "g": 1, "b": 1, "intensity": 5.0}
])

material_set_texture

Set material texture.

material_set_float

Set a float property on a material.

material_set_int

Set an integer property on a material.

material_set_keyword

Enable/disable shader keywords.

Common Keywords: _EMISSION, _NORMALMAP, _METALLICGLOSSMAP, _ALPHATEST_ON, _ALPHABLEND_ON

material_get_properties

Get all material properties.

Returns: {success, target, shader, renderQueue, keywords, giFlags, properties: {colors, floats, vectors, textures, integers}}

material_get_keywords

Get all enabled shader keywords on a material.

material_duplicate

Duplicate a material asset.

material_set_shader

Change the shader of a material.

material_set_vector

Set a Vector4 property on a material.

material_set_texture_offset

Set texture offset (tiling position).

material_set_texture_scale

Set texture scale (tiling).

material_set_render_queue

Set material render queue.

material_set_gi_flags

Set material global illumination flags.

Example: Efficient Material Setup

import unity_skills

# BAD: 6 API calls
unity_skills.call_skill("material_create", name="Mat1", savePath="Assets/Materials")
unity_skills.call_skill("material_create", name="Mat2", savePath="Assets/Materials")
unity_skills.call_skill("material_set_color", path="Assets/Materials/Mat1.mat", r=1, g=0, b=0)
unity_skills.call_skill("material_set_color", path="Assets/Materials/Mat2.mat", r=0, g=0, b=1)
unity_skills.call_skill("material_assign", name="Cube1", materialPath="Assets/Materials/Mat1.mat")
unity_skills.call_skill("material_assign", name="Cube2", materialPath="Assets/Materials/Mat2.mat")

# GOOD: 3 API calls
unity_skills.call_skill("material_create_batch", items=[
    {"name": "Mat1", "savePath": "Assets/Materials"},
    {"name": "Mat2", "savePath": "Assets/Materials"}
])
unity_skills.call_skill("material_set_colors_batch", items=[
    {"path": "Assets/Materials/Mat1.mat", "r": 1, "g": 0, "b": 0},
    {"path": "Assets/Materials/Mat2.mat", "r": 0, "g": 0, "b": 1}
])
unity_skills.call_skill("material_assign_batch", items=[
    {"name": "Cube1", "materialPath": "Assets/Materials/Mat1.mat"},
    {"name": "Cube2", "materialPath": "Assets/Materials/Mat2.mat"}
])

Render Pipeline Compatibility

Skills auto-detect and adapt to your render pipeline:

Best Practices

1. Save materials as assets for reuse
2. Use material instances (by name) for runtime changes
3. Use material assets (by path) for persistent changes
4. Check shader property names in Unity Inspector
5. URP/HDRP have different property names than Standard

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.

Common Errors

Full transport-level codes (COMPILING/RATE_LIMIT etc.) → ../../references/protocol-error-codes.md