Skip to content

Commit ff1f2ae

Browse files
esengineesengine
committed
docs: fix code example errors found during cross-page audit
- Fix defineSystem empty params receiving no callback args - Fix registerComponent usage (expects ComponentDef, not raw defaults) - Fix resource insertion to use Commands pattern - Fix query.get(entity) which doesn't exist on QueryInstance - Fix undefined world variable in UI examples - Add missing Mut() wrapper for modified components in sprite/spine - Add missing variable definitions in Commands example
1 parent 37d3e73 commit ff1f2ae

10 files changed

Lines changed: 102 additions & 76 deletions

File tree

‎docs/astro/src/content/docs/core-concepts/systems.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,9 @@ addSystemToSchedule(Schedule.FixedUpdate, physicsSystem);
7171
Create, modify, and destroy entities at runtime:
7272

7373
```typescript
74-
import { Commands, Sprite, LocalTransform } from 'esengine';
74+
import { Commands, Sprite, LocalTransform, Velocity, defineResource } from 'esengine';
75+
76+
const Score = defineResource({ value: 0 });
7577

7678
defineSystem([Commands()], (cmds) => {
7779
// Spawn a new entity with components (chainable)

‎docs/astro/src/content/docs/guides/plugins.mdx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Use `defineSystem()` and `addSystem()` to add game logic that runs every frame:
6565
```typescript
6666
import { defineSystem, addSystem, Schedule } from 'esengine';
6767

68-
addSystem(defineSystem([], (world) => {
68+
addSystem(defineSystem([], () => {
6969
// runs every frame during the Update phase
7070
}));
7171
```
@@ -75,7 +75,7 @@ You can also target a specific schedule phase:
7575
```typescript
7676
import { addSystemToSchedule, defineSystem, Schedule } from 'esengine';
7777

78-
addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], (world) => {
78+
addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], () => {
7979
// runs at fixed timestep, ideal for physics logic
8080
}));
8181
```
@@ -85,7 +85,7 @@ For one-time initialization, use `addStartupSystem()`:
8585
```typescript
8686
import { addStartupSystem, defineSystem } from 'esengine';
8787

