最近被这个报错折磨过的人应该不少：`time of day not set please run setup`。看到这行字的时候，十有八九是刚把Time of Day插件拖进场景，急着搭一个动态天气系统，结果第一步就被系统拦住了。我最初接触TOD的时候也在这上面卡了半天，后来才意识到，它根本不是“设置没点对”，而是整个系统在强制要求你按它的初始化流程来。把这个小坎跨过去之后，我才算真正理解了TOD的核心价值——它是一套能跟天气系统深度耦合的组件化框架，不是简单转个太阳、换个天空球就完事的工具。 这篇文章想做的事很清楚：把Time of Day（TOD）的组件化架构拆开给你看，讲清楚每个组件为什么存在、怎么协同、如何用这套框架搭出能自由切换晴雨雪雾的动态天气系统。适合正在做开放世界、模拟经营、沙盒生存类项目的场景美术和图形程序，也适合那些拿到TOD插件却只会拖默认预设、不知道怎么把天气逻辑加进去的独立开发者。读完你能收获一套可以直接落地的组件划分方案、一套天气状态切换的代码结构，以及一个能让你少走弯路的排错清单。 ## 1. 内容整体设计与思路拆解 ### 1.1 为什么坚持组件化而不是一把梭 大多数自研或开源的时间系统，最初都长成一个巨大的单体脚本，里面装着太阳角度、雾浓度、云层密度、天空盒颜色、环境光强度、阴影对比度……所有变量堆在一起，靠一个大的Update去驱动。我在一个昼夜循环项目里见过这样一个类，单文件两千多行，每次美术提个颜色需求，程序都要在那堆零散字段里翻找半天。这种单体实现的根本问题不是变量多，而是**变量之间的耦合关系没有边界**——云层密度和降雨强度本来是两件事，放在同一个类里就默认共享了生命周期，你改了一项就牵动另一项，调试就像在地雷阵里跳舞。 组件化的动机恰恰是给变量划分边界。TOD这类系统最合理的拆分方式，是围绕“时间”这个单一数据源，把影响场景表现的不同维度拆成独立组件：光照管太阳和阴影，天空管颜色和雾，云层管覆盖与形态，天气管降水与风。每个组件只依赖时间值，不直接依赖其他组件的内部状态，这样替换或扩展某个模块时，不会炸掉整条链路。 谁更适合组件化，不需要辩——只要你这个系统会被二次开发，组件化就稳赚不赔。固定在地表样式的测试工程可能无所谓，但一个面向多场景复用的动态天气系统，后续必然要加新天气、新季节甚至新时间特性。组件化牺牲的是一点点初期编码时间，换来的是长期的改动安全性和可测试性。 ### 1.2 核心架构：一条时间轴、三种数据流 这套系统的统率，是一条严格统一的时间轴。整个系统里所有变化都以它为单位，这个设计想通了，系统和天气的耦合问题就解决了一大半。 具体拆成三种数据流往下推： - **时间流**：时间源组件（TimeSource）输出一个归一化的时间值，范围0到1，代表一天内从午夜到次日午夜的进度。它不关心具体几点，只负责给整个系统提供统一的节奏。 - **插值流**：各组件拿到时间值后，去自己的关键帧曲线或预设表里查结果，得到当前的色温、光照强度、云层覆盖度等具体参数值。这一层核心是“平滑”，让数值变化不会跳变。 - **事件流**：当时间走到某个定义好的阈值，比如日出、日落、正午，系统广播事件。天气组件通过订阅事件来触发状态切换，比如烟雾在日落后自动变浓，这个设计能让各组件在特定时刻做出反应，但不需要知道谁在听。 三条数据流的分工是这套架构的核心。时间流保证了全局一致，插值流保证了视觉平滑，事件流保证了行为可触发。组件之间不直接打电话，全依赖这套总线，后期加新组件就像插USB设备一样自然。 ### 1.3 组件划分清单：哪些该拆，哪些不该拆 组件不是拆得越碎越好。我建议按“可独立调参+可独立复用”的标准来划分，最终落到这六个核心组件上： | 组件 | 职责 | 关键输出 | |---|---|---| | 时间源（TimeSource） | 维护时间轴，推进昼夜循环，输出归一化时间 | 时间值、天气事件广播 | | 光照组件（SunLight） | 计算太阳方位、仰角、色温、直射光强度 | 方向光参数、阴影强度 | | 天空组件（SkyAtmosphere） | 控制天空盒、大气散射、地平线颜色、星象 | 天空球参数、大气密度 | | 云层组件（CloudLayer） | 生成云层贴图、覆盖度、云层光照、流动速度 | 云密度、云层高度 | | 天气组件（WeatherSystem） | 管理天气状态机、切换参数快照、驱动降水粒子 | 降雨强度、降雪强度、风速 | | 后处理组件（PostFX） | 处理色差、泛光、对比度、色调映射 | 画面风格参数 | 风向这种就不单独拆了。风速、风向跟云层流动、粒子系统、植被摆动都相关，但它本身不是一个独立的视觉模块，只是天气组件的一个属性——拆出来就是过度设计。边做边体会，这套边界是设计的核心艺术：既要隔离变化，又不能让组件数量失控。 ## 2. 核心组件原理与细节剖析 ### 2.1 时间源与光照组件：太阳轨道、色温与强度的数学内核 光照组件是整套系统里最需要数学支撑的模块，它的任务是回答两个问题：太阳在哪，太阳有多亮。 太阳轨道计算，用简化的太阳赤纬模型就够了。对于游戏来说不需要精确到天文秒，用一个正弦函数模拟赤纬随季节变化就能获得不错的视觉效果。核心公式可以参考：

