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）需要用户授权；授权后会触发一次服务器端执行并返回结果。
• 自动 / 绕过：这些技能会直接执行。
• 查询技能（light_get_info、light_get_properties、light_find_all、light_get_lightmap_settings）属于 SkillMode.SemiAuto——在三种模式下均可运行，无需授权。
• 本模块不包含 删除 / PlayMode / Reload / 高风险 技能（没有 NeverInSemi）；要移除 Light，请从 gameobject 模块调用 gameobject_delete。

防护规则

请勿（常见幻觉）：

• light_add 不存在 → 使用 light_create（创建新的灯光 GameObject）
• 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	从一点向各方向发射	火把、灯泡
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	否	颜色 alpha（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 列出已生效的参数，名称与传入时完全一致（颜色通道分别显示为 r、g、b、a，不会合并为 color）；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	Cubemap 分辨率

返回： { 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 light 作为场景的主要照明
2. 使用 Point light 作为局部光源（灯具、火焰）
3. 使用 Spot light 产生聚焦光束（手电筒、舞台）
4. 限制实时阴影以提升性能
5. Area light 需要烘焙（不支持实时渲染）
6. 使用大于 1 的强度实现 HDR/泛光效果

---

精确签名

准确的名称、参数、默认值和返回值以 GET /skills/schema 或 unity_skills.get_skill_schema() 中的定义为准，而非此文件。