unity-light

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

トリガー

• ライトの追加や調整
• シーン照明の設定
• ライトの一括有効化／無効化
• ライトの追加や調整、シーン照明の設定、ライトの一括有効化／無効化

Unity ライトスキル

一括処理を優先：2 個以上のライトを操作する場合は、*_batch スキルを使用してください。

操作モード

• 承認（デフォルト）：変更を伴うスキル（light_create、light_set_properties、light_set_properties_batch、light_set_enabled、light_set_enabled_batch、light_add_probe_group、light_add_reflection_probe）にはユーザーの許可が必要です。許可すると、サーバー側で 1 回だけ実行され、結果が返されます。
• 自動／バイパス：これらのスキルは直接実行されます。
• クエリスキル（light_get_info、light_get_properties、light_find_all、light_get_lightmap_settings）は SkillMode.SemiAuto です。許可なしで、3 つすべてのモードで実行されます。
• このモジュールには Delete／PlayMode／Reload／高リスクのスキルはありません（NeverInSemi なし）。Light を削除するには、gameobject モジュールの gameobject_delete を呼び出してください。

ガードレール

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

• light_add は存在しません → 新しい Light GameObject を作成する light_create を使用してください
• light_set_color／light_set_intensity は存在しません → 色、強度、範囲、シャドウをまとめて設定する light_set_properties を使用してください
• light_delete は存在しません → ライトの GameObject に対して gameobject_delete を使用してください
• light_set_shadow は存在しません → shadows パラメーターを指定して light_set_properties を使用してください
• shadows の値は Unity の列挙型メンバー None／Hard／Soft です。入力は大文字と小文字を区別せず照合されます（"soft" も機能します）が、応答では常に先頭を大文字にした形式が返されます。そのため、検証時は soft ではなく Soft と比較してください

ルーティング：

• ライトマップのベイク設定 → light_get_lightmap_settings（このモジュール）
• リフレクションプローブ → light_add_reflection_probe（このモジュール）
• ライトプローブグループ → light_add_probe_group（このモジュール）

オブジェクトの指定：単一オブジェクトを対象とするすべてのスキルでは、name（文字列）と instanceId（整数、推奨）を指定できます。少なくとも一方を指定してください。注記のある箇所では path（ヒエラルキーパス）も指定できます。

スキルの概要

単一オブジェクト	一括処理版	一括処理を使う場合
light_set_properties	light_set_properties_batch	2 個以上のライトを設定する場合
light_set_enabled	light_set_enabled_batch	2 個以上のライトを切り替える場合

一括処理は不要：

• light_create - ライトを作成
• light_get_info - ライト情報を取得（light_get_properties はその別名です）
• light_find_all - すべてのライトを検索（一覧を返します）
• light_add_probe_group - 任意のグリッドレイアウトで Light Probe Group を追加
• light_add_reflection_probe - 指定位置に Reflection Probe を作成
• light_get_lightmap_settings - ライトマップのベイク設定を確認

---

ライトの種類

種類	説明	用途
Directional	位置を持たない平行光線	太陽、月
Point	1 点から全方向に広がる光	松明、電球
Spot	円錐状の光線	懐中電灯、スポットライト
Area	長方形／円盤形（ベイクのみ）	窓、柔らかな光

---

スキル

light_create

新しいライトを作成します。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ	"New Light"	ライト名
lightType	string	いいえ	"Point"	Directional/Point/Spot/Area
x, y, z	float	いいえ	0,3,0	位置
r, g, b	float	いいえ	1,1,1	色（0-1）
intensity	float	いいえ	1	ライトの強度
range	float	いいえ	10	範囲（Point/Spot）
spotAngle	float	いいえ	30	コーン角度（Spot のみ）
shadows	string	いいえ	"Soft"	None / Hard / Soft

戻り値: {success, name, instanceId, lightType, position, color, intensity, shadows}

light_set_properties

ライトのプロパティを設定します。すべてのパラメーターは省略可能で、省略したものは現在の値が維持されます。

パラメーター	型	必須	説明
name	string	いいえ*	ライトオブジェクト名
instanceId	int	いいえ*	インスタンス ID（優先）
path	string	いいえ*	階層パス
r, g, b	float	いいえ	色（0-1）。各チャンネルのデフォルト値はライトの現在値です
a	float	いいえ	色のアルファ（0-1）
intensity	float	いいえ	ライトの強度
range	float	いいえ	範囲（Point/Spot のみ）
spotAngle	float	いいえ	コーン角度（Spot のみ）
shadows	string	いいえ	None / Hard / Soft

戻り値: {success, name, applied, skipped, lightType, color, intensity, range, spotAngle, shadows} — applied には適用されたパラメーターが、渡したとおりの名前で列挙されます（色チャンネルは color にまとめられず、個別に r、g、b、a として表示されます）。skipped にはライトの種類が対応していないパラメーター（Directional ライトの range、Spot 以外のライトの spotAngle）が、それぞれ理由とともに列挙されます。どちらのリストにもないパラメーターは指定されていません。

認識できない shadows の値を指定すると、呼び出し全体が SEMANTIC_INVALID と validValues を返して拒否され、何も適用されません。そのため、タイプミスによってライトが一部だけ設定されることはありません。

light_set_properties_batch

複数のライトを設定します。各項目では、name/instanceId/path（識別子）と、r、g、b、a、intensity、range、spotAngle、shadows（すべて省略可能）を指定できます。このバッチ処理は全件成功か全件失敗です。不正な shadows の値がある項目は SEMANTIC_INVALID と validValues を返して失敗し、オブジェクト名は target に示されます。また、その呼び出しですでに適用されたすべての項目がロールバックされます。

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

