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: fix API errors and add missing properties across documentation

esengine3e18f222ec57
diff --git a/docs/astro/src/content/docs/core-concepts/events.mdx b/docs/astro/src/content/docs/core-concepts/events.mdx
index 72206f983..2f27f13bf 100644
--- a/docs/astro/src/content/docs/core-concepts/events.mdx
+++ b/docs/astro/src/content/docs/core-concepts/events.mdx
@@ -95,7 +95,7 @@ Events last exactly **1 frame**. If no system reads them, they are silently disc
A complete example with three decoupled systems:
```typescript
-import { defineEvent, defineSystem, addSystem, EventWriter, EventReader, Query, Mut, Commands, Health, Sprite } from 'esengine';
+import { defineEvent, defineSystem, addSystem, EventWriter, EventReader, GetWorld, Query, Mut, Commands, Health, Sprite } from 'esengine';
// 1. Define the event
interface DamageEvent {
@@ -120,13 +120,13 @@ const combatSystem = defineSystem(
// 3. Health system — applies damage
const healthSystem = defineSystem(
- [EventReader(Damage), Query(Mut(Health))],
- (events, query) => {
+ [EventReader(Damage), GetWorld()],
+ (events, world) => {
for (const { target, amount } of events) {
- const result = query.get(target);
- if (result) {
- const [_, health] = result;
+ const health = world.get(target, Health);
+ if (health) {
health.current -= amount;
+ world.set(target, Health, health);
}
}
}
@@ -134,12 +134,11 @@ const healthSystem = defineSystem(
// 4. VFX system — shows hit effects (reads same events)
const hitVFXSystem = defineSystem(
- [EventReader(Damage), Query(Transform)],
- (events, query) => {
+ [EventReader(Damage), GetWorld()],
+ (events, world) => {
for (const { target } of events) {
- const result = query.get(target);
- if (result) {
- const [_, transform] = result;
+ const transform = world.get(target, Transform);
+ if (transform) {
spawnHitParticle(transform.position);
}
}
diff --git a/docs/astro/src/content/docs/core-concepts/queries.mdx b/docs/astro/src/content/docs/core-concepts/queries.mdx
index f2d08c696..b72715075 100644
--- a/docs/astro/src/content/docs/core-concepts/queries.mdx
+++ b/docs/astro/src/content/docs/core-concepts/queries.mdx
@@ -77,6 +77,40 @@ query.count(); // number of matching entities
query.toArray(); // collect all results into an array
```
+## Query Filters
+
+Use `.with()` and `.without()` to filter entities by the presence or absence of components, without including them in the result tuple:
+
+```typescript
+import { Query, Transform, Sprite, Hidden } from 'esengine';
+
+// Match entities with Transform AND Sprite, but only those that also have Player
+defineSystem(
+ [Query(Mut(Transform), Sprite).with(Player)],
+ (query) => {
+ for (const [entity, transform, sprite] of query) {
+ // Player is guaranteed to be present, but not in the tuple
+ }
+ }
+);
+
+// Match entities with Transform, excluding any with Hidden
+defineSystem(
+ [Query(Transform).without(Hidden)],
+ (query) => {
+ for (const [entity, transform] of query) {
+ // Only entities that do NOT have Hidden
+ }
+ }
+);
+```
+
+You can chain multiple `.with()` and `.without()` calls:
+
+```typescript
+Query(Mut(Transform), Sprite).with(Player).without(Hidden, Disabled)
+```
+
## Change Detection Filters
Wrap components in `Added()`, `Changed()`, or use `Removed()` to react to component lifecycle events.
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdx
index 216fe6beb..302743f82 100644
--- a/docs/astro/src/content/docs/guides/physics.mdx
+++ b/docs/astro/src/content/docs/guides/physics.mdx
@@ -52,9 +52,9 @@ Every physics entity needs a `RigidBody` component. It defines the body type and
Each entity also needs a collider shape. Choose one:
-- **BoxCollider** — `halfExtents` (Vec2), `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`
-- **CircleCollider** — `radius`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`
-- **CapsuleCollider** — `radius`, `halfHeight`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`
+- **BoxCollider** — `halfExtents` (Vec2), `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`
+- **CircleCollider** — `radius`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`
+- **CapsuleCollider** — `radius`, `halfHeight`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`
See [Components](/microes/core-concepts/components/#physics) for the full property tables.
diff --git a/docs/astro/src/content/docs/guides/prefabs.mdx b/docs/astro/src/content/docs/guides/prefabs.mdx
index 3d7c41de3..5af099f03 100644
--- a/docs/astro/src/content/docs/guides/prefabs.mdx
+++ b/docs/astro/src/content/docs/guides/prefabs.mdx
@@ -111,9 +111,21 @@ import { instantiatePrefab } from 'esengine';
const result = await instantiatePrefab(world, prefab, {
assetServer: assets,
+ assetBaseUrl: 'https://cdn.example.com/game',
+ parent: parentEntity,
+ overrides: [
+ { prefabEntityId: 1, type: 'property', componentType: 'Transform', propertyName: 'position', value: { x: 100, y: 50, z: 0 } },
+ ],
});
```
+| Option | Type | Description |
+|--------|------|-------------|
+| `assetServer` | AssetServer | Asset server for loading referenced assets |
+| `assetBaseUrl` | string | Base URL for resolving asset paths |
+| `parent` | Entity | Parent entity to attach the prefab root to |
+| `overrides` | PrefabOverride[] | Property overrides applied during instantiation |
+
<Aside type="caution">
Circular prefab references are automatically detected and skipped with an error log, preventing infinite recursion.
</Aside>
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdx
index ef5ab254d..64c809d5f 100644
--- a/docs/astro/src/content/docs/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/guides/ui-text.mdx
@@ -56,6 +56,9 @@ Displays images with support for slicing, tiling, and fill modes.
| `fillOrigin` | FillOrigin | `Left` | `Left` (0), `Right` (1), `Bottom` (2), `Top` (3) |
| `fillAmount` | number | `1` | Fill progress 0–1 |
| `preserveAspect` | boolean | `false` | Maintain aspect ratio |
+| `tileSize` | Vec2 | `{x:32, y:32}` | Tile size in pixels (used when `imageType` is `Tiled`) |
+| `layer` | number | `0` | Render layer |
+| `material` | number | `0` | Custom material handle (0 = default) |
| `enabled` | boolean | `true` | Visibility toggle |
## Example: Score Display
diff --git a/docs/astro/src/content/docs/guides/ui-widgets.mdx b/docs/astro/src/content/docs/guides/ui-widgets.mdx
index 337c910d7..140f4f7ea 100644
--- a/docs/astro/src/content/docs/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/guides/ui-widgets.mdx
@@ -295,6 +295,9 @@ Editable text field with cursor, selection, and placeholder.
| `multiline` | boolean | `false` | Allow line breaks |
| `password` | boolean | `false` | Mask text |
| `readOnly` | boolean | `false` | Prevent editing |
+| `focused` | boolean | `false` | Whether the input currently has focus |
+| `cursorPos` | number | `0` | Current cursor position in the text |
+| `dirty` | boolean | `true` | Whether the input needs re-rendering |
**Events:** `change` (value changed), `submit` (Enter pressed in single-line mode)
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/guides/ui.mdx
index 73855bef4..57559284d 100644
--- a/docs/astro/src/content/docs/guides/ui.mdx
+++ b/docs/astro/src/content/docs/guides/ui.mdx
@@ -61,7 +61,7 @@ CSS Flexbox-like layout for automatic child arrangement.
| `justifyContent` | JustifyContent | `Start` | `Start`, `Center`, `End`, `SpaceBetween`, `SpaceAround`, `SpaceEvenly` |
| `alignItems` | AlignItems | `Stretch` | `Start`, `Center`, `End`, `Stretch` |
| `gap` | Vec2 | `{0, 0}` | Spacing between items |
-| `padding` | Vec4 | `{0, 0, 0, 0}` | Top, Right, Bottom, Left padding |
+| `padding` | Vec4 | `{x:0, y:0, z:0, w:0}` | Padding as `{x: top, y: right, z: bottom, w: left}` |
## FlexItem
diff --git a/docs/astro/src/content/docs/zh/core-concepts/events.mdx b/docs/astro/src/content/docs/zh/core-concepts/events.mdx
index 2f565e9e3..874fd59c4 100644
--- a/docs/astro/src/content/docs/zh/core-concepts/events.mdx
+++ b/docs/astro/src/content/docs/zh/core-concepts/events.mdx
@@ -95,7 +95,7 @@ events.toArray() // 将所有事件收集为数组
一个完整的示例,包含三个解耦的系统:
```typescript
-import { defineEvent, defineSystem, addSystem, EventWriter, EventReader, Query, Mut, Commands, Health, Sprite } from 'esengine';
+import { defineEvent, defineSystem, addSystem, EventWriter, EventReader, GetWorld, Query, Mut, Commands, Health, Sprite } from 'esengine';
// 1. 定义事件
interface DamageEvent {
@@ -120,13 +120,13 @@ const combatSystem = defineSystem(
// 3. 生命系统——应用伤害
const healthSystem = defineSystem(
- [EventReader(Damage), Query(Mut(Health))],
- (events, query) => {
+ [EventReader(Damage), GetWorld()],
+ (events, world) => {
for (const { target, amount } of events) {
- const result = query.get(target);
- if (result) {
- const [_, health] = result;
+ const health = world.get(target, Health);
+ if (health) {
health.current -= amount;
+ world.set(target, Health, health);
}
}
}
@@ -134,12 +134,11 @@ const healthSystem = defineSystem(
// 4. 特效系统——显示命中效果(读取相同事件)
const hitVFXSystem = defineSystem(
- [EventReader(Damage), Query(Transform)],
- (events, query) => {
+ [EventReader(Damage), GetWorld()],
+ (events, world) => {
for (const { target } of events) {
- const result = query.get(target);
- if (result) {
- const [_, transform] = result;
+ const transform = world.get(target, Transform);
+ if (transform) {
spawnHitParticle(transform.position);
}
}
diff --git a/docs/astro/src/content/docs/zh/core-concepts/queries.mdx b/docs/astro/src/content/docs/zh/core-concepts/queries.mdx
index e89eda90c..76a23b6fb 100644
--- a/docs/astro/src/content/docs/zh/core-concepts/queries.mdx
+++ b/docs/astro/src/content/docs/zh/core-concepts/queries.mdx
@@ -77,6 +77,40 @@ query.count(); // 匹配的实体数量
query.toArray(); // 将所有结果收集到数组中
```
+## 查询过滤器
+
+使用 `.with()` 和 `.without()` 按组件的有无过滤实体,且不将这些组件包含在结果元组中:
+
+```typescript
+import { Query, Transform, Sprite, Hidden } from 'esengine';
+
+// 匹配有 Transform 和 Sprite 的实体,但只要同时有 Player 的
+defineSystem(
+ [Query(Mut(Transform), Sprite).with(Player)],
+ (query) => {
+ for (const [entity, transform, sprite] of query) {
+ // 保证有 Player,但不在元组中
+ }
+ }
+);
+
+// 匹配有 Transform 的实体,排除有 Hidden 的
+defineSystem(
+ [Query(Transform).without(Hidden)],
+ (query) => {
+ for (const [entity, transform] of query) {
+ // 只有没有 Hidden 组件的实体
+ }
+ }
+);
+```
+
+可以链式调用多个 `.with()` 和 `.without()`:
+
+```typescript
+Query(Mut(Transform), Sprite).with(Player).without(Hidden, Disabled)
+```
+
## 变更检测过滤器
用 `Added()`、`Changed()` 包裹组件,或使用 `Removed()` 来响应组件的生命周期事件。
diff --git a/docs/astro/src/content/docs/zh/guides/physics.mdx b/docs/astro/src/content/docs/zh/guides/physics.mdx
index bb2dbdf6f..6d1f7554d 100644
--- a/docs/astro/src/content/docs/zh/guides/physics.mdx
+++ b/docs/astro/src/content/docs/zh/guides/physics.mdx
@@ -52,9 +52,9 @@ import { Aside } from '@astrojs/starlight/components';
每个实体还需要一个碰撞体形状,选择其一:
-- **BoxCollider** — `halfExtents`(Vec2)、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`
-- **CircleCollider** — `radius`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`
-- **CapsuleCollider** — `radius`、`halfHeight`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`
+- **BoxCollider** — `halfExtents`(Vec2)、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`
+- **CircleCollider** — `radius`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`
+- **CapsuleCollider** — `radius`、`halfHeight`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`
详见[组件](/microes/zh/core-concepts/components/#物理)完整属性表。
diff --git a/docs/astro/src/content/docs/zh/guides/prefabs.mdx b/docs/astro/src/content/docs/zh/guides/prefabs.mdx
index 87259cc49..743729943 100644
--- a/docs/astro/src/content/docs/zh/guides/prefabs.mdx
+++ b/docs/astro/src/content/docs/zh/guides/prefabs.mdx
@@ -111,9 +111,21 @@ import { instantiatePrefab } from 'esengine';
const result = await instantiatePrefab(world, prefab, {
assetServer: assets,
+ assetBaseUrl: 'https://cdn.example.com/game',
+ parent: parentEntity,
+ overrides: [
+ { prefabEntityId: 1, type: 'property', componentType: 'Transform', propertyName: 'position', value: { x: 100, y: 50, z: 0 } },
+ ],
});
```
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `assetServer` | AssetServer | 用于加载引用资源的资源服务器 |
+| `assetBaseUrl` | string | 解析资源路径的基础 URL |
+| `parent` | Entity | 预制体根实体要挂载到的父实体 |
+| `overrides` | PrefabOverride[] | 实例化时应用的属性覆盖 |
+
<Aside type="caution">
循环预制体引用会被自动检测并跳过,同时输出错误日志,防止无限递归。
</Aside>
diff --git a/docs/astro/src/content/docs/zh/guides/ui-text.mdx b/docs/astro/src/content/docs/zh/guides/ui-text.mdx
index 9d4c1e9a7..b46692237 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-text.mdx
@@ -56,6 +56,9 @@ addSystem(defineSystem(
| `fillOrigin` | FillOrigin | `Left` | `Left` (0)、`Right` (1)、`Bottom` (2)、`Top` (3) |
| `fillAmount` | number | `1` | 填充进度 0–1 |
| `preserveAspect` | boolean | `false` | 保持宽高比 |
+| `tileSize` | Vec2 | `{x:32, y:32}` | 平铺尺寸(`imageType` 为 `Tiled` 时使用) |
+| `layer` | number | `0` | 渲染层级 |
+| `material` | number | `0` | 自定义材质句柄(0 = 默认) |
| `enabled` | boolean | `true` | 可见性开关 |
## 示例:分数显示
diff --git a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
index db4dd82a2..71fc18d82 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
@@ -295,6 +295,9 @@ addSystem(defineSystem(
| `multiline` | boolean | `false` | 允许换行 |
| `password` | boolean | `false` | 密码遮罩 |
| `readOnly` | boolean | `false` | 禁止编辑 |
+| `focused` | boolean | `false` | 当前是否获得焦点 |
+| `cursorPos` | number | `0` | 文本中的当前光标位置 |
+| `dirty` | boolean | `true` | 是否需要重新渲染 |
**事件:** `change`(值变化)、`submit`(单行模式下按 Enter)
diff --git a/docs/astro/src/content/docs/zh/guides/ui.mdx b/docs/astro/src/content/docs/zh/guides/ui.mdx
index b9355029c..cd6e10671 100644
--- a/docs/astro/src/content/docs/zh/guides/ui.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui.mdx
@@ -61,7 +61,7 @@ addStartupSystem(defineSystem([Commands()], (cmds) => {
| `justifyContent` | JustifyContent | `Start` | `Start`、`Center`、`End`、`SpaceBetween`、`SpaceAround`、`SpaceEvenly` |
| `alignItems` | AlignItems | `Stretch` | `Start`、`Center`、`End`、`Stretch` |
| `gap` | Vec2 | `{0, 0}` | 子元素间距 |
-| `padding` | Vec4 | `{0, 0, 0, 0}` | 上、右、下、左内边距 |
+| `padding` | Vec4 | `{x:0, y:0, z:0, w:0}` | 内边距,格式为 `{x: 上, y: 右, z: 下, w: 左}` |
## FlexItem