地形编辑器氛围与 `.lightgroup` XML

地形编辑器里的“氛围”不是只存在于面板中的隐藏参数，而是一个可复用的 LightGroup 预设。项目通常把它保存为：

text

<项目根目录>/atmosphere/<预设名>.lightgroup

例如 atmosphere/default.lightgroup。.lightgroup 是项目约定的扩展名，文件内容仍是可读的 XML。atmosphere/name.json 只保存文件名到编辑器显示名的映射，不保存真正的光照参数。

“氛围”、LightGroup 和运行时 API 的关系

需求	应修改的对象
永久修改项目/地图的默认氛围	修改对应 `atmosphere/*.lightgroup`，或在地形编辑器的“氛围”面板中修改并保存
在编辑器中切换另一套已经存在的氛围	在“氛围”节点/项目列表中选择另一个 `.lightgroup`
游戏运行中临时变更当前客户端的天气、雾、主光或后处理	使用 `Scene.TryGetWeatherController()` / `Scene.TryGetLightingController()`
游戏运行中切换或渐变到另一套预设	使用 `SceneLightingController.LoadPreset(...)` / `StartPresetFade(...)`

运行时控制器只改变当前客户端内存中的场景状态，不会写回 atmosphere/ 文件，也不会自动同步到服务器或其他玩家。需要永久效果时，应改项目资产；需要动态效果时，应由代码应用运行时 API，必要时同步“天气/光照意图”而不是直接同步 XML。

通过 Editor MCP 编辑当前氛围

连接完整 Editor MCP，使用 editor_get_context 确认项目和场景已就绪。当前场景的氛围可以通过以下工具修改：

工具	作用
`terrain_get_atmosphere`	返回当前氛围路径、存储方式、主光方向及 Zone/Light 属性的值、类型和可编辑状态
`terrain_preview_atmosphere_edit`	只读检查属性补丁，返回变化计划和预览 token/hash
`terrain_apply_atmosphere_edit`	应用已确认补丁，生成一条可撤销的 `terrain.atmosphere_edit` 记录

这是当前已加载氛围的编辑接口。创建、复制、切换或删除预设仍通过编辑器氛围面板完成；接口不编辑附加灯光。点光源和聚光灯使用独立的 terrain_*light* 工具。

先读取 atmosphere.lightgroup_path，确认它是要修改的文件。若路径为空，storage=embedded_in_map，氛围随场景保存到 map.acmap。多个场景共享同一路径时，保存该文件也会影响之后加载它的其他场景。

部分属性补丁

zone 和 main_light 的键直接使用查询返回的属性名，未传字段保持当前值。查询结果是当前组件支持的属性目录；不要把下面的示例当成完整属性列表。每个属性提供 type、value、editable，枚举还提供 options，资源提供 resource_type。只传 editable=true 的字段；球谐系数等 Buffer 类型保留为只读，主光类型保持 Directional。

json

{
  "zone": {
    "Ambient Color": [0.02, 0.04, 0.12, 1],
    "Fog Color": [0.08, 0.14, 0.28, 1],
    "Depth Fog Enable": true,
    "Depth Fog Density": 1.15,
    "Bloom Weight": 0.25
  },
  "main_light": {
    "Color": [1, 0.75, 0.55, 1],
    "Brightness Multiplier": 2.4
  },
  "main_light_rotation": [25, 0, 140]
}

Color 使用 0~1 RGBA 数组，Vector2/3/4 使用分量数组，枚举使用查询返回的选项字符串。布尔、整数和数值使用相应 JSON 类型。资源属性填写已经存在的逻辑路径，例如 zone["Env Spec Texture"]；空字符串清除引用，不能传磁盘绝对路径或 ..。资源必须能按返回的资源类型加载。main_light_rotation 是主光节点的本地欧拉角 [x,y,z]，单位为度，无需计算 XML 四元数。

将补丁交给 terrain_preview_atmosphere_edit，检查 patch_plan。然后向 terrain_apply_atmosphere_edit 传入相同补丁及预览返回的 preview_token 或 preview_hash。预览后若场景、历史或氛围值变化，重新查询和预览；不要重试旧 token。自动化调用也可传 skip_preview=true 和当前 history_state_id 作为 expected_state_id。

预览不会修改场景。应用和撤销/重做只修改内存并标记光照脏状态，跳过旧氛围面板的本次自动保存通知；不会自动写文件或烘焙。没有实际变化时不新增历史。原生 setter 可能限制某些数值，应检查 apply 返回的实际 atmosphere，并再次查询。

保存与验收

