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(guides): fix correctness bugs surfaced by a full audit (en + zh-cn)

yhh16335f5a1e5d
diff --git a/docs/astro/src/content/docs/core-concepts/ecs.mdx b/docs/astro/src/content/docs/core-concepts/ecs.mdx
index 0dcdf34cf..20ef3f30b 100644
--- a/docs/astro/src/content/docs/core-concepts/ecs.mdx
+++ b/docs/astro/src/content/docs/core-concepts/ecs.mdx
@@ -35,7 +35,7 @@ You compose a game from three SDK primitives:
```typescript
import { App } from 'esengine';
-const app = new App();
+const app = App.new();
// register components, systems, and plugins on the app…
app.run();
```
diff --git a/docs/astro/src/content/docs/core-concepts/systems.mdx b/docs/astro/src/content/docs/core-concepts/systems.mdx
index 79c249fc2..a38595f3a 100644
--- a/docs/astro/src/content/docs/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/core-concepts/systems.mdx
@@ -39,9 +39,10 @@ in order:
- **`Res(Resource)`** — a shared resource, such as `Time` for frame timing.
<Aside type="caution">
- Only wrap a component in `Mut` when you actually write it. Read-only queries
- let the engine skip needless change-detection and let more systems run in
- parallel.
+ Only wrap a component in `Mut` when you actually write it — read-only queries
+ let the engine skip needless change-detection. (Systems run sequentially in
+ schedule order; marking reads correctly is about change-tracking, not
+ parallelism.)
</Aside>
## Running order
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
index 137717c5e..d647731ac 100644
--- a/docs/astro/src/content/docs/guides/audio.mdx
+++ b/docs/astro/src/content/docs/guides/audio.mdx
@@ -127,8 +127,9 @@ audio.muteBus('music', true);
```
Route a sound to a bus with the `AudioSource.bus` field, or leave `playSFX`
-defaulting to `sfx`. Use `master` for a global volume slider, and separate `music`
-/ `sfx` / `ui` / `voice` sliders in your options menu.
+defaulting to `sfx`. Volume setters exist for `setMasterVolume` (a global slider)
+and `setMusicVolume` / `setSFXVolume` / `setUIVolume`. The `voice` bus routes sounds
+but has no volume setter — toggle it with `muteBus('voice', …)`.
## Spatial audio
diff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/guides/lighting.mdx
index d3538018d..932e8ffdf 100644
--- a/docs/astro/src/content/docs/guides/lighting.mdx
+++ b/docs/astro/src/content/docs/guides/lighting.mdx
@@ -134,8 +134,8 @@ You can also build a lit material visually — set the **Material Graph**'s doma
<Aside type="tip">
Every renderer that takes a `material` — `Sprite`, `SpineAnimation`,
- `ParticleEmitter`, and tilemap layers — can be lit the same way: give it a Lit-2D
- material.
+ `ParticleEmitter`, `Mesh2D`, and `UIVisual` — can be lit the same way: give it a
+ Lit-2D material. (`Sprite` also has the one-flag `lit` toggle for the common case.)
</Aside>
### Normal maps
diff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/guides/localization.mdx
index 524b0b7e6..fd6a7d496 100644
--- a/docs/astro/src/content/docs/guides/localization.mdx
+++ b/docs/astro/src/content/docs/guides/localization.mdx
@@ -9,6 +9,21 @@ Register a translation catalog per locale, switch the active locale, and look up
strings with `t()` — all through the `Localization` resource. It's deliberately
`Intl`-free so behavior is identical on the web and WeChat.
+`Localization` is **opt-in** — install its plugin once before any system reads
+`Res(Localization)`:
+
+```typescript
+import { App, localizationPlugin, LocalizationPlugin } from 'esengine';
+
+app.addPlugin(localizationPlugin);
+// …or preload catalogs + set the initial/fallback locale up front:
+app.addPlugin(new LocalizationPlugin({
+ locale: 'en',
+ fallback: 'en',
+ catalogs: { en: { play: 'Play' }, 'zh-CN': { play: '开始' } },
+}));
+```
+
## Catalogs & translation
```typescript
@@ -30,9 +45,12 @@ const setupI18n = defineSystem([Res(Localization)], (i18n) => {
## Plurals
-A catalog entry can carry plural forms (`zero` / `one` / `other`); `t` selects the
-right one from a `count` param. Register a per-locale selector for languages whose
-rules differ from the default English-style one.
+A catalog entry can carry plural forms — the CLDR set `zero` / `one` / `two` / `few`
+/ `many` / `other`; `t` selects one from a `count` param (and a `zero` form always
+wins when `count === 0`). The default selector is English-style (`one`/`other`); for
+Slavic/Arabic/etc. rules register a per-locale selector with
+`setPluralSelector(locale, (count) => category)`, returning one of those six
+categories.
```typescript
i18n.addCatalog('en', { apples: { one: '{count} apple', other: '{count} apples' } });
diff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/guides/material.mdx
index ff25fe86a..a9a0a19fd 100644
--- a/docs/astro/src/content/docs/guides/material.mdx
+++ b/docs/astro/src/content/docs/guides/material.mdx
@@ -6,7 +6,7 @@ description: The complete guide to custom materials — authoring GLSL with refl
import { Aside } from '@astrojs/starlight/components';
A material is a **shader plus parameters**. Renderers that support materials —
-`Sprite`, `SpineAnimation`, `ParticleEmitter`, and tilemap layers — expose a
+`Sprite`, `SpineAnimation`, `ParticleEmitter`, `Mesh2D`, and `UIVisual` — expose a
`material` handle field; set it to draw with your own shader instead of the default.
## How it works
@@ -158,8 +158,9 @@ const v = Material.getUniform(tintMat, 'u_intensity');
<Aside type="note">
For raw shaders without reflected params, use `Material.createShader(vertexSrc,
- fragmentSrc)` instead of `compileShader`. `ShapeRenderer` has no `material` field —
- only `Sprite`, `SpineAnimation`, `ParticleEmitter`, and tilemap layers do.
+ fragmentSrc)` instead of `compileShader`. `ShapeRenderer` and `TilemapLayer` have no
+ `material` field — only `Sprite`, `SpineAnimation`, `ParticleEmitter`, `Mesh2D`, and
+ `UIVisual` do.
</Aside>
## See also
diff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/guides/networking.mdx
index dd4140df2..dff883c89 100644
--- a/docs/astro/src/content/docs/guides/networking.mdx
+++ b/docs/astro/src/content/docs/guides/networking.mdx
@@ -75,7 +75,7 @@ with snapshot interpolation. One declaration drives the wire format — no
hand-written sync code.
```typescript
-import { defineComponent, Net, Replicated, Transform } from 'esengine';
+import { defineComponent, Net, Replicated, Transform, createMemoryTransportPair } from 'esengine';
// Which fields replicate is declared on the component (builtins like
// Transform annotate `replicated` in C++; user components declare it here).
@@ -83,23 +83,24 @@ const Health = defineComponent('Health', { hp: 100, regen: 1 }, {
replicatedFields: ['hp'],
});
-// SERVER (the authority): spawn a replicated entity, owned by a connection.
-const net = app.getResource(Net);
-const server = net.startServer();
-// accept connections however your host likes:
-server.attachConnection(transport); // any NetTransport works
-
-const e = app.world.spawn('player');
-app.world.insert(e, Transform, { position: { x: 0, y: 0, z: 0 } });
-app.world.insert(e, Health, {});
-app.world.insert(e, Replicated, { owner: connectionId });
-
-// CLIENT: connect and everything arrives — ghosts spawn, state streams.
-await app.getResource(Net).connect(transport);
-net.client?.sendInput({ move: { x: 1, y: 0 } }); // per-tick input uplink
-
-// SERVER gameplay reads each connection's latest input:
-const input = server.inputOf(connectionId);
+// A transport carries frames between two ends. In-process (tests / a listen
+// server) use a memory pair; a real net puts a GameSocket on each side.
+const [serverEnd, clientEnd] = createMemoryTransportPair();
+
+// --- SERVER app (the authority) ---
+const server = serverApp.getResource(Net).startServer();
+const connectionId = server.attachConnection(serverEnd); // returns the connection id
+const e = serverApp.world.spawn('player');
+serverApp.world.insert(e, Transform, { position: { x: 0, y: 0, z: 0 } });
+serverApp.world.insert(e, Health, {});
+serverApp.world.insert(e, Replicated, { owner: connectionId }); // owned by that client
+const input = server.inputOf(connectionId); // that client's latest input
+// server.clientIds — poll each tick to spawn/retire a pawn per connected player.
+
+// --- CLIENT app ---
+const clientNet = clientApp.getResource(Net);
+await clientNet.connect(clientEnd, { interpolationDelayTicks: 2 }); // 2 = smoothing lag
+clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // per-tick input uplink
```
- **Authority**: only the server simulates; clients see replicated, interpolated
@@ -121,8 +122,9 @@ See the **Multiplayer Arena** example for the full pattern in ~100 lines.
- **Set an RPC timeout** so a lost reply rejects instead of hanging forever.
- **Push received state into components** via `Commands` so gameplay stays in ECS.
- **Queue-before-open is automatic** — you can `send` right after `connect()`.
-- **Gate authority in systems** — check `Net.role` so the same code runs as
- server, client, or offline single-player.
+- **Gate authority in systems** — check `app.getResource(Net).role` (`'server'` /
+ `'client'` / `'offline'`) so the same code runs as server, client, or offline
+ single-player.
<Aside type="note">
The transport is plain classes (create the socket/channel wherever it fits);
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
index 0b151882f..b4151bf91 100644
--- a/docs/astro/src/content/docs/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -14,20 +14,24 @@ several can stack in one frame at no extra target cost beyond the passes.
| Effect | What it does | Key uniforms |
|---|---|---|
-| `bloom` | Glow on bright areas | `threshold`, `intensity` |
+| `bloom` | Glow on bright areas | `threshold`, `intensity`, `radius` |
| `tonemap` | ACES filmic tonemapping | `exposure` |
| `colorGrade` | Exposure / contrast / saturation / white balance | `exposure`, `contrast`, `saturation`, `temperature`, `tint` |
| `lutGrade` | Color grading through a lookup-table texture | `u_lut` (texture), `intensity` |
-| `vignette` | Darkened screen edges | `intensity`, `radius` |
+| `vignette` | Darkened screen edges | `intensity`, `softness` |
| `chromaticAberration` | RGB fringing | `intensity` |
-| `blur` | Gaussian blur | `radius` |
+| `blur` | Gaussian blur | `intensity` |
| `fxaa` | Fast anti-aliasing | `intensity` |
| `lensDistortion` | Barrel / pincushion warp | `strength`, `zoom` |
| `pixelate` | Block quantization | `pixelSize` |
-| `grayscale` | Desaturate | — |
+| `grayscale` | Desaturate | `intensity` |
-Every effect is a no-op at its default values, so adding one to a stack doesn't
-change the image until you dial it in.
+The uniform names above are the friendly labels; **in code they are `u_`-prefixed**
+(`u_intensity`, `u_exposure`, …). Most effects are identity at their defaults
+(`colorGrade`, `blur`, `chromaticAberration`, `fxaa`, `lensDistortion`, `lutGrade`),
+so adding them changes nothing until you dial them in. A few are visible the moment
+you add them — `grayscale` (full desaturation), `vignette`, `bloom`, and `tonemap`
+(the ACES curve always applies) — so enable those only when you want them.
## Using a `PostProcessVolume`
@@ -47,49 +51,60 @@ volume) or fade them in over a transition.
## Programmatic control
-For a custom pipeline, read the `PostProcess` resource — create a stack, tune it,
-and bind it to a camera:
+For a fixed camera pipeline in code, use the `PostProcess` resource. A stack starts
+empty — add one **pass** per effect. Get the effect's shader from the registry with
+`getEffectDef(type).factory()`, then set its `u_`-prefixed uniforms and bind the
+stack to a camera:
```typescript
-import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
+import { defineSystem, Query, Res, Camera, PostProcess, getEffectDef } from 'esengine';
const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
+ const grade = getEffectDef('colorGrade')!;
for (const [camera] of q) {
const stack = pp.createStack();
- stack.setEnabled('bloom', true)
- .setUniform('bloom', 'intensity', 1.2)
- .setUniform('bloom', 'threshold', 0.8);
+ stack.addPass('colorGrade', grade.factory())
+ .setUniform('colorGrade', 'u_saturation', 1.3)
+ .setUniform('colorGrade', 'u_contrast', 1.1);
pp.bind(camera, stack); // pp.unbind(camera) to remove
}
});
```
+A **multi-pass** effect like `bloom` exposes `def.multiPass`; add each sub-pass
+(`for (const p of grade.multiPass!) stack.addPass(p.name, p.factory())`). For
+anything beyond a fixed pipeline, a `PostProcessVolume` is simpler — it resolves
+multi-pass and texture params for you.
+
| Method | Description |
|---|---|
-| `PostProcess.createStack()` | Create an effect stack. |
-| `PostProcess.bind(camera, stack)` | Attach a stack to a camera. |
-| `PostProcess.unbind(camera)` | Remove the camera's stack. |
-| `stack.setEnabled(name, on)` | Enable/disable an effect (chainable). |
-| `stack.setUniform(pass, uniform, value)` | Set an effect parameter (chainable). |
+| `PostProcess.createStack()` | Create an empty effect stack. |
+| `stack.addPass(name, shader)` | Add an effect pass; `shader` from `getEffectDef(type).factory()` (chainable). |
+| `stack.setUniform(pass, uniform, value)` | Set a `u_`-prefixed parameter (chainable). |
| `stack.setTexture(pass, uniform, handle)` | Bind a texture parameter, e.g. a LUT (chainable). |
+| `stack.setEnabled(name, on)` | Toggle an already-added pass (chainable). |
+| `PostProcess.bind(camera, stack)` / `unbind(camera)` | Attach / remove a camera's stack. |
+| `getEffectDef(type)` / `getAllEffectDefs()` / `getEffectTypes()` | Look up effect definitions (shader factory + uniforms). |
### Texture parameters (LUTs & masks)
Some effects take a texture, not just scalars. `lutGrade` samples a **color
lookup table** — a 2D-packed `1024×32` PNG (32 slices of a 32³ cube) — so you can
-author a whole grade in an image editor and drop it in. Bind it with `setTexture`
-(or, on a `PostProcessVolume`, list it under the effect's `textures: { u_lut: <ref> }`):
+author a whole grade in an image editor and drop it in. Add the pass, then bind the
+texture with `setTexture` (or, on a `PostProcessVolume`, list it under the effect's
+`textures: { u_lut: <ref> }`):
```typescript
-stack.setEnabled('lutGrade', true)
+stack.addPass('lutGrade', getEffectDef('lutGrade')!.factory())
.setTexture('lutGrade', 'u_lut', lutHandle)
.setUniform('lutGrade', 'u_intensity', 1);
```
## Best practices
-- **Order matters** — effects run in registration order and share the buffers, so
- a sensible chain is bloom → tonemap → color grade → vignette.
+- **Order matters** — passes run in the order you add them (or, on a volume, the
+ order of its `effects[]`) and share the buffers, so a sensible chain is
+ bloom → tonemap → color grade → vignette.
- **Use volumes for locality** (an area's mood) and the `PostProcess` API for a
fixed camera pipeline.
- **Fade with `weight`** on a volume for smooth transitions instead of toggling.
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdx
index 3df4194c2..3aa122f0e 100644
--- a/docs/astro/src/content/docs/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/guides/prefab.mdx
@@ -39,17 +39,23 @@ const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab',
## Per-instance overrides
-Pass `overrides` to change component values for **this instance only** without
-editing the prefab asset — spawn the same enemy with different health or tint:
+Pass `overrides` to change a value for **this instance only** without editing the
+prefab asset — spawn the same enemy with different health or tint. Each override
+targets a prefab entity by its **string** `prefabEntityId` (a UUID for
+editor-authored prefabs) and names the component + property:
```typescript
const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {
overrides: [
- { entity: 0, component: 'Health', field: 'value', value: 250 },
+ { prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
});
```
+Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'`,
+`'component_replaced'`, `'component_removed'`, `'metadata_set'`, or `'metadata_removed'`
+(the metadata forms use `metadataKey` in place of `componentType`/`propertyName`).
+
## `instantiate` reference
| Option | Type | Description |
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/guides/spine.mdx
index ad42263e3..f8b881786 100644
--- a/docs/astro/src/content/docs/guides/spine.mdx
+++ b/docs/astro/src/content/docs/guides/spine.mdx
@@ -42,7 +42,6 @@ import { Spine } from 'esengine/spine';
const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {
for (const [entity] of q) {
spine.setAnimation(entity, 'run', true); // play on track 0, looped
- spine.addAnimation(entity, 'jump', false, 0.5); // queue after 0.5s
spine.setDefaultMix(entity, 0.15); // default crossfade
spine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transition
spine.setTrackAlpha(entity, 0, 1.0); // blend a track in/out
@@ -53,25 +52,28 @@ const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) =>
| Method | Description |
|---|---|
| `setAnimation(entity, name, loop)` | Play an animation on track 0. |
-| `addAnimation(entity, name, loop, delay)` | Queue an animation after the current one. |
| `setDefaultMix(entity, seconds)` | Default crossfade between any two animations. |
| `setMixDuration(entity, from, to, seconds)` | Crossfade for a specific transition. |
| `setTrackAlpha(entity, track, alpha)` | Blend a track's contribution (0..1). |
-| `setEntityProps(entity, props)` | Update scale / flip / color / time scale at once. |
+| `setEntityProps(entity, props)` | Set `{ skeletonScale?, flipX?, flipY?, layer? }` at once. |
+| `setIKTarget(entity, constraint, x, y, mix)` | Aim an IK constraint at a world point (`mix` 0..1). |
+
+Transform / path constraint mixes are adjustable too — `listConstraints(entity)`,
+`getTransformConstraintMix` / `setTransformConstraintMix`, and the `path` equivalents.
## Skins & attachments
```typescript
spine.setSkin(entity, 'armored');
spine.setAttachment(entity, 'weapon-slot', 'sword'); // swap a slot's attachment
-spine.setSlotColor(entity, 'body', { r: 1, g: 0.5, b: 0.5, a: 1 });
+spine.setSlotColor(entity, 'body', 1, 0.5, 0.5, 1); // r, g, b, a (0..1)
```
| Method | Description |
|---|---|
| `setSkin(entity, name)` | Switch the active skin. |
| `setAttachment(entity, slot, attachment)` | Swap a slot's attachment (equip/variant). |
-| `setSlotColor(entity, slot, color)` | Tint an individual slot. |
+| `setSlotColor(entity, slot, r, g, b, a)` | Tint an individual slot (four 0..1 channels). |
## Query a skeleton
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
index a8bdcbeaf..990d62698 100644
--- a/docs/astro/src/content/docs/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -34,7 +34,7 @@ const attach = defineSystem([Commands()], (cmds) => {
| `timeline` | asset | `''` | The timeline asset (`.estimeline`). |
| `playing` | boolean | `false` | Whether it starts playing on attach. |
| `speed` | number | `1` | Playback rate multiplier. |
-| `wrapMode` | string | `'once'` | `'once'`, `'loop'`, or `'pingpong'`. |
+| `wrapMode` | string | `'once'` | `'once'`, `'loop'`, or `'pingPong'` (camelCase — other values silently play once). |
## Control playback
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx
index 7fd63e5da..79cef4f3d 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx
@@ -31,7 +31,7 @@ C++/WebAssembly 内核中,SDK 通过一份生成并经哈希校验的内存布
```typescript
import { App } from 'esengine';
-const app = new App();
+const app = App.new();
// 在 app 上注册组件、系统与插件……
app.run();
```
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
index 189d75ab4..0a5c4b81c 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/systems.mdx
@@ -36,8 +36,8 @@ addSystem(defineSystem(
- **`Res(Resource)`** —— 一个共享资源,例如提供帧计时的 `Time`。
<Aside type="caution">
- 只有当你确实要写入某个组件时才把它包进 `Mut`。只读查询让引擎可以跳过多余的变更
- 检测,也让更多系统能并行运行。
+ 只有当你确实要写入某个组件时才把它包进 `Mut`——只读查询让引擎可以跳过多余的变更
+ 检测。(系统按调度顺序**串行**运行;正确标注只读是为了变更追踪,不是为了并行。)
</Aside>
## 运行顺序
diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
index a08fcdb96..dc0d84139 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
@@ -120,8 +120,9 @@ audio.setUIVolume(0.9);
audio.muteBus('music', true);
```
-用 `AudioSource.bus` 字段把声音路由到某个总线,或让 `playSFX` 默认走 `sfx`。用 `master` 做
-全局音量滑条,在选项菜单里分开做 `music` / `sfx` / `ui` / `voice` 的滑条。
+用 `AudioSource.bus` 字段把声音路由到某个总线,或让 `playSFX` 默认走 `sfx`。音量设置器有
+`setMasterVolume`(全局滑条)和 `setMusicVolume` / `setSFXVolume` / `setUIVolume`。`voice`
+总线能路由声音但没有音量设置器——用 `muteBus('voice', …)` 开关它。
## 空间音频
diff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
index 3991c1f51..4cb070c76 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
@@ -130,8 +130,9 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {
[材质图](/docs/zh-cn/guides/material/)一节。
<Aside type="tip">
- 每个接受 `material` 的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter` 和瓦片图层——
- 都能用同样方式受光:给它一个 Lit-2D 材质。
+ 每个接受 `material` 的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter`、`Mesh2D`
+ 和 `UIVisual`——都能用同样方式受光:给它一个 Lit-2D 材质。(`Sprite` 常见场景还可用一键
+ `lit` 开关。)
</Aside>
### 法线贴图
diff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
index 36c46b701..ed7e80f09 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/localization.mdx
@@ -8,6 +8,20 @@ import { Aside } from '@astrojs/starlight/components';
为每个 locale 注册一份翻译目录(catalog),切换当前 locale,并用 `t()` 查字符串——都通过
`Localization` 资源完成。它刻意不依赖 `Intl`,所以在 Web 与微信上行为一致。
+`Localization` 是**可选(opt-in)**的——在任何系统读 `Res(Localization)` 之前先装一次它的插件:
+
+```typescript
+import { App, localizationPlugin, LocalizationPlugin } from 'esengine';
+
+app.addPlugin(localizationPlugin);
+// …或提前预载目录 + 设置初始/回退 locale:
+app.addPlugin(new LocalizationPlugin({
+ locale: 'en',
+ fallback: 'en',
+ catalogs: { en: { play: 'Play' }, 'zh-CN': { play: '开始' } },
+}));
+```
+
## 目录与翻译
```typescript
@@ -28,8 +42,10 @@ const setupI18n = defineSystem([Res(Localization)], (i18n) => {
## 复数
-目录条目可以携带复数形式(`zero` / `one` / `other`);`t` 会根据 `count` 参数选出正确的那个。
-为规则与默认英语式不同的语言注册按 locale 的选择器。
+目录条目可以携带复数形式——CLDR 全集 `zero` / `one` / `two` / `few` / `many` / `other`;
+`t` 会根据 `count` 参数选出一个(且 `count === 0` 时若有 `zero` 形式总是它胜出)。默认选择器
+是英语式(`one`/`other`);斯拉夫语 / 阿拉伯语等规则用
+`setPluralSelector(locale, (count) => category)` 注册,返回上述六个类别之一。
```typescript
i18n.addCatalog('en', { apples: { one: '{count} apple', other: '{count} apples' } });
diff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
index 57c926df0..efc6ffcbd 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/material.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
@@ -5,8 +5,8 @@ description: 自定义材质完整指南——用 #pragma param 反射 uniform
import { Aside } from '@astrojs/starlight/components';
-材质是**着色器加参数**。支持材质的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter`
-和瓦片图层——都暴露一个 `material` 句柄字段;设置它就用你自己的着色器绘制,而非默认。
+材质是**着色器加参数**。支持材质的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter`、
+`Mesh2D` 和 `UIVisual`——都暴露一个 `material` 句柄字段;设置它就用你自己的着色器绘制,而非默认。
## 工作原理
@@ -145,8 +145,8 @@ const v = Material.getUniform(tintMat, 'u_intensity');
<Aside type="note">
没有反射参数的原始着色器用 `Material.createShader(vertexSrc, fragmentSrc)` 而非
- `compileShader`。`ShapeRenderer` 没有 `material` 字段——只有 `Sprite`、`SpineAnimation`、
- `ParticleEmitter` 和瓦片图层有。
+ `compileShader`。`ShapeRenderer` 和 `TilemapLayer` 没有 `material` 字段——只有 `Sprite`、
+ `SpineAnimation`、`ParticleEmitter`、`Mesh2D` 和 `UIVisual` 有。
</Aside>
## 参见
diff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
index 36cda01a1..564ee2e0b 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
@@ -72,7 +72,7 @@ const stats = await channel.request<{ hp: number }>('getStats', { id: 'p1' }, 50
远端角色带快照插值渲染。一处声明驱动整个线格式——无需手写同步代码。
```typescript
-import { defineComponent, Net, Replicated, Transform } from 'esengine';
+import { defineComponent, Net, Replicated, Transform, createMemoryTransportPair } from 'esengine';
// 哪些字段复制在组件上声明(内置组件如 Transform 在 C++ 侧
// 用 `replicated` 注解;用户组件在这里声明)。
@@ -80,22 +80,24 @@ const Health = defineComponent('Health', { hp: 100, regen: 1 }, {
replicatedFields: ['hp'],
});
-// 服务器(权威端):生成一个复制实体,归某个连接所有。
-const net = app.getResource(Net);
-const server = net.startServer();
-server.attachConnection(transport); // 任何 NetTransport 都行
-
-const e = app.world.spawn('player');
-app.world.insert(e, Transform, { position: { x: 0, y: 0, z: 0 } });
-app.world.insert(e, Health, {});
-app.world.insert(e, Replicated, { owner: connectionId });
-
-// 客户端:连上即得——ghost 自动生成,状态持续流入。
-await app.getResource(Net).connect(transport);
-net.client?.sendInput({ move: { x: 1, y: 0 } }); // 每 tick 输入上行
-
-// 服务器玩法读取各连接的最新输入:
-const input = server.inputOf(connectionId);
+// transport 在两端之间传帧。进程内(测试 / listen server)用 memory pair;
+// 真实网络在两端各放一个 GameSocket。
+const [serverEnd, clientEnd] = createMemoryTransportPair();
+
+// --- 服务器 app(权威端) ---
+const server = serverApp.getResource(Net).startServer();
+const connectionId = server.attachConnection(serverEnd); // 返回连接 id
+const e = serverApp.world.spawn('player');
+serverApp.world.insert(e, Transform, { position: { x: 0, y: 0, z: 0 } });
+serverApp.world.insert(e, Health, {});
+serverApp.world.insert(e, Replicated, { owner: connectionId }); // 归该连接所有
+const input = server.inputOf(connectionId); // 该客户端的最新输入
+// server.clientIds —— 每 tick 轮询,为每个已连接玩家生成/回收一个 pawn。
+
+// --- 客户端 app ---
+const clientNet = clientApp.getResource(Net);
+await clientNet.connect(clientEnd, { interpolationDelayTicks: 2 }); // 2 = 平滑延迟
+clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // 每 tick 输入上行
```
- **权威**:只有服务器做模拟;客户端看到的是复制且插值后的状态(`NetGhost`
@@ -116,8 +118,8 @@ const input = server.inputOf(connectionId);
- **设置 RPC 超时**,让丢失的回复 reject 而不是永远挂起。
- **把收到的状态推入组件**(用 `Commands`),让玩法留在 ECS。
- **连接前排队是自动的**——`connect()` 之后就能立即 `send`。
-- **在系统里做权威门控**——检查 `Net.role`,同一份代码即可作为服务器、
- 客户端或离线单机运行。
+- **在系统里做权威门控**——检查 `app.getResource(Net).role`(`'server'` / `'client'` /
+ `'offline'`),同一份代码即可作为服务器、客户端或离线单机运行。
<Aside type="note">
传输层是普通类(在适合你应用的地方创建套接字/通道);复制层则是 ECS
diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
index 6f01c2776..2db1c6f43 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -13,19 +13,22 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
| 效果 | 作用 | 关键 uniform |
|---|---|---|
-| `bloom` | 亮部辉光 | `threshold`、`intensity` |
+| `bloom` | 亮部辉光 | `threshold`、`intensity`、`radius` |
| `tonemap` | ACES filmic 色调映射 | `exposure` |
| `colorGrade` | 曝光 / 对比度 / 饱和度 / 白平衡 | `exposure`、`contrast`、`saturation`、`temperature`、`tint` |
| `lutGrade` | 通过查找表纹理(LUT)调色 | `u_lut`(纹理)、`intensity` |
-| `vignette` | 屏幕边缘变暗 | `intensity`、`radius` |
+| `vignette` | 屏幕边缘变暗 | `intensity`、`softness` |
| `chromaticAberration` | RGB 色散 | `intensity` |
-| `blur` | 高斯模糊 | `radius` |
+| `blur` | 高斯模糊 | `intensity` |
| `fxaa` | 快速抗锯齿 | `intensity` |
| `lensDistortion` | 桶形 / 枕形畸变 | `strength`、`zoom` |
| `pixelate` | 块状量化 | `pixelSize` |
-| `grayscale` | 去色 | — |
+| `grayscale` | 去色 | `intensity` |
-每个效果在默认值下都是恒等(no-op),所以把它加进栈里、在你调参之前不会改变画面。
+上面是友好标签;**在代码里它们带 `u_` 前缀**(`u_intensity`、`u_exposure`……)。多数效果
+在默认值下是恒等(`colorGrade`、`blur`、`chromaticAberration`、`fxaa`、`lensDistortion`、
+`lutGrade`),加进去不调参不改画面。少数一加就可见——`grayscale`(完全去色)、`vignette`、
+`bloom`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。
## 使用 `PostProcessVolume`
@@ -44,47 +47,56 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
## 程序化控制
-自定义管线时,读 `PostProcess` 资源——创建一个栈、调参,并绑定到相机:
+固定的相机管线用 `PostProcess` 资源。栈初始为空——每个效果加一个 **pass**。用
+`getEffectDef(type).factory()` 从注册表拿到效果的着色器,再设它带 `u_` 前缀的 uniform,
+把栈绑到相机:
```typescript
-import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
+import { defineSystem, Query, Res, Camera, PostProcess, getEffectDef } from 'esengine';
const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
+ const grade = getEffectDef('colorGrade')!;
for (const [camera] of q) {
const stack = pp.createStack();
- stack.setEnabled('bloom', true)
- .setUniform('bloom', 'intensity', 1.2)
- .setUniform('bloom', 'threshold', 0.8);
+ stack.addPass('colorGrade', grade.factory())
+ .setUniform('colorGrade', 'u_saturation', 1.3)
+ .setUniform('colorGrade', 'u_contrast', 1.1);
pp.bind(camera, stack); // pp.unbind(camera) to remove
}
});
```
+**多 pass** 的效果(如 `bloom`)带 `def.multiPass`;逐个 sub-pass 加进去
+(`for (const p of grade.multiPass!) stack.addPass(p.name, p.factory())`)。固定管线之外,
+`PostProcessVolume` 更省事——它会替你解析多 pass 与纹理参数。
+
| 方法 | 说明 |
|---|---|
-| `PostProcess.createStack()` | 创建一个效果栈。 |
-| `PostProcess.bind(camera, stack)` | 把栈附加到相机。 |
-| `PostProcess.unbind(camera)` | 移除相机的栈。 |
-| `stack.setEnabled(name, on)` | 启用/禁用一个效果(可链式)。 |
-| `stack.setUniform(pass, uniform, value)` | 设置一个效果参数(可链式)。 |
+| `PostProcess.createStack()` | 创建一个空效果栈。 |
+| `stack.addPass(name, shader)` | 加一个效果 pass;`shader` 来自 `getEffectDef(type).factory()`(可链式)。 |
+| `stack.setUniform(pass, uniform, value)` | 设一个带 `u_` 前缀的参数(可链式)。 |
| `stack.setTexture(pass, uniform, handle)` | 绑定一个纹理参数,比如 LUT(可链式)。 |
+| `stack.setEnabled(name, on)` | 开关一个已加入的 pass(可链式)。 |
+| `PostProcess.bind(camera, stack)` / `unbind(camera)` | 附加 / 移除相机的栈。 |
+| `getEffectDef(type)` / `getAllEffectDefs()` / `getEffectTypes()` | 查效果定义(着色器工厂 + uniform)。 |
### 纹理参数(LUT 与遮罩)
有些效果吃的是纹理而不只是标量。`lutGrade` 采样一张**颜色查找表**——一张 2D 打包的
`1024×32` PNG(32³ 色立方切成 32 片)——于是你可以在图像编辑器里做好整套调色再丢进来。
-用 `setTexture` 绑定它(或在 `PostProcessVolume` 上,把它列在该效果的
+先加 pass,再用 `setTexture` 绑定纹理(或在 `PostProcessVolume` 上,把它列在该效果的
`textures: { u_lut: <ref> }` 下):
```typescript
-stack.setEnabled('lutGrade', true)
+stack.addPass('lutGrade', getEffectDef('lutGrade')!.factory())
.setTexture('lutGrade', 'u_lut', lutHandle)
.setUniform('lutGrade', 'u_intensity', 1);
```
## 最佳实践
-- **顺序有讲究**——效果按注册顺序运行并共享缓冲,合理的链是 bloom → tonemap → 调色 → vignette。
+- **顺序有讲究**——pass 按你加入的顺序运行(或在体积上按其 `effects[]` 的顺序)并共享缓冲,
+ 合理的链是 bloom → tonemap → 调色 → vignette。
- **用体积做局部**(某区域的氛围),用 `PostProcess` API 做固定的相机管线。
- 过渡时**用 `weight` 淡化**体积,而不是硬开关。
- 低端/移动端**让栈保持简短**——每一遍都是一次全屏绘制。
diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
index 00acc341d..61daa96da 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
@@ -36,16 +36,22 @@ const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab',
## 逐实例覆盖
-传 `overrides` 来**仅为这个实例**改组件值,而不编辑预制体资源——用不同血量或着色生成同一个敌人:
+传 `overrides` 来**仅为这个实例**改值,而不编辑预制体资源——用不同血量或着色生成同一个敌人。
+每条覆盖用**字符串** `prefabEntityId`(编辑器创作的预制体里是 UUID)定位一个预制体实体,并指明
+组件 + 属性:
```typescript
const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {
overrides: [
- { entity: 0, component: 'Health', field: 'value', value: 250 },
+ { prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
});
```
+除了 `'property'`,`type` 还可以是 `'name'`、`'visibility'`、`'component_added'`、
+`'component_replaced'`、`'component_removed'`、`'metadata_set'` 或 `'metadata_removed'`
+(metadata 两种用 `metadataKey` 代替 `componentType`/`propertyName`)。
+
## `instantiate` 参考
| 选项 | 类型 | 说明 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
index 22a12ff93..f1a638e00 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/spine.mdx
@@ -40,7 +40,6 @@ import { Spine } from 'esengine/spine';
const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) => {
for (const [entity] of q) {
spine.setAnimation(entity, 'run', true); // play on track 0, looped
- spine.addAnimation(entity, 'jump', false, 0.5); // queue after 0.5s
spine.setDefaultMix(entity, 0.15); // default crossfade
spine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transition
spine.setTrackAlpha(entity, 0, 1.0); // blend a track in/out
@@ -51,25 +50,28 @@ const control = defineSystem([Query(SpineAnimation), Res(Spine)], (q, spine) =>
| 方法 | 说明 |
|---|---|
| `setAnimation(entity, name, loop)` | 在轨道 0 播放一个动画。 |
-| `addAnimation(entity, name, loop, delay)` | 在当前动画之后排队一个动画。 |
| `setDefaultMix(entity, seconds)` | 任意两个动画之间的默认交叉淡入。 |
| `setMixDuration(entity, from, to, seconds)` | 特定转移的交叉淡入。 |
| `setTrackAlpha(entity, track, alpha)` | 混合某轨道的贡献(0..1)。 |
-| `setEntityProps(entity, props)` | 一次性更新 缩放 / 翻转 / 颜色 / 时间缩放。 |
+| `setEntityProps(entity, props)` | 一次性设置 `{ skeletonScale?, flipX?, flipY?, layer? }`。 |
+| `setIKTarget(entity, constraint, x, y, mix)` | 让 IK 约束对准一个世界坐标点(`mix` 0..1)。 |
+
+变换 / 路径约束的混合也可调——`listConstraints(entity)`、`getTransformConstraintMix` /
+`setTransformConstraintMix`,以及 `path` 对应项。
## 皮肤与附件
```typescript
spine.setSkin(entity, 'armored');
spine.setAttachment(entity, 'weapon-slot', 'sword'); // swap a slot's attachment
-spine.setSlotColor(entity, 'body', { r: 1, g: 0.5, b: 0.5, a: 1 });
+spine.setSlotColor(entity, 'body', 1, 0.5, 0.5, 1); // r, g, b, a (0..1)
```
| 方法 | 说明 |
|---|---|
| `setSkin(entity, name)` | 切换活动皮肤。 |
| `setAttachment(entity, slot, attachment)` | 替换某槽位的附件(换装/变体)。 |
-| `setSlotColor(entity, slot, color)` | 给单个槽位着色。 |
+| `setSlotColor(entity, slot, r, g, b, a)` | 给单个槽位着色(四个 0..1 通道)。 |
## 查询骨骼
diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
index 88f8cbeee..4b7f5d2cc 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
@@ -32,7 +32,7 @@ const attach = defineSystem([Commands()], (cmds) => {
| `timeline` | asset | `''` | 时间轴资源(`.estimeline`)。 |
| `playing` | boolean | `false` | 附加时是否开始播放。 |
| `speed` | number | `1` | 播放速率倍率。 |
-| `wrapMode` | string | `'once'` | `'once'`、`'loop'` 或 `'pingpong'`。 |
+| `wrapMode` | string | `'once'` | `'once'`、`'loop'` 或 `'pingPong'`(驼峰写法——其它值会静默地只播一次)。 |
## 控制播放