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: 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.mdxindex 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.mdxindex 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 fromdiff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdxindex 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 interactionThe 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.mdxindex 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.mdxindex 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.mdxindex 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>