JSAPIThree 天空和天气系统学习笔记：营造真实的环境氛围

作为一个刚开始学习 mapvthree 的小白，今天要学习天空和天气系统了！听说这个系统可以让场景更有氛围感，还能模拟真实的天气效果！想想就期待！

第一次听说天空系统

今天在文档里看到了"天空"这个词，一开始我还以为是背景色，结果查了一下才知道，原来这是用来营造场景氛围的环境系统！

文档说天空系统可以：

• 提供场景的背景和光照
• 模拟真实的昼夜交替
• 营造不同的氛围感
• 配合天气系统实现雨雪雾等效果

我的理解：简单说就是给场景"加个天空"，让场景看起来更真实、更有氛围！

第一步：发现天空系统

作为一个初学者，我习惯先看看引擎有哪些属性。文档说可以通过 rendering.sky 来设置天空！

我的发现：mapvthree 提供了三种类型的天空：

• DefaultSky：默认天空，风格化效果
• DynamicSky：动态天空，根据时间变化
• StaticSky：静态天空，预置天气状态

我的理解：不同类型的天空适合不同的场景，可以根据需求选择！

第二步：使用默认天空（DefaultSky）

默认天空适合风格化的天空效果，从下到上只有颜色的渐变，没有太阳、云层等元素。

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [116.404, 39.915],
        range: 1000,
        pitch: 80,
    },
    rendering: {
        sky: new mapvthree.DefaultSky(),
        enableAnimationLoop: true,
    },
});

我的发现：默认天空很简单，只有颜色渐变，适合不需要复杂效果的场景！

我的理解：

• 优点：性能好，配置简单
• 缺点：没有太阳、云层等元素
• 适用场景：风格化场景、性能要求高的场景

第三步：使用动态天空（DynamicSky）

动态天空根据时间有不同的光照效果，可以模拟日出日落、日夜交替等自然光照变化。

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [116.404, 39.915],
        range: 1000,
        pitch: 80,
    },
    rendering: {
        sky: new mapvthree.DynamicSky(),
        enableAnimationLoop: true,
    },
    clock: {
        currentTime: new Date('2025-05-15 14:00:00'),
        tickMode: 2, // TICK_LOOP
    },
});

我的发现：动态天空会根据时间自动变化，从日出到正午，再到黄昏，最后到夜晚！

我的理解：

• 优点：真实感强，有大气散射、体积云等高级特效
• 缺点：性能开销较大
• 适用场景：需要真实场景展示、需要昼夜交替效果

第四步：使用静态天空（StaticSky）

静态天空预置了常见的天气状态和时段状态，可以直接切换。

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [116.404, 39.915],
        range: 1000,
        pitch: 80,
    },
    rendering: {
        sky: new mapvthree.StaticSky(),
        enableAnimationLoop: true,
    },
});

我的发现：静态天空有预置的天气状态，可以直接切换，不需要手动配置！

我的理解：

• 优点：配置简单，有预置效果
• 缺点：不能动态变化
• 适用场景：需要固定天气状态的场景

第五步：添加天气效果

看到天空后，我想：能不能添加天气效果？

文档说可以用 DynamicWeather 来模拟雨、雪、雾等天气效果！

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [116.404, 39.915],
        range: 1000,
        pitch: 80,
    },
    rendering: {
        sky: null, // 先不设置，稍后添加
        enableAnimationLoop: true,
    },
});

// 添加动态天空
const sky = engine.add(new mapvthree.DynamicSky());

// 添加天气效果（需要配合 DynamicSky 使用）
const weather = engine.add(new mapvthree.DynamicWeather(sky));
weather.weather = 'rainy'; // 设置为雨天

我的发现 ：天气效果需要配合 DynamicSky 使用，不能单独使用！

我的理解 ：DynamicWeather 需要传入 DynamicSky 实例，这样才能正确显示天气效果。

天气类型

文档说支持多种天气类型：

weather.weather = 'clear';        // 晴天
weather.weather = 'partlyCloudy'; // 部分多云
weather.weather = 'cloudy';       // 多云
weather.weather = 'overcast';    // 阴天
weather.weather = 'foggy';       // 雾天
weather.weather = 'rainy';       // 雨天
weather.weather = 'snowy';       // 雪天

我的尝试：

// 切换不同天气
weather.weather = 'rainy';  // 下雨
weather.weather = 'snowy';  // 下雪
weather.weather = 'foggy';  // 起雾

