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 text-alignment and blend-tree diagrams (en + zh)

yhha257d1ffafe8
diff --git a/docs/astro/src/assets/guides/blend-tree.svg b/docs/astro/src/assets/guides/blend-tree.svg
new file mode 100644
index 000000000..1dda802e6
--- /dev/null
+++ b/docs/astro/src/assets/guides/blend-tree.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 424 174" width="424" height="174" role="img"><text x="20" y="26" fill="#cbd0db" font-size="14" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">blend on speed</text><text x="20" y="42" fill="#8b91a0" font-size="11.5" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">the highest threshold at or below the parameter wins — no transitions</text><rect x="20" y="54" width="128" height="46" rx="6" fill="#5b9cf0" fill-opacity="0.16" stroke="#5b9cf0" stroke-width="1.5"/><rect x="20" y="54" width="4" height="46" rx="0" fill="#5b9cf0"/><text x="36" y="76" fill="#cbd0db" font-size="15" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">idle</text><text x="36" y="93" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">speed below 0.5</text><line x1="20" y1="106" x2="20" y2="114" stroke="#8b91a0" stroke-width="1.5" stroke-linecap="round"/><text x="20" y="128" fill="#8b91a0" font-size="11" font-weight="500" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">value 0</text><rect x="148" y="54" width="128" height="46" rx="0" fill="#54c479" fill-opacity="0.16" stroke="#54c479" stroke-width="1.5"/><rect x="148" y="54" width="4" height="46" rx="0" fill="#54c479"/><text x="164" y="76" fill="#cbd0db" font-size="15" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">walk</text><text x="164" y="93" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">0.5 to 4</text><line x1="148" y1="106" x2="148" y2="114" stroke="#8b91a0" stroke-width="1.5" stroke-linecap="round"/><text x="148" y="128" fill="#8b91a0" font-size="11" font-weight="500" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">value 0.5</text><rect x="276" y="54" width="128" height="46" rx="0" fill="#f0bd4f" fill-opacity="0.16" stroke="#f0bd4f" stroke-width="1.5"/><rect x="276" y="54" width="4" height="46" rx="0" fill="#f0bd4f"/><text x="292" y="76" fill="#cbd0db" font-size="15" font-weight="700" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">run</text><text x="292" y="93" fill="#8b91a0" font-size="11" font-weight="400" text-anchor="start" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">speed 4 and up</text><line x1="276" y1="106" x2="276" y2="114" stroke="#8b91a0" stroke-width="1.5" stroke-linecap="round"/><text x="276" y="128" fill="#8b91a0" font-size="11" font-weight="500" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">value 4</text><line x1="20" y1="144" x2="404" y2="144" stroke="#8b91a0" stroke-width="2" stroke-linecap="round"/><path d="M 396 140 L 404 144 L 396 148" fill="none" stroke="#8b91a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><text x="212" y="162" fill="#8b91a0" font-size="11.5" font-weight="500" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">speed increases →</text></svg>
\ No newline at end of file
diff --git a/docs/astro/src/assets/guides/text-align.svg b/docs/astro/src/assets/guides/text-align.svg
new file mode 100644
index 000000000..f662e8b26
--- /dev/null
+++ b/docs/astro/src/assets/guides/text-align.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 440 250" width="440" height="250" role="img"><text x="132" y="20" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Left</text><text x="254" y="20" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Center</text><text x="376" y="20" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="middle" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Right</text><text x="66" y="64" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="end" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Top</text><text x="66" y="138" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="end" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Middle</text><text x="66" y="212" fill="#8b91a0" font-size="12" font-weight="600" text-anchor="end" font-family="ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif">Bottom</text><rect x="78" y="30" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="87" y="39" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="87" y="55" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="200" y="30" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="225" y="39" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="235" y="55" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="322" y="30" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="363" y="39" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="383" y="55" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="78" y="104" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="87" y="122" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="87" y="138" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="200" y="104" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="225" y="122" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="235" y="138" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="322" y="104" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="363" y="122" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="383" y="138" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="78" y="178" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="87" y="205" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="87" y="221" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="200" y="178" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="225" y="205" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="235" y="221" width="38" height="8" rx="2.5" fill="#aeb6c6"/><rect x="322" y="178" width="108" height="60" rx="6" fill="#14161c" stroke="#2b2f3a" stroke-width="1"/><rect x="363" y="205" width="58" height="8" rx="2.5" fill="#aeb6c6"/><rect x="383" y="221" width="38" height="8" rx="2.5" fill="#aeb6c6"/></svg>
\ No newline at end of file
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdx
index d0be12414..50c70b8ff 100644
--- a/docs/astro/src/content/docs/guides/animation.mdx
+++ b/docs/astro/src/content/docs/guides/animation.mdx
@@ -304,6 +304,10 @@ parameter and `eq` / `neq`.
### Blend trees
+![A 1D blend on speed selecting idle / walk / run by threshold](../../../assets/guides/blend-tree.svg)
+
+*A 1D blend: a float parameter picks the clip whose threshold is the highest one at or below it — here `idle` / `walk` / `run` as `speed` rises, with no transitions between them.*
+
A state can carry a 1D **blend** instead of a single clip: a float parameter
selects between `AnimatorBlendThreshold` stops. Because the sprite channel plays
one clip at a time, this is a *selection* by threshold — the stop with the
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdx
index c2e15493e..f5edc15ac 100644
--- a/docs/astro/src/content/docs/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/guides/ui-text.mdx
@@ -101,6 +101,10 @@ Defaults below are the component defaults (what the inspector shows).
## Alignment — with and without a box
+![The nine text-alignment combinations: align Left/Center/Right by verticalAlign Top/Middle/Bottom](../../../assets/guides/text-align.svg)
+
+*`align` (Left / Center / Right) and `verticalAlign` (Top / Middle / Bottom) place the text block within its box — the nine combinations.*
+
One rule covers both cases: **`align` / `verticalAlign` position the text block
within its box, and a missing box collapses to a zero-size box at the entity
origin** — so the same fields *anchor* a free label instead of silently doing
diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
index 9f7a4c9c5..3a8717dc6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
@@ -286,6 +286,10 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)
### 混合树
+![一维 blend 按 speed 阈值在 idle / walk / run 之间选择](../../../../assets/guides/blend-tree.svg)
+
+*一维 blend:float 参数挑出「阈值 ≤ 它」中最高的那个片段——这里随 `speed` 上升在 `idle` / `walk` / `run` 之间切换,彼此不做过渡。*
+
状态可以携带一个 1D **blend** 来代替单个片段:由一个 float 参数在
`AnimatorBlendThreshold` 档位之间做选择。因为精灵通道一次只播一个片段,这里的混合是
按阈值的*选择*——`value` 不超过参数值的档位中取最大者(低于所有档位时播第一个)——
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
index e2dee3486..feb6f5b0d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
@@ -94,6 +94,10 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t
## 对齐——有盒与无盒
+![九种文本对齐组合:align 左/中/右 × verticalAlign 上/中/下](../../../../assets/guides/text-align.svg)
+
+*`align`(Left / Center / Right)和 `verticalAlign`(Top / Middle / Bottom)把文本块定位在它的盒内——九种组合。*
+
一条规则覆盖两种情况:**`align` / `verticalAlign` 把文本块定位在它的盒内,而
"没有盒" 塌缩为实体原点处的零尺寸盒**——同样的字段用来*锚定*自由标签,而不是
静默失效。