// 太阳赤纬（单位：弧度） declination = sin(radians(23.44)) * sin(radians(360 * (dayOfYear - 81) / 365))

知道赤纬后，结合摄像机的纬度 `lat` 和当前时间时的时角 `hourAngle`，就能算出太阳仰角：

elevation = asin(sin(lat) * sin(declination) + cos(lat) * cos(declination) * cos(hourAngle))

这个仰角是后面所有光照计算的基础。仰角小于零意味着在地下，直接让直射光强度为零；仰角接近零时是日出日落，色温偏暖；仰角最高时是正午，色温最高。 色温映射是我做得比较得意的一块。白天的5600K到傍晚的3400K，直接线性插值会发闷，我用了一个分段映射方案：仰角从0度到15度时，色温从2900K快速爬升到4200K，这段变化最快，要专门做更密的采样；15度到45度时缓慢逼近5500K；45度以上保持5600K。这段曲线存储为动画曲线或关键帧表，手工调起来比公式直观得多，美术同事看了也能直接动手改。 光强度也一样：日出前保持0，日出后按仰角的正弦曲线爬升，正午达到最大值，阴天时在天气组件的干预下乘以衰减系数。为了避免正午光照过曝，强度曲线通常不是线性增长而是带一个饱和值，超过饱和值的部分直接截断。 ### 2.2 天空与云层组件：插值逻辑与体积渲染的关键参数 天空组件承载了视觉上的大背景，它做得好不好，直接影响玩家对画面的第一印象。我采用的是双层天空球方案：一层是远处的星空贴图，一层是可变的动态天空色。动态层的插值不是单纯的RGB插值，而是在色温空间里操作——这在TOD系统里极其常用，因为阳光色温变化时天空颜色才会跟着“活”起来。如果直接对RGB做插值，傍晚那种青紫渐变是做不出来的。 地平线颜色和高空颜色的差异化处理也很关键。白天高空蓝而地平线发白，傍晚高空深邃而地平线橙红。我给高空和地平线各维护了一条色温曲线，高空用固定色温插值，地平线用阳光色温加成，两条曲线之间用高度做权重混合。这个混合逻辑让日出日落的画面变得极具层次感。 云层组件的核心参数是“覆盖度”和“高度偏移”。覆盖度决定云在天空中的占比，高度偏移决定云的形态——低云厚而扁平，高云薄而丝状。云层贴图最好用双层的，一张基础噪声，一张细节噪声；细节噪声随时间偏移，让云产生流动感。每层纹理都有一个UV滚动参数，受风速影响。这套系统的输出会暂时写入单独的渲染纹理，供后续后处理阶段采样。 体积云的实现更吃性能，但和组件化不冲突。把体积渲染的结果Cache到一个低分辨率3D纹理中，每隔几帧更新一次，更新的频率由天气组件控制（雨雪天可以降低更新频率），这样既保住了云层的体积感，也护住了帧率。 ### 2.3 天气组件：状态机、参数快照与权重混合 真正让这个系统被称为“动态天气系统”的，是天气组件。它的核心是状态机：晴天、小雨、暴雨、小雪、大雪、雾。每个状态背后不是散落的if/else，而是一组完整的参数快照，描述了目前这套天气应当如何影响其他组件。 一个典型的晴雨快照参数如下：