text

terrain_get_atmosphere
-> terrain_preview_atmosphere_edit
-> terrain_apply_atmosphere_edit
-> terrain_get_atmosphere / terrain_list_history
-> terrain_undo / terrain_redo（需要时）
-> terrain_save_scene
-> editor_reload_scene -> editor_lifecycle_wait
-> terrain_get_atmosphere + 编辑器预览截图

terrain_save_scene 当前支持离散瓦片地形；其他地形使用编辑器的正常场景保存。保存复用编辑器氛围序列化链，将当前氛围写回引用的 .lightgroup，或保存到场景内嵌数据。保存后应重载并核对数值与画面；未保存时，磁盘 XML 仍是旧值。

参阅场景氛围 MCP Skill。

XML 的基本结构

一个典型文件由一个根节点、一个 Zone 和一个主光节点组成：

xml

<node origin="Editor/Light/Engine/default.lightgroup">
  <component type="Zone">
    <attribute name="Ambient Color" value="0 0.01717 0.05 1" />
    <attribute name="Fog Color" value="0.231373 0.392157 0.658824 1" />
    <attribute name="Depth Fog Density" value="1" />
  </component>
  <node>
    <attribute name="Rotation" value="0.165611 -0.052217 -0.939228 -0.296137" />
    <component type="Light">
      <attribute name="Color" value="1 0.92736 0.9 1" />
      <attribute name="Brightness Multiplier" value="3" />
      <attribute name="Shadow Intensity" value="0.05" />
    </component>
  </node>
</node>

XML 中的 attribute/@name 是引擎组件属性名，attribute/@value 是序列化后的值。颜色通常是 0～1 的 RGBA，而编辑器颜色控件通常显示 0～255；不要把 255 180 120 1 直接写进 XML。Rotation 是节点旋转的四元数序列化值；如果只是想改变太阳方向，优先使用编辑器面板，不要让 AI 手算四元数。

值得修改的字段

下面列的是当前 SCE 氛围文件中最常用于调色的字段。不同引擎版本或模板可能有额外字段；修改现有字段时应保留未知字段，不要把文件裁剪成只剩下这张表。

`Zone`：环境光、雾和环境反射

XML 属性	作用	修改提示
`Ambient Color`	全局环境光颜色	影响场景整体底色；RGBA 通常为 0～1
`Vertex Ambient Color`	顶点环境光颜色	某些地形/模型路径会使用；没有时不要凭空添加
`Fog Color`	深度雾和高度雾颜色	先确认对应雾开关已启用
`Depth Fog Enable`	开关大气/深度雾	为 `true` 时才会显示深度雾
`Depth Fog AutoCompute`	是否自动计算深度雾距离	为 `true` 时手动改 `Start/End` 可能看不到效果
`Depth Fog Start` / `Depth Fog End`	深度雾起止距离	世界单位；先关闭自动计算再调
`Depth Fog Density`	深度雾密度	数值越大通常越浓，建议小步调整
`Height Fog Enable`	开关高度/指数高度雾	与深度雾是两套效果
`Height Fog Height`	高度雾基准高度	以场景世界坐标为准
`Height Fog Falloff` / `Height Fog Density`	高度雾衰减与密度	用于控制雾在高度方向的分布
`Env Diff Texture` / `Env Spec Texture`	环境贴图漫反射/镜面贴图	资源路径必须存在于项目或客户端资源包
`Env texture diff intensity` / `Env texture spec intensity`	环境贴图强度	影响材质受环境光照的明暗和高光
`Env Cube Angle` / `Env Cube Follow Angle`	环境立方体贴图方向	改方向不会改变贴图内容
`Global Roughness`、`Using Global Roughness`	全局粗糙度覆盖	只有启用覆盖开关时才适合作为统一调色手段
`Use Role SH`、`Role SphericalHarmonicsL2`	角色球谐光照	这是模板生成的数据，通常只改开关/强度，不手填长串系数
`Bloom Threshold` / `Bloom Weight`	Bloom 阈值和强度	属于后处理，过高会造成泛白
`Vignette Enabled` / `Vignette Intensity`	暗角开关和强度	仅在当前渲染链支持时可见
`Water Reflection Cube` / `Using Water Reflection Param`	水面反射相关参数	没有水面时不必修改

`Light`：主光方向、颜色、亮度和阴影

主光通常是根节点下第一个 Light 组件。常用字段如下：

