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: group the sidebar + add Plugins & Resources concept page
yhhbd040c5a594e
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 } });+});+```