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: depth layers and the perspective viewport, in both languages

esengine9b6bcd2352eb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d4b88ec1e..67f948210 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,57 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **A sorting layer can resolve by depth instead of paint order — 2.5D.** Check a
+ layer under Project Settings → Rendering → Depth-sorted layers and what covers
+ what is decided by the depth buffer, from each entity's `Transform` z; with a
+ perspective camera, sprites at different depths occlude each other correctly
+ from any angle with no sort order to maintain by hand. Depth belongs to the
+ LAYER because half a layer sorted by depth and half by paint order is not a
+ thing that can be rendered — there is no single sequence satisfying both — and
+ a layer already works this way for y-sort. Inside such a layer the stage and
+ depth state are derived, not declared: an opaque draw (blend mode `None`, new)
+ writes depth and sorts front-to-back so early-z pays off, a blended one only
+ tests and stays back-to-front, because a translucent draw that wrote depth is
+ exactly how sprites clip each other into black edges. Y-sort and depth are one
+ answer resolved in one place — y-sort IS a depth projected from world Y, so a
+ layer claiming both keeps y-sorting. The scene target grows a depth attachment
+ only when some layer asks for one. Default off: a project with no depth layer
+ renders exactly as it did, to the pixel.
+
+- **The editor viewport has a perspective eye.** The scene toolbar's 2D / 3D
+ button switches the editor's own projection, which is the only way to look at
+ 2.5D content while authoring it. It keeps its own projection rather than
+ following the scene camera — an orthographic view of a perspective scene is a
+ working mode, not a mismatch — and zoom moves the camera there instead of
+ widening a box, since changing the fov would alter the projection being
+ previewed. Picking and dragging follow onto the plane each entity actually sits
+ on, so a sprite at z = -400 is grabbable where it is drawn.
+
+### Fixed
+
+- **Compressed and uncompressed sprites no longer disagree about where a sprite
+ is.** A screen point is a ray, and `screenToWorld` multiplied only the x/y
+ columns of the inverse view-projection — correct orthographically, where a
+ screen point names the same world x/y at every depth, and wrong under any
+ perspective camera, where it answered with wherever the near plane happened to
+ be. It intersects the ray with a world plane now, with the orthographic case as
+ the degenerate form rather than a second branch.
+
+- **An optional native binding no longer declares older hosts rendererless.**
+ `hasRendererBindings` is an all-or-nothing probe: bind every renderer entry
+ point and the SDK drives the frame, miss one and it hands the frame back. A
+ capability added after a host shipped therefore has to stay out of it, or a
+ shell that was working goes blank on an SDK upgrade.
+
+- **A material's inherited vertex stage carries z.** A fragment-only `.esshader`
+ — which is what a material normally is — gets a vertex stage injected by the
+ shader parser, and that stage was flattening the position it was handed. On GL
+ it hid (a shader may read fewer components than the buffer supplies); in a
+ depth layer it would have resolved every fragment at z = 0, and on WebGPU the
+ entry simply did not match the vertex format.
+
## [0.43.0] - 2026-08-04
A release about a game that is no longer alone once it ships. Four more of the
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdx
index aea2c0d47..aa3d77e3b 100644
--- a/docs/astro/src/content/docs/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/guides/sprites.mdx
@@ -1,6 +1,6 @@
---
title: Sprites & Rendering
-description: Draw 2D images with the Sprite component — textures, tint and transparency, size and pivot, flipping, sorting layers and draw order, parallax — plus texture filtering, hit-testing, cache-as-bitmap, ShapeRenderer primitives, sprite filters, motion trails, and world-space bitmap text.
+description: Draw 2D images with the Sprite component — textures, tint and transparency, size and pivot, flipping, sorting layers and draw order, y-sort and depth layers (2.5D), parallax — plus texture filtering, hit-testing, cache-as-bitmap, ShapeRenderer primitives, sprite filters, motion trails, and world-space bitmap text.
---
import { Aside } from '@astrojs/starlight/components';
@@ -142,6 +142,39 @@ front of it — no manual `layer` or z juggling.
gameplay layer(s) that need it.
</Aside>
+### Depth layers (2.5D)
+
+Check a layer under **Project Settings → Rendering → Depth-sorted layers** and it
+stops using paint order entirely: what covers what is decided by the depth buffer,
+from each entity's `Transform` z. With a perspective camera that is 2.5D — sprites
+at different depths occlude each other correctly from any angle, with no sort order
+to maintain by hand.
+
+Which sprites take part is decided by their material's **blend mode**, because that
+is what says whether a draw reads what is already on screen:
+
+| Blend mode | In a depth layer |
+| --- | --- |
+| `None` (opaque) | Writes depth and is occluded by anything nearer, whatever order it was drawn in. |
+| Anything else (translucent) | Tests against depth but never writes it, and stays in back-to-front paint order. |
+
+That split is not a setting — a translucent sprite that wrote depth would clip the
+sprites behind it into hard black edges. So a sprite you want to occlude properly
+needs an opaque material; leave the blend mode alone and it behaves as it always has,
+just with things in front of it hiding it.
+
+To look at any of this while authoring, switch the viewport's **2D / 3D** button
+(scene toolbar) — the editor's own eye becomes a perspective one. It changes only
+your view: the Game view always shows the scene's camera. Picking and dragging follow,
+so a sprite at z = -400 is grabbable where it is drawn.
+
+<Aside type="note">
+ A layer is either y-sorted or depth-sorted, never both — y-sort *is* a depth
+ projected from world Y, and a layer that declares both keeps y-sorting. Usable z
+ range is ±`far` under an orthographic camera (±1000 by default) and `near`..`far`
+ under a perspective one; content outside it is clipped away entirely.
+</Aside>
+
## Flipping, atlases & scrolling
- **Flip** a sprite with `flipX` / `flipY` — e.g. face a character left or right without
diff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
index cf9e3fe8e..f9a6cfa41 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
@@ -1,6 +1,6 @@
---
title: 精灵与渲染
-description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、尺寸与轴心、翻转、排序层与绘制顺序、视差——外加纹理过滤、点击检测、位图缓存、ShapeRenderer 图元、精灵滤镜、拖尾与世界空间位图文字。
+description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、尺寸与轴心、翻转、排序层与绘制顺序、Y 排序与深度层(2.5D)、视差——外加纹理过滤、点击检测、位图缓存、ShapeRenderer 图元、精灵滤镜、拖尾与世界空间位图文字。
---
import { Aside } from '@astrojs/starlight/components';
@@ -125,6 +125,32 @@ world.applyEntityOrder([other, another, card]);
只对需要它的玩法层开启 Y 排序。
</Aside>
+### 深度层(2.5D)
+
+在 **Project Settings → Rendering → Depth-sorted layers** 勾选某个层后,该层完全不再依赖
+绘制顺序:谁遮住谁由深度缓冲判定,依据是各实体 `Transform` 的 z。配合透视相机就是 2.5D——
+不同深度的精灵在任意角度下都能正确互相遮挡,无需手工维护排序。
+
+哪些精灵参与,由其材质的**混合模式**决定,因为它正说明了这次绘制要不要读取屏幕上已有的内容:
+
+| 混合模式 | 在深度层中 |
+| --- | --- |
+| `None`(不透明) | 写入深度,并被任何更近的内容遮挡,与绘制先后无关。 |
+| 其它(半透明) | 只测试深度、从不写入,仍按由远及近的绘制顺序。 |
+
+这个区分不是一个可选项——半透明精灵若写入深度,会把它背后的精灵裁出生硬的黑边。所以想要正确
+遮挡的精灵需要不透明材质;不动混合模式则一切照旧,只是前面的东西会挡住它。
+
+编辑时要看到这些,切换视口工具栏的 **2D / 3D** 按钮——编辑器自己的眼睛变成透视的。它只改变
+你的视角:Game 视图始终显示场景相机。拾取和拖拽会跟着走,所以 z = -400 的精灵在它被画出的
+位置就能抓到。
+
+<Aside type="note">
+ 一个层要么 Y 排序、要么深度排序,不会两者兼有——Y 排序本就是从世界 Y 投影出的深度,
+ 同时声明两者的层仍按 Y 排序。可用 z 范围在正交相机下是 ±`far`(默认 ±1000),
+ 透视相机下是 `near`..`far`;超出范围的内容会被整个裁掉。
+</Aside>
+
## 翻转、图集与滚动
- 用 `flipX` / `flipY` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。