Unity Light Agent Skill

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

| instanceId | int | No* | Instance ID |

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

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

• Use Directional light for main scene illumination
• Point lights for localized sources (lamps, fires)
• Spot lights for focused beams (flashlights, stage)
• Limit real-time shadows for performance
• Area lights require baking (not real-time)
• 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.