88-
addStartupSystem(defineSystem([], (world) => {
88+
addStartupSystem(defineSystem([], () => {
8989
// runs once when the game starts
9090
}));
9191
```
@@ -99,15 +99,15 @@ addStartupSystem(defineSystem([], (world) => {
9999
Resources are global singleton data that can be shared across systems:
100100

101101
```typescript
102-
import { defineResource, addStartupSystem, defineSystem } from 'esengine';
102+
import { defineResource, addStartupSystem, defineSystem, Commands } from 'esengine';
103103

104104
const GameState = defineResource<{ score: number; level: number }>(
105105
{ score: 0, level: 1 },
106106
'GameState'
107107
);
108108

109-
addStartupSystem(defineSystem([], (world) => {
110-
world.app.insertResource(GameState, { score: 0, level: 1 });
109+
addStartupSystem(defineSystem([Commands()], (cmds) => {
110+
cmds.insertResource(GameState, { score: 0, level: 1 });
111111
}));
112112
```
113113

@@ -136,15 +136,15 @@ Systems run in a defined order each frame:
136136
A plugin is an object implementing the `Plugin` interface:
137137

138138
```typescript
139-
import { type Plugin, type App, defineResource, defineSystem, Schedule, registerComponent } from 'esengine';
139+
import { type Plugin, type App, defineResource, defineComponent, defineSystem, Schedule } from 'esengine';
140140

141141
const ScoreData = defineResource<{ value: number }>({ value: 0 }, 'Score');
142+
const Health = defineComponent('Health', { hp: 100, maxHp: 100 });
142143

143144
const myPlugin: Plugin = {
144145
name: 'MyGamePlugin',
145146
build(app: App) {
146147
app.insertResource(ScoreData, { value: 0 });
147-
registerComponent('Health', { hp: 100, maxHp: 100 });
148148
app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
149149
// game logic
150150
}));

‎docs/astro/src/content/docs/guides/spine.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ const CharacterState = defineComponent('CharacterState', {
110110
});
111111

112112
addSystem(defineSystem(
113-
[Res(Input), Res(Time), Query(Mut(LocalTransform), Mut(SpineAnimation), CharacterState)],
113+
[Res(Input), Res(Time), Query(Mut(LocalTransform), Mut(SpineAnimation), Mut(CharacterState))],
114114
(input, time, query) => {
115115
for (const [entity, transform, spine, state] of query) {
116116
let moving = false;

‎docs/astro/src/content/docs/guides/sprite.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ const Animation = defineComponent('Animation', {
102102
});
103103

104104
addSystem(defineSystem(
105-
[Res(Time), Query(Mut(Sprite), Animation)],
105+
[Res(Time), Query(Mut(Sprite), Mut(Animation))],
106106
(time, query) => {
107107
for (const [entity, sprite, anim] of query) {
108108
anim.elapsed += time.delta;

‎docs/astro/src/content/docs/guides/ui.mdx‎

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -161,11 +161,14 @@ import { ScrollList } from './components';
161161
addSystem(defineSystem(
162162
[Res(Input), Query(Children, UIMask, ScrollList), Query(Mut(LocalTransform))],
163163
(input, maskQuery, childQuery) => {
164-
for (const [entity, children, mask, scroll] of maskQuery) {
165-
const scroll = input.getScrollDelta();
166-
for (const child of children.entities) {
167-
const [, transform] = childQuery.get(child);
168-
transform.position.y += scroll.y * 20;
164+
const scrollDelta = input.getScrollDelta();
165+
if (scrollDelta.y === 0) return;
166+
167+
for (const [entity, children] of maskQuery) {
168+
for (const [childEntity, transform] of childQuery) {
169+
if (children.entities.includes(childEntity)) {
170+
transform.position.y += scrollDelta.y * 20;
171+
}
169172
}
170173
}
171174
}
@@ -202,16 +205,18 @@ Adds a state machine on top of `Interactable` with optional color transitions.
202205
When `transition` is set, the `Sprite` color is automatically updated on state change:
203206

204207
```typescript
205-
import { Button, Interactable } from 'esengine';
206-
207-
world.insert(entity, Button, {
208-
state: 0,
209-
transition: {
210-
normalColor: { r: 1, g: 1, b: 1, a: 1 },
211-
hoveredColor: { r: 0.9, g: 0.9, b: 0.9, a: 1 },
212-
pressedColor: { r: 0.7, g: 0.7, b: 0.7, a: 1 },
213-
disabledColor: { r: 0.5, g: 0.5, b: 0.5, a: 0.5 },
214-
},
208+
import { defineSystem, Commands, Button, Interactable } from 'esengine';
209+
210+
defineSystem([Commands()], (cmds) => {
211+
cmds.entity(entity).insert(Button, {
212+
state: 0,
213+
transition: {
214+
normalColor: { r: 1, g: 1, b: 1, a: 1 },
215+
hoveredColor: { r: 0.9, g: 0.9, b: 0.9, a: 1 },
216+
pressedColor: { r: 0.7, g: 0.7, b: 0.7, a: 1 },
217+
disabledColor: { r: 0.5, g: 0.5, b: 0.5, a: 0.5 },
218+
},
219+
});
215220
});
216221
```
217222

@@ -251,16 +256,19 @@ addSystem(defineSystem(
251256
A tag component for root UI entities. Entities with `ScreenSpace`, `UIRect`, and `LocalTransform` are laid out relative to the camera bounds by `UILayoutPlugin`.
252257

253258
```typescript
254-
import { ScreenSpace, UIRect, LocalTransform } from 'esengine';
255-
256-
world.insert(entity, ScreenSpace);
257-
world.insert(entity, UIRect, {
258-
anchorMin: { x: 0, y: 0 },
259-
anchorMax: { x: 1, y: 1 },
260-
offsetMin: { x: 0, y: 0 },
261-
offsetMax: { x: 0, y: 0 },
262-
size: { x: 100, y: 100 },
263-
pivot: { x: 0.5, y: 0.5 },
259+
import { defineSystem, Commands, ScreenSpace, UIRect, LocalTransform } from 'esengine';
260+
261+
defineSystem([Commands()], (cmds) => {
262+
cmds.entity(entity)
263+
.insert(ScreenSpace)
264+
.insert(UIRect, {
265+
anchorMin: { x: 0, y: 0 },
266+
anchorMax: { x: 1, y: 1 },
267+
offsetMin: { x: 0, y: 0 },
268+
offsetMax: { x: 0, y: 0 },
269+
size: { x: 100, y: 100 },
270+
pivot: { x: 0.5, y: 0.5 },
271+
});
264272
});
265273
```
266274

@@ -309,8 +317,11 @@ addSystem(defineSystem(
309317
[Query(TextInput), Res(UIEvents)],
310318
(query, events) => {
311319
for (const e of events.query('submit')) {
312-
const [, input] = query.get(e.entity);
313-
console.log('Submitted:', input.value);
320+
for (const [entity, input] of query) {
321+
if (entity === e.entity) {
322+
console.log('Submitted:', input.value);
323+
}
324+
}
314325
}
315326
}
316327
));

‎docs/astro/src/content/docs/zh/core-concepts/systems.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,9 @@ addSystemToSchedule(Schedule.FixedUpdate, physicsSystem);
7171
在运行时创建、修改和销毁实体：
7272

7373
```typescript
74-
import { Commands, Sprite, LocalTransform } from 'esengine';
74+
import { Commands, Sprite, LocalTransform, Velocity, defineResource } from 'esengine';
75+
76+
const Score = defineResource({ value: 0 });
7577

7678
defineSystem([Commands()], (cmds) => {
7779
// 创建新实体并添加组件（可链式调用）

‎docs/astro/src/content/docs/zh/guides/plugins.mdx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ const Enemy = defineTag('Enemy');
6565
```typescript
6666
import { defineSystem, addSystem, Schedule } from 'esengine';
6767

68-
addSystem(defineSystem([], (world) => {
68+
addSystem(defineSystem([], () => {
6969
// 每帧在 Update 阶段执行
7070
}));
7171
```
@@ -75,7 +75,7 @@ addSystem(defineSystem([], (world) => {
7575
```typescript
7676
import { addSystemToSchedule, defineSystem, Schedule } from 'esengine';
7777

78-
addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], (world) => {
78+
addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], () => {
7979
// 以固定时间步执行，适合物理逻辑
8080
}));
8181
```
@@ -85,7 +85,7 @@ addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], (world) => {
8585
```typescript
8686
import { addStartupSystem, defineSystem } from 'esengine';
8787

88-
addStartupSystem(defineSystem([], (world) => {
88+
addStartupSystem(defineSystem([], () => {
8989
// 游戏启动时执行一次
9090
}));
9191
```
@@ -99,15 +99,15 @@ addStartupSystem(defineSystem([], (world) => {
9999
资源是可在系统间共享的全局单例数据：
100100

101101
```typescript
102-
import { defineResource, addStartupSystem, defineSystem } from 'esengine';
102+
import { defineResource, addStartupSystem, defineSystem, Commands } from 'esengine';
103103

104104
const GameState = defineResource<{ score: number; level: number }>(
105105
{ score: 0, level: 1 },
106106
'GameState'
107107
);
108108

109-
addStartupSystem(defineSystem([], (world) => {
110-
world.app.insertResource(GameState, { score: 0, level: 1 });
109+
addStartupSystem(defineSystem([Commands()], (cmds) => {
110+
cmds.insertResource(GameState, { score: 0, level: 1 });
111111
}));
112112
```
113113

@@ -136,15 +136,15 @@ addStartupSystem(defineSystem([], (world) => {
136136
插件是实现了 `Plugin` 接口的对象：
137137

138138
```typescript
139-
import { type Plugin, type App, defineResource, defineSystem, Schedule, registerComponent } from 'esengine';
139+
import { type Plugin, type App, defineResource, defineComponent, defineSystem, Schedule } from 'esengine';
140140

141141
const ScoreData = defineResource<{ value: number }>({ value: 0 }, 'Score');
142+
const Health = defineComponent('Health', { hp: 100, maxHp: 100 });
142143

143144
const myPlugin: Plugin = {
144145
name: 'MyGamePlugin',
145146
build(app: App) {
146147
app.insertResource(ScoreData, { value: 0 });
147-
registerComponent('Health', { hp: 100, maxHp: 100 });
148148
app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
149149
// 游戏逻辑
150150
}));

‎docs/astro/src/content/docs/zh/guides/spine.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ const CharacterState = defineComponent('CharacterState', {
110110
});
111111

112112
addSystem(defineSystem(
113-
[Res(Input), Res(Time), Query(Mut(LocalTransform), Mut(SpineAnimation), CharacterState)],
113+
[Res(Input), Res(Time), Query(Mut(LocalTransform), Mut(SpineAnimation), Mut(CharacterState))],
114114
(input, time, query) => {
115115
for (const [entity, transform, spine, state] of query) {
116116
let moving = false;

‎docs/astro/src/content/docs/zh/guides/sprite.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ const Animation = defineComponent('Animation', {
102102
});
103103

104104
addSystem(defineSystem(
105-
[Res(Time), Query(Mut(Sprite), Animation)],
105+
[Res(Time), Query(Mut(Sprite), Mut(Animation))],
106106
(time, query) => {
107107
for (const [entity, sprite, anim] of query) {
108108
anim.elapsed += time.delta;

‎docs/astro/src/content/docs/zh/guides/ui.mdx‎

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -161,11 +161,14 @@ import { ScrollList } from './components';
161161
addSystem(defineSystem(
162162
[Res(Input), Query(Children, UIMask, ScrollList), Query(Mut(LocalTransform))],
163163
(input, maskQuery, childQuery) => {
164-
for (const [entity, children, mask, scroll] of maskQuery) {
165-
const scroll = input.getScrollDelta();
166-
for (const child of children.entities) {
167-
const [, transform] = childQuery.get(child);
168-
transform.position.y += scroll.y * 20;
164+
const scrollDelta = input.getScrollDelta();
165+
if (scrollDelta.y === 0) return;
166+
167+
for (const [entity, children] of maskQuery) {
168+
for (const [childEntity, transform] of childQuery) {
169+
if (children.entities.includes(childEntity)) {
170+
transform.position.y += scrollDelta.y * 20;
171+
}
169172
}
170173
}
171174
}
@@ -202,16 +205,18 @@ ESEngine 提供了内置的 UI 交互系统，用于处理 UI 元素的悬停、
202205
设置 `transition` 后，状态变化时 `Sprite` 颜色会自动更新：
203206

204207
```typescript
205-
import { Button, Interactable } from 'esengine';
206-
207-
world.insert(entity, Button, {
208-
state: 0,
209-
transition: {
210-
normalColor: { r: 1, g: 1, b: 1, a: 1 },
211-
hoveredColor: { r: 0.9, g: 0.9, b: 0.9, a: 1 },
212-
pressedColor: { r: 0.7, g: 0.7, b: 0.7, a: 1 },
213-
disabledColor: { r: 0.5, g: 0.5, b: 0.5, a: 0.5 },
214-
},
208+
import { defineSystem, Commands, Button, Interactable } from 'esengine';
209+
210+
defineSystem([Commands()], (cmds) => {
211+
cmds.entity(entity).insert(Button, {
212+
state: 0,
213+
transition: {
214+
normalColor: { r: 1, g: 1, b: 1, a: 1 },
215+
hoveredColor: { r: 0.9, g: 0.9, b: 0.9, a: 1 },
216+
pressedColor: { r: 0.7, g: 0.7, b: 0.7, a: 1 },
217+
disabledColor: { r: 0.5, g: 0.5, b: 0.5, a: 0.5 },
218+
},
219+
});
215220
});
216221
```
217222

@@ -251,16 +256,19 @@ addSystem(defineSystem(
251256
用于根 UI 实体的标签组件。拥有 `ScreenSpace`、`UIRect` 和 `LocalTransform` 的实体会由 `UILayoutPlugin` 相对于相机边界进行布局。
252257

253258
```typescript
254-
import { ScreenSpace, UIRect, LocalTransform } from 'esengine';
255-
256-
world.insert(entity, ScreenSpace);
257-
world.insert(entity, UIRect, {
258-
anchorMin: { x: 0, y: 0 },
259-
anchorMax: { x: 1, y: 1 },
260-
offsetMin: { x: 0, y: 0 },
261-
offsetMax: { x: 0, y: 0 },
262-
size: { x: 100, y: 100 },
263-
pivot: { x: 0.5, y: 0.5 },
259+
import { defineSystem, Commands, ScreenSpace, UIRect, LocalTransform } from 'esengine';
260+
261+
defineSystem([Commands()], (cmds) => {
262+
cmds.entity(entity)
263+
.insert(ScreenSpace)
264+
.insert(UIRect, {
265+
anchorMin: { x: 0, y: 0 },
266+
anchorMax: { x: 1, y: 1 },
267+
offsetMin: { x: 0, y: 0 },
268+
offsetMax: { x: 0, y: 0 },
269+
size: { x: 100, y: 100 },
270+
pivot: { x: 0.5, y: 0.5 },
271+
});
264272
});
265273
```
266274

@@ -309,8 +317,11 @@ addSystem(defineSystem(
309317
[Query(TextInput), Res(UIEvents)],
310318
(query, events) => {
311319
for (const e of events.query('submit')) {
312-
const [, input] = query.get(e.entity);
313-
console.log('提交内容：', input.value);
320+
for (const [entity, input] of query) {
321+
if (entity === e.entity) {
322+
console.log('提交内容：', input.value);
323+
}
324+
}
314325
}
315326
}
316327
));

0 commit comments

Comments
 (0)