Back to Details

unity-light

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unity Light Skills

Unity灯光技能

BATCH-FIRST: Use 
*_batch
skills when operating on 2+ lights.
优先批量操作：当操作2个及以上灯光时，请使用
*_batch
技能。

Guardrails

约束规则

Mode: Full-Auto required
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.
模式：需使用全自动模式
禁止操作（常见错误）：
  • 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
    （参数值为"none"/"hard"/"soft"）
路由规则：
  • 关于光照贴图烘焙设置 → 使用
    light_get_lightmap_settings
    （本模块）
  • 关于反射探针 → 使用
    light_add_reflection_probe
    （本模块）
  • 关于光照探针组 → 使用
    light_add_probe_group
    （本模块）
对象定位：所有单对象技能支持
name
（字符串）和
instanceId
（整数，推荐使用）。至少提供其中一个。部分场景也支持
path
（层级路径）。

Skills Overview

技能概览

Single ObjectBatch VersionUse 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_set_properties
light_set_properties_batch
配置2个及以上灯光
light_set_enabled
light_set_enabled_batch
切换2个及以上灯光的启用状态
无需批量操作的技能：
  • light_create
    - 创建灯光
  • light_get_info
    - 获取灯光信息
  • light_find_all
    - 查找所有灯光（返回列表）

Light Types

灯光类型

TypeDescriptionUse Case
Directional
Parallel rays, no positionSun, moon
Point
Omnidirectional from a pointTorches, bulbs
Spot
Cone-shaped beamFlashlights, spotlights
Area
Rectangle/disc (baked only)Windows, soft lights
类型描述使用场景
Directional
平行光线，无位置限制太阳、月亮
Point
从点向全方向发射光线火把、灯泡
Spot
锥形光束手电筒、聚光灯
Area
矩形/圆盘形（仅支持烘焙）窗户、柔和光源

Skills

技能详情

light_create

light_create

Create a new light.
ParameterTypeRequiredDefaultDescription
name
stringNo"New Light"Light name
lightType
stringNo"Point"Directional/Point/Spot/Area
x
, 
y
, 
z
floatNo0,3,0Position
r
, 
g
, 
b
floatNo1,1,1Color (0-1)
intensity
floatNo1Light intensity
range
floatNo10Range (Point/Spot)
spotAngle
floatNo30Cone angle (Spot only)
shadows
stringNo"soft"none/hard/soft
Returns: 
{success, name, instanceId, lightType, position, color, intensity, shadows}
创建新灯光。
参数类型是否必填默认值描述
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

light_set_properties

Configure light properties.
ParameterTypeRequiredDescription
name
stringNo*Light object name
instanceId
intNo*Instance ID (preferred)
r
, 
g
, 
b
floatNoColor (0-1)
intensity
floatNoLight intensity
range
floatNoRange (Point/Spot)
shadows
stringNonone/hard/soft
配置灯光属性。
参数类型是否必填描述
name
string否*灯光对象名称
instanceId
int否*实例ID（推荐使用）
r
, 
g
, 
b
float否颜色（取值0-1）
intensity
float否灯光强度
range
float否光照范围（Point/Spot类型适用）
shadows
string否none/hard/soft

light_set_properties_batch

light_set_properties_batch

Configure multiple lights. Each item accepts: 
name
/
instanceId
/
path
(identifier) + 
r
, 
g
, 
b
, 
intensity
, 
range
, 
shadows
(all optional).
Returns: 
{success, totalItems, successCount, failCount, results: [{success, name}]}
python
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}
])
配置多个灯光。每个条目可包含：
name
/
instanceId
/
path
（标识符） + 
r
, 
g
, 
b
, 
intensity
, 
range
, 
shadows
（均为可选参数）。
返回值：
{success, totalItems, successCount, failCount, results: [{success, name}]}
python
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

light_set_enabled

Enable or disable a light.
ParameterTypeRequiredDescription
name
stringNo*Light object name
instanceId
intNo*Instance ID
enabled
boolYesEnable state
启用或禁用灯光。
参数类型是否必填描述
name
string否*灯光对象名称
instanceId
int否*实例ID
enabled
bool是启用状态

light_set_enabled_batch

light_set_enabled_batch

Enable or disable multiple lights.
Returns: 
{success, totalItems, successCount, failCount, results: [{success, name, enabled}]}
python
unity_skills.call_skill("light_set_enabled_batch", items=[
    {"name": "Torch1", "enabled": False},
    {"name": "Torch2", "enabled": False},
    {"name": "Torch3", "enabled": False}
])
启用或禁用多个灯光。
返回值：
{success, totalItems, successCount, failCount, results: [{success, name, enabled}]}
python
unity_skills.call_skill("light_set_enabled_batch", items=[
    {"name": "Torch1", "enabled": False},
    {"name": "Torch2", "enabled": False},
    {"name": "Torch3", "enabled": False}
])

