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(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.mdxindex 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).+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 & coordinatesWorld 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 asgizmos 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 alsodiff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxindex 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% 透明+轴心超出 `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 补偿),于是你可以直接用眼睛把转动点放到脚下或+ 门轴上。它在移动/旋转/缩放工具下会隐藏——那几个工具的中心抓手正好在同一个位置。## 参见