WeatherPreset_HeavyRain { cloudCoverage = 0.92 cloudHeight = 520 windSpeed = 14 fogDensity = 8 rainStrength = 1.0 snowStrength = 0.0 lightMultiplier = 0.25 skyTint = (0.36, 0.44, 0.56) }

这里值得注意的不只是降水数值，还包括了 `lightMultiplier` 和 `skyTint`。这两个参数把天气有效传导给光照组件与天空组件，让阴雨天的光衰和色调统一起来，不会出现“雨下得很大但阳光刺眼”的失真感。 多个天气状态之间的切换采用权重混合实现。每个天气状态持有0到1的活跃权重，最终由权重最大的主导天气决定具体参数。切换时初始权重不变，再以平滑的方式给目标权重增加权重，同时给退出天气降低权重。这种方式过渡连续且稳定，不会出现跳变的“切天窗”感。 天气组件对时间流的事件响应也在这里。比如日落用户要求雾浓度自动加重，只要在天气组件里订阅 `OnSunset` 事件，不需要任何组件反复监听时间值。这让系统能响应特定时刻，而不是每帧轮询判断，CPU占用也舒服一些。 ## 3. 实操核心：从零搭建一套动态天气系统 ### 3.1 第一阶段：搭出最小可运行的Time of Day框架 先不碰天气，第一步要把TOD本身架起来，让太阳从升到落，天空也跟着变化。时间源组件要连通“运行即产生时间”的生命周期：在Awake里初始化并校准时间，Start里拉取初始时间值，Update里推进时间点。如果在这里漏掉初始化，就会出现文章开头那个报错提示——系统找不到当前时间。 时间源基本代码骨架如下： ```csharp public class TimeSource : MonoBehaviour { public float dayLengthInMinutes = 20f; public float startTime = 0.4f; // 0.4 约等于早上10点 public float currentTime { get; private set; } public event Action OnSunrise; public event Action OnSunset; private bool _initialized; public void Initialize() { currentTime = startTime; _initialized = true; } private void Update() { if (!_initialized) return; currentTime += Time.deltaTime / (dayLengthInMinutes * 60f); if (currentTime >= 1f) currentTime -= 1f; // 事件触发逻辑... } }

光照组件要订阅currentTime，把它换算成太阳高度角和方位角，再设置场景里直射光的角度。加上色温与强度的曲线映射，TOD的基本骨架就跑起来了。

我建议这一步先只调“光照曲线”和“天空渐变曲线”，不看云层细节，不看后处理效果，确定太阳和天空是协调的，再进入天气阶段。这样做能大幅度减少排查问题的时间。

3.2 第二阶段：把天气状态挂进架构里

天气系统的第一版不用太复杂，只需要定义三个状态：晴、雨、雪。每个状态写一个预设类，包含影响光照、云层、雾、降水粒子的参数。在天气组件里建一个状态机，注册所有状态以及对应的预设数据。

