unity-light

> 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

• 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_get_properties, 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 the shadows parameter
• shadows values are the Unity enum members None / Hard / Soft. Input is matched case-insensitively ("soft" still works) but responses always echo the capitalised form, so compare against Soft, not soft, when verifying

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_get_properties is an alias of it)
• 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. Every parameter is optional and omitted ones keep their current value.

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| name | string | No* | Light object name |

| instanceId | int | No* | Instance ID (preferred) |

| path | string | No* | Hierarchy path |

| r, g, b | float | No | Color (0-1); each channel defaults to the light's current value |

| a | float | No | Colour alpha (0-1) |

| intensity | float | No | Light intensity |

| range | float | No | Range (Point/Spot only) |

| spotAngle | float | No | Cone angle (Spot only) |

| shadows | string | No | None / Hard / Soft |

Returns: {success, name, applied, skipped, lightType, color, intensity, range, spotAngle, shadows} — applied lists the parameters that took effect, named exactly as you passed them (the colour channels appear individually as r, g, b, a, not lumped under color), and skipped the ones the light type cannot carry (a range on a Directional light, a spotAngle on anything but a Spot), each with the reason. A parameter in neither list was not supplied.

An unrecognised shadows value rejects the whole call with SEMANTIC_INVALID + validValues and applies nothing, so a typo can no longer leave a half-configured light behind.

light_set_properties_batch

Configure multiple lights. Each item accepts: name/instanceId/path (identifier) + r, g, b, a, intensity, range, shadows (all optional). A bad shadows value fails that item with SEMANTIC_INVALID + validValues and names the object in target; the other items still run.

| 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* | Light object name |

| instanceId | int | No* | Instance ID |

| path | string | No* | Hierarchy path |

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

light_get_properties

Alias of light_get_info — same parameters, same response. It exists because the setter is light_set_properties, so the matching getter name resolves instead of 404-ing.

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| name | string | No* | Light object name |

| instanceId | int | No* | Instance ID |

| path | string | No* | Hierarchy path |

Returns: identical to light_get_info.

light_find_all

Find all lights in scene.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| lightType | string | No | null | Filter by type |

| limit | int | No | 50 | Max results |

Returns: {count, lights: [{name, instanceId, path, lightType, intensity, enabled}]}

light_add_probe_group

Add a Light Probe Group to a GameObject. Optional grid layout: gridX/gridY/gridZ (count per axis), spacingX/spacingY/spacingZ (meters between probes).

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| name | string | No | null | GameObject name |

| instanceId | int | No | 0 | Instance ID |

| path | string | No | null | Hierarchy path |

| gridX | int | No | 0 | Probe count on X axis |

| gridY | int | No | 0 | Probe count on Y axis |

| gridZ | int | No | 0 | Probe count on Z axis |

| spacingX | float | No | 2 | Meters between probes on X |

| spacingY | float | No | 1.5 | Meters between probes on Y |

| spacingZ | float | No | 2 | Meters between probes on Z |

Returns: { success, gameObject, probeCount, existed, hasGrid }

light_add_reflection_probe

Create a Reflection Probe at a position.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| probeName | string | No | "ReflectionProbe" | Probe name |

| x, y, z | float | No | 0,1,0 | Position |

| sizeX, sizeY, sizeZ | float | No | 10,10,10 | Probe box size |

| resolution | int | No | 256 | Cubemap resolution |

Returns: { success, name, instanceId, resolution, size }

light_get_lightmap_settings

Get Lightmap baking settings.

No parameters.

Returns: { success, bakedGI, realtimeGI, lightmapSize, lightmapPadding, isRunning, lightmapCount }

---

Example: Efficient Lighting Setup

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

Minimal Example

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

---

Best Practices

1. Use Directional light for main scene illumination
2. Point lights for localized sources (lamps, fires)
3. Spot lights for focused beams (flashlights, stage)
4. Limit real-time shadows for performance
5. Area lights require baking (not real-time)
6. Use intensity > 1 for HDR/bloom effects

---

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.