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: add sprite draw-order and camera scale-mode diagrams (en + zh)

yhh9537c9868fdc
diff --git a/docs/astro/src/assets/guides/scale-modes.svg b/docs/astro/src/assets/guides/scale-modes.svg
new file mode 100644
index 000000000..28276365b
--- /dev/null
+++ b/docs/astro/src/assets/guides/scale-modes.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 250" width="640" height="250" role="img"><defs><pattern id="crop" width="7" height="7" patternTransform="rotate(45)" patternUnits="userSpaceOnUse"><rect width="7" height="7" fill="#ef4444" fill-opacity="0.14"/><line x1="0" y1="0" x2="0" y2="7" stroke="#ef4444" stroke-width="1.4" stroke-opacity="0.55"/></pattern></defs><text x="320" y="22" fill="#c7cdd8" font-size="13" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">A 16:9 design on a taller 4:3 screen</text><line x1="320" y1="40" x2="320" y2="228" stroke="#2b2f3a" stroke-width="1"/><text x="167" y="46" fill="#c7cdd8" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">FixedWidth · Expand</text><rect x="92" y="58" width="150" height="14" fill="#22c55e" fill-opacity="0.22"/><rect x="92" y="156" width="150" height="14" fill="#22c55e" fill-opacity="0.22"/><rect x="92" y="72" width="150" height="84" fill="#3b82f6" fill-opacity="0.16" stroke="#6b7280" stroke-width="1.2" stroke-dasharray="4 3"/><text x="167" y="118" fill="#aeb6c6" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">design</text><rect x="92" y="58" width="150" height="112" rx="3" fill="none" stroke="#c7cdd8" stroke-width="1.6"/><text x="167" y="194" fill="#8b91a0" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">reveals world above + below</text><text x="167" y="210" fill="#5f95d6" font-size="10" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">(nothing cut off)</text><text x="490" y="46" fill="#c7cdd8" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">FixedHeight · Shrink</text><rect x="390.5" y="58" width="199" height="112" fill="#3b82f6" fill-opacity="0.16"/><rect x="390.5" y="58" width="24.5" height="112" fill="url(#crop)"/><rect x="565" y="58" width="24.5" height="112" fill="url(#crop)"/><text x="490" y="118" fill="#aeb6c6" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">design</text><rect x="415" y="58" width="150" height="112" rx="3" fill="none" stroke="#c7cdd8" stroke-width="1.6"/><text x="490" y="194" fill="#8b91a0" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">crops the left + right</text><text x="490" y="210" fill="#d67d7d" font-size="10" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">(screen always filled)</text></svg>
\ No newline at end of file
diff --git a/docs/astro/src/assets/guides/sprite-sort.svg b/docs/astro/src/assets/guides/sprite-sort.svg
new file mode 100644
index 000000000..1f9f70ffa
--- /dev/null
+++ b/docs/astro/src/assets/guides/sprite-sort.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 660 250" width="660" height="250" role="img"><text x="150" y="22" fill="#c7cdd8" font-size="13" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Sorting layers</text><text x="510" y="22" fill="#c7cdd8" font-size="13" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Y-sort (top-down)</text><line x1="330" y1="40" x2="330" y2="228" stroke="#2b2f3a" stroke-width="1"/><rect x="30" y="44" width="150" height="66" rx="7" fill="#4b5563" stroke="#0d0e11" stroke-width="1.5"/><text x="92" y="62" fill="#ffffff" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Background · 0</text><rect x="76" y="84" width="150" height="66" rx="7" fill="#3b82f6" stroke="#0d0e11" stroke-width="1.5"/><text x="138" y="102" fill="#ffffff" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Default · 1</text><rect x="122" y="124" width="150" height="66" rx="7" fill="#22c55e" stroke="#0d0e11" stroke-width="1.5"/><text x="197" y="161" fill="#ffffff" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Foreground · 2</text><defs><marker id="ah" markerWidth="8" markerHeight="8" refX="6" refY="4" orient="auto"><path d="M0 0 L8 4 L0 8 z" fill="#8b91a0"/></marker></defs><line x1="250" y1="70" x2="296" y2="150" stroke="#8b91a0" stroke-width="1.4" stroke-dasharray="4 3" marker-end="url(#ah)"/><text x="150" y="232" fill="#8b91a0" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">higher layer = in front</text><line x1="380" y1="210" x2="640" y2="210" stroke="#2b2f3a" stroke-width="1"/><circle cx="466" cy="120" r="15" fill="#e0b341" stroke="#0d0e11" stroke-width="1.5"/><rect x="494" y="118" width="12" height="92" rx="2" fill="#7c5a3a"/><polygon points="500,62 542,140 458,140" fill="#2f9e57" stroke="#0d0e11" stroke-width="1.5"/><circle cx="500" cy="182" r="17" fill="#4aa3ff" stroke="#0d0e11" stroke-width="1.5"/><text x="408" y="116" fill="#8b91a0" font-size="10" font-weight="600" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">behind</text><line x1="440" y1="118" x2="456" y2="120" stroke="#8b91a0" stroke-width="1"/><text x="530" y="186" fill="#8b91a0" font-size="10" font-weight="600" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">in front</text><line x1="528" y1="182" x2="515" y2="182" stroke="#8b91a0" stroke-width="1"/><text x="510" y="232" fill="#8b91a0" font-size="11" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">lower on screen = in front</text></svg>
\ No newline at end of file
diff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdx
index 6659a7d57..b6122f066 100644
--- a/docs/astro/src/content/docs/core-concepts/screen.mdx
+++ b/docs/astro/src/content/docs/core-concepts/screen.mdx
@@ -66,6 +66,8 @@ const readCanvas = defineSystem([GetWorld()], (world) => {
## Scale modes
+![On a 4:3 screen, FixedWidth/Expand reveal extra world above and below the 16:9 design box, while FixedHeight/Shrink fill the height and crop the sides](../../../assets/guides/scale-modes.svg)
+
The fit math is one pure function, exported as `computeEffectiveOrthoSize`. Given
the design box and the actual screen aspect it produces the **effective ortho
half-height** — half the height of the world box the camera will show, in world
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdx
index b28b5435f..ec168badb 100644
--- a/docs/astro/src/content/docs/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/guides/sprites.mdx
@@ -94,6 +94,8 @@ layer** (`sprite.layer`) — a named layer list you define in **Project Settings
Rendering**, so the inspector shows a dropdown of *Background*, *Default*, *Foreground*,
etc. instead of a raw number. Lower layers draw first (behind).
+![Left: three sorting layers stacked so a higher layer draws in front. Right: on a Y-sorted layer a sprite lower on screen draws in front of one higher up.](../../../assets/guides/sprite-sort.svg)
+
```typescript
sprite.layer = 0; // e.g. "Background"
sprite.layer = 2; // e.g. "Foreground" — drawn on top
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
index bc2d6eb24..88f0bf0f2 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx
@@ -60,6 +60,8 @@ const readCanvas = defineSystem([GetWorld()], (world) => {
## 缩放模式
+![在 4:3 屏幕上,FixedWidth/Expand 在 16:9 设计盒的上下露出额外世界,而 FixedHeight/Shrink 填满高度并裁掉两侧](../../../../assets/guides/scale-modes.svg)
+
适配数学是一个纯函数,导出为 `computeEffectiveOrthoSize`。给定设计盒与实际屏幕宽高比,
它产出**有效正交半高**——相机将显示的世界盒高度的一半,单位是世界单位(设计像素)。
存在两个候选答案:
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 3e3862272..d7f571734 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
@@ -84,6 +84,8 @@ sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% 透明
**项目设置 → 渲染**里定义的命名层列表,于是检视器显示 *Background*、*Default*、*Foreground* 等
下拉,而不是裸数字。较低的层先画(在后面)。
+![左:三个排序层堆叠,更高的层画在前面。右:在 Y-排序层上,屏幕上更靠下的精灵画在更靠上的前面。](../../../../assets/guides/sprite-sort.svg)
+
```typescript
sprite.layer = 0; // 例如 "Background"
sprite.layer = 2; // 例如 "Foreground" —— 画在上面