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: 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.mdxindex 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 discA 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 eventinterface DamageEvent {@@ -120,13 +120,13 @@ const combatSystem = defineSystem(// 3. Health system — applies damageconst 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.mdxindex 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 entitiesquery.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 FiltersWrap 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.mdxindex 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 andEach 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.mdxindex 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.mdxindex 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 Displaydiff --git a/docs/astro/src/content/docs/guides/ui-widgets.mdx b/docs/astro/src/content/docs/guides/ui-widgets.mdxindex 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.mdxindex 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}` |## FlexItemdiff --git a/docs/astro/src/content/docs/zh/core-concepts/events.mdx b/docs/astro/src/content/docs/zh/core-concepts/events.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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