Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(templates): the 3D Starter ships a finished look - sun shadows, sky light, fog, exposure and grade - with a guide to getting it

yhhdc59f221de30
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 87e736350..4a1726430 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Changed
+
+- **The 3D Starter looks finished out of the box.** Its sun casts mesh shadows (they were off, so every object floated), its camera carries a `PostProcessVolume` with a sky that lights the scene, height fog, GTAO, auto exposure, bloom, grade, vignette and FXAA, and its ground reaches the horizon. A new guide, *Getting a good 3D look*, lists what it sets and how to carry a three.js scene's numbers over (units, light intensity, colours, lamps).
+
## [0.102.0] - 2026-11-11
### Added
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 8a027583f..1a53dc089 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -223,6 +223,7 @@ export default defineConfig({
{ label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'graphics/camera' },
{ label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'graphics/materials' },
{ label: '2D Lighting & Shadows', translations: { 'zh-CN': '2D 光照与阴影' }, slug: 'graphics/lighting' },
+ { label: 'Getting a good 3D look', translations: { 'zh-CN': '做出好看的 3D 画面' }, slug: 'graphics/3d-look' },
{ label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'graphics/post-processing' },
{ label: 'Terrain', translations: { 'zh-CN': '地形' }, slug: 'graphics/terrain' },
{ label: 'Foliage', translations: { 'zh-CN': '植被' }, slug: 'graphics/foliage' },
diff --git a/docs/astro/src/content/docs/graphics/3d-look.mdx b/docs/astro/src/content/docs/graphics/3d-look.mdx
new file mode 100644
index 000000000..48d1ef576
--- /dev/null
+++ b/docs/astro/src/content/docs/graphics/3d-look.mdx
@@ -0,0 +1,65 @@
+---
+title: Getting a good 3D look
+description: The settings that make a 3D scene look finished instead of flat — colour pipeline, sky light, sun shadows, fog, exposure and grade — and how to carry numbers over from a three.js scene.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+A scene that looks "good" in a three.js demo is rarely physically exact. It is a sky,
+a sun with shadows, some fog, an exposure and a grade, tuned by eye. Estella has every
+one of those; they are just not on until a project asks for them. The **3D Starter**
+template turns them on, and this page lists what it sets and why.
+
+## What the 3D Starter sets
+
+| Where | Setting | Why |
+| --- | --- | --- |
+| `project.esproject` | `colorSpace: linear`, `outputTransform: aces` | Lighting is added in linear space and then tone mapped. With the gamma fallback a lit scene saturates (measured: 80% of a frame had a channel at 255, against 2.6% in the three.js original). |
+| `Sun` (Light, Directional) | `meshShadows`, `shadowExtent`, `shadowSoftness` | **Mesh shadows are off by default.** Without them every object floats and the scene reads flat. |
+| `Sky` (Light, Ambient) | no environment, intensity 1 | With *Light the Scene* on, an Ambient light that names no environment is lit by the sky. |
+| Camera → `PostProcessVolume` | `skyAtmosphere` with **Light the Scene** | Draws a sky and lights the scene from it, diffuse and reflection. |
+| | `heightFog` | Gives the ground a horizon, so the ground's edge never shows. |
+| | `gtao` | Contact darkening where objects meet the ground. |
+| | `autoExposure`, `bloom`, `colorGrade`, `vignette`, `fxaa` | Exposure that follows the light, glow on bright pixels, a touch of contrast and saturation, and clean edges. |
+| `Camera` | `farPlane` 20000 | The ground and sky reach the horizon. |
+
+## Carrying numbers over from three.js
+
+- **Units.** A project's physics defaults to 100 units per metre. A glTF import comes in
+ metres. Post effects ship with defaults sized for centimetre worlds (rain shelter range,
+ SSR distance, GTAO radius, contact shadow length): retune them by hand for a metre-scale
+ scene.
+- **Light intensity.** Estella multiplies albedo by the intensity directly (a sun of 1.8
+ measured as albedo × 1.8 × cosine). Recent three.js divides by π, so a three.js value
+ often needs dividing by π here. Start there and judge by eye.
+- **Colours.** In linear mode a hex typed into a plain colour field is stored raw and
+ reads pale. Convert sRGB to linear for `MeshRenderer.color`.
+- **Point lamps.** Turn on **Inverse Square** for a lamp that pools light the way a
+ three.js `PointLight` with `decay: 2` does. Its intensity is the light one metre away.
+- **New materials.** Check `depthTest` on a hand-written material. One written with it off
+ draws far faces over near ones, which looks like a shadow bug and is not.
+- **Hemisphere light.** Use an Ambient light with **Hemisphere** on, sky colour above and
+ ground colour below, for the equivalent of `HemisphereLight`.
+
+## Making it your own
+
+Change the look in this order. Each step changes more of the picture than the next:
+
+1. **Sun direction and colour.** Low and warm for evening, high and white for noon. Keep
+ shadows on.
+2. **Sky.** `u_clouds`, `u_haze` and the sun elevation set the mood. Raise *Sky Light*
+ intensity if shadows are too black.
+3. **Fog.** A little density and a fog colour near the horizon colour.
+4. **Exposure.** `autoExposure` bias, then the Color Grade after the tone map.
+5. **Grade.** Split tone (`shadowTint`, `highlightTint`) and `lift` are what give a frame
+ a colour identity. Put the grade after the tone map.
+
+<Aside type="tip">
+ Look at the frame, then change one thing. Turning effects off one at a time at a fixed
+ camera finds which one is washing a frame out far faster than reading values.
+</Aside>
+
+## See also
+
+- [2D Lighting & Shadows](/docs/graphics/lighting/) for the Light component and shadow options.
+- [Post-processing](/docs/graphics/post-processing/) for each effect's parameters.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/3d-look.mdx b/docs/astro/src/content/docs/zh-cn/graphics/3d-look.mdx
new file mode 100644
index 000000000..17e63a120
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/graphics/3d-look.mdx
@@ -0,0 +1,57 @@
+---
+title: 做出好看的 3D 画面
+description: 让 3D 场景看起来像成品而不是白模的设置——色彩管线、天空光、太阳阴影、雾、曝光与调色,以及怎样把 three.js 场景里的数值搬过来。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+three.js 示例里"好看"的场景很少是物理精确的,它其实是一片天空、一个带阴影的太阳、一点雾、
+一个曝光和一套调色,凭眼睛调出来的。Estella 这些都有,只是项目不主动要求就不会打开。
+**3D 入门**模板把它们都打开了,本页列出它设置了什么、为什么。
+
+## 3D 入门模板设置了什么
+
+| 位置 | 设置 | 原因 |
+| --- | --- | --- |
+| `project.esproject` | `colorSpace: linear`,`outputTransform: aces` | 光照在线性空间相加再做色调映射。回退到 gamma 时受光场景会过曝(实测:一帧里 80% 的像素有通道到 255,而 three.js 原版只有 2.6%)。 |
+| `Sun`(Light,Directional) | `meshShadows`、`shadowExtent`、`shadowSoftness` | **网格阴影默认关闭。** 没有阴影,物体像漂在地上,画面发平。 |
+| `Sky`(Light,Ambient) | 不指定环境,强度 1 | 开启"照亮场景"后,没有指定环境的 Ambient 光由天空提供。 |
+| Camera → `PostProcessVolume` | `skyAtmosphere` 并开启 **Light the Scene** | 画出天空,并用它照亮场景(漫反射与反射)。 |
+| | `heightFog` | 让地面有地平线,看不到地面的边缘。 |
+| | `gtao` | 物体与地面接触处的暗化。 |
+| | `autoExposure`、`bloom`、`colorGrade`、`vignette`、`fxaa` | 随光线变化的曝光、亮部辉光、轻微的对比与饱和度、干净的边缘。 |
+| `Camera` | `farPlane` 20000 | 地面与天空能延伸到地平线。 |
+
+## 把 three.js 的数值搬过来
+
+- **单位。** 项目物理默认每米 100 单位,glTF 导入则是米。后处理特效的默认值按厘米世界设计
+ (雨的遮蔽范围、SSR 距离、GTAO 半径、接触阴影长度),米制场景要手动重调。
+- **光强。** Estella 直接用强度乘反照率(实测太阳 1.8 即反照率 × 1.8 × 余弦)。较新的
+ three.js 会除以 π,所以 three.js 的数值搬过来通常要除以 π,再凭眼睛判断。
+- **颜色。** 线性模式下,普通颜色框里输入的十六进制按原值存储,看起来发白。给
+ `MeshRenderer.color` 填值时先把 sRGB 转成线性。
+- **点光。** 要让灯像 three.js 里 `decay: 2` 的 `PointLight` 那样聚成光池,开启
+ **Inverse Square**,其强度是 1 米外的亮度。
+- **新建材质。** 检查手写材质的 `depthTest`。关掉它会让远处的面盖住近处的面,看起来像
+ 阴影 bug,其实不是。
+- **半球光。** 用开启 **Hemisphere** 的 Ambient 光(上方天空色、下方地面色)对应 `HemisphereLight`。
+
+## 做成自己的风格
+
+按这个顺序调,越靠前对画面影响越大:
+
+1. **太阳方向与颜色。** 傍晚低而暖,正午高而白。保持阴影开启。
+2. **天空。** `u_clouds`、`u_haze` 与太阳高度决定氛围。阴影太黑就提高 Sky Light 强度。
+3. **雾。** 一点点密度,雾色接近地平线的颜色。
+4. **曝光。** 先调 `autoExposure` 的偏移,再调色调映射之后的 Color Grade。
+5. **调色。** 分色调(`shadowTint`、`highlightTint`)和 `lift` 决定画面的色彩性格,
+ 调色放在色调映射之后。
+
+<Aside type="tip">
+ 先看画面,再每次只改一件事。固定相机,把特效逐个关掉,比读数值更快找出是哪个效果让画面发白。
+</Aside>
+
+## 另请参阅
+
+- [2D 光照与阴影](/docs/zh-cn/graphics/lighting/):Light 组件与阴影选项。
+- [后处理](/docs/zh-cn/graphics/post-processing/):各特效的参数。
diff --git a/templates/3d-starter/assets/scenes/main.esscene b/templates/3d-starter/assets/scenes/main.esscene
index 59f2d76e5..3b1f8a92e 100644
--- a/templates/3d-starter/assets/scenes/main.esscene
+++ b/templates/3d-starter/assets/scenes/main.esscene
@@ -34,10 +34,100 @@
"projectionType": 0,
"fov": 55,
"nearPlane": 10,
- "farPlane": 5000,
+ "farPlane": 20000,
"isActive": true,
"priority": 0
}
+ },
+ {
+ "type": "PostProcessVolume",
+ "data": {
+ "isGlobal": true,
+ "priority": 0,
+ "weight": 1,
+ "effects": [
+ {
+ "type": "skyAtmosphere",
+ "enabled": true,
+ "uniforms": {
+ "u_intensity": 1.0,
+ "u_lightScene": 1,
+ "u_clouds": 0.3
+ }
+ },
+ {
+ "type": "heightFog",
+ "enabled": true,
+ "uniforms": {
+ "u_density": 0.0002,
+ "u_heightFalloff": 0.002,
+ "u_baseHeight": 0,
+ "u_inscatter": 0.4,
+ "u_skyFog": 0.7
+ },
+ "colors": {
+ "u_fogColor": {
+ "r": 0.7,
+ "g": 0.78,
+ "b": 0.88,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "gtao",
+ "enabled": true,
+ "uniforms": {
+ "u_radius": 120,
+ "u_intensity": 0.8
+ }
+ },
+ {
+ "type": "autoExposure",
+ "enabled": true,
+ "uniforms": {
+ "u_bias": 0.15,
+ "u_minEV": -2,
+ "u_maxEV": 2
+ }
+ },
+ {
+ "type": "bloom",
+ "enabled": true,
+ "uniforms": {
+ "u_threshold": 1.0,
+ "u_intensity": 0.3,
+ "u_radius": 1.2
+ }
+ },
+ {
+ "type": "colorGrade",
+ "enabled": true,
+ "uniforms": {
+ "u_exposure": 0,
+ "u_contrast": 1.06,
+ "u_saturation": 1.15,
+ "u_temperature": 0,
+ "u_tint": 0
+ }
+ },
+ {
+ "type": "vignette",
+ "enabled": true,
+ "uniforms": {
+ "u_intensity": 0.2,
+ "u_softness": 0.8
+ }
+ },
+ {
+ "type": "fxaa",
+ "enabled": true,
+ "uniforms": {
+ "u_intensity": 1
+ }
+ }
+ ]
+ }
}
],
"visible": true
@@ -68,14 +158,17 @@
"type": "Light",
"data": {
"type": 1,
- "intensity": 0.52,
+ "intensity": 3.0,
"enabled": true,
"color": {
"r": 1,
"g": 0.96,
"b": 0.9,
"a": 1
- }
+ },
+ "meshShadows": true,
+ "shadowExtent": 1400,
+ "shadowSoftness": 1.5
}
}
],
@@ -102,7 +195,7 @@
"type": "Light",
"data": {
"type": 2,
- "intensity": 0.09,
+ "intensity": 1.0,
"enabled": true,
"color": {
"r": 0.55,
@@ -131,9 +224,9 @@
"z": 0
},
"scale": {
- "x": 10,
+ "x": 400,
"y": 1,
- "z": 7
+ "z": 400
}
}
},
@@ -182,9 +275,9 @@
"type": "BoxCollider3D",
"data": {
"halfExtents": {
- "x": 500,
+ "x": 4000,
"y": 40,
- "z": 350
+ "z": 4000
},
"friction": 0.6
}
@@ -413,4 +506,4 @@
"visible": true
}
]
-}
+}
\ No newline at end of file