DynamicLight

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Light
  • [DynamicLight]（11 属性）
    • DynamicPointLight
    • DynamicRectLight（3 属性）
    • DynamicSpotLight（2 属性）

动态真光源的抽象基类，用来描述能够真实照亮周围物体并投射阴影的光源，并统一提供位置、旋转、强度、照射范围、颜色、雾效钳制和阴影开关等通用属性。它本身不直接创建，具体的光照形态由点光源、矩形光源和聚光源等子类承载，因此可以把该基类视为调整场景真光源表现的统一入口。

适用场景

在需要真实照明和阴影的场景里，先创建 DynamicPointLight、DynamicRectLight 或 DynamicSpotLight 这类具体光源实例，再按基类属性统一调整亮度、影响范围、颜色和阴影质量，用来塑造局部重点照明或整体环境光氛围。

使用要点

先通过 game:CreateUnit("DynamicPointLight", {})（或 "DynamicRectLight"、"DynamicSpotLight"）取得具体光源实例，该实例同样具备 DynamicLight 的基类属性；接着写入 Position 与 Rotation 安排位置和朝向，用 Intensity、Range、Color、FogClamp 调整发光表现；需要阴影时把 EnableShadow 置真并用 Enums.ShadowQuality 指定 ShadowQuality，最后通过 Enabled 控制启停，配合 Priority 与 IsStaticOptimization 参与光源管理。

注意事项

DynamicLight 是抽象基类，禁止用 game:CreateUnit 或 World:CreateUnit 直接创建，实例只能来自子类的创建结果或公开 API 返回值。对 Position、Intensity、Color 等基类属性的读写必须在拿到有效实例后进行，实例销毁后不应继续访问。各子类还有各自专属属性，但基类属性对它们统一生效，注意不要把子类专有能力误当作基类成员使用。

属性 (11)

Name	类型	默认值	说明
Position	Vector3	[0.0, 0.0, 0.0]	Position 是 DynamicLight 的向量属性，以 Vector3 表示该动态光源所在的位置。
Rotation	Quaternion	[0.7071067690849304, 0.0, 0.0, 0.7071067094802856]	Rotation 是 DynamicLight 的四元数属性，以 Quaternion 表示该动态光源的旋转。
Enabled	Bool	true	Enabled 是 DynamicLight 的布尔属性，用于表示该动态光源当前是否启用。
Intensity	Float	100	Intensity 是 DynamicLight 的浮点属性，表示该动态光源的发光强度。
Range	Float	10.0	Range 是 DynamicLight 的浮点属性，表示该动态光源的作用范围。
Color	Color	Color.New(255, 255, 255, 255)	DynamicLight 的 Color 属性，类型为 Color，用于表示该动态光源的颜色；该属性公开、可编辑且非只读，既可读取当前颜色，也可赋入新的 Color 值。
FogClamp	Float	0.0	FogClamp 是 DynamicLight 的浮点属性，用于表达该动态光源的雾效钳制参数。
EnableShadow	Bool	false	EnableShadow 是 DynamicLight 的布尔属性，用于控制该动态光源是否投射阴影。
ShadowQuality	ShadowQuality	Enums.ShadowQuality.LOW	ShadowQuality 是 DynamicLight 的枚举属性，类型为 ShadowQuality，用于表示该动态光源的阴影质量档位。
Priority	Int	0	Priority 是 DynamicLight 的整数属性，表示该动态光源的优先级。
IsStaticOptimization	Bool	false	IsStaticOptimization 是 DynamicLight 的布尔属性，用于标记该动态光源是否启用静态优化。

关联类型

• Color
• Quaternion
• ShadowQuality
• Vector3