light_get_info

light_get_info

Get detailed light information.
ParameterTypeRequiredDescription
name
stringNo*Light object name
instanceId
intNo*Instance ID
Returns: 
{name, instanceId, path, lightType, color, intensity, range, spotAngle, shadows, enabled}
获取灯光详细信息。
参数类型是否必填描述
name
string否*灯光对象名称
instanceId
int否*实例ID
返回值：
{name, instanceId, path, lightType, color, intensity, range, spotAngle, shadows, enabled}

light_find_all

light_find_all

Find all lights in scene.
ParameterTypeRequiredDefaultDescription
lightType
stringNonullFilter by type
limit
intNo50Max results
Returns: 
{count, lights: [{name, instanceId, path, lightType, intensity, enabled}]}
查找场景中所有灯光。
参数类型是否必填默认值描述
lightType
string否null按类型过滤
limit
int否50最大返回数量
返回值：
{count, lights: [{name, instanceId, path, lightType, intensity, enabled}]}

light_add_probe_group

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
name
stringNonullGameObject name
instanceId
intNo0Instance ID
path
stringNonullHierarchy path
gridX
intNo0Probe count on X axis
gridY
intNo0Probe count on Y axis
gridZ
intNo0Probe count on Z axis
spacingX
floatNo2Meters between probes on X
spacingY
floatNo1.5Meters between probes on Y
spacingZ
floatNo2Meters between probes on Z
Returns: 
{ success, gameObject, probeCount, existed, hasGrid }
为GameObject添加光照探针组。可选网格布局：gridX/gridY/gridZ（各轴探针数量），spacingX/spacingY/spacingZ（探针间距，单位米）。
参数类型是否必填默认值描述
name
string否nullGameObject名称
instanceId
int否0实例ID
path
string否null层级路径
gridX
int否0X轴探针数量
gridY
int否0Y轴探针数量
gridZ
int否0Z轴探针数量
spacingX
float否2X轴探针间距（米）
spacingY
float否1.5Y轴探针间距（米）
spacingZ
float否2Z轴探针间距（米）
返回值: 
{ success, gameObject, probeCount, existed, hasGrid }

light_add_reflection_probe

light_add_reflection_probe

Create a Reflection Probe at a position.
ParameterTypeRequiredDefaultDescription
probeName
stringNo"ReflectionProbe"Probe name
x
, 
y
, 
z
floatNo0,1,0Position
sizeX
, 
sizeY
, 
sizeZ
floatNo10,10,10Probe box size
resolution
intNo256Cubemap resolution
Returns: 
{ success, name, instanceId, resolution, size }
在指定位置创建反射探针。
参数类型是否必填默认值描述
probeName
string否"ReflectionProbe"探针名称
x
, 
y
, 
z
float否0,1,0位置坐标
sizeX
, 
sizeY
, 
sizeZ
float否10,10,10探针盒尺寸
resolution
int否256立方体贴图分辨率
返回值: 
{ success, name, instanceId, resolution, size }

light_get_lightmap_settings

light_get_lightmap_settings

Get Lightmap baking settings.
No parameters.
Returns: 
{ success, bakedGI, realtimeGI, lightmapSize, lightmapPadding, isRunning, lightmapCount }
获取光照贴图烘焙设置。
无参数。
返回值: 
{ success, bakedGI, realtimeGI, lightmapSize, lightmapPadding, isRunning, lightmapCount }

Example: Efficient Lighting Setup

示例：高效灯光设置

python
import unity_skills
python
import unity_skills

BAD: 4 API calls

不推荐：4次API调用

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

推荐：1次API调用

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

Minimal Example

极简示例

python
unity_skills.call_skill("light_create",
    name="Sun", lightType="Directional",
    r=1, g=0.95, b=0.85, intensity=1.2, shadows="soft"
)
python
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
  1. 使用Directional灯光作为场景主光源
  2. 使用Point灯光作为局部光源（台灯、火焰）
  3. 使用Spot灯光作为聚焦光束（手电筒、舞台灯）
  4. 限制实时阴影数量以提升性能
  5. Area灯光仅支持烘焙（不支持实时渲染）
  6. 强度大于1时可实现HDR/ bloom效果

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by 
GET /skills/schema
or 
unity_skills.get_skill_schema()
, not by this file.
技能的精确名称、参数、默认值及返回值由
GET /skills/schema
或
unity_skills.get_skill_schema()
定义，而非本文档。