public class WeatherSystem : MonoBehaviour { private Dictionary<WeatherType, WeatherPreset> _presets; private WeatherType _current; private WeatherType _target; private float _blendWeight = 0f; public void SwitchWeather(WeatherType type) { _target = type; _blendWeight = 0f; } private void Update() { _blendWeight = Mathf.MoveTowards(_blendWeight, 1f, Time.deltaTime / blendDuration); WeatherPreset blended = WeatherPreset.Lerp(_presets[_current], _presets[_target], _blendWeight); // 应用 blended 到各组件 } }

当切换天气的入口暴露出来后，这套架构就算成立了一半。光照组件和云层组件不需要知道自己身处的天气状态，只要持续获取概括后的参数并应用即可。每个模块之间依然是松耦合，事件驱动让状态变化通知到整个系统。

3.3 第三阶段：平滑过渡与碰撞处理

真正让画面看起来“高级”的，是天气切换时覆盖一切参数的平滑过渡。过渡的本质是每帧将所有快照参数同步插值一次，两个关键点如下：插值时长在5到15秒之间，时长低于3秒肉眼能看到明显的转折；雪和雨的切换尤其要长一些，中途需要完全清零降水粒子再降到新的粒子密度。

碰撞处理体现在目标天气与当前天气同时驱动降水系统时。如果直接切，雪片和雨滴会同时出现在画面上，看起来很脏。我的方案是为降水子系统加一个独立的强度槽，只接收经过处理的降水参数。切换时雨强槽和雪强槽独立淡入淡出，它们的和始终为1，保证了场景中只会存在一种降水粒子。这个逻辑听起来简单，实际做的时候能原地省掉一大类画面Bug。

3.4 第四阶段：配置驱动与快速调试

最后一个阶段是配置工具化。把天气预设写成ScriptableObject资源，每个资源代表一门天气，美术可以直接在Inspector里调参数。相比在代码里填一堆字典，这种方式最大的优势是可回溯：某天的天气改坏了，能比较资源记录和上次的差别。

调试加速方面，我加了一个全局热键面板，可以快速时间定位，快捷键直接跳转到日出、正午、日落、午夜四个关键时间点。这样的话，你可以用足了编辑器运行时间，测试动作就能非常快地跑完整套昼夜循环，不需要对着天空等太阳慢慢爬。这也是“time of day not set”这类初始化问题最容易被忽略的场景：测试期你强制跳过了时间初始化过程，后续的事件时序就全乱了。

4. 常见问题与排查技巧实录

4.1 那个绕不开的初始化报错：time of day not set please run setup

先把这个报错重点聊透。这个提示不是“提示你按某个按钮”，它是一个防御式设计——系统发现自己没有任何时间基准数据，拒绝渲染后续内容。触发它的情形通常有三种：

• 你拿到TOD就被美术拿去挂到场景，但场景里没有Setup管理器，没有任何组件初始化时间源。
• 时序出问题了，时间源组件在某个区域使用了引擎初值0，但UI或者后处理又在0点就做了渲染判定，被系统安全机制拦住。
• 反复进出场景导致的重复初始化，最常见，见4.3详细说。

我把排查顺序排成了一条固定流程：检查场景里是否存在且只有一个时间源管理器组件；检查生命周期的初始化调用，确认它在任何渲染前执行；确认没有两套一致的时间源同时向整个系统写入时间。做完这三步，这一类报错基本消灭了。

4.2 常见问题速查表

下面这张表是我在实际项目中使用次数最高的排错清单，覆盖了TOD组件化改造过程中最容易爆的幾类问题：

这里面最隐蔽的是第一行“插值器优先级冲突”。我遇到过一种状况：云层密度在晴天状态是0.2，雨天是0.8，同时天气组件与云组件各自维护着密度读数，二者的初始值不一致，结果过渡过程中云层密度先掉到0.4再弹到0.6，画面上云就抖了两下。这类问题典型的解法是：让天气组件成为参数的唯一下发方，其他组件只做“接收器”。执行权必须唯一，否则任何多写者场景都会出现这类鬼畜。

4.3 性能优化与编辑器真机行为差异

组件化TOD的性能问题往往不在单个组件，而在组件数量叠加后的累积效应。我的优化策略是分优先级：

• 固定开销模块：每帧都跑但计算量小，比如色温插值、光照方向计算。这些变化平稳，可以每2帧采样一次。
• 低频模块：时间很短，比如云的形态贴图、大气散射的3D纹理更新，可以隔8到16帧刷新。这样分辨率导致的性能损失可以压缩到最低。
• 事件响应模块：只有事件发生时才会响应，比如降水粒子的切换、后处理参数跳变。它们本身不该占用每帧周期。

编辑器里帧率高但真机卡顿的情况，常见原因是编辑器模式下时间源组件的临时状态和系统时间绑定在一起，而真机上没有这个保证。这里尤其要注意那个“time of day not set”的报错，它频繁出现在编辑器与真机行为不一致的场景：编辑器慢速逐帧调试时时间推进正常，真机上时间字段进不了初始化流程，整体系统就崩了。保持：初始化流程孤注一掷，不依赖其他组件的Awake顺序，不给系统在真机上留任何猜测空间。

结尾的个人体会

这套组件化TOD系统从零搭到能支撑动态天气切换，我踩过最大的坑就是试图在一开始就模拟完整的大气物理。后来想通了——游戏引擎的时间系统本质是让人相信眼前的画面是活的，物理精确度只是通往这个结果的一条路，不是唯一的路。先让白天明亮、黄昏温暖、午夜深沉这三个pose立住，再让雨天和晴天在过渡时长上有明显区分，画面就成功了一大半。

要我用一句话总结这套工程经验，那就是：组件化真正的价值不是代码结构漂亮，而是将来天气扩展时，你不必半夜三更为了一个暴雨参数把整个系统的代码翻个底朝天。这也是为什么我坚持在做一个新天气时只需要添加新预设，不需要新增一行逻辑代码。

最后分享一个我个人的经验技巧：不要在清晨调试阴雨天效果。你会因为画面过于暗沉而反复提亮参数，最后到真正运行到正午时会过曝得一塌糊涂。最好用固定时间跳转功能先锁定正午，调完光照再切换回动态时间跑全循环，这样整个系统的晴天画面才不会崩掉。