unity-material

このモジュールのスキルを呼び出す前に： 名前や説明から推測したパラメーターを使ってスキルを呼び出そうとしている場合は、いったん止めて、まずこのファイルを読むか、GET /skills/recommend?includeSchema=true でスキーマを取得してください。recommend／schema からすでにパラメーター定義を入手している場合は、そのまま dryRun に進めます。

トリガー

• サーフェスの見た目を変更する
• マテリアルのパラメーターを調整する
• シェーダーを切り替える
• オブジェクトの外観を調整する、マテリアルのパラメーターを変更する、Shader を切り替える

Unity マテリアルスキル

バッチ優先：2 個以上のオブジェクト／マテリアルを操作する場合は、*_batch スキルを使用してください。

動作モード

• 承認（デフォルト）：すべての変更系スキル（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 および *_batch バリアント）にはユーザーの許可が必要です。許可されると、サーバー側で 1 回実行され、結果が返されます。
• 自動／バイパス：これらのスキルは直接実行されます。
• クエリスキル（material_get_properties、material_get_keywords）は SkillMode.SemiAuto です。許可なしで、3 つすべてのモードで実行されます。
• このモジュールには、削除／PlayMode／Reload／高リスクのスキルはありません（NeverInSemi はありません）。マテリアルアセットを削除するには、asset モジュールを呼び出してください。

ガードレール

禁止事項（よくある誤認）：

• material_set_metallic ／ material_set_smoothness は存在しません → material_set_float を使用し、propertyName="_Metallic" または "_Glossiness"（Standard）／ "_Smoothness"（URP）を指定してください
• material_set_color の r／g／b／a の範囲は 0～1 であり、0～255 ではありません
• material_set_property は存在しません → 個別のセッターを使用してください：material_set_float、material_set_int、material_set_vector、material_set_color
• material_get_color は存在しません → material_get_properties を使用してください（カラーを含むすべてのプロパティを返します）

振り分け：

• シェーダーを変更する場合 → material_set_shader（このモジュール）
• テクスチャのタイリングを変更する場合 → material_set_texture_scale ／ material_set_texture_offset
• レンダーパイプラインによってプロパティ名が異なります。このドキュメントの「レンダーパイプライン互換性」表を確認してください

⚠️ GameObject を対象にすると、そのオブジェクトだけでなくマテリアルアセットが編集されます。 ここではオブジェクトごとのマテリアルインスタンスはありません。すべての material_set_* は GameObject を renderer.sharedMaterial に解決し、ディスク上のアセットに書き込みます。各スキルの宣言済みフラグにかかわらず、これはシーンの編集ではなく、アセットの変更です。新しく作成したプリミティブには Unity 組み込みの Default-Material が割り当てられているため、material_set_color(name="Cube") を使うと、まだそれを使用しているプロジェクト内のすべてのオブジェクトの色が変わります。これは「キューブを 1 つ着色したらシーン全体の色が変わった」という典型的なバグです。GameObject 名で対象を指定するのは、そのオブジェクトが他と共有していないマテリアルを持つことを確認してからにしてください（material_get_properties → materialPath に、書き込み対象のアセットが示されます）。

「このオブジェクトを赤くする」安全な手順 — アセットを作成し、パスを指定して色を設定してから割り当てます。

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

オブジェクトの指定：単一オブジェクトを対象とするほとんどのスキルでは、name（GameObject 名）または path を指定できます。path の動作：

• material_set_* ／ material_get_*（color／emission／texture／float／int／vector／keyword／shader／render_queue／gi_flags／properties）では、path に GameObject 階層パスまたは Assets/Materials/X.mat のようなマテリアルアセットパスを指定できます。スキルが自動判別します（Assets/ で始まるパス、または .mat で終わるパスはマテリアルアセットとして扱われます）。
• material_assign では、path は GameObject 階層パスのみです。割り当てるマテリアルは、別の materialPath パラメーターに指定します。

スキルの概要

単一オブジェクト	バッチ版	バッチ版を使用する場合
material_create	material_create_batch	マテリアルを2つ以上作成する場合
material_assign	material_assign_batch	2つ以上のオブジェクトに割り当てる場合
material_set_color	material_set_colors_batch	2つ以上のオブジェクトの色を設定する場合
material_set_emission	material_set_emission_batch	2つ以上のオブジェクトのエミッションを設定する場合

バッチ版は不要です：

• material_set_texture - テクスチャを設定
• material_set_texture_offset / material_set_texture_scale - テクスチャのタイリング
• material_set_float / material_set_int / material_set_vector - プロパティを設定
• material_set_keyword - シェーダーキーワードを有効化／無効化
• material_set_render_queue - レンダーキューを設定
• material_set_shader - シェーダーを変更
• material_set_gi_flags - グローバルイルミネーションフラグを設定
• material_get_properties / material_get_keywords - プロパティを照会
• material_duplicate - マテリアルを複製

