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: group the sidebar + add Plugins & Resources concept page

yhhbd040c5a594e
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 461087455..f9063341f 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -42,22 +42,35 @@ export default defineConfig({
{ label: 'ECS Architecture', translations: { 'zh-CN': 'ECS 架构' }, slug: 'core-concepts/ecs' },
{ label: 'Components', translations: { 'zh-CN': '组件' }, slug: 'core-concepts/components' },
{ label: 'Systems', translations: { 'zh-CN': '系统' }, slug: 'core-concepts/systems' },
+ { label: 'Plugins & Resources', translations: { 'zh-CN': '插件与资源' }, slug: 'core-concepts/plugins-resources' },
],
},
{
- label: 'Guides',
- translations: { 'zh-CN': '指南' },
+ label: 'Gameplay',
+ translations: { 'zh-CN': '玩法' },
items: [
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
- { label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
{ label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
+ { label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
+ ],
+ },
+ {
+ label: 'Graphics & UI',
+ translations: { 'zh-CN': '图形与 UI' },
+ items: [
{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },
{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },
- { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },
{ label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'guides/postprocess' },
+ ],
+ },
+ {
+ label: 'Content & Flow',
+ translations: { 'zh-CN': '内容与流程' },
+ items: [
{ label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'guides/assets' },
+ { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
],
diff --git a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx
new file mode 100644
index 000000000..e39ea5950
--- /dev/null
+++ b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx
@@ -0,0 +1,77 @@
+---
+title: Plugins & Resources
+description: How subsystems are composed and reached — the Res(XxxAPI) pattern.
+---
+
+An Estella game is an `App` composed of **plugins**. Each subsystem — physics,
+audio, tilemaps, particles, UI, and so on — is a plugin that registers its
+systems and exposes a runtime API as a **resource**.
+
+## Reaching a subsystem: `Res(XxxAPI)`
+
+Inside a system, list the resource you need in the parameter array; the callback
+receives it in the same order:
+
+```typescript
+import { defineSystem, Res, Audio } from 'esengine';
+
+defineSystem([Res(Audio)], (audio) => {
+ audio.playSFX('assets/hit.wav');
+});
+```
+
+Every subsystem's imperative API is reached the same way:
+
+| Subsystem | Resource | Import from |
+|---|---|---|
+| Input | `Res(Input)` | `esengine` |
+| Audio | `Res(Audio)` | `esengine` |
+| Assets | `Res(Assets)` | `esengine` |
+| Tilemaps | `Res(Tilemaps)` | `esengine` |
+| Particles | `Res(Particle)` | `esengine` |
+| Post-processing | `Res(PostProcess)` | `esengine` |
+| Scenes | `Res(SceneManager)` | `esengine` |
+| Tweens | `Res(Tween)` | `esengine` |
+| Animator | `Res(AnimatorController)` | `esengine` |
+| Physics | `Res(PhysicsAPI)` | `esengine/physics` |
+| Spine | `Res(Spine)` | `esengine/spine` |
+
+Physics and Spine are **optional side-modules** loaded on demand, so their APIs
+live on subpaths to keep the base bundle small; everything else is in the main
+`esengine` package.
+
+## Components vs. resources
+
+- **Components** are per-entity data. You attach them (in the editor or with
+ `Commands`) and iterate them with `Query`.
+- **Resources** are per-app singletons — shared state and subsystem APIs — read
+ with `Res`.
+
+## Getting an entity
+
+Subsystem APIs act on an entity, and that entity comes from a `Query` (or a
+spawn). This is the shape you'll see throughout the guides:
+
+```typescript
+import { defineSystem, Query, Res, SpriteAnimator, Tween, TweenTarget } from 'esengine';
+
+defineSystem([Query(SpriteAnimator), Res(Tween)], (q, tween) => {
+ for (const [entity] of q) {
+ tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {});
+ }
+});
+```
+
+## Spawning: `Commands`
+
+To create entities and attach components from a system, take `Commands()`:
+
+```typescript
+import { defineSystem, Commands, Transform, Sprite } from 'esengine';
+
+defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Sprite, { size: { x: 32, y: 32 } });
+});
+```
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx
new file mode 100644
index 000000000..514bc080d
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx
@@ -0,0 +1,73 @@
+---
+title: 插件与资源
+description: 子系统如何组合与取用 —— Res(XxxAPI) 范式。
+---
+
+一个 Estella 游戏就是由**插件**组合成的 `App`。每个子系统——物理、音频、瓦片地图、
+粒子、UI 等等——都是一个插件,它注册自己的系统,并把运行时 API 暴露为一个**资源**。
+
+## 取用子系统:`Res(XxxAPI)`
+
+在系统里,把你需要的资源列进参数数组;回调会按同样的顺序收到它:
+
+```typescript
+import { defineSystem, Res, Audio } from 'esengine';
+
+defineSystem([Res(Audio)], (audio) => {
+ audio.playSFX('assets/hit.wav');
+});
+```
+
+每个子系统的命令式 API 都用同一种方式取用:
+
+| 子系统 | 资源 | 导入自 |
+|---|---|---|
+| 输入 | `Res(Input)` | `esengine` |
+| 音频 | `Res(Audio)` | `esengine` |
+| 资源 | `Res(Assets)` | `esengine` |
+| 瓦片地图 | `Res(Tilemaps)` | `esengine` |
+| 粒子 | `Res(Particle)` | `esengine` |
+| 后处理 | `Res(PostProcess)` | `esengine` |
+| 场景 | `Res(SceneManager)` | `esengine` |
+| 补间 | `Res(Tween)` | `esengine` |
+| 动画机 | `Res(AnimatorController)` | `esengine` |
+| 物理 | `Res(PhysicsAPI)` | `esengine/physics` |
+| Spine | `Res(Spine)` | `esengine/spine` |
+
+物理和 Spine 是**可选 side-module**,按需加载,因此它们的 API 放在子路径上以保持基础
+包精简;其余都在主 `esengine` 包里。
+
+## 组件 vs 资源
+
+- **组件**是逐实体的数据。你(在编辑器里或用 `Commands`)把它挂到实体上,用 `Query`
+ 遍历它。
+- **资源**是逐 App 的单例——共享状态与子系统 API——用 `Res` 读取。
+
+## 获取实体
+
+子系统 API 作用于某个实体,而这个实体来自一个 `Query`(或一次 spawn)。这是你在各专题
+里会反复看到的写法:
+
+```typescript
+import { defineSystem, Query, Res, SpriteAnimator, Tween, TweenTarget } from 'esengine';
+
+defineSystem([Query(SpriteAnimator), Res(Tween)], (q, tween) => {
+ for (const [entity] of q) {
+ tween.to(entity, TweenTarget.PositionX, 0, 100, 1.0, {});
+ }
+});
+```
+
+## 生成实体:`Commands`
+
+要在系统里创建实体并挂组件,取一个 `Commands()`:
+
+```typescript
+import { defineSystem, Commands, Transform, Sprite } from 'esengine';
+
+defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(Sprite, { size: { x: 32, y: 32 } });
+});
+```