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: rewrite the Spine guide to the complete-reference template
yhhf82792cad074
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdxindex 14d955e13..ad42263e3 100644--- a/docs/astro/src/content/docs/guides/spine.mdx+++ b/docs/astro/src/content/docs/guides/spine.mdx@@ -1,24 +1,39 @@---title: Spine Animation-description: Skeletal animation — play tracks, blend, swap skins and attachments, read events.+description: The complete guide to Spine skeletal animation — the SpineAnimation component, the Spine track/mix/skin/attachment API, queries, and events.---import { Aside } from '@astrojs/starlight/components';-Estella has built-in [Spine](https://esotericsoftware.com/) skeletal animation,-driven by the `SpineAnimation` component and controlled at runtime through the-`Spine` resource (from the `esengine/spine` subpath).+Estella has built-in [Spine](https://esotericsoftware.com/) skeletal animation:+bones, meshes, IK, skins, and events. It's driven by the `SpineAnimation` component+and controlled at runtime through the `Spine` resource (from the `esengine/spine`+subpath).## The `SpineAnimation` component-Add it in the editor and point it at your Spine assets. Fields (the component is-in the main `esengine` package):--- `skeletonPath`, `atlasPath` — the skeleton and atlas to load.-- `animation`, `loop`, `playing` — the current track.-- `skin`, `timeScale`, `skeletonScale`, `flipX`, `flipY`, `color`, `layer`.--## Play and blend animations+Add it in the editor and point it at your Spine assets. The component lives in the+main `esengine` package.++| Property | Type | Default | Description |+|---|---|---|---|+| `skeletonPath` | asset | `''` | Skeleton file (`.json` / `.skel`). |+| `atlasPath` | asset | `''` | Atlas file. |+| `skin` | string | `''` | Active skin (empty = default). |+| `animation` | string | `''` | Initial animation on track 0. |+| `loop` | boolean | `true` | Loop the initial animation. |+| `playing` | boolean | `true` | Whether playback advances. |+| `timeScale` | number | `1` | Per-entity playback speed. |+| `skeletonScale` | number | `1` | Uniform skeleton scale. |+| `flipX` / `flipY` | boolean | `false` | Mirror horizontally / vertically. |+| `color` | Color | `{1,1,1,1}` | Tint (RGBA, 0..1). |+| `layer` | number | `0` | Sorting layer for draw order. |+| `material` | asset | none | Optional custom material. |+| `enabled` | boolean | `true` | Disable to freeze and hide. |++## Play & blend animations++The `Spine` resource controls tracks, mixing (crossfade), and per-track blending:```typescriptimport { defineSystem, Query, Res, SpineAnimation } from 'esengine';@@ -26,7 +41,8 @@ import { Spine } from 'esengine/spine';const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {for (const [entity] of q) {- spine.setAnimation(entity, 'run', true); // play, looped+ spine.setAnimation(entity, 'run', true); // play on track 0, looped+ spine.addAnimation(entity, 'jump', false, 0.5); // queue after 0.5sspine.setDefaultMix(entity, 0.15); // default crossfadespine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transitionspine.setTrackAlpha(entity, 0, 1.0); // blend a track in/out@@ -34,13 +50,29 @@ const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) =>});```-## Skins and attachments+| Method | Description |+|---|---|+| `setAnimation(entity, name, loop)` | Play an animation on track 0. |+| `addAnimation(entity, name, loop, delay)` | Queue an animation after the current one. |+| `setDefaultMix(entity, seconds)` | Default crossfade between any two animations. |+| `setMixDuration(entity, from, to, seconds)` | Crossfade for a specific transition. |+| `setTrackAlpha(entity, track, alpha)` | Blend a track's contribution (0..1). |+| `setEntityProps(entity, props)` | Update scale / flip / color / time scale at once. |++## Skins & attachments```typescriptspine.setSkin(entity, 'armored');spine.setAttachment(entity, 'weapon-slot', 'sword'); // swap a slot's attachment+spine.setSlotColor(entity, 'body', { r: 1, g: 0.5, b: 0.5, a: 1 });```+| Method | Description |+|---|---|+| `setSkin(entity, name)` | Switch the active skin. |+| `setAttachment(entity, slot, attachment)` | Swap a slot's attachment (equip/variant). |+| `setSlotColor(entity, slot, color)` | Tint an individual slot. |+## Query a skeleton```typescript@@ -49,13 +81,10 @@ const skins = spine.getSkins(entity); // string[]const bounds = spine.getBounds(entity); // { x, y, width, height } | null```-`setEntityProps(entity, props)` updates several visual props (scale, flip, color,-time scale) at once.-## Animation events-The `SpineEvents` resource publishes track events once per frame — read it in the-same frame:+The `SpineEvents` resource publishes track events once per frame — read it the same+frame:```typescriptimport { defineSystem, Res } from 'esengine';@@ -69,11 +98,29 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {});```+| Event `type` | Fired when |+|---|---|+| `start` | An animation starts on a track. |+| `interrupt` | An animation is interrupted by another. |+| `end` | An animation is removed from a track. |+| `complete` | An animation loop/playthrough completes. |+| `event` | A user-authored event keyframe fires (`eventName` + values). |++## Best practices++- **Set a default mix** (`setDefaultMix`) so transitions crossfade instead of+ snapping; override hot paths with `setMixDuration`.+- **Layer with tracks + `setTrackAlpha`** (e.g. an aim/overlay on track 1 blended+ over a locomotion track 0).+- **Share skeleton + atlas** across entities — they ref-count a single loaded+ skeleton.+- **Drive whole characters from the [Animator](/docs/guides/animation/) state+ machine**, which can target Spine as well as sprites.+<Aside type="note">Estella supports Spine **3.8 / 4.1 / 4.2** — each skeleton version loads its own- WebAssembly backend on demand (pay-for-use), which is why the `Spine` and- `SpineEvents` resources live on the `esengine/spine` subpath. Entities sharing a- skeleton + atlas share one ref-counted skeleton.+ WebAssembly backend on demand (pay-for-use), which is why `Spine` and+ `SpineEvents` live on the `esengine/spine` subpath.</Aside><Aside type="caution">@@ -81,3 +128,8 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {requires a valid Spine license from Esoteric Software — separate from Estella'sown license.</Aside>++## See also++- [Animation](/docs/guides/animation/) — the Animator state machine can drive Spine.+- [Assets](/docs/guides/assets/) — loading skeleton + atlas assets.diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdxindex 9bbdf17e9..22a12ff93 100644--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx@@ -1,22 +1,37 @@---title: Spine 动画-description: 骨骼动画 —— 播放轨道、混合、切换皮肤与附件、读取事件。+description: Spine 骨骼动画的完整指南——SpineAnimation 组件、Spine 的轨道/混合/皮肤/附件 API、查询与事件。---import { Aside } from '@astrojs/starlight/components';-Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画,由 `SpineAnimation`-组件驱动,并通过 `Spine` 资源(来自 `esengine/spine` 子路径)在运行时控制。+Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画:骨骼、网格、IK、皮肤与事件。+它由 `SpineAnimation` 组件驱动,并在运行时通过 `Spine` 资源(来自 `esengine/spine` 子路径)+控制。## `SpineAnimation` 组件-在编辑器里添加它并指向你的 Spine 资源。字段(组件在主 `esengine` 包里):+在编辑器里添加并指向你的 Spine 资源。组件本身在主 `esengine` 包里。-- `skeletonPath`、`atlasPath` —— 要加载的骨骼与图集。-- `animation`、`loop`、`playing` —— 当前轨道。-- `skin`、`timeScale`、`skeletonScale`、`flipX`、`flipY`、`color`、`layer`。+| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `skeletonPath` | asset | `''` | 骨骼文件(`.json` / `.skel`)。 |+| `atlasPath` | asset | `''` | 图集文件。 |+| `skin` | string | `''` | 活动皮肤(空 = 默认)。 |+| `animation` | string | `''` | 轨道 0 上的初始动画。 |+| `loop` | boolean | `true` | 循环初始动画。 |+| `playing` | boolean | `true` | 播放是否推进。 |+| `timeScale` | number | `1` | 逐实体的播放速度。 |+| `skeletonScale` | number | `1` | 骨骼统一缩放。 |+| `flipX` / `flipY` | boolean | `false` | 水平 / 垂直镜像。 |+| `color` | Color | `{1,1,1,1}` | 着色(RGBA,0..1)。 |+| `layer` | number | `0` | 决定绘制顺序的排序层。 |+| `material` | asset | 无 | 可选的自定义材质。 |+| `enabled` | boolean | `true` | 关掉即冻结并隐藏。 |-## 播放与混合动画+## 播放与混合++`Spine` 资源控制轨道、混合(crossfade)与逐轨道混合:```typescriptimport { defineSystem, Query, Res, SpineAnimation } from 'esengine';@@ -24,21 +39,38 @@ import { Spine } from 'esengine/spine';const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {for (const [entity] of q) {- spine.setAnimation(entity, 'run', true); // 循环播放- spine.setDefaultMix(entity, 0.15); // 默认交叉淡入- spine.setMixDuration(entity, 'idle', 'run', 0.25); // 指定过渡- spine.setTrackAlpha(entity, 0, 1.0); // 淡入/淡出某轨道+ spine.setAnimation(entity, 'run', true); // play on track 0, looped+ spine.addAnimation(entity, 'jump', false, 0.5); // queue after 0.5s+ spine.setDefaultMix(entity, 0.15); // default crossfade+ spine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transition+ spine.setTrackAlpha(entity, 0, 1.0); // blend a track in/out}});```+| 方法 | 说明 |+|---|---|+| `setAnimation(entity, name, loop)` | 在轨道 0 播放一个动画。 |+| `addAnimation(entity, name, loop, delay)` | 在当前动画之后排队一个动画。 |+| `setDefaultMix(entity, seconds)` | 任意两个动画之间的默认交叉淡入。 |+| `setMixDuration(entity, from, to, seconds)` | 特定转移的交叉淡入。 |+| `setTrackAlpha(entity, track, alpha)` | 混合某轨道的贡献(0..1)。 |+| `setEntityProps(entity, props)` | 一次性更新 缩放 / 翻转 / 颜色 / 时间缩放。 |+## 皮肤与附件```typescriptspine.setSkin(entity, 'armored');-spine.setAttachment(entity, 'weapon-slot', 'sword'); // 替换某槽位的附件+spine.setAttachment(entity, 'weapon-slot', 'sword'); // swap a slot's attachment+spine.setSlotColor(entity, 'body', { r: 1, g: 0.5, b: 0.5, a: 1 });```+| 方法 | 说明 |+|---|---|+| `setSkin(entity, name)` | 切换活动皮肤。 |+| `setAttachment(entity, slot, attachment)` | 替换某槽位的附件(换装/变体)。 |+| `setSlotColor(entity, slot, color)` | 给单个槽位着色。 |+## 查询骨骼```typescript@@ -47,11 +79,9 @@ const skins = spine.getSkins(entity); // string[]const bounds = spine.getBounds(entity); // { x, y, width, height } | null```-`setEntityProps(entity, props)` 可一次性更新多个视觉属性(缩放、翻转、颜色、时间缩放)。-## 动画事件-`SpineEvents` 资源每帧发布一次轨道事件——在同一帧里读取它:+`SpineEvents` 资源每帧发布一次轨道事件——在同一帧读取:```typescriptimport { defineSystem, Res } from 'esengine';@@ -60,18 +90,37 @@ import { SpineEvents } from 'esengine/spine';const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {for (const e of spineEvents.events) {// e.type: 'start' | 'interrupt' | 'end' | 'complete' | 'event'- // e.entity、e.track、e.animationName;对 'event':e.eventName + 各值+ // e.entity, e.track, e.animationName; for 'event': e.eventName + values}});```+| 事件 `type` | 触发时机 |+|---|---|+| `start` | 某轨道上开始一个动画。 |+| `interrupt` | 一个动画被另一个打断。 |+| `end` | 一个动画从轨道移除。 |+| `complete` | 一个动画循环/播放完成。 |+| `event` | 用户编辑的事件关键帧触发(`eventName` + 值)。 |++## 最佳实践++- **设一个默认混合**(`setDefaultMix`)让转移交叉淡入而非硬切;热点路径用 `setMixDuration` 覆盖。+- **用轨道 + `setTrackAlpha` 分层**(例如在轨道 1 放一个瞄准/叠加,混合在轨道 0 的移动之上)。+- **跨实体共享骨骼 + 图集**——它们引用计数同一份已加载骨骼。+- **用 [Animator](/docs/zh-cn/guides/animation/) 状态机驱动整个角色**,它既能驱动 Spine 也能驱动精灵。+<Aside type="note">- Estella 支持 Spine **3.8 / 4.1 / 4.2** —— 每个骨骼版本按需加载各自的 WebAssembly- 后端(用到才加载),这也是 `Spine` 和 `SpineEvents` 资源位于 `esengine/spine` 子路径- 的原因。共享同一套骨骼 + 图集的实体共享同一份引用计数的骨骼。+ Estella 支持 Spine **3.8 / 4.1 / 4.2**——每个骨骼版本按需加载自己的 WebAssembly 后端+ (按需付费),这也是 `Spine` 与 `SpineEvents` 位于 `esengine/spine` 子路径的原因。</Aside><Aside type="caution">- 随附的 Spine Runtimes 是专有软件。发布使用 Spine 的游戏需要 Esoteric Software 的- 有效 Spine 授权——与 Estella 自身的许可证相互独立。+ 捆绑的 Spine Runtimes 是专有的。发布使用 Spine 的游戏需要 Esoteric Software 的有效 Spine+ 授权——与 Estella 自身的授权相互独立。</Aside>++## 参见++- [动画](/docs/zh-cn/guides/animation/) —— Animator 状态机可以驱动 Spine。+- [资源](/docs/zh-cn/guides/assets/) —— 加载骨骼 + 图集资源。