---

スキル

material_create

新しいマテリアルを作成します（レンダーパイプラインを自動検出します）。

パラメーター	型	必須	デフォルト	説明
name	string	はい	-	マテリアル名
shaderName	string	いいえ	自動検出	シェーダー（URP/HDRP/Standardを自動検出）。名前を解決できない場合はパイプラインのデフォルトにフォールバックし、レスポンスに shaderRequested と warnings が追加されます
savePath	string	いいえ	null	Assets/...、または埋め込み／ローカルパッケージ内のフォルダー（Packages/<id>/...）。読み取り専用パッケージは拒否されます

material_create_batch

複数のマテリアルを作成します。

パラメーター	型	必須	デフォルト	説明
items	json string	はい	-	項目ごとのオブジェクトを含むJSON配列（以下の例を参照）

戻り値：{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

オブジェクトのレンダラーにマテリアルを割り当てます。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject名
instanceId	int	いいえ*	インスタンスID
path	string	いいえ*	GameObjectの階層パス
materialPath	string	はい	割り当てるマテリアルアセット（例：Assets/Materials/X.mat）

material_assign_batch

複数のオブジェクトにマテリアルを割り当てます。

パラメーター	型	必須	デフォルト	説明
items	json string	はい	-	項目ごとのオブジェクトを含むJSON配列（以下の例を参照）

戻り値：{success, totalItems, successCount, failCount, results: [{success, gameObject, material}]} — 各項目には gameObject（オブジェクト名）と material（割り当てられたアセットパス）が含まれます。失敗時は {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

オプションで HDR 強度を指定して、マテリアルの色を設定します。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	GameObject 名
instanceId	int	いいえ*	0	GameObject のインスタンス ID
path	string	いいえ*	-	マテリアルアセットのパス
r, g, b	float	いいえ	1	色（0-1）
a	float	いいえ	1	アルファ
propertyName	string	いいえ	自動検出	色プロパティ
intensity	float	いいえ	1.0	HDR 強度（ブルームには >1）

戻り値：{success, target, color, intensity, propertyUsed, hdrEnabled, materialPath}。自動検出では、まずパイプラインのプロパティを試し、次に _BaseColor、_Color、_TintColor、_EmissionColor を試します。また、実際に書き込まれたプロパティは propertyUsed に報告されるため、色が「適用されなかった」と判断する前に確認してください。シェーダーに存在しないプロパティ、または _Metallic などの色以外のプロパティを指定した場合、明示的な propertyName は validValues とともに拒否されます。指定したプロパティが存在せず、_BaseColor／_Color／_MainColor／_TintColor のいずれかの場合は、そのファミリーのうち存在するプロパティにフォールバックします（propertyRequested と warnings に報告されます）。明示的な指定では、_EmissionColor にフォールバックすることはありません。

material_set_colors_batch

複数のオブジェクトに色を設定します。各項目では、識別子（name／instanceId／path）と r、g、b、a、およびオプションの項目ごとの propertyName（material_set_color と同じ解決ルールに従い、バッチレベルの propertyName を上書きします）を指定できます。

パラメーター	型	必須	デフォルト	説明
items	json string	はい	-	項目ごとの {name|instanceId|path, r, g, b, a, propertyName?} オブジェクトの JSON 配列（下記の例を参照）
propertyName	string	いいえ	自動検出	項目で上書きされない限り、すべての項目に適用されるデフォルトの色プロパティ

戻り値：{success, totalItems, successCount, failCount, results: [{target, success, propertyUsed, color}]} — 項目ごとのキーは name ではなく target（GameObject 名、またはアセットを指定した場合はパス）です。項目が拒否されるとバッチ全体が失敗し、ほかの項目はロールバックされます（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

キーワードを自動的に有効にして、エミッションの色を設定します。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	GameObject 名
instanceId	int	いいえ*	0	GameObject のインスタンス ID
path	string	いいえ*	-	マテリアルアセットのパス
r, g, b	float	いいえ	1	エミッションの色（0-1）
intensity	float	いいえ	1.0	HDR 強度（ブルームには >1）
enableEmission	bool	いいえ	true	_EMISSION キーワードを自動的に有効化

material_set_emission_batch

複数のオブジェクトのエミッションを設定します。

パラメーター	型	必須	デフォルト	説明
items	json string	はい	-	項目ごとのオブジェクトの JSON 配列（下記の例を参照）

戻り値：{success, totalItems, successCount, failCount, results: [{success, target, emissionColor, intensity, hdrColor, emissionEnabled}]} — 項目が拒否されるとバッチ全体が失敗し、ほかの項目はロールバックされます（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

マテリアルのテクスチャを設定します。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	GameObject 名
instanceId	int	いいえ*	0	GameObject のインスタンス ID
path	string	いいえ*	-	マテリアルアセットのパス
texturePath	string	はい	-	テクスチャアセットのパス
propertyName	string	いいえ	自動検出	テクスチャプロパティ

material_set_float

マテリアルの float プロパティを設定します。

Parameter	Type	Required	Description
name	string	No*	GameObject 名
instanceId	int	No*	GameObject のインスタンス ID
path	string	No*	マテリアルアセットのパス
propertyName	string	Yes	プロパティ名
value	float	No	値（デフォルトは 0）

material_set_int

マテリアルの整数プロパティを設定します。

Parameter	Type	Required	Description
name	string	No*	GameObject 名
instanceId	int	No*	GameObject のインスタンス ID
path	string	No*	マテリアルアセットのパス
propertyName	string	Yes	プロパティ名
value	int	No	値（デフォルトは 0）

material_set_keyword

シェーダーキーワードを有効または無効にします。

Parameter	Type	Required	Default	Description
name	string	No*	-	GameObject 名
instanceId	int	No*	0	GameObject のインスタンス ID
path	string	No*	-	マテリアルアセットのパス
keyword	string	Yes	-	キーワード名
enable	bool	No	true	有効または無効にする

一般的なキーワード：_EMISSION、_NORMALMAP、_METALLICGLOSSMAP、_ALPHATEST_ON、_ALPHABLEND_ON

material_get_properties

すべてのマテリアルプロパティを取得します。

Parameter	Type	Required	Description
name	string	No*	GameObject 名
instanceId	int	No*	GameObject のインスタンス ID
path	string	No*	マテリアルアセットのパス

戻り値：{success, target, materialPath, shader, renderQueue, keywords, giFlags, properties: {...}}

properties はフラットなリストではなく、型ごとに分類された 5 つのグループからなる ディクショナリ です：colors、floats、vectors、textures、integers。各グループは {name, description, value} の配列です（float には min／max も含まれ、texture の value はテクスチャ名または null です）。したがって、プロパティを参照するには properties.colors[i].name を使い、properties[i] は使いません。

materialPath は実際に調査したマテリアルのアセットパスで、直接渡し戻せるパスのみが設定されます。組み込みマテリアルの場合は "" となり、.fbx などの別のアセットに埋め込まれたマテリアルの場合も "" となります。このようなマテリアルを含むファイルは存在しますが、そのファイルのメインアセットは Material ではなく GameObject であるため、.fbx のパスを渡し戻すと「material not found」エラーになります。したがって、空の materialPath は「このマテリアルはパスで指定できない」という意味です。代わりに GameObject を通じて解決し、モデルのパスからパスを生成しないでください。マテリアルを GameObject 経由で解決した場合は、必ずこの値を確認してください。空でない値は、そのオブジェクトに対する後続の material_set_* が書き込むファイルです。

material_get_keywords

マテリアルで有効になっているすべてのシェーダーキーワードを取得します。

Parameter	Type	Required	Description
name	string	No*	GameObject 名
instanceId	int	No*	GameObject のインスタンス ID
path	string	No*	マテリアルアセットのパス

戻り値：{success, target, materialPath, shader, enabledKeywords, commonKeywordStatus} — materialPath は実際に調査したマテリアルの解決済みアセットパスです（material_get_properties と同様の保証があり、組み込みマテリアルの場合、および .fbx など別のアセットに埋め込まれたマテリアルの場合は "" となります。後者は、コンテナのパスを渡し戻せないためです）。commonKeywordStatus は、よく使われる 14 個のキーワードを網羅する {keyword, enabled} の配列です。これにより、キーワードが存在しない場合と、未チェックの場合を区別できます。

material_duplicate

マテリアルアセットを複製します。

パラメーター	型	必須	説明
sourcePath	string	はい	元のマテリアルのパス
newName	string	はい	複製したマテリアルの名前
savePath	string	いいえ	複製したマテリアルの保存先フォルダー／パスの上書き指定（Assets/... または埋め込み／ローカルのパッケージフォルダー）。読み取り専用のパッケージは拒否されます。省略した場合：元のマテリアルと同じ場所に保存されます

material_set_shader

マテリアルのシェーダーを変更します。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject の名前
instanceId	int	いいえ*	GameObject のインスタンス ID
path	string	いいえ*	マテリアルアセットのパス
shaderName	string	はい	シェーダー名

material_set_vector

マテリアルの Vector4 プロパティを設定します。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject の名前
instanceId	int	いいえ*	GameObject のインスタンス ID
path	string	いいえ*	マテリアルアセットのパス
propertyName	string	はい	プロパティ名
x, y, z, w	float	はい	ベクトルの各成分

material_set_texture_offset

テクスチャのオフセット（タイリング位置）を設定します。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject の名前
instanceId	int	いいえ*	GameObject のインスタンス ID
path	string	いいえ*	マテリアルアセットのパス
propertyName	string	いいえ	テクスチャプロパティ名
x, y	float	はい	オフセット値

material_set_texture_scale

テクスチャのスケール（タイリング）を設定します。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject の名前
instanceId	int	いいえ*	GameObject のインスタンス ID
path	string	いいえ*	マテリアルアセットのパス
propertyName	string	いいえ	テクスチャプロパティ名
x, y	float	はい	スケール値

material_set_render_queue

マテリアルのレンダーキューを設定します。

パラメーター	型	必須	説明
name	string	いいえ*	GameObject の名前
instanceId	int	いいえ*	GameObject のインスタンス ID
path	string	いいえ*	マテリアルアセットのパス
renderQueue	int	いいえ	レンダーキューの値（デフォルト -1 = シェーダーのデフォルト）

material_set_gi_flags

マテリアルのグローバルイルミネーションフラグを設定します。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	GameObject の名前
instanceId	int	いいえ*	0	GameObject のインスタンス ID
path	string	いいえ*	-	GameObject の階層パスまたはマテリアルアセットのパス
flags	string	いいえ	RealtimeEmissive	GI フラグ：None / RealtimeEmissive / BakedEmissive / EmissiveIsBlack / AnyEmissive

---

例：効率的なマテリアル設定

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"}
])

