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: update spine/tilemap/ui guides for the unified runtime APIs

yhhe2d7b1a957f2
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index c5633f9ab..d8c61c3e6 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -1,45 +1,53 @@
---
title: Spine Animation
-description: Play Spine skeletal animations with the SpineAnimation component.
+description: Play Spine skeletal animations with the SpineAnimation component and Res(Spine).
---
import { Aside } from '@astrojs/starlight/components';
Estella has built-in [Spine](https://esotericsoftware.com/) skeletal animation,
-driven by the `SpineAnimation` component.
+driven by the `SpineAnimation` component and controlled at runtime through the
+`Spine` resource.
## The `SpineAnimation` component
-You usually add it in the editor and point it at your Spine assets. Its fields:
+Add it in the editor and point it at your Spine assets. Its fields (import the
+component from `esengine`):
- `skeletonPath`, `atlasPath` — the skeleton and atlas to load.
- `animation`, `loop`, `playing` — the current track and its playback state.
- `skin`, `timeScale`, `skeletonScale`, `flipX`, `flipY`, `color`, `layer`.
-## Control it at runtime
+## Control at runtime with `Res(Spine)`
-Because it's a normal component, you change playback by writing its fields from
-a system — query it with `Mut`:
+The `Spine` resource (from the `esengine/spine` subpath) is the imperative API:
```typescript
-import { defineSystem, Query, Mut, SpineAnimation } from 'esengine';
+import { defineSystem, Query, Res, SpineAnimation } from 'esengine';
+import { Spine } from 'esengine/spine';
-const play = defineSystem([Query(Mut(SpineAnimation))], (q) => {
- for (const [entity, spine] of q) {
- spine.animation = 'walk';
- spine.loop = true;
- spine.playing = true;
+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
}
});
```
+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.
+
## Animation events
-The `SpineEvents` resource publishes track events once per frame — read it in
-the same frame:
+The `SpineEvents` resource (also from `esengine/spine`) publishes track events
+once per frame — read it in the same frame:
```typescript
-import { defineSystem, Res, SpineEvents } from 'esengine';
+import { defineSystem, Res } from 'esengine';
+import { SpineEvents } from 'esengine/spine';
const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
for (const e of spineEvents.events) {
@@ -50,9 +58,11 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
```
<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). Entities that share the same
- skeleton + atlas share one loaded, ref-counted skeleton.
+ 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
+ skeleton + atlas share one ref-counted skeleton.
</Aside>
<Aside type="caution">
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdx
index cb35259d2..010741fcb 100644
--- a/docs/astro/src/content/docs/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/guides/tilemap.mdx
@@ -1,6 +1,6 @@
---
title: Tilemaps
-description: Load Tiled maps, or build tile layers with the TilemapAPI.
+description: Load Tiled maps, or build tile layers with Res(Tilemaps).
---
import { Aside } from '@astrojs/starlight/components';
@@ -24,39 +24,41 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
});
```
-## Low-level: build layers with `TilemapAPI`
+## Low-level: build layers with `Res(Tilemaps)`
-`TilemapAPI` is a singleton you import from `esengine` and call directly with a
-layer entity. Spawn an entity, initialise a layer on it, then write tiles:
+The `Tilemaps` resource is the tilemap runtime API — read it with `Res(Tilemaps)`
+and call it with a layer entity. Spawn an entity, initialise a layer on it, then
+write tiles:
```typescript
-import { defineSystem, Commands, Transform, TilemapAPI } from 'esengine';
+import { defineSystem, Commands, Res, Transform, Tilemaps } from 'esengine';
-const buildLayer = defineSystem([Commands()], (cmds) => {
+const buildLayer = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
const layer = cmds
.spawn()
.insert(Transform, { position: { x: 0, y: 0, z: 0 } })
.id(); // the layer entity
- TilemapAPI.initLayer(layer, 32, 32, 16, 16); // 32x32 tiles, 16px cells
+ tilemap.initLayer(layer, 32, 32, 16, 16); // 32x32 tiles, 16px cells
- const tiles = new Uint16Array(32 * 32); // tile ids (0 = empty)
+ const tiles = new Uint16Array(32 * 32); // tile ids (0 = empty)
tiles[0] = 1;
- TilemapAPI.setTiles(layer, tiles);
+ tilemap.setTiles(layer, tiles);
- TilemapAPI.setTile(layer, 5, 3, 7); // one tile
- TilemapAPI.flipTile(layer, 5, 3, true, false, false); // flip horizontally
+ tilemap.setTile(layer, 5, 3, 7); // one tile
+ tilemap.flipTile(layer, 5, 3, true, false, false); // flip horizontally
- TilemapAPI.setTileAnimation(layer, 10, [ // animate tile id 10
+ tilemap.setTileAnimation(layer, 10, [ // animate tile id 10
{ tileId: 10, duration: 100 },
{ tileId: 11, duration: 100 },
]);
});
```
-Other `TilemapAPI` methods: `getTile`, `fillRect`, `rotateTile`,
-`initInfiniteLayer` (chunked infinite maps), `setTilesets`, `setTint`,
-`setVisible`, and `tileToWorld` / `worldToTile`.
+Other methods: `getTile`, `fillRect`, `rotateTile`, `initInfiniteLayer` (chunked
+infinite maps), `setTilesets`, `setTint`, `setVisible`, and `tileToWorld` /
+`worldToTile`. (The same object is also exported directly as `TilemapAPI` for use
+outside a system.)
<Aside type="note">
Tile **collision is play-mode only** — static colliders are spawned from
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdx
index 63ee4ab38..dc8e53599 100644
--- a/docs/astro/src/content/docs/guides/ui.mdx
+++ b/docs/astro/src/content/docs/guides/ui.mdx
@@ -1,18 +1,16 @@
---
title: UI
-description: Flexbox layout, text, and pointer interaction.
+description: Flexbox layout, text, and interaction — in the editor or in code.
---
import { Aside } from '@astrojs/starlight/components';
-Estella's UI is a CSS-like flexbox system solved in the C++ core. You compose an
-interface in the editor from UI components, then read interaction state from
-your systems.
+Estella's UI is a CSS-like flexbox system solved in the C++ core. Compose an
+interface from UI components — in the editor or in code — and read interaction
+state from your systems.
## UI components
-Add these to entities in the editor to build an interface:
-
- **`UINode`** — the layout box. Flexbox fields live on it directly: `width`,
`height` (and min/max), `flexGrow`, `flexShrink`, `flexBasis`, `alignSelf`,
`margin*`, and `inset*` for absolute positioning. Layout is recomputed each
@@ -24,6 +22,31 @@ Add these to entities in the editor to build an interface:
- **`Interactable`** — marks an entity hit-testable (`enabled`, `blockRaycast`,
`raycastTarget`).
+## Build UI in code
+
+The composition helpers are public. Spawn a node with `spawnUIEntity` +
+`buildUINode`, sized with the dimension helpers `px` / `percent` / `auto`:
+
+```typescript
+import {
+ defineSystem, GetWorld,
+ spawnUIEntity, buildUINode, px, percent,
+} from 'esengine';
+
+const buildHUD = defineSystem([GetWorld()], (world) => {
+ spawnUIEntity({
+ world,
+ node: buildUINode({ width: px(220), height: percent(100) }),
+ text: { content: 'Score: 0', fontSize: 18 },
+ });
+});
+```
+
+Use **`FlexContainer`** (with `FlexDirection` / `JustifyContent` / `AlignItems`)
+for flex layout, and the widget factories — **`createButton`**, `createToggle`,
+`createSlider`, `createProgress`, `createDialog`, `createDropdown` — for
+ready-made controls.
+
## Handling interaction
The hit-test system writes per-frame pointer state into `UIInteraction`
@@ -51,7 +74,7 @@ event bus.
<Aside type="note">
There is no `RectTransform`: `UINode` is real flexbox, sized with `px`,
- `percent`, and `auto` dimensions (set in the inspector), plus `Absolute`
- positioning via insets. `UIInteraction` is written by the engine each frame —
- drive your logic from it or from `UIEvents`, don't mutate it.
+ `percent`, and `auto`, plus `Absolute` positioning via insets. `UIInteraction`
+ is written by the engine each frame — drive your logic from it or from
+ `UIEvents`, don't mutate it.
</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
index 6abf15b93..3688e35bc 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
@@ -1,43 +1,51 @@
---
title: Spine 动画
-description: 用 SpineAnimation 组件播放 Spine 骨骼动画。
+description: 用 SpineAnimation 组件和 Res(Spine) 播放 Spine 骨骼动画。
---
import { Aside } from '@astrojs/starlight/components';
Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画,由 `SpineAnimation`
-组件驱动。
+组件驱动,并通过 `Spine` 资源在运行时控制。
## `SpineAnimation` 组件
-通常你在编辑器里添加它并指向你的 Spine 资源。它的字段:
+在编辑器里添加它并指向你的 Spine 资源。它的字段(组件从 `esengine` 导入):
- `skeletonPath`、`atlasPath` —— 要加载的骨骼与图集。
- `animation`、`loop`、`playing` —— 当前轨道及其播放状态。
- `skin`、`timeScale`、`skeletonScale`、`flipX`、`flipY`、`color`、`layer`。
-## 运行时控制
+## 用 `Res(Spine)` 在运行时控制
-因为它就是个普通组件,你在系统里写它的字段即可改变播放——用 `Mut` 查询它:
+`Spine` 资源(来自 `esengine/spine` 子路径)是命令式 API:
```typescript
-import { defineSystem, Query, Mut, SpineAnimation } from 'esengine';
+import { defineSystem, Query, Res, SpineAnimation } from 'esengine';
+import { Spine } from 'esengine/spine';
-const play = defineSystem([Query(Mut(SpineAnimation))], (q) => {
- for (const [entity, spine] of q) {
- spine.animation = 'walk';
- spine.loop = true;
- spine.playing = true;
+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 秒交叉淡入
}
});
```
+方法包括 `setAnimation`、`setSkin`、`setMixDuration`、`setDefaultMix`、
+`setTrackAlpha`、`setAttachment`,以及查询 `getAnimations`、`getSkins`、
+`getBounds`。简单的播放/停止也可以直接在 `Query(Mut(SpineAnimation))` 系统里写
+组件字段。
+
## 动画事件
-`SpineEvents` 资源每帧发布一次轨道事件——在同一帧里读取它:
+`SpineEvents` 资源(同样来自 `esengine/spine`)每帧发布一次轨道事件——在同一帧里
+读取它:
```typescript
-import { defineSystem, Res, SpineEvents } from 'esengine';
+import { defineSystem, Res } from 'esengine';
+import { SpineEvents } from 'esengine/spine';
const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
for (const e of spineEvents.events) {
@@ -48,8 +56,10 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {
```
<Aside type="note">
- Estella 支持 Spine **3.8 / 4.1 / 4.2** —— 每个骨骼版本按需加载各自的 WebAssembly
- 后端(用到才加载)。共享同一套骨骼 + 图集的实体共享同一份加载后、引用计数的骨骼。
+ `SpineAnimation` **组件**在主 `esengine` 包里,但 `Spine` 和 `SpineEvents`
+ **运行时资源**位于 `esengine/spine` 子路径——spine 是可选 side-module(按骨骼
+ 版本 3.8 / 4.1 / 4.2 **按需加载**),不占用基础包。共享同一套骨骼 + 图集的实体
+ 共享同一份引用计数的骨骼。
</Aside>
<Aside type="caution">
diff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
index beb0f29e8..ce083beb1 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
@@ -1,6 +1,6 @@
---
title: 瓦片地图
-description: 加载 Tiled 地图,或用 TilemapAPI 构建瓦片图层。
+description: 加载 Tiled 地图,或用 Res(Tilemaps) 构建瓦片图层。
---
import { Aside } from '@astrojs/starlight/components';
@@ -22,39 +22,39 @@ const loadLevel = defineSystem([Commands()], (cmds) => {
});
```
-## 低层:用 `TilemapAPI` 构建图层
+## 低层:用 `Res(Tilemaps)` 构建图层
-`TilemapAPI` 是一个从 `esengine` 导入的单例,直接传入图层实体来调用。先生成一个实体,
-在它上面初始化图层,再写入瓦片:
+`Tilemaps` 资源就是瓦片地图运行时 API——用 `Res(Tilemaps)` 读取它,传入图层实体来
+调用。先生成一个实体,在它上面初始化图层,再写入瓦片:
```typescript
-import { defineSystem, Commands, Transform, TilemapAPI } from 'esengine';
+import { defineSystem, Commands, Res, Transform, Tilemaps } from 'esengine';
-const buildLayer = defineSystem([Commands()], (cmds) => {
+const buildLayer = defineSystem([Commands(), Res(Tilemaps)], (cmds, tilemap) => {
const layer = cmds
.spawn()
.insert(Transform, { position: { x: 0, y: 0, z: 0 } })
.id(); // 图层实体
- TilemapAPI.initLayer(layer, 32, 32, 16, 16); // 32x32 格,16px 格子
+ tilemap.initLayer(layer, 32, 32, 16, 16); // 32x32 格,16px 格子
- const tiles = new Uint16Array(32 * 32); // 瓦片 id(0 = 空)
+ const tiles = new Uint16Array(32 * 32); // 瓦片 id(0 = 空)
tiles[0] = 1;
- TilemapAPI.setTiles(layer, tiles);
+ tilemap.setTiles(layer, tiles);
- TilemapAPI.setTile(layer, 5, 3, 7); // 单个瓦片
- TilemapAPI.flipTile(layer, 5, 3, true, false, false); // 水平翻转
+ tilemap.setTile(layer, 5, 3, 7); // 单个瓦片
+ tilemap.flipTile(layer, 5, 3, true, false, false); // 水平翻转
- TilemapAPI.setTileAnimation(layer, 10, [ // 让瓦片 id 10 动起来
+ tilemap.setTileAnimation(layer, 10, [ // 让瓦片 id 10 动起来
{ tileId: 10, duration: 100 },
{ tileId: 11, duration: 100 },
]);
});
```
-`TilemapAPI` 的其他方法:`getTile`、`fillRect`、`rotateTile`、`initInfiniteLayer`
-(分块的无限地图)、`setTilesets`、`setTint`、`setVisible`,以及 `tileToWorld` /
-`worldToTile`。
+其他方法:`getTile`、`fillRect`、`rotateTile`、`initInfiniteLayer`(分块的无限地图)、
+`setTilesets`、`setTint`、`setVisible`,以及 `tileToWorld` / `worldToTile`。(同一个
+对象也以 `TilemapAPI` 直接导出,供在系统之外使用。)
<Aside type="note">
瓦片**碰撞仅在运行模式**存在——静态碰撞体在场景运行时由可碰撞瓦片(在 `.estileset`
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
index b1e9713e5..c50a8bbaa 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ui.mdx
@@ -1,17 +1,15 @@
---
title: UI
-description: 弹性盒布局、文本与指针交互。
+description: 弹性盒布局、文本与交互 —— 在编辑器里或用代码。
---
import { Aside } from '@astrojs/starlight/components';
-Estella 的 UI 是一套在 C++ 内核里求解的类 CSS 弹性盒(flexbox)系统。你在编辑器里用
-UI 组件组合界面,再从系统里读取交互状态。
+Estella 的 UI 是一套在 C++ 内核里求解的类 CSS 弹性盒(flexbox)系统。你用 UI 组件
+组合界面——在编辑器里或用代码——再从系统里读取交互状态。
## UI 组件
-在编辑器里把这些加到实体上来搭建界面:
-
- **`UINode`** —— 布局盒。弹性盒字段直接在它身上:`width`、`height`(以及 min/max)、
`flexGrow`、`flexShrink`、`flexBasis`、`alignSelf`、`margin*`,以及用于绝对定位的
`inset*`。布局每帧重新计算。
@@ -22,6 +20,30 @@ UI 组件组合界面,再从系统里读取交互状态。
- **`Interactable`** —— 标记实体可命中测试(`enabled`、`blockRaycast`、
`raycastTarget`)。
+## 用代码构建 UI
+
+组合助手都是公开的。用 `spawnUIEntity` + `buildUINode` 生成节点,并用尺寸助手
+`px` / `percent` / `auto` 设定大小:
+
+```typescript
+import {
+ defineSystem, GetWorld,
+ spawnUIEntity, buildUINode, px, percent,
+} from 'esengine';
+
+const buildHUD = defineSystem([GetWorld()], (world) => {
+ spawnUIEntity({
+ world,
+ node: buildUINode({ width: px(220), height: percent(100) }),
+ text: { content: 'Score: 0', fontSize: 18 },
+ });
+});
+```
+
+用 **`FlexContainer`**(配合 `FlexDirection` / `JustifyContent` / `AlignItems`)
+做弹性布局;用控件工厂——**`createButton`**、`createToggle`、`createSlider`、
+`createProgress`、`createDialog`、`createDropdown`——做开箱即用的控件。
+
## 处理交互
命中测试系统每帧把指针状态写入 `UIInteraction`(`hovered`、`pressed`、`justPressed`、
@@ -46,7 +68,7 @@ const handleClicks = defineSystem(
`drag` 等事件——请读取 `UIEvents` 资源,即 UI 事件总线。
<Aside type="note">
- 这里没有 `RectTransform`:`UINode` 是真正的弹性盒,用 `px`、`percent`、`auto` 尺寸
- (在检视面板里设置)加上通过 inset 的 `Absolute` 定位。`UIInteraction` 由引擎每帧
- 写入——请用它或 `UIEvents` 驱动逻辑,不要去修改它。
+ 这里没有 `RectTransform`:`UINode` 是真正的弹性盒,用 `px`、`percent`、`auto` 设定
+ 尺寸,加上通过 inset 的 `Absolute` 定位。`UIInteraction` 由引擎每帧写入——请用它或
+ `UIEvents` 驱动逻辑,不要去修改它。
</Aside>