/light

name: unity-light
description: Create and configure Unity lights. 创建与配置 Unity 灯光。

Triggers

• Adding or tuning lights
• Setting up scene lighting
• Batch-enabling/disabling lights
• 添加或调校灯光、布置场景照明、批量开关灯光

Unity Light Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ lights.

Operating Mode

• **Approval** (default): mutating skills (`light_create`, `light_set_properties`, `light_set_properties_batch`, `light_set_enabled`, `light_set_enabled_batch`, `light_add_probe_group`, `light_add_reflection_probe`) need user grant; grant triggers a single server-side execution that returns the result.
• **Auto / Bypass**: those skills execute directly.
• Query skills (`light_get_info`, `light_find_all`, `light_get_lightmap_settings`) are `SkillMode.SemiAuto` — they run in all three modes without grant.
• This module contains **no** Delete / PlayMode / Reload / high-risk skills (no NeverInSemi); to remove a Light, call `gameobject_delete` from the `gameobject` module.

Guardrails

**DO NOT** (common hallucinations):

• `light_add` does not exist → use `light_create` (creates a new light GameObject)
• `light_set_color` / `light_set_intensity` do not exist → use `light_set_properties` (sets color, intensity, range, shadows together)
• `light_delete` does not exist → use `gameobject_delete` on the light's GameObject
• `light_set_shadow` does not exist → use `light_set_properties` with `shadows` parameter ("none"/"hard"/"soft")

**Routing**:

• For lightmap baking settings → `light_get_lightmap_settings` (this module)
• For reflection probes → `light_add_reflection_probe` (this module)
• For light probe groups → `light_add_probe_group` (this module)

> **Object Targeting**: All single-object skills accept `name` (string) and `instanceId` (int, preferred). Provide at least one. `path` (hierarchy path) is also accepted where noted.

Skills Overview

| Single Object | Batch Version | Use Batch When | |---------------|---------------|----------------| | `light_set_properties` | `light_set_properties_batch` | Configuring 2+ lights | | `light_set_enabled` | `light_set_enabled_batch` | Toggling 2+ lights |

**No batch needed**:

• `light_create` - Create a light
• `light_get_info` - Get light information
• `light_find_all` - Find all lights (returns list)
• `light_add_probe_group` - Add a Light Probe Group with optional grid layout
• `light_add_reflection_probe` - Create a Reflection Probe at a position
• `light_get_lightmap_settings` - Inspect Lightmap baking settings

---

Light Types

| Type | Description | Use Case | |------|-------------|----------| | `Directional` | Parallel rays, no position | Sun, moon | | `Point` | Omnidirectional from a point | Torches, bulbs | | `Spot` | Cone-shaped beam | Flashlights, spotlights | | `Area` | Rectangle/disc (baked only) | Windows, soft lights |

---

Skills

light_create

Create a new light.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No | "New Light" | Light name | | `lightType` | string | No | "Point" | Directional/Point/Spot/Area | | `x`, `y`, `z` | float | No | 0,3,0 | Position | | `r`, `g`, `b` | float | No | 1,1,1 | Color (0-1) | | `intensity` | float | No | 1 | Light intensity | | `range` | float | No | 10 | Range (Point/Spot) | | `spotAngle` | float | No | 30 | Cone angle (Spot only) | | `shadows` | string | No | "soft" | none/hard/soft |

**Returns**: `{success, name, instanceId, lightType, position, color, intensity, shadows}`

light_set_properties

Configure light properties.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | Light object name | | `instanceId` | int | No* | Instance ID (preferred) | | `r`, `g`, `b` | float | No | Color (0-1) | | `intensity` | float | No | Light intensity | | `range` | float | No | Range (Point/Spot) | | `spotAngle` | float | No | Cone angle (Spot only) | | `shadows` | string | No | none/hard/soft |

**Returns**: `{success, name, lightType, color, intensity, range, spotAngle, shadows}`

light_set_properties_batch

Configure multiple lights. Each item accepts: `name`/`instanceId`/`path` (identifier) + `r`, `g`, `b`, `intensity`, `range`, `shadows` (all optional). | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `items` | json string | Yes | - | JSON array of per-item objects (see example below) |

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

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

Enable or disable a light.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No* | - | Light object name | | `instanceId` | int | No* | - | Instance ID | | `path` | string | No* | - | Hierarchy path | | `enabled` | bool | No | `true` | Enable state |

**Returns**: `{success, name, enabled}`

light_set_enabled_batch

Enable or disable multiple lights. | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `items` | json string | Yes | - | JSON array of per-item objects (see example below) |

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

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

light_get_info

Get detailed light information.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | Ligh