レンダーパイプラインとの互換性

スキルはレンダーパイプラインを自動検出し、それに合わせて設定します。

パイプライン	デフォルトのシェーダー	色プロパティ	テクスチャプロパティ
Built-in	Standard	_Color	_MainTex
URP	Universal Render Pipeline/Lit	_BaseColor	_BaseMap
HDRP	HDRP/Lit	_BaseColor	_BaseColorMap

URP Lit は _BaseColor とレガシーの _Color の両方を公開していますが、正しい値として使われるのは _BaseColor のみです。 material_get_properties は両方を一覧表示しますが、_BaseColor に書き込んでも _Color の項目は更新されません。そのため、_Color を読み取る検証処理では古い色が返され、書き込みに失敗したように見えます。_BaseColor と比較し、どのプロパティが使用されたかについては、自分の推測よりもセッターの propertyUsed フィールドを信頼してください。自動検出で誤ったプロパティが選択された場合に限り、propertyName を明示的に指定してください。

ベストプラクティス

1. マテリアルをアセットとして保存し、再利用します
2. アセットパス（path="Assets/.../X.mat"）で指定します。変更されるアセットが正確に示されます
3. GameObject 名で指定すると、そのレンダラーの共有マテリアルアセットに書き込みます。このファイルの先頭にある警告を参照してください。オブジェクトごとの上書きではありません
4. Unity Inspector でシェーダーのプロパティ名を確認するか、material_get_properties から読み取ります
5. URP/HDRP のプロパティ名は Standard と異なります

---

正確なシグネチャ

正確な名前、パラメーター、デフォルト値、戻り値は、このファイルではなく GET /skills/schema または unity_skills.get_skill_schema() で定義されています。

よくあるエラー

トランスポートレベルのコード（COMPILING/RATE_LIMIT など）の全一覧 → ../../references/protocol-error-codes.md

エラー	発生条件	修正方法
TARGET_NOT_FOUND	マテリアルアセット、GameObject/レンダラー、シェーダー、テクスチャ、またはプロパティが見つかりません（例：Material asset not found、No Renderer component found、Shader not found）。	asset_find でアセットパスを確認し、gameobject_find でオブジェクトを確認するか、material_get_properties で利用可能なプロパティを調べます。
MISSING_PARAM	materialPath、sourcePath、texturePath、propertyName、keyword、shaderName など、必須パラメーターが指定されていません。	エラーに記載されたパラメーターを指定して再試行します。スキーマ全体を確認するには mode=dryRun を使用します。
SEMANTIC_INVALID	認識されない GI フラグ、無効なアセットパス、シェーダーで使用されていないプロパティ名、またはシェーダーでカラーとして宣言されていない propertyName など、無効な値が指定されました。	エラーに記載された許容範囲、列挙値、パス規則に従って値を修正します。