共同三维光照
首选 map.setLight(light, options?) 与 await map.getLight()。同一份脚本可用于网页、桌面调试板和启用内置脚本的原生动态库。SqsMap 使用自研引擎，参考 MapLibre 的调用形状不代表完整行为兼容。
共同脚本
import { map } from 'sqsmap';
const subscription = map.on('sqs.lightingchange', event => {
console.log(event.method, event.lightingState);
});
map.jumpTo({ center: [0, 0], zoom: 1 });
map.setProjection({ type: 'globe' });
map.setLight({ anchor: 'viewport', position: [1.15, 210, 30],
color: '#ffffff', intensity: 0.75 });
await map.sqs.flush();
console.log(await map.getLight());
console.log(await map.lighting.set({ view: 'globe', mode: 'sun',
sunTime: Date.parse('2024-06-21T12:00:00Z'), ambient: 0.25 }));
subscription.unsubscribe();
链式 setter 的实际应用用 map.sqs.flush() 确认；getter 使用 await。原始浏览器 SDK 创建 MapView 后用 view.flush()；view.lighting.set() 返回已应用配置。脚本事件属于运行会话，结束后自动释放；长期监听请使用持久会话。
常量与坐标
| 字段 | 默认值与语义 |
|---|---|
| anchor | viewport；也可为 map。viewport 随相机基向量转动，map 使用视野中心的东、北、天顶方向。 |
| position | 1.15, 210, 30；依次为正半径、正北/视口顶部顺时针方位角、天顶向下的极角。半径归一化，不产生距离衰减；极角 0～180°，方位角归一化到 [0,360)。 |
| color | #ffffff；使用不透明 CSS 名称、hex、rgb、hsl 颜色。颜色作用于实际受光曲面，sRGB 输出先转换到线性空间。 |
| intensity | 0.5；0～1，对应原有 strength 的两倍映射。ambient 仍由各视图的既有设置决定。 |
部分更新保留未传字段；首次共同设置从上述默认值开始，并同步到 globe/building 两套配置。地图未配置共同 light 时 getter 为 null；太阳/旧方向配置不能伪装成共同 light。无活动三维视图时 getter 读取 building 配置，二维画面本身没有曲面光照。共同光照在地图会话内保留，更换或清空样式不会丢失；销毁地图后结束。
太阳与分视图扩展
map.lighting.state() 返回 {active,globe,building}；每套包含 mode、azimuth、elevation、strength、ambient、sunTime、utcOffsetMinutes 和 mapLight。map.lighting.set(options) 返回应用后的完整状态。指定 view 为 globe/building；无活动三维视图时必须显式指定。该扩展只覆盖选中视图，并清除它的 mapLight；另一视图保持原配置。
mode 为 default/fixed/sun；显式 azimuth 0～360°、elevation -10～90°、strength 0～2、ambient 0～1。共同 position 允许下半球方向，转为扩展模式时继承的 elevation 可到 -90°。sunTime 为 now 或 UTC 年 1～9999 的 Unix 毫秒，向下取整到秒；负毫秒同样向下取整。utcOffsetMinutes 为 -720～840 的整数，用于时间显示，不改变 UTC 时刻。reset 先恢复选中视图默认值，再应用同次参数。
事件、错误与边界
sqs.lightingchange 携带 method 和深度冻结的 lightingState 历史快照，以及地图身份和序号。后续写入不改变旧快照。整个候选在输出和通知预算预检后才提交；无效字段、数值、访问器或超限输入不改变配置。监听器退出应 unsubscribe/off；地图销毁和脚本会话停止释放剩余订阅。
仅常量已接通：不透明 CSS 名称/hex/rgb/hsl，零 duration/delay 的属性过渡，validate:true 或省略选项。透明颜色、表达式、非零过渡和 validate:false 尚未开放。lighting/lightColor 能力为 true，lightTransitions/lightExpressions 为 false。不能据此宣称所有三维图层已在浏览器和移动宿主接通；本阶段验证球面、原生建筑渲染入口和原生地形曲面颜色，未提供新的三维 UI。
原生入口与完整示例
C ABI 复用 sqsm_map_scene_json：请求 {"method":"setLight","args":[{"color":"#ffffff","intensity":0.75}]}；读取用 getLight 或 sqs.lighting.state，分视图扩展用 sqs.lighting.set。返回输出通过 sqsm_map_bytes_free 释放；事件通过既有地图事件队列或独立订阅读取。ABI1 和既有符号保持一致。HTTP 资源仍由原生宿主下载并回传。
完整 HTML/CSS/事件处理示例 与匹配 SDK 同目录，可直接下载后部署。默认底图使用 OpenFreeMap 并显示引擎返回的来源署名；切换第三方图源时仍须保留其署名。
语法依据：Map API setLight、Light style specification。实际能力与验收记录以本页和当前构建清单为准。
样式重载仍需异步下载资源；flush({render:true}) 不等于底图资源就绪。完整示例同时输出 basemapStatus；自动验收等待真实 ready 状态和浏览器合成帧后才读像素。
标准颜色名称和现代数值 RGB/HSL 共用颜色输入规则，cssNamedColors/cssModernRgbHsl 能力均为 true。原生 map.sqs.state().lightingState 与持久事件 event.state.lightingState 为深度冻结的历史快照。