ursina 并未内置完整的物理光照系统（如点光源衰减、阴影投射、pbr材质支持等），图中炫酷的“聚光灯”效果实为通过 projector_shader 配合 vignette 纹理实现的视觉欺骗，而非真实光照计算。
ursina 并未内置完整的物理光照系统（如点光源衰减、阴影投射、pbr材质支持等），图中炫酷的“聚光灯”效果实为通过 projector_shader 配合 vignette 纹理实现的视觉欺骗，而非真实光照计算。
Ursina 是一个面向教育与快速原型开发的 Python 3D 引擎，其设计哲学强调简洁性与易用性，因此默认不提供基于光照模型（如 Phong、PBR）的完整光照管线。官方文档中 Light 类仅支持 DirectionalLight（方向光）并可启用基础阴影（需配合 camera.render_to_texture 和 ShadowMap），而 PointLight、SpotLight 等常见光源类型在当前稳定版本（v4.x）中尚未实现——它们虽存在于 API 参考中，但实际无渲染逻辑支撑。
图中官网首页展示的“聚焦光斑”效果（类似舞台追光灯），并非由 Light 实例驱动，而是源自 ursina/shaders/projector_shader.py 提供的投影着色器（Projector Shader）。该着色器本质是一个屏幕空间纹理投射器：它将一张渐变 vignette 纹理（中心亮、边缘暗）按指定位置、缩放和旋转，叠加到场景中特定实体（如 Entity 或 Button）的表面，从而营造出“被照亮”的错觉。
以下是一个最小可行示例，演示如何复现该效果：
from ursina import *
from ursina.shaders import projector_shader
app = Ursina()
# 创建基础场景
ground = Entity(model='plane', scale=(10,10), texture='grass', collider='box')
cube = Entity(model='cube', color=color.gray, position=(0,1,0), collider='box')
# 创建“投影灯”实体（仅作视觉参考，不参与光照计算）
projector = Entity(
parent=camera,
position=(0, 0, -5), # 相对于相机前方
scale=(3, 3, 1),
rotation_z=0,
shader=projector_shader,
shader_params={
'texture': 'vignette', # 内置 vignette 纹理（中心透明/亮，边缘黑）
'scale': Vec2(0.5, 0.5),
'rotation': 0,
'intensity': 0.8,
}
)
# 将投影效果绑定到目标实体（此处为 cube）
cube.shader = projector_shader
cube.set_shader_input('projector', projector)
EditorCamera() # 启用自由视角
app.run()⚠️ 关键注意事项：
- 这不是真实光照：projector_shader 不影响光照计算、不产生阴影、无距离衰减、不与材质法线或金属度交互；
- 性能友好但功能受限：适合 UI 光效、氛围提示、教学演示等非物理场景，不可用于需要真实光影交互的游戏核心逻辑；
- 自定义纹理支持：可替换 'vignette' 为任意 .png 资源（如手绘光斑、logo 投影），路径需在 assets/ 下或使用绝对路径；
- 方向光阴影仍可用：若需基础阴影，务必启用 DirectionalLight(shadows=True) 并确保模型有 collider 且 render_mode='default'。
总结而言，Ursina 的“灯光系统”现阶段应理解为 “光照可视化工具集”而非“光照引擎”。开发者需明确区分：方向光 + 阴影 → 物理近似；投影着色器 → 视觉增强。合理组合二者（例如用方向光提供全局明暗，用 projector_shader 添加局部焦点），可在保持开发效率的同时达成出色的视觉表现。
