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: deepen the Spine guide (tracks/mix, skins, attachments, queries, events)
yhh1ba7780c6c6e
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdxindex d8c61c3e6..14d955e13 100644--- a/docs/astro/src/content/docs/guides/spine.mdx+++ b/docs/astro/src/content/docs/guides/spine.mdx@@ -1,26 +1,24 @@---title: Spine Animation-description: Play Spine skeletal animations with the SpineAnimation component and Res(Spine).+description: Skeletal animation — play tracks, blend, swap skins and attachments, read 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.+`Spine` resource (from the `esengine/spine` subpath).## The `SpineAnimation` component-Add it in the editor and point it at your Spine assets. Its fields (import the-component from `esengine`):+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 and its playback state.+- `animation`, `loop`, `playing` — the current track.- `skin`, `timeScale`, `skeletonScale`, `flipX`, `flipY`, `color`, `layer`.-## Control at runtime with `Res(Spine)`--The `Spine` resource (from the `esengine/spine` subpath) is the imperative API:+## Play and blend animations```typescriptimport { defineSystem, Query, Res, SpineAnimation } from 'esengine';@@ -28,22 +26,36 @@ import { Spine } from 'esengine/spine';const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {for (const [entity] of q) {- spine.setAnimation(entity, 'walk', true); // play looped 'walk'- spine.setSkin(entity, 'armor'); // swap skin- spine.setMixDuration(entity, 'idle', 'walk', 0.2); // 0.2s crossfade+ spine.setAnimation(entity, 'run', true); // play, looped+ 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}});```-Methods include `setAnimation`, `setSkin`, `setMixDuration`, `setDefaultMix`,-`setTrackAlpha`, `setAttachment`, and the queries `getAnimations`, `getSkins`,-`getBounds`. You can also just write the `SpineAnimation` component's fields from-a `Query(Mut(SpineAnimation))` system for simple play/stop.+## Skins and attachments++```typescript+spine.setSkin(entity, 'armored');+spine.setAttachment(entity, 'weapon-slot', 'sword'); // swap a slot's attachment+```++## Query a skeleton++```typescript+const anims = spine.getAnimations(entity); // string[]+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 (also from `esengine/spine`) publishes track events-once per frame — read it in the same frame:+The `SpineEvents` resource publishes track events once per frame — read it in the+same frame:```typescriptimport { defineSystem, Res } from 'esengine';@@ -52,21 +64,20 @@ import { SpineEvents } from 'esengine/spine';const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {for (const e of spineEvents.events) {// e.type: 'start' | 'interrupt' | 'end' | 'complete' | 'event'- if (e.type === 'complete') { /* e.entity, e.animationName */ }+ // e.entity, e.track, e.animationName; for 'event': e.eventName + values}});```<Aside type="note">- The `SpineAnimation` **component** is in the main `esengine` package, but the- `Spine` and `SpineEvents` **runtime resources** live on the `esengine/spine`- subpath — spine is an optional side-module (loaded on demand per skeleton- version 3.8 / 4.1 / 4.2), kept off the base bundle. Entities sharing a+ 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 askeleton + atlas share one ref-counted skeleton.</Aside><Aside type="caution">The bundled Spine Runtimes are proprietary. Shipping a game that uses Spine- requires a valid Spine license from Esoteric Software — separate from- Estella's own license.+ requires a valid Spine license from Esoteric Software — separate from Estella's+ own license.</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdxindex 3688e35bc..9bbdf17e9 100644--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx@@ -1,24 +1,22 @@---title: Spine 动画-description: 用 SpineAnimation 组件和 Res(Spine) 播放 Spine 骨骼动画。+description: 骨骼动画 —— 播放轨道、混合、切换皮肤与附件、读取事件。---import { Aside } from '@astrojs/starlight/components';Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画,由 `SpineAnimation`-组件驱动,并通过 `Spine` 资源在运行时控制。+组件驱动,并通过 `Spine` 资源(来自 `esengine/spine` 子路径)在运行时控制。## `SpineAnimation` 组件-在编辑器里添加它并指向你的 Spine 资源。它的字段(组件从 `esengine` 导入):+在编辑器里添加它并指向你的 Spine 资源。字段(组件在主 `esengine` 包里):- `skeletonPath`、`atlasPath` —— 要加载的骨骼与图集。-- `animation`、`loop`、`playing` —— 当前轨道及其播放状态。+- `animation`、`loop`、`playing` —— 当前轨道。- `skin`、`timeScale`、`skeletonScale`、`flipX`、`flipY`、`color`、`layer`。-## 用 `Res(Spine)` 在运行时控制--`Spine` 资源(来自 `esengine/spine` 子路径)是命令式 API:+## 播放与混合动画```typescriptimport { defineSystem, Query, Res, SpineAnimation } from 'esengine';@@ -26,22 +24,34 @@ import { Spine } from 'esengine/spine';const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {for (const [entity] of q) {- spine.setAnimation(entity, 'walk', true); // 循环播放 'walk'- spine.setSkin(entity, 'armor'); // 切换皮肤- spine.setMixDuration(entity, 'idle', 'walk', 0.2); // 0.2 秒交叉淡入+ spine.setAnimation(entity, 'run', true); // 循环播放+ spine.setDefaultMix(entity, 0.15); // 默认交叉淡入+ spine.setMixDuration(entity, 'idle', 'run', 0.25); // 指定过渡+ spine.setTrackAlpha(entity, 0, 1.0); // 淡入/淡出某轨道}});```-方法包括 `setAnimation`、`setSkin`、`setMixDuration`、`setDefaultMix`、-`setTrackAlpha`、`setAttachment`,以及查询 `getAnimations`、`getSkins`、-`getBounds`。简单的播放/停止也可以直接在 `Query(Mut(SpineAnimation))` 系统里写-组件字段。+## 皮肤与附件++```typescript+spine.setSkin(entity, 'armored');+spine.setAttachment(entity, 'weapon-slot', 'sword'); // 替换某槽位的附件+```++## 查询骨骼++```typescript+const anims = spine.getAnimations(entity); // string[]+const skins = spine.getSkins(entity); // string[]+const bounds = spine.getBounds(entity); // { x, y, width, height } | null+```++`setEntityProps(entity, props)` 可一次性更新多个视觉属性(缩放、翻转、颜色、时间缩放)。## 动画事件-`SpineEvents` 资源(同样来自 `esengine/spine`)每帧发布一次轨道事件——在同一帧里-读取它:+`SpineEvents` 资源每帧发布一次轨道事件——在同一帧里读取它:```typescriptimport { defineSystem, Res } from 'esengine';@@ -50,16 +60,15 @@ import { SpineEvents } from 'esengine/spine';const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {for (const e of spineEvents.events) {// e.type: 'start' | 'interrupt' | 'end' | 'complete' | 'event'- if (e.type === 'complete') { /* e.entity, e.animationName */ }+ // e.entity、e.track、e.animationName;对 'event':e.eventName + 各值}});```<Aside type="note">- `SpineAnimation` **组件**在主 `esengine` 包里,但 `Spine` 和 `SpineEvents`- **运行时资源**位于 `esengine/spine` 子路径——spine 是可选 side-module(按骨骼- 版本 3.8 / 4.1 / 4.2 **按需加载**),不占用基础包。共享同一套骨骼 + 图集的实体- 共享同一份引用计数的骨骼。+ Estella 支持 Spine **3.8 / 4.1 / 4.2** —— 每个骨骼版本按需加载各自的 WebAssembly+ 后端(用到才加载),这也是 `Spine` 和 `SpineEvents` 资源位于 `esengine/spine` 子路径+ 的原因。共享同一套骨骼 + 图集的实体共享同一份引用计数的骨骼。</Aside><Aside type="caution">