XML 属性	作用	修改提示
节点 `Rotation`	主光方向（太阳方向）	是四元数，不是 XYZ 欧拉角
`Light Type`	`Directional` / `Point` / `Spot` 等光源类型	地图主光通常保持 `Directional`
`Color`	主光颜色	仍是 0～1 RGBA
`Brightness Multiplier`	主光亮度倍率	先调颜色，再小步调亮度，避免整体过曝
`Use Temperature` / `Temperature`	色温控制	开启后仅改 `Color` 可能不符合预期；可调整色温或关闭色温
`Cast Shadows`	是否投射阴影	关闭可降低开销，但会改变场景立体感
`Shadow Intensity`	阴影强度	值越大通常越明显；应结合客户端实际效果验证
`Shadow Resolution`	阴影分辨率倍率	过高会增加显存和渲染压力
`Max Extrusion`	方向光阴影最大挤出距离	远景阴影异常时才考虑修改
`CSM Splits` / `Num Auto Shadow Cascade`	级联阴影分段	属于高级性能参数，优先沿用模板
`Use Weather Values`、天气颜色/亮度字段	天气系统对主光的附加颜色和亮度	用于运行时天气过渡；静态氛围通常不需要单独改天气字段
`Volumetric Blend` 等体积光字段	体积光参与程度	需要客户端渲染链和资源支持，改动后必须实际验收

一个安全的最小修改

例如，只想让当前预设更偏蓝、雾更浓、主光略暗，可以只修改已有属性：

xml

<!-- Zone：颜色仍然使用 0～1 RGBA -->
<attribute name="Ambient Color" value="0.02 0.04 0.12 1" />
<attribute name="Fog Color" value="0.08 0.14 0.28 1" />
<attribute name="Depth Fog Density" value="1.15" />

<!-- 主 Light：亮度是倍率，不是 0～255 颜色值 -->
<attribute name="Brightness Multiplier" value="2.4" />

这类修改不应删除同一 Zone 或 Light 中的其他 <attribute>。如果用户要求改变太阳方向，应让地形编辑器写入 Rotation，避免 AI 直接猜测四元数。

AI 助手修改氛围的推荐流程

当用户说“把地图氛围改成黄昏/更蓝/雾更浓/太阳低一点”时，AI 应按下面顺序处理：

先确认这是永久修改项目资产还是运行时临时效果。前者查项目 atmosphere/，后者查 SceneLightingController / SceneWeatherController。
如果项目有多个 .lightgroup，先列出文件名和 name.json 的显示名，确认要改哪一个；不要默认覆盖 default.lightgroup。
目标场景已打开且氛围 MCP 可用时，优先走查询、预览、应用和显式保存。离线处理文件时再直接读取 XML，只修改目标 Zone / 主 Light 属性，保留未知属性、origin 和已有 id，不把 .lightgroup 重命名成 .xml。
只根据用户意图改最小字段集合。例如“天空更蓝”通常改 Ambient Color、Fog Color 和主光 Color；“雾更浓”通常改 Fog Color 与对应的 Depth/Height Fog Density；“太阳更低”应通过编辑器调主光旋转。
保存后重新选择该氛围或重新打开地图，在编辑器预览中确认；必要时再启动客户端检查编辑器和客户端渲染链差异。
若新建或复制氛围，优先通过地形编辑器的“另存氛围/添加到项目”操作生成文件和 name.json 映射，不要让 AI 直接伪造显示名映射。

常见误区

.lightgroup 是 XML，但它不是普通 LightComponent 片段，而是包含 Zone、节点变换和一个或多个组件的完整场景节点 XML。
atmosphere/*.lightgroup 是编辑器/地图资产；文档示例中的 LightGroup/Daytime.xml 可能是引擎内置预设，两者路径和生命周期不要混用。
直接改 XML 是持久化资产修改；SceneLightingController 的 Apply* 和 LoadPreset 是客户端运行时修改，不会自动保存回 XML。
只改环境光不一定能改变角色最终颜色：材质、渲染路径、角色球谐光照、天气参数和后处理可能共同影响结果。
修改贴图路径前必须确认资源存在；AI 不应编造新的 HDR、反射立方体或 shader 资源路径。

地形编辑器氛围与 .lightgroup XML ​

“氛围”、LightGroup 和运行时 API 的关系 ​

通过 Editor MCP 编辑当前氛围 ​

部分属性补丁 ​

保存与验收 ​

XML 的基本结构 ​

值得修改的字段 ​

Zone：环境光、雾和环境反射 ​

Light：主光方向、颜色、亮度和阴影 ​

一个安全的最小修改 ​

AI 助手修改氛围的推荐流程 ​

常见误区 ​

相关文档 ​