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: depth layers and the perspective viewport, in both languages
esengine9b6bcd2352eb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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-04A release about a game that is no longer alone once it ships. Four more of thediff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdxindex 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 withoutdiff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdxindex 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` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。