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(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.mdxindex 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:```typescriptimport { 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.mdxindex 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 orderdiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex 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 audiodiff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/guides/lighting.mdxindex 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 mapsdiff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/guides/localization.mdxindex 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 upstrings 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.```typescripti18n.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.mdxindex 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 reflimport { 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 alsodiff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/guides/networking.mdxindex 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 — nohand-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.mdxindex 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 **colorlookup 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 afixed 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.mdxindex 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:```typescriptconst { 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.mdxindex 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.5sspine.setDefaultMix(entity, 0.15); // default crossfadespine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transitionspine.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```typescriptspine.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 skeletondiff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdxindex 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 playbackdiff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdxindex 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 通过一份生成并经哈希校验的内存布```typescriptimport { 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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)` 注册,返回上述六个类别之一。```typescripti18n.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.mdxindex 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 反射 uniformimport { 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.mdxindex 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">传输层是普通类(在适合你应用的地方创建套接字/通道);复制层则是 ECSdiff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdxindex 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.mdxindex 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)定位一个预制体实体,并指明+组件 + 属性:```typescriptconst { 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.mdxindex 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.5sspine.setDefaultMix(entity, 0.15); // default crossfadespine.setMixDuration(entity, 'idle', 'run', 0.25); // specific transitionspine.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` 对应项。## 皮肤与附件```typescriptspine.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.mdxindex 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'`(驼峰写法——其它值会静默地只播一次)。 |## 控制播放