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.

docs(changelog): a panorama becomes an environment

esengine09b1ca5cd30c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e7555739a..8998a9548 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,28 @@ published separately; it ships inside the editor.
### Added
+- **A panorama becomes an environment, and an ambient light casts it.** An
+ equirectangular `.hdr` in a project now bakes into the two things a renderer
+ asks an environment for, and an `Ambient` `Light2D` can point at the result:
+ a surface takes its fill light from the direction it faces, and a metal
+ reflects the sky rather than one flat colour. The light's colour and intensity
+ scale both halves, so an environment is tinted the way the flat term was.
+
+ The diffuse half is nine spherical-harmonic coefficients — no texture at all —
+ and its convolution is divided by pi, which is what makes a constant
+ environment reconstruct as that same constant. That identity is why a light
+ with no environment is the order-zero case of one expression rather than a
+ second lighting path, and why every existing lit scene is byte-identical. The
+ specular half is one ordinary RGBA8 image: octahedral faces stacked by mip,
+ RGBM-encoded, so nothing downstream learns a cube map or a float format.
+
+ Two defects a saturated probe would have hidden turned up in the first gate.
+ The RGBM decode did not match the encode — a whole factor of the multiplier,
+ which read a 0.9 reflection back as 2.66 and clipped it to white. And the
+ atlas was being loaded as a picture, so its rows arrived turned over: mip 0
+ sat where the last mip should be, and a head-on mirror reflected the sky
+ behind it. Its rows are a layout, not an image.
+
- **A skinned model deforms.** The joints an import recorded now move the
vertices bound to them: each bone is the joint entity's world placement times
the mesh's own bind matrix, and the result is world-space, so a skinned mesh's
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index 1d26a83a3..7c5ba7e14 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -180,6 +180,38 @@ direction, so an `Ambient` `Light2D` is what keeps a metal from being black
everywhere no light happens to point. Raise its color to give metals something to
show.
+### An environment with content
+
+A flat ambient is an environment with no detail — every direction the same colour.
+Import an equirectangular `.hdr` panorama and the same light becomes one that has
+detail: sky above, ground below, whatever the file holds.
+
+| How | What happens |
+|---|---|
+| Drag a `.hdr` onto the Content Browser | The source is copied in and baked. |
+| Put one in the project folder | The editor notices and bakes it. |
+| `estella import-hdr <file> [outDir]` | The same bake, on the command line. `--face-size <n>` sets the sharpest reflection. |
+
+The bake writes two products beside the source: **`<name>.esenv`**, which holds the
+whole diffuse half as nine numbers — no texture at all — and **`<name>_env.png`**,
+a prefiltered reflection with one mip per roughness.
+
+Point an `Ambient` light at the `.esenv` and both halves arrive: a surface takes
+its fill light from the direction it faces, and a metal reflects the panorama
+rather than one flat colour.
+
+```typescript
+cmds.spawn().insert(Light2D, {
+ type: Light2DType.Ambient,
+ environment: 'assets/sky.esenv',
+ intensity: 1,
+});
+```
+
+`color` and `intensity` still scale it, so an environment is tinted and dimmed the
+way the flat term is. A light with no environment stays exactly what it was: the
+coefficients are zero, and the same expression is the flat term again.
+
<Aside>
Lights are still placed in the plane: a `Light2D` has no third coordinate, so
distance is measured in xy and a point light's height comes from its radius. The
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
index 5b1466a0a..f0cc1af39 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -171,6 +171,35 @@ highp vec3 lit = applyLightingPBR(
方向等量到达的环境:所以一盏 `Ambient` 的 `Light2D` 正是让金属在没有灯照到的地方不至于
全黑的东西。把它的颜色调亮,金属才有东西可显。
+
+### 有内容的环境
+
+平坦的 ambient 是一个没有细节的环境——每个方向都是同一个颜色。导入一张等距柱状投影的
+`.hdr` 全景图,同一盏灯就有了细节:上方是天空,下方是地面,文件里是什么就是什么。
+
+| 方式 | 会发生什么 |
+|---|---|
+| 把 `.hdr` 拖进内容浏览器 | 源文件被拷入并烘焙。 |
+| 把它放进项目目录 | 编辑器会发现并烘焙它。 |
+| `estella import-hdr <file> [outDir]` | 同一次烘焙,在命令行上。`--face-size <n>` 决定最清晰的那级反射。 |
+
+烘焙在源文件旁写出两个产物:**`<name>.esenv`** 用九个数字装下整个漫反射一半——完全不占纹理
+——以及 **`<name>_env.png`**,一张预过滤的反射图,每级 mip 对应一个粗糙度。
+
+让一盏 `Ambient` 灯指向那个 `.esenv`,两半就都到位了:一个表面按它朝向的方向取环境光,
+而金属反射的是这张全景图,不再是一个平坦的颜色。
+
+```typescript
+cmds.spawn().insert(Light2D, {
+ type: Light2DType.Ambient,
+ environment: 'assets/sky.esenv',
+ intensity: 1,
+});
+```
+
+`color` 与 `intensity` 依然缩放它,所以环境同样可以被染色和调暗。没有环境的灯则原样不动:
+系数为零,同一个表达式又变回那个平坦项。
+
<Aside>
灯仍然摆在平面上:`Light2D` 没有第三个坐标,所以距离在 xy 内度量,点光的高度来自它的
半径。法线与视线才是这个模型里三维的部分。