Unity Material

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

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

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, gameObject, material}]} — each item echoes gameObject (the object name) and material (the assigned asset path); failures come back as {error, target}.

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.

Returns: {success, target, color, intensity, propertyUsed, hdrEnabled, materialPath}. Auto-detection tries the pipeline's property first, then _BaseColor, _Color, _TintColor, _EmissionColor, and propertyUsed reports which one it actually wrote — check it before concluding a colour "didn't apply". An explicit propertyName that the shader doesn't have (or that names a non-colour property like _Metallic) is rejected with validValues; one that's missing but is _BaseColor/_Color/_MainColor/_TintColor falls back to whichever of that family exists (propertyRequested + warnings report it). It never falls back to _EmissionColor for an explicit request.

material_set_colors_batch

Set colors on multiple objects. Each item accepts: identifier (name/instanceId/path) + r, g, b, a, optional per-item propertyName (same resolution rules as material_set_color; overrides the batch-level propertyName).

Returns: {success, totalItems, successCount, failCount, results: [{target, success, propertyUsed, color}]} — the per-item key is target (GameObject name, or the path when you addressed the asset), not name; a rejected item fails the whole batch and rolls back the others (rolledBack:true, results[i].reverted:true).

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, target, emissionColor, intensity, hdrColor, emissionEnabled}]} — a rejected item fails the whole batch and rolls back the others (rolledBack:true).

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