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(sprites): say how a pivot is authored, not just what it stores

yhh587b5d03ecea
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index ce16b7d1f..6cc9c9890 100644
--- a/docs/astro/src/content/docs/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/graphics/sprites.mdx
@@ -38,7 +38,7 @@ Content Browser onto an entity, or set the Sprite's texture field in Details.
| `texture` | `0` | Texture handle from a loader (`0` = untextured, draws a white quad). |
| `color` | `{1,1,1,1}` | Tint multiplied into the texture (white = unchanged). |
| `size` | `{100,100}` | Rendered size in world units. |
-| `pivot` | `{0.5,0.5}` | Anchor point (0–1) the sprite rotates and scales about. |
+| `pivot` | `{0.5,0.5}` | Anchor point the sprite rotates and scales about, as a fraction of its `size`. Values outside 0–1 sit off the sprite. |
| `layer` | `0` | Sorting layer — controls draw order (see below). |
| `flipX` / `flipY` | `false` | Mirror horizontally / vertically. |
| `material` | `0` | A custom [material](/docs/graphics/materials/) handle (`0` = the default sprite shader). |
@@ -72,6 +72,14 @@ the ground).
![The same sprite rotated about three different pivots — the pivot dot stays fixed while the quad swings around it: center spins in place, a corner swings out, bottom-center pins the feet](@/assets/guides/sprite-pivot.svg)
+A pivot outside `0–1` is legal and useful: `{0.5, -1}` puts the turning point a full
+sprite-height below the art, which is how you hang a swinging arm or a door off a
+hinge it doesn't contain.
+
+Storing a fraction is what lets a pivot survive a resize, but it isn't how anyone
+thinks about one — see [In the editor](#in-the-editor) for entering it in pixels,
+picking it from the nine common positions, or dragging it on the sprite itself.
+
## Units & coordinates
World units are **design pixels**. Dropping a texture into the viewport spawns a
@@ -432,6 +440,16 @@ without a depth buffer.
Browser into the viewport to spawn one already textured.
- Every field above is editable in **Details**; sprites, cameras, and lights show as
gizmos in the viewport. See [The Editor](/docs/editor/overview/).
+- **`pivot` is authored three ways**, all writing the same stored fraction:
+ - The **3×3 grid** under the field picks the nine common positions in one click.
+ - The **`frac` / `px`** switch on the row enters it in pixels instead — `px` shows
+ `pivot × size`, and typing `32` stores `32 / size`. The unit is a view; the scene
+ always holds the fraction.
+ - With the **pointer tool**, a single selected sprite gets a **pivot dot** in the
+ viewport. Dragging it moves the pivot through the artwork *without moving the
+ artwork* — the transform takes up the slack — so you can put the turning point on
+ a foot or a hinge by eye. It hides under Move/Rotate/Scale, whose centre grab sits
+ in the same place.
## See also
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
index 38b6423b5..d6f2f85f5 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
@@ -35,7 +35,7 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)
| `texture` | `0` | 加载器给的纹理句柄(`0` = 无纹理,画白色四边形)。 |
| `color` | `{1,1,1,1}` | 乘进纹理的着色(白 = 不变)。 |
| `size` | `{100,100}` | 渲染尺寸,世界单位。 |
-| `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点(0–1)。 |
+| `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点,取值是相对 `size` 的比例。超出 0–1 就落在精灵外面。 |
| `layer` | `0` | 排序层——控制绘制顺序(见下)。 |
| `flipX` / `flipY` | `false` | 水平 / 垂直镜像。 |
| `material` | `0` | 自定义[材质](/docs/zh-cn/graphics/materials/)句柄(`0` = 默认精灵着色器)。 |
@@ -65,6 +65,12 @@ sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% 透明
![同一个精灵绕三个不同轴心旋转——轴心点(黄点)保持不动、四边形绕它摆动:居中=原地旋转,角点=甩出去,底部中心=钉住脚下](@/assets/guides/sprite-pivot.svg)
+轴心超出 `0–1` 是合法且有用的:`{0.5, -1}` 把转动点放到画面下方整整一个精灵高度处——
+摆动的手臂、挂在自己画面之外那根轴上的门,就是这么做的。
+
+存成比例才能让轴心在改尺寸后依然成立,但没人是这么想事情的——**按像素输入**、
+**从九个常用位置里点一个**、或者**直接在精灵上拖**,见[在编辑器里](#在编辑器里)。
+
## 单位与坐标
世界单位就是**设计像素**。把纹理拖进视口会生成一个尺寸等于纹理像素尺寸的精灵
@@ -387,6 +393,13 @@ Draw.texture(pos, { x: 512, y: 256 }, cache.textureId);
- **创建 → 精灵** 添加一个精灵实体,或从内容浏览器**把图拖**进视口,生成一个已带纹理的精灵。
- 上面每个字段都能在 **Details** 里编辑;精灵、相机、光源在视口里显示为 gizmo。见
[编辑器](/docs/zh-cn/editor/overview/)。
+- **`pivot` 有三种授权方式**,写进去的都是同一个比例值:
+ - 字段下方的 **3×3 网格**,一次点击选中九个常用位置之一。
+ - 该行上的 **`比例` / `px`** 切换按像素输入:`px` 显示 `pivot × size`,输入 `32` 存进去的是
+ `32 / size`。单位只是视图,场景里始终存比例。
+ - 用**指针工具**时,单选中的精灵会在视口里得到一个**轴心点**。拖它会让轴心在画面内移动
+ 而**画面本身不动**(位移由 Transform 补偿),于是你可以直接用眼睛把转动点放到脚下或
+ 门轴上。它在移动/旋转/缩放工具下会隐藏——那几个工具的中心抓手正好在同一个位置。
## 参见