戻り値: {success, totalItems, successCount, failCount, results: [{target, success, lightType, applied, skipped, color, intensity, range, spotAngle, shadows}]} — applied/skipped は light_set_properties と同じ規則に従います（Directional ライトの range、または Spot 以外のライトの spotAngle はエラーではなく skipped に列挙されます）。

unity_skills.call_skill("light_set_properties_batch", items=[
    {"name": "Light1", "intensity": 2.0, "r": 1, "g": 0.9, "b": 0.8},
    {"instanceId": 12345, "intensity": 1.5, "shadows": "soft"},
    {"name": "Light3", "intensity": 2.0}
])

light_set_enabled

ライトを有効または無効にします。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ*	-	ライトオブジェクト名
instanceId	int	いいえ*	-	インスタンス ID
path	string	いいえ*	-	階層パス
enabled	bool	いいえ	true	有効状態

戻り値: {success, name, enabled}

light_set_enabled_batch

複数のライトを有効または無効にします。各項目で enabled は必須です（light_set_enabled とは異なり、省略すると値を推測せずに拒否されます）。このバッチ処理は全件成功または全件失敗です。

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

戻り値: {success, totalItems, successCount, failCount, results: [{target, success, enabled}]}。enabled がない項目は MISSING_PARAM で失敗し、呼び出し中にすでに切り替えられたすべてのライトをロールバックします。

unity_skills.call_skill("light_set_enabled_batch", items=[
    {"name": "Torch1", "enabled": False},
    {"name": "Torch2", "enabled": False},
    {"name": "Torch3", "enabled": False}
])

light_get_info

ライトの詳細情報を取得します。

パラメーター	型	必須	説明
name	string	いいえ*	ライトオブジェクト名
instanceId	int	いいえ*	インスタンス ID
path	string	いいえ*	階層パス

戻り値: {name, entityId, instanceId, path, lightType, color, intensity, range, spotAngle, shadows, enabled, cullingMask, bounceIntensity}

light_get_properties

light_get_info のエイリアスです。パラメーターとレスポンスは同じです。セッターが light_set_properties であるため、対応するゲッター名で呼び出せるように用意されています。これにより 404 を回避できます。

パラメーター	型	必須	説明
name	string	いいえ*	ライトオブジェクト名
instanceId	int	いいえ*	インスタンス ID
path	string	いいえ*	階層パス

戻り値: light_get_info と同じです。

light_find_all

シーン内のすべてのライトを検索します。

パラメーター	型	必須	デフォルト	説明
lightType	string	いいえ	null	タイプで絞り込みます
limit	int	いいえ	50	結果の最大数

戻り値: {count, lights: [{name, instanceId, path, lightType, intensity, enabled}]}

light_add_probe_group

GameObject に Light Probe Group を追加します。オプションでグリッド配置を指定できます。gridX/gridY/gridZ は各軸の個数、spacingX/spacingY/spacingZ はプローブ間の距離（メートル）です。

パラメーター	型	必須	デフォルト	説明
name	string	いいえ	null	GameObject 名
instanceId	int	いいえ	0	インスタンス ID
path	string	いいえ	null	階層パス
gridX	int	いいえ	0	X 軸上のプローブ数
gridY	int	いいえ	0	Y 軸上のプローブ数
gridZ	int	いいえ	0	Z 軸上のプローブ数
spacingX	float	いいえ	2	X 軸上のプローブ間の距離
spacingY	float	いいえ	1.5	Y 軸上のプローブ間の距離
spacingZ	float	いいえ	2	Z 軸上のプローブ間の距離

戻り値: { success, gameObject, probeCount, existed, hasGrid }

light_add_reflection_probe

指定した位置に Reflection Probe を作成します。

パラメーター	型	必須	デフォルト	説明
probeName	string	いいえ	"ReflectionProbe"	プローブ名
x, y, z	float	いいえ	0,1,0	位置
sizeX, sizeY, sizeZ	float	いいえ	10,10,10	プローブボックスのサイズ
resolution	int	いいえ	256	キューブマップの解像度

戻り値: { success, name, instanceId, resolution, size }

light_get_lightmap_settings

Lightmap のベイク設定を取得します。

パラメーターはありません。

戻り値: { success, bakedGI, realtimeGI, lightmapSize, lightmapPadding, isRunning, lightmapCount }

---

例：効率的なライティング設定

import unity_skills

# BAD: 4 API calls
unity_skills.call_skill("light_set_properties", name="Light1", intensity=2.0)
unity_skills.call_skill("light_set_properties", name="Light2", intensity=2.0)
unity_skills.call_skill("light_set_properties", name="Light3", intensity=2.0)
unity_skills.call_skill("light_set_properties", name="Light4", intensity=2.0)

# GOOD: 1 API call
unity_skills.call_skill("light_set_properties_batch", items=[
    {"name": "Light1", "intensity": 2.0},
    {"name": "Light2", "intensity": 2.0},
    {"name": "Light3", "intensity": 2.0},
    {"name": "Light4", "intensity": 2.0}
])

最小限の例

unity_skills.call_skill("light_create",
    name="Sun", lightType="Directional",
    r=1, g=0.95, b=0.85, intensity=1.2, shadows="soft"
)

---

ベストプラクティス

1. シーン全体の主な照明には Directional ライトを使用します
2. 局所的な光源（ランプ、炎）には Point ライトを使用します
3. 集中した光線（懐中電灯、ステージ）には Spot ライトを使用します
4. パフォーマンスのため、リアルタイムシャドウを制限します
5. Area ライトにはベイクが必要です（リアルタイムではありません）
6. HDR／ブルーム効果には 1 より大きい intensity を使用します

---

正確なシグネチャ

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