我的发现：可以动态切换天气，效果很真实！

第六步：如何选择合适的天空气候

看到这么多天空类型后，我想：应该怎么选择？

场景 1：风格化场景

如果做风格化的场景，用 DefaultSky：

rendering: {
    sky: new mapvthree.DefaultSky(),
}

我的想法：风格化场景不需要真实的光照，用默认天空就够了！

场景 2：真实场景展示

如果做真实场景展示，用 DynamicSky：

rendering: {
    sky: new mapvthree.DynamicSky(),
},
clock: {
    currentTime: new Date('2025-05-15 14:00:00'),
    tickMode: 2, // TICK_LOOP
},

我的想法：真实场景需要真实的光照和昼夜交替，用动态天空！

场景 3：固定天气状态

如果需要固定的天气状态，用 StaticSky：

rendering: {
    sky: new mapvthree.StaticSky(),
}

我的想法：固定天气状态不需要动态变化，用静态天空！

场景 4：需要天气效果

如果需要天气效果，用 DynamicSky + DynamicWeather：

const sky = engine.add(new mapvthree.DynamicSky());
const weather = engine.add(new mapvthree.DynamicWeather(sky));
weather.weather = 'rainy';

我的想法：天气效果必须配合动态天空使用！

第七步：完整示例

我想写一个完整的示例，展示天空和天气的使用：

import * as mapvthree from '@baidumap/mapv-three';
import {Mesh, SphereGeometry, MeshStandardMaterial} from 'three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [116.404, 39.915],
        range: 1000,
        pitch: 80,
    },
    rendering: {
        sky: null, // 稍后添加
        enableAnimationLoop: true,
    },
    clock: {
        currentTime: new Date('2025-05-15 14:00:00'),
        tickMode: 2, // TICK_LOOP
    },
});

// 添加动态天空
const sky = engine.add(new mapvthree.DynamicSky());

// 添加天气效果
const weather = engine.add(new mapvthree.DynamicWeather(sky));
weather.weather = 'rainy';

// 添加一个测试物体
const sphere = new Mesh(
    new SphereGeometry(100, 32, 32),
    new MeshStandardMaterial({
        color: 0xffff00,
        metalness: 0.8,
        roughness: 0.2,
    })
);
const position = engine.map.projectArrayCoordinate([116.404, 39.915]);
sphere.position.set(position[0], position[1], position[2]);
engine.add(sphere);

我的感受：写一个完整的示例，把学到的都用上，感觉很有成就感！

第八步：踩过的坑

作为一个初学者，我踩了不少坑，记录下来避免再犯：

坑 1：动态天空没有效果

原因：没有开启循环渲染。

解决 ：确保开启了 enableAnimationLoop: true。

坑 2：天气效果不显示

原因 ：天气效果没有配合 DynamicSky 使用。

解决 ：天气效果必须配合 DynamicSky 使用，不能单独使用。

坑 3：天空没有动画效果

原因：没有开启循环渲染，或者没有设置时钟。

解决：

1. 开启 enableAnimationLoop: true
2. 设置 clock.tickMode 让时间自动流逝

坑 4：天气切换不生效

原因 ：天气对象没有正确创建，或者没有传入 DynamicSky 实例。

解决 ：确保 DynamicWeather 传入了 DynamicSky 实例。

我的学习总结

经过这一天的学习，我掌握了：

1. 天空系统的作用：提供场景的背景和光照，营造氛围感
2. 三种天空类型 ：
   • DefaultSky：风格化效果，性能好
   • DynamicSky：真实场景，有昼夜交替
   • StaticSky：预置天气状态
3. 天气效果 ：通过 DynamicWeather 模拟雨、雪、雾等天气
4. 如何选择：根据场景需求选择合适的天空类型
5. 注意事项：动态天空不能用于 BMapGL，天气效果必须配合动态天空使用

我的感受：天空和天气系统真的很强大！虽然功能很多，但是用起来其实不难。关键是要理解每种天空的特点，然后根据需求选择合适的类型！

下一步计划：

1. 学习更多天空的配置选项
2. 尝试创建复杂的天气效果
3. 做一个完整的环境展示项目

---

学习笔记就到这里啦！作为一个初学者，我觉得天空和天气系统虽然功能很多，但是用起来其实不难。关键是要理解每种天空的特点，然后根据需求选择合适的类型！希望我的笔记能帮到其他初学者！大家一起加油！