OpenParable
Skip to content
← Back to skills

Unity Light

Development
unity-light

Unity Light is an Agent Skill for development published in the Besty0728/Unity-Skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create and configure Unity lights — Directional/Point/Spot/Area lights and batch-toggling scene lights. Use when adding or tuning lights, setting up scene lighting, or batch-enabling/disabling lights, even if the user just says "加个灯" or "打光". 创建与配置 Unity 灯光(Directional/Point/Spot/Area 灯光、批量开关场景灯光);当用户要添加或调校灯光、布置场景照明、或批量启用/禁用灯光时使用。

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Besty0728/Unity-Skills/blob/HEAD/SkillsForUnity/unity-skills~/skills/light/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/unity-light, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 ObjectBatch VersionUse Batch When
light_set_propertieslight_set_properties_batchConfiguring 2+ lights
light_set_enabledlight_set_enabled_batchToggling 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

TypeDescriptionUse Case
DirectionalParallel rays, no positionSun, moon
PointOmnidirectional from a pointTorches, bulbs
SpotCone-shaped beamFlashlights, spotlights
AreaRectangle/disc (baked only)Windows, soft lights

Skills

light_create

Create a new light.

ParameterTypeRequiredDefaultDescription
namestringNo"New Light"Light name
lightTypestringNo"Point"Directional/Point/Spot/Area
x, y, zfloatNo0,3,0Position
r, g, bfloatNo1,1,1Color (0-1)
intensityfloatNo1Light intensity
rangefloatNo10Range (Point/Spot)
spotAnglefloatNo30Cone angle (Spot only)
shadowsstringNo"soft"none/hard/soft

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

light_set_properties

Configure light properties.

ParameterTypeRequiredDescription
namestringNo*Light object name
instanceIdintNo*Instance ID (preferred)
r, g, bfloatNoColor (0-1)
intensityfloatNoLight intensity
rangefloatNoRange (Point/Spot)
spotAnglefloatNoCone angle (Spot only)
shadowsstringNonone/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).

ParameterTypeRequiredDefaultDescription
itemsjson stringYes-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.

ParameterTypeRequiredDescription
namestringNo*Light object name
instanceIdintNo*Instance ID
enabledboolYesEnable state

light_set_enabled_batch

Enable or disable multiple lights.

ParameterTypeRequiredDefaultDescription
itemsjson stringYes-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.

ParameterTypeRequiredDescription
namestringNo*Light object name
instanceIdintNo*Instance ID

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

light_find_all

Find all lights in scene.

ParameterTypeRequiredDefaultDescription
lightTypestringNonullFilter by type
limitintNo50Max 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).

ParameterTypeRequiredDefaultDescription
namestringNonullGameObject name
instanceIdintNo0Instance ID
pathstringNonullHierarchy path
gridXintNo0Probe count on X axis
gridYintNo0Probe count on Y axis
gridZintNo0Probe count on Z axis
spacingXfloatNo2Meters between probes on X
spacingYfloatNo1.5Meters between probes on Y
spacingZfloatNo2Meters between probes on Z

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

light_add_reflection_probe

Create a Reflection Probe at a position.

ParameterTypeRequiredDefaultDescription
probeNamestringNo"ReflectionProbe"Probe name
x, y, zfloatNo0,1,0Position
sizeX, sizeY, sizeZfloatNo10,10,10Probe box size
resolutionintNo256Cubemap 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.