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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdindex 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### Addeddiff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.essceneindex 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