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
docs(changelog): a panorama becomes an environment
esengine09b1ca5cd30c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thevertices bound to them: each bone is the joint entity's world placement timesthe mesh's own bind matrix, and the result is world-space, so a skinned mesh'sdiff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex 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 blackeverywhere no light happens to point. Raise its color to give metals something toshow.+### 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, sodistance is measured in xy and a point light's height comes from its radius. Thediff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex 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 内度量,点光的高度来自它的半径。法线与视线才是这个模型里三维的部分。