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: check every field table, default, signature and snippet against the code, align the Chinese pages with the English ones, and add pictures of the examples running, the navigation mesh overlay and the Details panel of the components the guides describe
yhhacd8ca90558f
diff --git a/desktop b/desktopindex efd1df332..acd72db73 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit efd1df332540665fe3dc68052d9d98bdb9a44288+Subproject commit acd72db737ad01eb1734c75bcac3d2617d920114diff --git a/docs/astro/src/assets/guides/en/details-character-3d.png b/docs/astro/src/assets/guides/en/details-character-3d.pngnew file mode 100644index 000000000..3b3153f46Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-character-3d.png differdiff --git a/docs/astro/src/assets/guides/en/details-hinge-joint-3d.png b/docs/astro/src/assets/guides/en/details-hinge-joint-3d.pngnew file mode 100644index 000000000..15584d256Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-hinge-joint-3d.png differdiff --git a/docs/astro/src/assets/guides/en/details-light.png b/docs/astro/src/assets/guides/en/details-light.pngnew file mode 100644index 000000000..276d4f921Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-light.png differdiff --git a/docs/astro/src/assets/guides/en/details-lod-group.png b/docs/astro/src/assets/guides/en/details-lod-group.pngnew file mode 100644index 000000000..8a4d94d14Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-lod-group.png differdiff --git a/docs/astro/src/assets/guides/en/details-nav-agent.png b/docs/astro/src/assets/guides/en/details-nav-agent.pngnew file mode 100644index 000000000..79ff5866aBinary files /dev/null and b/docs/astro/src/assets/guides/en/details-nav-agent.png differdiff --git a/docs/astro/src/assets/guides/en/details-particle-emitter.png b/docs/astro/src/assets/guides/en/details-particle-emitter.pngnew file mode 100644index 000000000..3473edc55Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-particle-emitter.png differdiff --git a/docs/astro/src/assets/guides/en/details-perceiver.png b/docs/astro/src/assets/guides/en/details-perceiver.pngnew file mode 100644index 000000000..075b20e87Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-perceiver.png differdiff --git a/docs/astro/src/assets/guides/en/details-terrain.png b/docs/astro/src/assets/guides/en/details-terrain.pngnew file mode 100644index 000000000..f125f9c26Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-terrain.png differdiff --git a/docs/astro/src/assets/guides/en/details-time-of-day.png b/docs/astro/src/assets/guides/en/details-time-of-day.pngnew file mode 100644index 000000000..3d6af8683Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-time-of-day.png differdiff --git a/docs/astro/src/assets/guides/en/details-weather.png b/docs/astro/src/assets/guides/en/details-weather.pngnew file mode 100644index 000000000..95ec1aa4fBinary files /dev/null and b/docs/astro/src/assets/guides/en/details-weather.png differdiff --git a/docs/astro/src/assets/guides/en/details-worldgen.png b/docs/astro/src/assets/guides/en/details-worldgen.pngnew file mode 100644index 000000000..bbb04d541Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-worldgen.png differdiff --git a/docs/astro/src/assets/guides/en/details-worldzone.png b/docs/astro/src/assets/guides/en/details-worldzone.pngnew file mode 100644index 000000000..af8df68e0Binary files /dev/null and b/docs/astro/src/assets/guides/en/details-worldzone.png differdiff --git a/docs/astro/src/assets/guides/en/play-drawing.png b/docs/astro/src/assets/guides/en/play-drawing.pngnew file mode 100644index 000000000..70c6bcbd5Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-drawing.png differdiff --git a/docs/astro/src/assets/guides/en/play-effects.png b/docs/astro/src/assets/guides/en/play-effects.pngnew file mode 100644index 000000000..28c5e917dBinary files /dev/null and b/docs/astro/src/assets/guides/en/play-effects.png differdiff --git a/docs/astro/src/assets/guides/en/play-lighting-2d.png b/docs/astro/src/assets/guides/en/play-lighting-2d.pngnew file mode 100644index 000000000..08cc173e0Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-lighting-2d.png differdiff --git a/docs/astro/src/assets/guides/en/play-mobile-controls.png b/docs/astro/src/assets/guides/en/play-mobile-controls.pngnew file mode 100644index 000000000..e58e0b454Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-mobile-controls.png differdiff --git a/docs/astro/src/assets/guides/en/play-particles.png b/docs/astro/src/assets/guides/en/play-particles.pngnew file mode 100644index 000000000..6c51c874fBinary files /dev/null and b/docs/astro/src/assets/guides/en/play-particles.png differdiff --git a/docs/astro/src/assets/guides/en/play-physics-3d.png b/docs/astro/src/assets/guides/en/play-physics-3d.pngnew file mode 100644index 000000000..3f1f8e0a7Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-physics-3d.png differdiff --git a/docs/astro/src/assets/guides/en/play-postprocess.png b/docs/astro/src/assets/guides/en/play-postprocess.pngnew file mode 100644index 000000000..6672b7a14Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-postprocess.png differdiff --git a/docs/astro/src/assets/guides/en/play-rich-text.png b/docs/astro/src/assets/guides/en/play-rich-text.pngnew file mode 100644index 000000000..235d1d047Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-rich-text.png differdiff --git a/docs/astro/src/assets/guides/en/play-spine.png b/docs/astro/src/assets/guides/en/play-spine.pngnew file mode 100644index 000000000..136f18fc6Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-spine.png differdiff --git a/docs/astro/src/assets/guides/en/play-sprites.png b/docs/astro/src/assets/guides/en/play-sprites.pngnew file mode 100644index 000000000..84a1f8f8dBinary files /dev/null and b/docs/astro/src/assets/guides/en/play-sprites.png differdiff --git a/docs/astro/src/assets/guides/en/play-terrain-water.png b/docs/astro/src/assets/guides/en/play-terrain-water.pngnew file mode 100644index 000000000..f334930c3Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-terrain-water.png differdiff --git a/docs/astro/src/assets/guides/en/play-third-person.png b/docs/astro/src/assets/guides/en/play-third-person.pngnew file mode 100644index 000000000..2384e8857Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-third-person.png differdiff --git a/docs/astro/src/assets/guides/en/play-trail.png b/docs/astro/src/assets/guides/en/play-trail.pngnew file mode 100644index 000000000..d82218b35Binary files /dev/null and b/docs/astro/src/assets/guides/en/play-trail.png differdiff --git a/docs/astro/src/assets/guides/en/view-navmesh.png b/docs/astro/src/assets/guides/en/view-navmesh.pngnew file mode 100644index 000000000..efe12c78eBinary files /dev/null and b/docs/astro/src/assets/guides/en/view-navmesh.png differdiff --git a/docs/astro/src/assets/guides/zh/details-character-3d.png b/docs/astro/src/assets/guides/zh/details-character-3d.pngnew file mode 100644index 000000000..ab3435f78Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-character-3d.png differdiff --git a/docs/astro/src/assets/guides/zh/details-hinge-joint-3d.png b/docs/astro/src/assets/guides/zh/details-hinge-joint-3d.pngnew file mode 100644index 000000000..fc7f8573aBinary files /dev/null and b/docs/astro/src/assets/guides/zh/details-hinge-joint-3d.png differdiff --git a/docs/astro/src/assets/guides/zh/details-light.png b/docs/astro/src/assets/guides/zh/details-light.pngnew file mode 100644index 000000000..ef6262842Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-light.png differdiff --git a/docs/astro/src/assets/guides/zh/details-lod-group.png b/docs/astro/src/assets/guides/zh/details-lod-group.pngnew file mode 100644index 000000000..841ce46c1Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-lod-group.png differdiff --git a/docs/astro/src/assets/guides/zh/details-nav-agent.png b/docs/astro/src/assets/guides/zh/details-nav-agent.pngnew file mode 100644index 000000000..c281c9df7Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-nav-agent.png differdiff --git a/docs/astro/src/assets/guides/zh/details-particle-emitter.png b/docs/astro/src/assets/guides/zh/details-particle-emitter.pngnew file mode 100644index 000000000..15c2261e3Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-particle-emitter.png differdiff --git a/docs/astro/src/assets/guides/zh/details-perceiver.png b/docs/astro/src/assets/guides/zh/details-perceiver.pngnew file mode 100644index 000000000..1839da472Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-perceiver.png differdiff --git a/docs/astro/src/assets/guides/zh/details-terrain.png b/docs/astro/src/assets/guides/zh/details-terrain.pngnew file mode 100644index 000000000..b9b4e1a5fBinary files /dev/null and b/docs/astro/src/assets/guides/zh/details-terrain.png differdiff --git a/docs/astro/src/assets/guides/zh/details-time-of-day.png b/docs/astro/src/assets/guides/zh/details-time-of-day.pngnew file mode 100644index 000000000..7620ca47eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/details-time-of-day.png differdiff --git a/docs/astro/src/assets/guides/zh/details-weather.png b/docs/astro/src/assets/guides/zh/details-weather.pngnew file mode 100644index 000000000..35257aa32Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-weather.png differdiff --git a/docs/astro/src/assets/guides/zh/details-worldgen.png b/docs/astro/src/assets/guides/zh/details-worldgen.pngnew file mode 100644index 000000000..2f0db6442Binary files /dev/null and b/docs/astro/src/assets/guides/zh/details-worldgen.png differdiff --git a/docs/astro/src/assets/guides/zh/details-worldzone.png b/docs/astro/src/assets/guides/zh/details-worldzone.pngnew file mode 100644index 000000000..46798511aBinary files /dev/null and b/docs/astro/src/assets/guides/zh/details-worldzone.png differdiff --git a/docs/astro/src/assets/guides/zh/play-drawing.png b/docs/astro/src/assets/guides/zh/play-drawing.pngnew file mode 100644index 000000000..70c6bcbd5Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-drawing.png differdiff --git a/docs/astro/src/assets/guides/zh/play-effects.png b/docs/astro/src/assets/guides/zh/play-effects.pngnew file mode 100644index 000000000..28c5e917dBinary files /dev/null and b/docs/astro/src/assets/guides/zh/play-effects.png differdiff --git a/docs/astro/src/assets/guides/zh/play-lighting-2d.png b/docs/astro/src/assets/guides/zh/play-lighting-2d.pngnew file mode 100644index 000000000..08cc173e0Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-lighting-2d.png differdiff --git a/docs/astro/src/assets/guides/zh/play-mobile-controls.png b/docs/astro/src/assets/guides/zh/play-mobile-controls.pngnew file mode 100644index 000000000..e58e0b454Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-mobile-controls.png differdiff --git a/docs/astro/src/assets/guides/zh/play-particles.png b/docs/astro/src/assets/guides/zh/play-particles.pngnew file mode 100644index 000000000..6c51c874fBinary files /dev/null and b/docs/astro/src/assets/guides/zh/play-particles.png differdiff --git a/docs/astro/src/assets/guides/zh/play-physics-3d.png b/docs/astro/src/assets/guides/zh/play-physics-3d.pngnew file mode 100644index 000000000..3f1f8e0a7Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-physics-3d.png differdiff --git a/docs/astro/src/assets/guides/zh/play-postprocess.png b/docs/astro/src/assets/guides/zh/play-postprocess.pngnew file mode 100644index 000000000..6672b7a14Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-postprocess.png differdiff --git a/docs/astro/src/assets/guides/zh/play-rich-text.png b/docs/astro/src/assets/guides/zh/play-rich-text.pngnew file mode 100644index 000000000..235d1d047Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-rich-text.png differdiff --git a/docs/astro/src/assets/guides/zh/play-spine.png b/docs/astro/src/assets/guides/zh/play-spine.pngnew file mode 100644index 000000000..136f18fc6Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-spine.png differdiff --git a/docs/astro/src/assets/guides/zh/play-sprites.png b/docs/astro/src/assets/guides/zh/play-sprites.pngnew file mode 100644index 000000000..84a1f8f8dBinary files /dev/null and b/docs/astro/src/assets/guides/zh/play-sprites.png differdiff --git a/docs/astro/src/assets/guides/zh/play-terrain-water.png b/docs/astro/src/assets/guides/zh/play-terrain-water.pngnew file mode 100644index 000000000..f334930c3Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-terrain-water.png differdiff --git a/docs/astro/src/assets/guides/zh/play-third-person.png b/docs/astro/src/assets/guides/zh/play-third-person.pngnew file mode 100644index 000000000..2384e8857Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-third-person.png differdiff --git a/docs/astro/src/assets/guides/zh/play-trail.png b/docs/astro/src/assets/guides/zh/play-trail.pngnew file mode 100644index 000000000..d82218b35Binary files /dev/null and b/docs/astro/src/assets/guides/zh/play-trail.png differdiff --git a/docs/astro/src/assets/guides/zh/view-navmesh.png b/docs/astro/src/assets/guides/zh/view-navmesh.pngnew file mode 100644index 000000000..efe12c78eBinary files /dev/null and b/docs/astro/src/assets/guides/zh/view-navmesh.png differdiff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex 861bd91fc..da28aab5d 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -427,6 +427,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `controller` | string | `''` | An `.esanimator` asset ref (what the editor writes) or a name passed to `registerController` in code. || `avatar` | string | `''` | An `.esavatar` asset saying how this rig spells the joints the clips name (see [Avatars](#layers-masks-and-ik)). || `currentState` | string | `''` | The base layer's active state, as a `/`-separated path for nested machines (seeded from the controller's initial state). |+| `layerStates` | string[] | `[]` | The active state of each layer above the base one, in layer order (the base layer's is `currentState`). || `enabled` | boolean | `true` | Disable to freeze the state machine. || `AnimatorController` method | Description |diff --git a/docs/astro/src/content/docs/animation/spine.mdx b/docs/astro/src/content/docs/animation/spine.mdxindex 1cdd4222b..94a14dfa5 100644--- a/docs/astro/src/content/docs/animation/spine.mdx+++ b/docs/astro/src/content/docs/animation/spine.mdx@@ -45,6 +45,10 @@ viewport — including across Play/Stop — and once it loads, the `animation` afile from the Content Browser onto the slot works too.</Aside>+++*The Spine demo example: a skeleton played through the **SpineAnimation** component.*+## AtlasesSpine `.atlas` files work as exported — including **multi-page** atlases (eachdiff --git a/docs/astro/src/content/docs/animation/spring-bones.mdx b/docs/astro/src/content/docs/animation/spring-bones.mdxindex 5930afe25..e84e41cc6 100644--- a/docs/astro/src/content/docs/animation/spring-bones.mdx+++ b/docs/astro/src/content/docs/animation/spring-bones.mdx@@ -18,18 +18,18 @@ is simulated.| Field | What it does ||---|---|| `enabled` | Off leaves the chain exactly as the animation poses it. |-| `stiffness` | How hard each bone is pulled back toward its animated pose, 0 to 1 a frame at 60 Hz. 0 hangs free. |-| `drag` | How much of its speed a bone loses each frame, 0 to 1. Higher settles sooner; the default is damped enough not to ring. |-| `gravity` | World units a second squared (world y is up). The default is a metre a hundred units. |+| `stiffness` | How hard each bone is pulled back toward its animated pose, 0 to 1 a frame at 60 Hz. 0 hangs free. Default 0.1. |+| `drag` | How much of its speed a bone loses each frame, 0 to 1. Higher settles sooner; the default (0.5) is damped enough not to ring. |+| `gravity` | World units a second squared (world y is up). The default is `{0, -980, 0}`: a metre a hundred units. || `wind` | A steady wind on the chain, world units a second squared. Zero is still air. || `windGust` | How far gusts swing the wind's strength, 0 to 1. 0 is steady; 1 takes it from calm to twice its strength. Each bone meets a gust a moment after the one above, so the strand ripples. |-| `windFrequency` | Gusts a second. |+| `windFrequency` | Gusts a second (default 0.5). || `endLength` | A leaf bone has no child to aim at; this gives it a tip that long. 0 leaves leaf bones unsimulated. || `radius` | The thickness of the strand, kept clear of the colliders. |-| `weight` | How much of the simulation is used, 0 to 1. 0 is the animation alone. |+| `weight` | How much of the simulation is used, 0 to 1 (default 1). 0 is the animation alone. || `colliders` | Entities with a `SpringBoneCollider` the chain is kept out of. |-A `SpringBoneCollider` is a sphere, or a capsule along its entity's own Y axis, placed by the entity's transform (and its `offset`). Put them on the head+A `SpringBoneCollider` is a sphere (the default, `radius` 10), or a capsule along its entity's own Y axis (`height` 20, the distance between its end centres), placed by the entity's transform (and its `offset`). Put them on the headand shoulders bones so hair does not pass through the body.## From a modeldiff --git a/docs/astro/src/content/docs/animation/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdxindex 85c444973..10cd77888 100644--- a/docs/astro/src/content/docs/animation/timeline.mdx+++ b/docs/astro/src/content/docs/animation/timeline.mdx@@ -182,7 +182,7 @@ import {} from 'esengine';const slideIn: TimelineAsset = {- version: '1.1',+ version: '1.3',type: 'timeline',duration: 2,wrapMode: WrapMode.Once,diff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxindex 797be128c..312f57b7d 100644--- a/docs/astro/src/content/docs/assets/audio.mdx+++ b/docs/astro/src/content/docs/assets/audio.mdx@@ -265,7 +265,7 @@ audio.setBusDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, releaudio.setBusDucking('music', null); // remove```-While the `trigger` bus carries signal, the target's duck stage ramps to+`attack` (default 0.05 s) and `release` (default 0.4 s) are time constants, and `threshold` (default 0.003, an RMS level from 0 to 1) is how loud the trigger bus must be to count as active. While the `trigger` bus carries signal, the target's duck stage ramps to`amount`; on silence it releases back to 1. Ducking is a separate gain stage,so it never fights the user's volume setting. On backends without a WebAudiograph (WeChat) both APIs degrade to no-ops, like the volume calls.@@ -280,7 +280,7 @@ apply live in the editor; Play and every export boot the identical mix.### Import settings & cooked audioSelecting an audio asset shows a decoded waveform with play/seek plus **Import-Settings**: `Compress` and `Bitrate` control the cook's WAV → MP3 transcode+Settings**: `Compress` (default on) and `Bitrate` (96, 128 or 192 kbps; default 128) control the cook's WAV → MP3 transcode(enable **Compress audio** in the Package dialog). Already-compressed formatspass through untouched. MP3 has a small encoder delay — turn `Compress` off onclips that must loop seamlessly.diff --git a/docs/astro/src/content/docs/assets/models.mdx b/docs/astro/src/content/docs/assets/models.mdxindex 393614fcb..48b8bf407 100644--- a/docs/astro/src/content/docs/assets/models.mdx+++ b/docs/astro/src/content/docs/assets/models.mdx@@ -220,6 +220,15 @@ replaces them — a model told to occlude itself keeps doing so through its mateA model's materials import on the Model shader. Turn on **Character Materials** (`characterMaterials: auto`) in the model's import settings and a material whose name says skin, face, head, hair or eye gets the Skin, Hair or Eye shader instead, with its normal map and its occlusion/roughness map bound to them. The hair's triangles are also put in the order a blended draw wants, the cards nearest the middle of the hair first, which is back to front from any side for a shell of cards around a head (a ponytail that leaves the shell is not ordered by it). A hair material is cut out by its alpha (`u_alphaCutoff`, 0.5 unless the source says otherwise) and drawn without blending, so its edges are feathered by coverage. The name is read word by word, so `BodySkin` and `Hair_A` match while `Eyelashes` and `Headband` do not, and the colour texture's file name counts too. A name is a convention, not a fact: look at what it chose in the materials the import writes, and change a shader by hand where it guessed wrong. Eyes need their iris maps (`u_depthMap`, `u_irisNormalMap`) assigned by hand, as the source has no slot for them. Hair's strand-direction and highlight-shift maps have no glTF slot either, so a hair material names them in its extras (`flow_map` and `shift_map`, paths from the model, and `suggested_tipSoftness`) and the import binds them as `u_flowMap`, `u_shiftMap` and `u_tipSoftness`. It is off by default, so re-importing never changes a material you did not ask about.+## Spring bones and the specular map++Two more model import settings, both under advanced:++| Setting | Default | What it does |+|---|---|---|+| **Spring Bones** (`springBones`) | Off | **From File Data and Names** gives hair its secondary motion from what the model already says: a VRM spring-bone extension or `extras.estella.springBone` / `springCollider` is used as stated, and for what they leave out a bone called `Hair_<region>_<chain>_00` becomes a `SpringBone` and an empty called `SBC_Sphere_<name>_r<cm>` or `SBC_Capsule_<name>_r<cm>_h<cm>` a collider. See [Spring bones](/docs/animation/spring-bones/). |+| **Specular Map** (`specularMap`) | Specular Color | What the source's specular map holds. **Packed ORM** binds it as occlusion, roughness and metalness, for scenes that pack them there (Bistro, Sun Temple); the default reads it as a highlight tint, which the metal/rough shading has no slot for. FBX only. |+## AnimationsEach animation in the source becomes an `.estimeline` beside the meshes, and the prefab'sdiff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdxindex 958df723c..4d3d70fd8 100644--- a/docs/astro/src/content/docs/assets/overview.mdx+++ b/docs/astro/src/content/docs/assets/overview.mdx@@ -63,11 +63,15 @@ const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets|---|---|| `loadTexture(ref)` | `{ handle, width, height }` || `loadAudio(ref)` | `{ bufferId }` |-| `loadFont(ref)` | `{ handle }` |+| `loadFont(ref)` | `{ handle, family? }` (`family` for outline fonts) || `loadMaterial(ref)` | `{ handle, shaderHandle }` |-| `loadSpine(skeletonRef, atlasRef?)` | `{ skeletonHandle }` |+| `loadSpine(skeletonRef, atlasRef?)` | `{ skelData, atlasText, isBinary, textures }` — the prepared skeleton and atlas, which the `Spine` component draws from || `loadTilemap(ref)` / `loadTileset(ref)` | `{ sourceId }` / `{ tilesetId }` || `loadTimeline(ref)` | `{ timelineId }` |+| `loadAnimClip(ref)` | `{ clipId }` |+| `loadAnimatorController(ref)` | `{ controllerId }` |+| `loadStateMachine(ref)` / `loadBehaviorTree(ref)` | `{ fsmId }` / `{ btId }` |+| `loadLocaleTable(ref)` | `{ locale, keyCount }` || `loadPrefab(ref)` | `{ data }` || `loadJson<T>(ref)` | `{ data: T }` |@@ -207,8 +211,8 @@ subpackage / remote delivery, writing to the same `.esengine/asset-groups.json`:}```-It is Unity's `Resources` folder and Unreal's additional cook directory, in the-model this project already had. **Off by default**, deliberately.+It is a folder-level override of reachability, in the model this project already had.+**Off by default**, deliberately.<Aside type="tip">Assets under `subpackages/` are always included even when unreachable — onlydiff --git a/docs/astro/src/content/docs/assets/textures.mdx b/docs/astro/src/content/docs/assets/textures.mdxindex a3dfd06b1..0416c7d1e 100644--- a/docs/astro/src/content/docs/assets/textures.mdx+++ b/docs/astro/src/content/docs/assets/textures.mdx@@ -117,15 +117,18 @@ Browser — every sprite that uses the texture inherits them.| Setting | Default | What it does ||---|---|---|-| **Max Size** | `2048` | Downscale cap applied at cook (a power of two). A source larger than this on its longest side is box-filtered down; a smaller source is untouched. |+| **Max Size** | `2048` | Downscale cap applied at cook (256 to 8192, a power of two). A source larger than this on its longest side is box-filtered down; a smaller source is untouched. || **Compression** | `Auto` | **GPU compressed** ships a KTX2 (Basis Universal) that stays compressed in video memory — about a quarter of the decoded image — and transcodes per device. **Original image** ships the file as it is: exact, and for flat art far smaller to download, but decoded in full on the GPU. **Auto** is GPU compressed for a texture a mesh draws (directly or through its material) and the original image for sprites and UI. A build does what this row says; it never swaps one for the other because a file came out smaller. || **Compress Format** | `uastc` | `uastc` — high quality, larger. `etc1s` — much smaller, lower quality (good for photographic art). Only used when the texture is GPU compressed. || **Mip Maps** | on | Keep a chain of half-size copies so a texture drawn small samples a filtered image instead of shimmering; costs a third more memory. Turn it off for pixel art and UI that is always drawn at its own size. || **Filter** | `linear` | Sampling filter. `nearest` keeps pixel art crisp; `linear` smooths. || **Wrap** | `repeat` | How UVs outside `[0,1]` are addressed: `repeat`, `clamp`, `mirror`. || **sRGB Color** | `true` | The image stores sRGB-encoded color (albedo, UI). Disable for authored-linear data — normal maps, masks. Only meaningful when the project renders in linear color. |-| **Mip Coverage Cutoff** | `0` | For a cutout (leaves, grass, fences): the alpha cutoff its material tests. Each mip level keeps the share of texels above it that the full image has, so the cutout does not thin out with distance. `0` = off; applies to UASTC-compressed textures. |+| **Mip Coverage Cutoff** | `0` | For a cutout (leaves, grass, fences): the alpha cutoff its material tests. Each mip level keeps the share of texels above it that the full image has, so the cutout does not thin out with distance. `0` = off (0 to 1); applies to UASTC-compressed textures. || **9-Slice Border** | `0,0,0,0` | Left/right/top/bottom border in **texture pixels**: where the image's corners end. Authored once here, inherited by every `UIVisual` set to Sliced. |+| **Cell Width / Cell Height** | `0` | The size of one cell of a sprite sheet, in pixels. `0` means the image is not a sheet; setting it lets a `Sprite` pick a frame of the image instead of showing all of it. |+| **Margin** | `0` | Padding before the first cell, on both axes. |+| **Spacing** | `0` | Gap between neighbouring cells, paid between cells only, never after the last one. |<Aside type="tip">**Pixel art**: set Filter to `nearest` and Compression to **Original image** (Auto alreadydiff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex 082c37b7b..194125266 100644--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx@@ -47,13 +47,15 @@ importable from `esengine`) with `wasmBaseUrl`:| `sideModules` | `SideModuleHost` | built from `wasmBaseUrl`, else none | The realm's acquirer for optional native modules. Realms that inline their modules (Playable, WeChat) pass a host directly instead of a URL. || `plugins` | `Plugin[]` | `[]` | Extra plugins, appended **after** the default set. || `getViewportSize` | `() => { width, height }` | — | Viewport size callback for the camera system (and the WebGPU init size; `800×600` if absent). |-| `glContextHandle` | `number` | — | A pre-registered WebGL2 context handle to render into; without it the module creates its own context via `initRenderer()`. |-| `backend` | `'webgl2' \| 'webgpu'` | `'webgl2'` | `'webgpu'` boots the injected-device path — the host must have acquired a `GPUDevice` and passed it as the module factory's `preinitializedWebGPUDevice` before instantiation. |-| `canvasSelector` | `string` | `'#canvas'` | CSS selector for the WebGPU swapchain canvas (must be in the DOM). WebGL ignores it. |+| `renderSurface` | `RenderSurfaceSource` | `{ kind: 'default' }` | How the host provides the render surface: `{ kind: 'gl-context', handle, glx? }` renders into a pre-registered WebGL2 context handle (`glx` marks WeChat's EmscriptenGLX context); `{ kind: 'webgpu', canvasSelector?, readback? }` boots the injected-device path — the host must have acquired a `GPUDevice` and passed it as the module factory's `preinitializedWebGPUDevice` before instantiation, `canvasSelector` defaults to `'#canvas'` (must be in the DOM) and `readback` lets the engine read its own frames back (`captureFrame`); `{ kind: 'default' }` lets the module create its own context via `initRenderer()`. || `colorSpace` | `'gamma' \| 'linear'` | `'gamma'` | Project color space. `'linear'` renders in linear light (sRGB decode on sample, linear blending, explicit encode in the final blit). Must be declared **at app creation** — shaders compile against it. || `randomSeed` | `number` | — | Seed the engine's randomness so the run reproduces — a replay, a bug report, an assertion about a frame. Absent, every run differs, which is what a player wants of particles. Subsystems take independent named streams, so adding an emitter cannot change what something else rolled. || `ySortLayers` | `number` | `0` | Bitmask of render layers (bits 0–31) that sort by world Y within the layer (top-down occlusion). |-| `screenFit` | `ScreenScalingData` | off (`scaleMode: -1`) | Project camera fit: letterboxes a design resolution into the actual aspect. Only installed when `scaleMode` is a real mode (≥ 0); `SCREEN_FIT_OFF` (-1) keeps the legacy Canvas-or-raw fit. |+| `depthLayers` | `number` | `0` | Bitmask of render layers (bits 0–31) that resolve by real depth instead of painter's order — the 2.5D opt-in. Opaque draws write the depth buffer and sort front-to-back; blended ones test without writing. A layer that also y-sorts keeps y-sorting. |+| `outputTransform` | `'none' \| 'aces' \| 'neutral'` | `'none'` | The curve the frame applies once, last, on its way to the display. `'aces'` is the filmic shoulder a lit 3D scene wants; `'neutral'` (Khronos PBR Neutral) keeps hue and saturation. |+| `msaaSamples` | `number` | `4` | Scene-target multisampling; `1` turns it off. The device clamps it, so this is what the project asks for, not what it gets. |+| `quality` | `QualityConfig` | — | Quality mode (`'off'`, `'auto'`, `'low'`, `'medium'`, `'high'`), target frame rate, dynamic resolution, per-level profiles, device rules, async shader compile and render-on-demand. Installed only when given. |+| `screenFit` | `ScreenScalingData` | off (`scaleMode: -1`) | Project camera fit: letterboxes a design resolution into the actual aspect. The camera fit applies only when `scaleMode` is a real mode (≥ 0); `SCREEN_FIT_OFF` (-1) keeps the legacy Canvas-or-raw fit. The resource is also installed when `renderPolicy` is not `Surface`. |### What it installs@@ -172,11 +174,11 @@ sorts the batch by `dependencies` / `before` / `after` and throws on a cycle.If `build()` throws, the plugin is rolled back and the failure stays visible inthe subsystem registry as an `error` entry.-**`flushPendingSystems(app)`** — module-level `addSystem` /-`addStartupSystem` / `defineBehavior` calls (made at import time, outside any+**`flushPendingRegistrations(app)`** — module-level `addPlugin` /+`addSystem` / `addStartupSystem` / `defineBehavior` calls (made at import time, outside anyplugin) queue on the ambient context rather than on a specific app. The-factories' runtimes drain that queue into the app for you; call-`flushPendingSystems` yourself when you build a bare `App` manually and still+factories' runtimes drain that queue into the app for you (plugins first, then+systems); call `flushPendingRegistrations` yourself when you build a bare `App` manually and stillwant those module-level registrations.## The `App` surface@@ -421,7 +423,7 @@ after a reload — write them as idempotent setup (see- **Name your plugins.** A `name` costs nothing and buys observability: thesubsystem registry entry, liveness attribution for the plugin's systems, andusable dependency errors.-- **Declare `colorSpace` and `backend` up front.** Both are baked in at+- **Declare `colorSpace` and `renderSurface` up front.** Both are baked in atcreation (shader compilation, device injection) — they cannot be toggled on alive app.- **Don't fight the lifecycle auto-pause.** Turn it off withdiff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdxindex a4b28d0eb..02e6cccda 100644--- a/docs/astro/src/content/docs/core-concepts/screen.mdx+++ b/docs/astro/src/content/docs/core-concepts/screen.mdx@@ -43,6 +43,7 @@ found is the one the engine uses.| `scaleMode` | `ScaleMode` | `FixedHeight` | How the design resolution adapts to the actual screen aspect (see below). || `matchWidthOrHeight` | number | `0.5` | `Match`-mode blend, 0–1: `0` = fit width, `1` = fit height. Ignored by the other modes. || `backgroundColor` | Color | `{r:0, g:0, b:0, a:1}` | Background color declared for the letterbox/pillarbox areas outside the design box. |+| `layer` | number | `0` | Sorting layer this canvas' UI belongs to — cameras include or exclude the UI through it (see [`Camera.cullingMask`](#which-cameras-see-it-cameracullingmask)). |```typescriptimport { defineSystem, GetWorld, Canvas } from 'esengine';@@ -143,9 +144,10 @@ carries an older resolution than the project fit cannot lay UI out one way in theditor and another in the shipped build.<Aside type="caution">- While a fit source is active, the main camera's authored `orthoSize` is **not- used** — the visible half-height comes entirely from the design resolution and- the scale mode. Zoom by editing/tweening `orthoSize` only takes effect when no+ While a fit source is active, a full-screen orthographic scene camera's authored+ `orthoSize` is **not used** — the visible half-height comes entirely from the+ design resolution and the scale mode. Sub-viewport cameras, cameras that render+ into a texture and perspective cameras keep their own zoom. Zoom by editing/tweening `orthoSize` only takes effect when nofit source is active (no `Canvas` in the scene and `ScreenScaling` off).</Aside>@@ -165,9 +167,10 @@ runtime image of **Settings → Project → Game → Display → Camera fit**.| `designHeight` | number | `1080` | Design (reference) resolution height in px. || `scaleMode` | number | `SCREEN_FIT_OFF` (`-1`) | A real `ScaleMode` (`0`–`4`) turns the project fit **on**; `SCREEN_FIT_OFF` keeps the legacy behavior (Canvas fit when present, else raw `orthoSize`). || `matchWidthOrHeight` | number | `0.5` | `Match`-mode blend 0–1 (`0` = fit width, `1` = fit height); ignored by other modes. |+| `renderPolicy` | `RenderResolution` (optional) | `RenderResolution.Surface` (`0`) | How the scene's own resolution is chosen. `Surface` renders straight to the screen; `Design` (`1`) renders at the size the camera's world height asks for (one world unit = one rendered pixel) and scales that one image to the screen — no seams between sprites, slightly soft at non-integer ratios; `IntegerMultiple` (`2`) presents it at a whole multiple of its size, with black bars where that does not fill the screen. Independent of `scaleMode`. |`DEFAULT_SCREEN_SCALING` is that off-by-default value, and `SCREEN_FIT_OFF` (`-1`)-is the sentinel. When the project fit is on it is **authoritative** — for the+is the sentinel. The resource is installed when `scaleMode` is a real mode **or** `renderPolicy` is not `Surface`; the camera fit itself needs the former. When the project fit is on it is **authoritative** — for thecamera and for the UI layout box alike, since both resolve the fit the same way.The shipped runtimes install it from the project config (`createWebApp`'s@@ -309,11 +312,13 @@ insets or screen change. The system ships as part of the standard UI plugin| `applyBottom` | boolean | `true` | Same for the bottom inset. || `applyLeft` | boolean | `true` | Same for the left inset. || `applyRight` | boolean | `true` | Same for the right inset. |+| `avoidHostMenu` | boolean | `false` | Also clear the host's own overlay — WeChat's capsule menu, which sits *inside* the safe area. The top inset becomes the larger of the safe-area inset and the capsule's bottom edge. Set it only on a node the capsule actually reaches: the whole node moves down. |Platform insets are converted from device pixels into UI design pixels beforebeing written, so the layout stays resolution-independent:- **WeChat:** read from `wx.getSystemInfoSync().safeArea` automatically.+- **Native (iOS / Android):** read from the platform's cached OS insets every frame.- **Web:** read from the `--sat` / `--sab` / `--sal` / `--sar` CSS customproperties on the root element — define them from `env(safe-area-inset-*)` inyour host page to opt in (they read as `0` otherwise).@@ -361,22 +366,9 @@ Where each **Settings → Project → Game → Display** field lives and lands:| Orientation | `packaging.orientation` (`'portrait'` \| `'landscape'`; absent = derived from the design aspect) | WeChat `game.json`, web/playable rotate hint, desktop window aspect, editor device preview. || Camera fit | `features.rendering.cameraScaleMode` (`'none'`, `'fixed-width'`, `'fixed-height'`, `'expand'`, `'shrink'`, `'match'`; absent = `'none'`) | Mapped to `ScreenScaling.scaleMode` (`'none'` → `SCREEN_FIT_OFF`). || Camera fit match | `features.rendering.cameraMatch` (0–1, default `0.5`) | `ScreenScaling.matchWidthOrHeight`. |+| Render resolution | `features.rendering.renderResolution` (`'surface'`, `'design'`, `'integer'`; absent = `'surface'`) | `ScreenScaling.renderPolicy` (`Surface` / `Design` / `IntegerMultiple`). |-Separately, two `RuntimeConfig` knobs set the **default `scaleMode` for newly-created `Canvas` components** (they do not touch canvases already saved in a-scene): `RuntimeConfig.canvasScaleMode` (default `1` = `FixedHeight`) and-`RuntimeConfig.canvasMatchWidthOrHeight` (default `0.5`). Build configs set them-by name through `applyBuildRuntimeConfig` — canonical `CanvasScaleMode` names plus-the `ShowAll` / `NoBorder` aliases; unknown names fall back to `FixedHeight`:--```typescript-import { applyBuildRuntimeConfig } from 'esengine';--applyBuildRuntimeConfig(app, {- canvasScaleMode: 'Expand', // name-based: 'FixedWidth' … 'Match', 'ShowAll', 'NoBorder'- canvasMatchWidthOrHeight: 0.5,-});-```+A newly created `Canvas` starts with `scaleMode` `FixedHeight` (`1`) and `matchWidthOrHeight` `0.5` — the component defaults. Canvases already saved in a scene keep what they saved.## Best practicesdiff --git a/docs/astro/src/content/docs/core-concepts/transforms.mdx b/docs/astro/src/content/docs/core-concepts/transforms.mdxindex 4eef6ec7d..11ac7c921 100644--- a/docs/astro/src/content/docs/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/core-concepts/transforms.mdx@@ -43,7 +43,7 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {});```-`position.x/y/z`, `rotation.z`, and `scale.x/y/z` are animatable (the+`position.x/y/z`, `rotation.x/y/z/w`, `rotation.angle` (the Z turn, in radians, which leaves the other two axes intact) and `scale.x/y/z` are animatable (the[Sequencer](/docs/animation/timeline/) and [tweens](/docs/animation/overview/#tweens)can key them), and `position` / `rotation` / `scale` are replicated by[networking](/docs/scripting/networking/)'s state replication.@@ -56,8 +56,9 @@ can key them), and `position` / `rotation` / `scale` are replicated by</Aside><Aside type="tip">- The editor's Details panel shows rotation as a single **Z angle in degrees**- for convenience, but the stored data is always the quaternion.+ The editor's Details panel shows rotation as **X / Y / Z Euler angles in+ degrees** (applied X, then Y, then Z; 2D content turns about Z alone), but the+ stored data is always the quaternion.</Aside>## Coordinate system@@ -190,7 +191,7 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],To animate a rotation, `TweenTarget.RotationZ` drives the Z angle **in radians**(the engine rebuilds the quaternion each step), and the Sequencer keys-`rotation.z` the same way — see [Animation](/docs/animation/overview/#tweens).+`rotation.angle` the same way — see [Animation](/docs/animation/overview/#tweens).<Aside type="tip">For aiming math without touching rotation at all, `v2.fromAngle(angle, len)`@@ -262,8 +263,11 @@ the parent in world space. The decomposed results land inthe engine (layout, rendering, despawn) walks `Children`. Always`world.setParent`.- **Sibling order is not stable across removals.** Detaching a child swap-removes- it from `Children`, reordering the remaining siblings. Don't encode meaning in- `Children` order; use `position.z` or sorting layers for draw order.+ it from `Children`, reordering the remaining siblings. `Children` order is what UI+ layout and UI draw order follow, and what hierarchy-order layers+ (`Renderer.setTreeSortLayers`) stack by — so reorder those in the editor's Outliner rather than by detaching and+ re-attaching. For ordinary 2D+ draw order, don't encode meaning in it: use `position.z` or sorting layers.## Scalediff --git a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/gameplay/ai/advanced.mdxindex 44c79fed1..ef87f8a54 100644--- a/docs/astro/src/content/docs/gameplay/ai/advanced.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/advanced.mdx@@ -24,25 +24,26 @@ const grid = new NavGrid({ width: 32, height: 24, cellSize: 32 });const path = findPath(grid,- grid.worldToCell(hero.x, hero.y), // Cell — integer grid coordinates- grid.worldToCell(chest.x, chest.y),+ grid.worldToCell(hero), // Cell — integer grid coordinates+ grid.worldToCell(chest),{ diagonal: false },);if (path) {- const waypoints = pathToWorld(grid, path); // Vec2[] — cell centers, world pixels+ const waypoints = pathToWorld(grid, path); // Vec3[] — cell centers, world pixels}````findPath(grid, start, goal, opts?)` returns the `Cell[]` path inclusive of bothendpoints, or `null` when unreachable. A `Cell` is an integer grid coordinate`{ x, y }` (kept distinct from `Vec2` to flag cell space); convert with-`grid.worldToCell` / `grid.cellToWorld`, or turn a whole path into world-space+`grid.worldToCell(point)` / `grid.cellToWorld(gx, gy)`, or turn a whole path into world-spacewaypoints with `pathToWorld`.| `PathfindOptions` field | Default | Description ||---|---|---|| `diagonal` | `true` | Allow 8-connected diagonal moves. || `snapRadius` | `8` | When start/goal lands on a blocked cell, snap to the nearest walkable cell within this ring radius before searching; `0` disables snapping. |+| `clearance` | `0` | Cells of room the body needs on every step (`0` plans for a point). A `NavAgent`'s `radius` is turned into this for you. |`navGridFromTiles` builds the walkability mask from any tile reader — it is thecore under `navGridFromTilemapLayer`, which just plugs in `TilemapAPI.getTile`:diff --git a/docs/astro/src/content/docs/gameplay/ai/authoring.mdx b/docs/astro/src/content/docs/gameplay/ai/authoring.mdxindex aa6f4ea40..6c424cccb 100644--- a/docs/astro/src/content/docs/gameplay/ai/authoring.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/authoring.mdx@@ -6,8 +6,8 @@ description: "The intended workflow: register leaf logic once in code, then builThe intended workflow is **data, not code** for the graphs themselves — you registerthe leaf logic once, then build and tune the machines/trees visually:-1. In the **Content Browser**, create a **State Machine** (`.esfsm`) or **Behavior- Tree** (`.esbt`) asset and double-click it to open the node-graph editor.+1. In the **Content Browser**, use the create menu (**New State Machine** / **New Behavior+ Tree**) to make a `.esfsm` or `.esbt` asset and double-click it to open the node-graph editor.2. Add states/nodes, drag to connect them, and fill each leaf's **action** or**condition** with one of your registered names. Set transition conditions,triggers, and blackboard guards in the inspector.diff --git a/docs/astro/src/content/docs/gameplay/ai/behavior-trees.mdx b/docs/astro/src/content/docs/gameplay/ai/behavior-trees.mdxindex 23f259844..48f9bf9d0 100644--- a/docs/astro/src/content/docs/gameplay/ai/behavior-trees.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/behavior-trees.mdx@@ -47,16 +47,21 @@ registerBt('guard', {});```+The tree is **reactive**: composites re-evaluate their children from the first one every tick and+keep no memory of which child was running, so a higher-priority branch whose condition just became+true preempts a lower-priority branch that was `Running`. Only `wait` and `repeater` keep per-node+state (elapsed time, completed runs).+Node types:| Category | Type | Behavior ||---|---|---|-| Composite | `sequence` | Ticks children in order; fails on the first failure, succeeds if all succeed. |-| | `selector` | Ticks children in order; succeeds on the first success, fails if all fail. |-| | `parallel` | Ticks all children; `policy: 'one'` succeeds when any does, `'all'` (default) when all do. |-| Decorator | `inverter` | Inverts its child's Success/Failure. |-| | `succeeder` | Always reports Success. |-| | `repeater` | Re-runs its child `count` times (`0` = forever). |-| | `wait` | Runs for `seconds` before reporting Success. |-| Leaf | `action` | Runs the registered action `name`; its `Status` (or `Success` on void) propagates up. |+| Composite | `sequence` | Ticks children in order; fails on the first failure, succeeds if all succeed, and stops at the first child that is `Running`. |+| | `selector` | Ticks children in order; succeeds on the first success, fails if all fail, and stops at the first child that is `Running`. |+| | `parallel` | Ticks all children every frame. `policy: 'all'` (default) fails as soon as any child fails and succeeds when all succeed; `'one'` succeeds when any succeeds and fails only when all fail. Otherwise it reports `Running`. |+| Decorator | `inverter` | Inverts its child's Success/Failure; `Running` passes through. |+| | `succeeder` | Reports Success whenever its child finishes; `Running` passes through. |+| | `repeater` | Re-runs its child `count` times (`0` = forever). Each finished run, success or failure, counts as one; it reports `Running` between runs and `Success` after the last. |+| | `wait` | Reports `Running` for `seconds` (a leaf; it has no child), then `Success`. |+| Leaf | `action` | Runs the registered action `name`; its `Status` (or `Success` on void) propagates up. An unregistered name fails. || | `condition` | Returns `Success` when the registered condition `name` is true, else `Failure`. |diff --git a/docs/astro/src/content/docs/gameplay/ai/blackboard.mdx b/docs/astro/src/content/docs/gameplay/ai/blackboard.mdxindex 28f81fbda..0623102f4 100644--- a/docs/astro/src/content/docs/gameplay/ai/blackboard.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/blackboard.mdx@@ -21,7 +21,25 @@ registerAction('takeDamage', (ctx) => {| `has(key)` / `delete(key)` | Test / remove a key. || `fire(trigger)` | Fire a one-shot event; a transition keyed on it becomes enabled until taken. || `isFired(trigger)` / `consume(trigger)` | Test / clear a trigger. |+| `clearTriggers()` | Drop every pending trigger. |Blackboard values back the `guard` comparisons on FSM transitions, and the `trigger`mechanism is the Unity-style edge event: fired once, consumed by the transition thattakes it.++Game code outside a leaf reaches an agent's blackboard through two resources, which also+let it seed values or fire a trigger before the agent's first tick. The blackboard lives+as long as the entity and is never serialized:++```typescript+import { AiFsm, AiBt } from 'esengine/ai';++const fsm = app.getResource(AiFsm);+fsm.blackboard(enemy).set('health', 100);+fsm.fire(enemy, 'alarm'); // consumed by the agent's next enabled transition+fsm.state(enemy); // active state name, or null before the first tick++const bt = app.getResource(AiBt);+bt.blackboard(enemy); // a tree agent's blackboard+bt.status(enemy); // last root status+```diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdxindex 614da8f1c..4f91e9103 100644--- a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx@@ -38,8 +38,8 @@ export const setupNav = defineSystem([Res(Nav)], (nav) => {| `width` | number | Cell columns. || `height` | number | Cell rows. || `cellSize` | number | World pixels per cell (square). |-| `origin` | `Vec3` | World position of cell `(0,0)`'s center. Its `z` is the depth every waypoint comes back at. Defaults to `(0,0,0)`. |-| `walkable` | `Uint8Array` | Optional row-major `width*height` mask, `1` = walkable, `0` = blocked. Omitted → all walkable. |+| `origin` | `{ x, y, z? }` | World position of cell `(0,0)`'s center. Its `z` is the depth every waypoint comes back at. Defaults to `(0,0,0)`. |+| `walkable` | `ArrayLike<number>` | Optional row-major `width*height` mask, `1` = walkable, `0` = blocked. Omitted → all walkable. Copied in, not retained. |To derive a grid from a painted tilemap instead of hand-authoring the mask, use`navGridFromTilemapLayer` (which cells a layer's solid tiles block) or@@ -127,7 +127,7 @@ are two places and a route can use either.Each volume is baked once, on the first frame its geometry is available — a meshcollider contributes nothing until its asset has loaded, so the bake waits for it.`buildNavMesh(verts, indices, options)` is callable directly if a game wants to bake-on its own terms, and `collectNavGeometry(world, box)` is what gathers the triangles.+on its own terms, and `collectNavGeometry(world, { min, max, layers? })` is what gathers the triangles.<Aside type="caution">**One agent size per mesh.** `agentRadius` is baked in, not applied per query: the@@ -232,6 +232,10 @@ opening gives back exactly the ground that was there.is a job for the character controller it collides with, not for the bake.</Aside>+++*The baked walkable surface, filled and outlined in the viewport by **View ▸ Show Navigation Mesh**.*+### Seeing what was bakedThe volume's wireframe says where the bake looked. To see what it **found** while@@ -244,14 +248,19 @@ in front of you.The same picture from inside a running game comes from the `NavDebugDraw` resource:```typescript+import { NavDebugDraw } from 'esengine/ai';+app.getResource(NavDebugDraw).enabled = true;```+Its `showFaces`, `showBorders` and `showLinks` (all `true`) switch the face outlines, the red+stop edges and the `NavLink` connections on and off individually.+Every walkable face is outlined where it actually is — at the height of the groundfor a mesh, in the scene's own plane for a grid — and every edge the walkable world**stops** at is marked in red. Those edges are the only thing that explains a routegoing the long way round. Off by default (a surface is thousands of loops a frame),-and it stops after a few thousand faces: `cellSize` is the knob for seeing more of a+and it stops after 4096 faces: `cellSize` is the knob for seeing more of abig world.<Aside type="tip">@@ -279,8 +288,9 @@ distinguished from reaching the destination. It returns `{ path, status, reason| `partial` / `disconnected` | Stops on the reachable side of a disconnected region or closed passage. || `partial` / `insufficient-clearance` | A point can get through the grid, but the requested body cannot. || `unavailable` / `no-surface` | No navigation surface is installed. |+| `unavailable` / `building` | A surface update is pending (`nav.surfaceUpdatePending`). || `unavailable` / `start-unavailable` | No usable starting point was found. |-| `target-unavailable` | No usable destination was found; a mesh may still return a partial approach. |+| `unavailable` (grid) or `partial` (mesh) / `target-unavailable` | No usable destination was found; a mesh still returns a partial approach toward it. || `unavailable` / `radius-mismatch` | The requested body is wider than the mesh's baked radius. || `unknown` / `diagnostics-unavailable` | A custom surface implements only the legacy path API. |@@ -322,6 +332,10 @@ obstacle clearance. Reports record source and bundle identity, raw rebuild andquery times, and frame gaps. They measure navigation CPU work, excluding physicsgeometry collection, avoidance, rendering and the rest of the game frame.+++*A **Nav Agent**: how it moves, then where it is going.*+### Moving an agent`NavAgentSystem` serves planning requests in FIFO order across frames. By default@@ -386,9 +400,9 @@ stopNavAgent(world, entity);| `radius` | `0` | How wide the body is, in pixels. On a grid, planning routes it around anything it would not fit through; on a mesh this is the volume's `agentRadius` instead. || `arriveRadius` | `6` | Stop distance from the final goal. || `repathInterval` | `0.5` | Seconds between periodic replans; `0` disables periodic refresh. Target/topology changes and blocked-route recovery still replan. |-| `hasTarget` | `false` | Whether a destination is set (managed for you). |+| `hasTarget` | `false` | Whether a destination is set. Set by `setNavDestination`; cleared on arrival and by `stopNavAgent`. || `targetX`, `targetY`, `targetZ` | `0` | Current destination in world pixels. |-| `arrived` | `false` | Set true the frame the agent reaches its goal. |+| `arrived` | `false` | Set true when the agent reaches its goal; stays true until the next `setNavDestination`. |`setNavDestination` is safe to call every frame to chase a moving target — the agentreplans for changed targets/topology, stalled-route recovery or an elapsed periodic timer. Readdiff --git a/docs/astro/src/content/docs/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/gameplay/ai/overview.mdxindex 2b50de86d..c1e98d2f6 100644--- a/docs/astro/src/content/docs/gameplay/ai/overview.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/overview.mdx@@ -71,11 +71,18 @@ is the same programming model as a [`defineBehavior`](/docs/scripting/overview/)| `ctx.dt` | `number` | Frame delta in seconds. || `ctx.world` | `World` | Full world access for cross-entity reads. || `ctx.commands` | `Commands` | Deferred spawn/despawn, safe mid-tick. |+| `ctx.input` | `InputState` | Runtime input — the same state a `defineBehavior` reads. Empty (nothing pressed) when the host has no devices. || `ctx.blackboard` | `Blackboard` | This agent's AI data plane (see [Blackboard](/docs/gameplay/ai/blackboard/)). || `ctx.get(Comp)` | `ComponentData` | Read another component on **this** entity. || `ctx.set(Comp, data)` | `void` | Write a component on **this** entity. || `ctx.has(Comp)` | `boolean` | Whether this entity has `Comp`. |+An action is called as `(ctx, blackboard, arg?, params?, out?)` and a condition as+`(ctx, blackboard)`; `registerAction` also accepts a spec object+(`{ run, params, outputs, pure, touches, separator }`) that declares typed parameters, which the+editor then renders as real controls instead of one text box. `registerValue(name, spec)`+registers a pure name that only answers a question, for script graphs to read.+<Aside type="tip">Register your actions and conditions at module load (top-level, or in a`Schedule.Startup` system) so they exist before any agent ticks. The@@ -142,18 +149,21 @@ the agent entity (the same channel your code and the editor use):| `audio.stop` | action | Lower the `AudioSource` play flag. || `audio.finished` | condition | True once a non-looping clip has ended and is no longer playing. || `soundEvent.trigger` / `soundEvent.stop` | action | Start / stop the agent's `SoundEventSource`. |-| `property.set` | action | Write any component field on the agent (or another entity) by `Component.field` path and a value, e.g. `UIVisual.color.a`. |+| `property.set` | action | Write any component field on the agent (or another entity, via the optional `entity` parameter) by `Component.field` path and a value, e.g. `UIVisual.color.a`. The argument form is `path=value`; the value is read as JSON when it parses (`3`, `true`, `{"r":1}`), otherwise kept as a string. |Actions can carry an optional **string argument** — set it next to the actionname in the FSM state inspector (or on a BT action node). Built-ins use it fordata the component can't carry per-state, like which clip `spriteAnim.play`should switch to; your own registered actions receive it as their third-parameter: `(ctx, blackboard, arg) => …`.+parameter: `(ctx, blackboard, arg) => …`. An action that declares `params` also+receives the same values by name as the fourth.Together they make a **code-free cutscene state**: entering the state starts theclip, and its completion drives the transition out.```typescript+import { registerFsm } from 'esengine/ai';+registerFsm('intro', {initial: 'Cutscene',states: [@@ -212,12 +222,17 @@ enemy.add(MeleeAttack, { radius: 110, damage: 20, anchor: swordSocket });enemy.add(Health, { current: 50, max: 50 });```-| Field | What it does |-|---|---|-| `attackRange` | Ground-plane distance it closes to before it swings. |-| `attackInterval` | Seconds between swings. |-| `rotationSpeed` | How fast it turns to face, degrees/second. |-| `idleThreshold` | Speed under which the animator is told it is standing still. |+`Hunter` is a 3D component: it measures distance in the x/z ground plane, moves through+`CharacterController3D`, and sets the animator trigger named `attack`, so the entity+needs an `Animator` whose graph answers that trigger.++| Field | Default | What it does |+|---|---|---|+| `attackRange` | `110` | Ground-plane distance it closes to before it swings. |+| `attackInterval` | `1.6` | Seconds between swings. |+| `rotationSpeed` | `540` | How fast it turns to face, degrees/second. |+| `idleThreshold` | `8` | Speed under which the animator is told it is standing still. |+| `enabled` | `true` | When off, the hunter is skipped entirely. || `state` | Engine-written: `idle` / `chase` / `attack` / `dead`. || `cooldown` | Engine-written: seconds until it may swing again. |diff --git a/docs/astro/src/content/docs/gameplay/ai/perception.mdx b/docs/astro/src/content/docs/gameplay/ai/perception.mdxindex a7ec75541..cd1529b30 100644--- a/docs/astro/src/content/docs/gameplay/ai/perception.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/perception.mdx@@ -4,8 +4,14 @@ description: "A Perceiver senses nearby targets within a sight cone and writes w---A `Perceiver` scans for the nearest visible `PerceptionTarget` each frame and writes-the result into a `Perception` component on the same entity. Decisions read-`Perception`; sensing is just ECS data, not a side channel.+the result into a `Perception` component on the same entity (adding one if the entity has none). A+`Perceiver` never senses itself. Decisions read `Perception`; sensing is just ECS data, not a side+channel. The step runs in `PreUpdate`, in play mode only, so a decision system reads a fresh result+the same frame.++++*A **Perceiver** (above) and the **Perception** it writes (below, off until play).*```typescriptimport { Perceiver, PerceptionTarget, Perception } from 'esengine/ai';@@ -25,7 +31,7 @@ cmds.spawn()| Component | Field | Default | Description ||---|---|---|---|| **`Perceiver`** | `range` | `220` | Sight range in world pixels. |-| | `fovDegrees` | `360` | Field-of-view cone in degrees (`360` = omnidirectional). |+| | `fovDegrees` | `360` | Field-of-view cone in degrees, `0`–`360` (`360` = omnidirectional). || | `facingAxis` | `'x'` | Which of the entity's own axes the cone points down: `'x'` is screen-right (a flat scene), `'-z'` is where an imported 3D model faces. || | `losLayers` | `0` | 3D only: physics layers the line-of-sight ray may hit (`0` = every layer). || **`Perception`** | `visible` | `false` | A target is currently seen. |diff --git a/docs/astro/src/content/docs/gameplay/ai/state-machines.mdx b/docs/astro/src/content/docs/gameplay/ai/state-machines.mdxindex 4962a4ac6..2fe162d6a 100644--- a/docs/astro/src/content/docs/gameplay/ai/state-machines.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/state-machines.mdx@@ -52,7 +52,11 @@ registerFsm('guard', {```Each state carries up to three named hooks — `onEnter`, `onUpdate`, `onExit` — and a-list of `transitions`. A transition is enabled when **all** of its specified+list of `transitions`. A hook is a registered action name, or `{ name, arg?, params? }` when it+needs an argument. `onEnter` runs on the first tick the state is active (so the tick after a+transition into it), `onExit` runs as a transition is taken, and `onUpdate` runs on ticks where no+transition fires. At most one transition is taken per tick. A transition naming a condition that is+not registered is never enabled. A transition is enabled when **all** of its specifiedmechanisms hold; a transition with none is unconditional:| Transition field | Description |@@ -63,4 +67,5 @@ mechanisms hold; a transition with none is unconditional:| `guard` | One or more blackboard comparisons, AND-combined. |Guards compare a blackboard key with `==`, `!=`, `<`, `<=`, `>`, `>=`, `truthy`, or-`falsy` — e.g. `{ key: 'health', op: '<', value: 20 }`.+`falsy` — e.g. `{ key: 'health', op: '<', value: 20 }`. `value` is ignored by `truthy` / `falsy`;+a missing key reads as `undefined`, and the ordering operators compare numerically.diff --git a/docs/astro/src/content/docs/gameplay/markers.mdx b/docs/astro/src/content/docs/gameplay/markers.mdxindex 3a488a31f..2c10d8598 100644--- a/docs/astro/src/content/docs/gameplay/markers.mdx+++ b/docs/astro/src/content/docs/gameplay/markers.mdx@@ -69,7 +69,8 @@ position the player:```typescriptimport { defineSystem, Commands, Query, Marker, Transform } from 'esengine';-// Runs once: find every spawn marker and place the player at the first one.+// Find every spawn marker and place the player at the first one.+// Register it with app.addSystemToSchedule(Schedule.Startup, placePlayer) to run it once.const placePlayer = defineSystem([Commands(), Query(Marker, Transform)], (cmds, markers) => {for (const [entity, marker, transform] of markers) {if (marker.type !== 'spawn') continue;@@ -129,7 +130,9 @@ Keep sensors cheap in a busy world by putting triggers and the bodies that shoulnotice them on dedicated [collision layers](/docs/gameplay/physics/#collision-filtering),so each sensor's mask narrows what it considers. See[Collision & sensor events](/docs/gameplay/physics/#collision--sensor-events) for the-full event surface.+full event surface. The same crossings are also sent as per-entity `trigger_enter` /+`trigger_exit` events, which an [event binding](/docs/scripting/events/) on the area can+react to without code.## Imported from Tiled@@ -139,14 +142,14 @@ converge onto the same entities you author by hand — no separate structure to| Tiled object | Becomes ||---|---|| **Point** | A `Marker` (its `type` = the Tiled class, its custom properties → `Marker.properties`). |-| **Rectangle / ellipse / polygon / polyline** | A trigger **Region** — a `Marker` plus a matching sensor collider (or solid geometry when the object group is named `collision`). |+| **Rectangle / ellipse / polygon / polyline** | A trigger **Region** — a `Marker` (its `type` = the Tiled class) plus a static body and a matching collider: a box, a circle, a polygon of up to 8 vertices (more falls back to its bounding box) or an open chain. It is a sensor, or solid geometry when the object group is named `collision`. || **Tile object** (has a gid) | A sprite child of the map. |So one `Query(Marker)` reads spawn points whether you dropped them in the Estellaeditor or drew them in Tiled. (Imported objects are re-derived from the `.tmj` on eachload, so they exist in play mode only; hand-authored Markers are ordinary serialized-entities.) The raw object-group data is still available through `getTilemapSource`-if you need a shape's exact vertices.+entities.) The raw object-group data is still available through `tilemapSource(assets, ref)`+(from `esengine/tilemap`) if you need a shape's exact vertices.## Finding what is nearest@@ -159,7 +162,7 @@ const near = nearestMarkers(world, { x: player.x, y: player.y }, { radius: 60, tif (near[0]) promptFor(world.get(near[0].entity, Marker).type); // what the button says is the game's```-`type` takes one type or several, `has` keeps only markers whose `properties` carry every given key and value, `radius` and `limit` bound the answer, and `plane: 'xz'` measures on the ground.+`type` takes one type or several, `has` keeps only markers whose `properties` carry every given key and value, `radius` and `limit` bound the answer, and `plane: 'xz'` measures on the ground (then `from.y` is the ground z). Each result is `{ entity, distance, x, y }`.`nearestEntities(world, Component, from, options)` is the same over any component, with a `filter` on its data. An entity switched off with `Disabled` is not found. It is one pass overthe entities that carry the component each time it is asked, which a button press or a prompt refreshed once a frame affords over the hundreds of things a village holds.diff --git a/docs/astro/src/content/docs/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/gameplay/physics-3d.mdxindex 8e2f3769e..459ade277 100644--- a/docs/astro/src/content/docs/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/gameplay/physics-3d.mdx@@ -18,7 +18,8 @@ never asks for a 3D world never loads it.Like the 2D side module, the 3D world loads on its own in the editor and the webruntime when a scene uses a 3D body. In a custom app, add the plugin yourself; everyoption is optional (gravity defaults to `{ x: 0, y: -9.81, z: 0 }`, `fixedTimestep` to-`1/60`, `pixelsPerUnit` to `100`, `maxBodies` to `1024`):+`1/60`, `collisionSteps` to `1`, `pixelsPerUnit` to `100`, `maxBodies` to `1024`; `layerMasks` is covered under+[collision layers](#collision-layers)):```typescriptimport { Physics3DPlugin } from 'esengine/physics3d';@@ -43,7 +44,7 @@ cmds.spawn()|---|---|| `bodyType` | `Static` never moves, `Kinematic` is moved by hand, `Dynamic` is solved. || `gravityScale` | This body's share of world gravity. `0` is weightlessness, not slow falling. |-| `linearDamping` / `angularDamping` | How quickly motion bleeds off. |+| `linearDamping` / `angularDamping` | How quickly motion bleeds off (both default `0.05`; 2D bodies default to `0`). || `fixedRotation` | Freezes the orientation the body was given — what keeps a character from toppling. It does not right a body that starts tilted. || `layer` | Which of the sixteen [collision layers](#collision-layers) the body is in. || `continuousCollision` | Checks the whole path a step covers rather than where the body ended up. What a bullet needs; off by default, since it costs more. |@@ -56,6 +57,10 @@ cmds.spawn()| `SphereCollider3D` | `radius`. || `CapsuleCollider3D` | An upright capsule: `halfHeight` is the cylinder's half, with a cap of `radius` on each end, so the total height is `2 * (halfHeight + radius)`. |+Defaults: `halfExtents` `{ 0.5, 0.5, 0.5 }`, `radius` `0.5` (`0.3` on the capsule), `halfHeight` `0.5` —+world units, so a freshly added shape is small until you size it. All three also carry `friction` (`0.3`),+`restitution` (`0`) and `isSensor` (`false`).+Each of the three also takes an optional `center`: the shape's place from the entity origin, in worldunits (default `{ 0, 0, 0 }`). The body stays at the entity, so a dynamic body turns about its origin andan off-centre shape swings round it.@@ -99,6 +104,10 @@ cmds.spawn().insert(ConvexCollider3D, { mesh: 'assets/models/rock.esmesh' });```+++*The 3D Physics example with the physics debug draw on: every collider is outlined, whatever the body does.*+## Seeing a shapeThe viewport draws every 3D collider as a wireframe, turned the way its entity is —@@ -154,18 +163,25 @@ body the solver pushes and a character that sweeps are two answers to where anentity is. Set `velocity` from gameplay each step and read the result back.```typescript-const c = world.get(player, CharacterController3D);-c.velocity.x = input.axis('move') * 200;-if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;+const drive = defineSystem([Query(Mut(CharacterController3D)), Res(Input)], (q, input) => {+ for (const [, c] of q) {+ c.velocity.x = (input.isKeyDown('KeyD') ? 200 : 0) - (input.isKeyDown('KeyA') ? 200 : 0);+ if (input.isKeyPressed('Space') && c.isOnFloor) c.velocity.y = 500;+ }+});+app.addSystemToSchedule(Schedule.FixedUpdate, drive);```| Field | What it does ||---|---|| `velocity` | Desired velocity in world units/second. A positive `y` is a jump. |-| `stepHeight` | Tallest step it climbs instead of stopping at. `0` climbs nothing. |-| `snapDown` | How far it reaches down to stay on the floor over a crest. `0` is off. |-| `maxSlope` | Steepest ground it can stand on; beyond this it slides. |-| `pushForce` | How hard it shoves dynamic bodies it walks into. `0` moves nothing. |+| `radius` / `halfHeight` | The upright capsule that is swept (defaults `0.3` / `0.5`, world units), shaped like `CapsuleCollider3D`'s. |+| `stepHeight` | Tallest step it climbs instead of stopping at (default `0.4`). `0` climbs nothing. |+| `snapDown` | How far it reaches down to stay on the floor over a crest (default `0.5`). `0` is off. |+| `maxSlope` | Steepest ground it can stand on, radians (default `0.87`, about 50°); beyond this it slides. |+| `mass` | The character's mass in kilograms (default `70`), used when it shoves bodies. |+| `pushForce` | How hard it shoves dynamic bodies it walks into (default `5000`). `0` moves nothing. |+| `layer` | Which [collision layer](#collision-layers) it is in (0–15). || `isOnFloor` / `floorNormal` / `realVelocity` | Outputs, read after the step. |<Aside>@@ -180,6 +196,10 @@ if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;`0` walks into everything as if it were a wall.</Aside>+++*The **Character Controller 3D** and **Third Person Controller** of the Third Person example's player.*+## Third person`ThirdPersonController` and `ThirdPersonCamera` are the gameplay layer above a@@ -188,8 +208,8 @@ answer is what the animator hears.```typescript// Nothing to write. Both are components a scene declares.-player.add(ThirdPersonController, { moveSpeed: 320, jumpSpeed: 520 });-rig.add(ThirdPersonCamera, { target: player, distance: 420 });+world.insert(player, ThirdPersonController, { moveSpeed: 320, jumpSpeed: 520 });+world.insert(rig, ThirdPersonCamera, { target: player, distance: 420 });```The stick is read in the camera's GROUND plane, so an eye angled steeply down@@ -197,12 +217,27 @@ still walks the character across the floor. Pitch never reaches the character.| Field | What it does ||---|---|-| `moveSpeed` | Top speed on the ground, world units/second. |-| `acceleration` / `deceleration` | How fast it reaches that speed, and sheds it. |-| `rotationSpeed` | How fast it turns to face where it went, degrees/second. |-| `jumpSpeed` | Upward speed a jump starts with. `0` cannot jump. |-| `airControl` | How much of `acceleration` applies off the ground, 0..1. |-| `camera` | Whose forward the stick is read against. |+| `moveSpeed` | Top speed on the ground, world units/second (default `320`). |+| `acceleration` / `deceleration` | How fast it reaches that speed, and sheds it, units/second² (defaults `2400` / `3200`). |+| `rotationSpeed` | How fast it turns to face where it went, degrees/second (default `720`). |+| `jumpSpeed` | Upward speed a jump starts with. `0` (the default) cannot jump. |+| `airControl` | How much of `acceleration` applies off the ground, 0..1 (default `0.3`). |+| `cameraRelative` | Read the stick in the camera's ground plane (default `true`) rather than the world's. |+| `camera` | Whose forward the stick is read against; `0` (the default) means the first `ThirdPersonCamera` found. |+| `idleThreshold` | Speed under which the animator is told the character is standing still (default `8`). |++`ThirdPersonCamera` orbits a `target` under pointer control:++| Field | What it does |+|---|---|+| `target` | The entity it orbits; `0` leaves the camera inert. |+| `distance` | How far back it sits when nothing is in the way, world units (default `420`). |+| `yaw` / `pitch` | Turn about world up, and above the horizon (positive looks down), degrees (defaults `0` / `15`). |+| `minPitch` / `maxPitch` | Pitch limits, degrees (defaults `-30` / `70`). |+| `sensitivity` | Degrees per pixel of pointer travel (default `0.2`). |+| `followDamping` | How fast the position catches up, per second; `0` is rigid (default `12`). |+| `targetOffset` | Lifts the pivot off the target's origin so the eye frames the chest, not the feet (default `{ 0, 90, 0 }`). |+| `obstruction` / `obstructionRadius` / `obstructionLayers` | Pull in when something solid is between pivot and eye (default on), how fat the probe is (default `15`), and which layers it hits (`0` is all). |<Aside>The animator is told the speed the character REACHED, not the speed it asked@@ -231,14 +266,14 @@ or re-balanced without touching the other two.on a `customEvent` track — `attack-start`, `hit`, `attack-end`:```typescript-player.add(MeleeAttack, { radius: 70, damage: 25, anchor: swordSocket });-dummy.add(Health, { current: 100, max: 100 });+world.insert(player, MeleeAttack, { radius: 70, damage: 25, anchor: swordSocket });+world.insert(dummy, Health, { current: 100, max: 100 });```| Field | What it does ||---|---|-| `radius` | Radius of the sphere a `hit` beat tests, world units. |-| `damage` | What a landed blow takes off. |+| `radius` | Radius of the sphere a `hit` beat tests, world units (default `60`). |+| `damage` | What a landed blow takes off (default `25`). || `layers` | Physics layers the swing can reach; `0` is every layer. || `anchor` | The entity whose WORLD placement the query is centred on. || `attackId` | Engine-written: the live swing, `0` when none is running. |@@ -279,7 +314,7 @@ const hitSparks = defineSystem();```-A blow carries `target`, `source`, `amount` and the point it landed at — that+A blow carries `target`, `source`, `amount` and the point it landed at (`x`, `y`, `z`) — thatpoint cannot be recovered later, because by the time a spark is drawn the swinghas moved on. The bus is double buffered, so a blow sent this frame lands on thenext.@@ -339,6 +374,10 @@ the door swung without integrating the swing a second time.also how a scene says which is which.</Aside>+++*A **Hinge Joint 3D** on the 3D Physics example's door: the connected frame, the hinge axis and its angle limits.*+## Asking the world what is whereThe `Physics3D` resource answers spatial questions in world units.@@ -359,9 +398,12 @@ const occupants = q.overlapSphere(spawnPoint, 50);| Query | Answers ||---|---|-| `raycast` | The nearest body on a line. |-| `sphereCast` | The first body a moving sphere would meet. |-| `overlapSphere` / `overlapBox` | Every body already inside a volume. |+| `raycast(origin, direction, layerMask?)` | The nearest body on a line, as `{ entity, fraction, x, y, z, normalX, normalY, normalZ }`, or `null`. `direction` carries the ray's length. |+| `sphereCast(origin, radius, direction, layerMask?)` | The first body a moving sphere would meet, same shape, or `null`. |+| `overlapSphere(centre, radius, layerMask?)` / `overlapBox(centre, halfExtents, layerMask?)` | Every body already inside a volume, as `{ entity, x, y, z }[]`. |++`Physics3D` holds `null` until the physics module has finished loading, so a system+that asks in the first frames should check for it.<Aside>A layer mask of `0` means EVERY layer, not none: a caller that did not ask todiff --git a/docs/astro/src/content/docs/gameplay/physics.mdx b/docs/astro/src/content/docs/gameplay/physics.mdxindex 5ffc015b3..04ce2bdf8 100644--- a/docs/astro/src/content/docs/gameplay/physics.mdx+++ b/docs/astro/src/content/docs/gameplay/physics.mdx@@ -22,6 +22,20 @@ import { Physics2DPlugin } from 'esengine/physics';app.addPlugin(new Physics2DPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));```+The second argument is a `Physics2DPluginConfig`; every field is optional:++| Field | Default | Description |+|---|---|---|+| `gravity` | `{ x: 0, y: -9.81 }` | World gravity, m/s². |+| `fixedTimestep` | `1/30` | Physics step in seconds. The plugin also sets the app's fixed step to it, so `FixedUpdate` systems run at the same 30 Hz. |+| `subStepCount` | `4` | Solver substeps per step. |+| `contactHertz` / `contactDampingRatio` / `contactSpeed` | `30` / `10` / `3` | Contact softness and the maximum push-out speed (m/s). |+| `collisionLayerMasks` | none | Per-layer collision masks (index = layer 0–15) that replace each collider's own `maskBits`; the editor fills it from the collision matrix. |+| `enableSleep` | `true` | Let resting bodies sleep. |+| `enableContinuous` | `true` | Continuous collision for fast bodies. |+| `restitutionThreshold` | Box2D default | Minimum impact speed (m/s) that produces a bounce; `0` or less keeps the default. |+| `maxLinearSpeed` | Box2D default | Clamp on body speed; `0` or less keeps the default. |+<Aside type="note">Physics types are imported from **`esengine/physics`** (the API, plugin, events),while the components (`RigidBody2D`, colliders, `CharacterController2D`) come from the@@ -41,6 +55,9 @@ side of that boundary:| Solver-facing methods — `applyForce` / `applyImpulse`, `setLinearVelocity` / `getLinearVelocity`, `setGravity`, … | **Meters** (m/s, m/s²). || Spatial queries — `raycast`, `shapeCast*`, `overlapCircle` / `overlapAABB`, `moveCharacter` | **World pixels**, scaled by the live PPU. || `CharacterController2D.velocity`, `MotorJoint2D.linearVelocity` | World pixels per second. |+| Joint components' `anchorA` / `anchorB`, `length`, `minLength` / `maxLength`, `lowerTranslation` / `upperTranslation`; the pixel-taking joint methods (`setDistanceJointLength`, `setDistanceJointLimits`, `setPrismaticJointLimits`, `setWheelJointLimits`, …) and their getters | **World pixels.** Angles (`lowerAngle`, `motorSpeed` of a hinge) are radians. |+| Contact event positions and speeds — `contactX/Y`, `pointX/Y`, `approachSpeed` | World pixels, pixels per second. |+| `createRevoluteJoint`'s `anchorA` / `anchorB` | **Meters** — passed to the solver as is, unlike the joint component's pixel anchors. |`physics.getPixelsPerUnit()` returns the live PPU (pushed from the `Canvas` eachframe), so conversions never hard-code `100`:@@ -95,8 +112,8 @@ const spawnBall = defineSystem([Commands()], (cmds) => {### Colliders-All colliders share these fields; each adds its own shape parameters. Dimensions-are in meters.+Colliders share these fields; each adds its own shape parameters (the table below+lists the exceptions). Dimensions are in meters.| Shared property | Type | Default | Description ||---|---|---|---|@@ -113,10 +130,10 @@ are in meters.|---|---|| `BoxCollider2D` | `halfExtents` (`{0.5, 0.5}`), `radius` (rounded corner, `0.05`). || `CircleCollider2D` | `radius` (`0.5`). |-| `CapsuleCollider2D` | `radius`, `halfHeight`. |-| `SegmentCollider2D` | `point1`, `point2` (a one-sided edge). |-| `PolygonCollider2D` | `vertices: Vec2[]` (any shape, concave allowed), `radius` (rounded). |-| `ChainCollider2D` | `points: Vec2[]`, `isLoop` (static edge chain; no `density`/`isSensor`). |+| `CapsuleCollider2D` | `radius` (`0.25`), `halfHeight` (`0.5`). |+| `SegmentCollider2D` | `point1` (`{-0.5, 0}`), `point2` (`{0.5, 0}`) — a one-sided edge; no `offset`. |+| `PolygonCollider2D` | `vertices: Vec2[]` (any shape, concave allowed; default a unit square), `radius` (rounded, `0`); no `offset`. |+| `ChainCollider2D` | `points: Vec2[]` (at least 4), `isLoop` (`true`) — a static edge chain; `friction` defaults to `0.6`, and it has no `offset`, `density` or `isSensor`. |#### Concave polygons, and how many vertices you may draw@@ -231,15 +248,15 @@ for (const hit of hits) {const nearby = physics.overlapCircle(center, 64); // Entity[]const inBox = physics.overlapAABB(min, max); // Entity[]-const swept = physics.shapeCastCircle(/* … */); // sweep a shape+const swept = physics.shapeCastCircle(center, 16, { x: 100, y: 0 }); // ShapeCastHit[]```| Method | Returns | Description ||---|---|---|-| `raycast(origin, dir, dist, maskBits?)` | hit list | All hits along a ray, nearest first. |+| `raycast(origin, dir, dist, maskBits?)` | `RaycastHit[]` | All hits along a ray, nearest first. `dir` is a direction, `dist` is in pixels. || `overlapCircle(center, radius, maskBits?)` | `Entity[]` | Colliders overlapping a circle. || `overlapAABB(min, max, maskBits?)` | `Entity[]` | Colliders overlapping a box. |-| `shapeCastCircle` / `shapeCastBox` / `shapeCastCapsule` | hit | Sweep a shape and get what it would hit. |+| `shapeCastCircle(center, radius, translation, maskBits?)` / `shapeCastBox(center, halfExtents, angle, translation, maskBits?)` / `shapeCastCapsule(center1, center2, radius, translation, maskBits?)` | `ShapeCastHit[]` | Sweep a shape along `translation` and get everything it would hit. |Casts return `RaycastHit`s (`ShapeCastHit` is the same shape):@@ -294,6 +311,14 @@ const onHit = defineSystem([Res(Physics2DEvents)], (events) => {});```+The events carry world pixels (`contactX/Y`, `pointX/Y`) and pixels per second+(`approachSpeed`). The resource is published once per rendered frame and holds every+contact from all fixed steps in that frame. The same events are also re-sent per entity+as `collision_enter`, `collision_exit`, `collision_hit`, `trigger_enter` and+`trigger_exit` (the `Physics2DEventType` constants) — both participants receive one+carrying the other entity as `other`, which is what lets an authored event binding react+to a trigger zone without code.+| Event list | Fired when ||---|---|| `collisionEnters` / `collisionExits` | Two solid colliders begin / stop touching. |@@ -376,7 +401,8 @@ world.insert(platform, OneWayPlatform2D, { normal: { x: 0, y: 1 } }); // solid t````normal` is the solid-side direction in world space; `{ x: 0, y: 1 }` (the default)-means "solid top". Set `enabled: false` to turn the platform back into a normal solid.+means "solid top". Set `localSpace: true` (default `false`) to rotate the normal with the+body instead, including its parent's rotation. Set `enabled: false` to turn the platform back into a normal solid.In the editor, a one-way platform's collider gizmo grows an arrow along the solid-sidenormal, so which way it carries is visible at a glance.@@ -399,7 +425,8 @@ physics.destroyMouseJoint();```Only one drag is live at a time. Pass `{ hertz, dampingRatio, maxForce }` to tune the-spring's stiffness and grip.+spring's stiffness (`hertz`, default `7.5`), damping (`dampingRatio`, default `1`) and grip+(`maxForce`, default auto-sized from the body's weight). `cursorWorld` is in world pixels.## Character controller@@ -412,14 +439,15 @@ instead of sticking to it. It writes the resolved pose back and reports what ittouched:```typescript-import { defineSystem, Query, Mut, CharacterController2D } from 'esengine';+import { defineSystem, Query, Mut, Res, Time, Schedule, CharacterController2D } from 'esengine';-const drive = defineSystem([Query(Mut(CharacterController2D))], (q) => {+const drive = defineSystem([Query(Mut(CharacterController2D)), Res(Time)], (q, time) => {for (const [entity, cc] of q) {- cc.velocity = { x: input.moveX * 240, y: cc.velocity.y - 900 * dt }; // gravity+ cc.velocity = { x: moveX * 240, y: cc.velocity.y - 900 * time.fixedDelta }; // gravityif (cc.isOnFloor && jumpPressed) cc.velocity.y = 480;}});+app.addSystemToSchedule(Schedule.FixedUpdate, drive); // moveX / jumpPressed: your input```Give the entity a collider (the mover shape is derived from it — a box becomes a@@ -486,8 +514,9 @@ collider/joint gizmos under the Physics Show Flag (see## Best practices-- **Fixed timestep**: apply continuous forces and read `Physics2DEvents` *every frame*,- since physics substeps independently of the frame delta.+- **Fixed timestep**: apply continuous forces from a `FixedUpdate` system, and read+ `Physics2DEvents` *every frame* — the resource is published once per frame and holds the+ contacts from every fixed step in it.- **`bullet: true`** on fast, thin bodies (bullets, thin platforms) to avoid tunneling.- **`fixedRotation: true`** for characters so they don't topple.- **Colliders and the solver in meters, queries and the character controller indiff --git a/docs/astro/src/content/docs/gameplay/script-graphs.mdx b/docs/astro/src/content/docs/gameplay/script-graphs.mdxindex 1016decf0..45ca6eb19 100644--- a/docs/astro/src/content/docs/gameplay/script-graphs.mdx+++ b/docs/astro/src/content/docs/gameplay/script-graphs.mdx@@ -60,6 +60,18 @@ groups (**Events**, **Flow**, **Variables**, **Values**, **Actions**, **Queries*| **Queries** | Value-only nodes (no exec pin): `math.*` (add, subtract, multiply, divide, min, max, abs, clamp, lerp, random), `compare.*` (equal, less, greater), `logic.*` (and, or, not), `string.concat`, `property.get`, `entity.self`, `entity.byName`, `input.down` / `pressed` / `axis` / `pointer` — plus every registered condition. || **Graphs** | Every other callable graph in the project, to call it with a **Call graph** node (empty until a graph declares an input). |+A few nodes carry data worth knowing:++- **Every frame** outputs `dt`, the frame's delta in seconds.+- **On event** listens for an entity event by type (for example `trigger_enter` from a+ [Trigger Area](/docs/gameplay/markers/), or `click` from a button) and outputs `target`+ and `other` — the entity the event was sent to, and the one it names besides (the+ other body of a contact; `0` when it names nobody).+- **Sequence** has 1–16 pins (2 by default). **While** has a `body` and a `done` pin.+- **Delay** waits `seconds`, then continues. Entering a Delay that is already counting+ does nothing, so a fast caller cannot keep restarting it. A graph another graph calls+ cannot contain a Delay (a call finishes inside one step), and the graph reports it as a problem.+The menu lists the verbs by their registry name; once placed, a node is titledreadably (**Find entity by name**, **Key pressed**, **Set property**…) with the nameunderneath.diff --git a/docs/astro/src/content/docs/graphics/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdxindex 91cc9e3be..622d6cd74 100644--- a/docs/astro/src/content/docs/graphics/camera.mdx+++ b/docs/astro/src/content/docs/graphics/camera.mdx@@ -61,6 +61,8 @@ the camera by moving its entity's `Transform`.| `viewport` | Vec4 | `{0,0,1,1}` | Screen rect `x, y, w, h` in 0–1 (split-screen / PiP). || `clearFlags` | `ClearFlags` | `ColorAndDepth` | What to clear first: `Nothing` / `Color` / `Depth` / `ColorAndDepth`. || `pixelPerfect` | boolean | `false` | Snap to the world pixel grid for crisp pixel art (Orthographic). |+| `cullingMask` | number | all layers | Bitmask of sorting layers this camera renders (bit *i* = layer *i*). |+| `renderTarget` | number | `0` | `RenderTexture` handle this camera draws into instead of the screen (`0` = screen) — a minimap or mirror; set from a script at run time. || `showFrustum` | boolean | `false` | Editor-only: draw this camera's whole view volume, near face to far. Off, its gizmo outlines what it frames on the content plane — which is empty for a camera aimed away from it. |## Zoom & projection@@ -104,6 +106,10 @@ and unfitted views agree at the design aspect. Scale modes, worked letterboxexamples, and the `ScreenScaling` fields are covered in[Screen & Design Resolution](/docs/core-concepts/screen/).+++*The Third Person example: a camera that follows the character from behind.*+## Follow a targetAdd a `FollowTarget` to the camera and point it at an entity. The follow is a@@ -132,7 +138,9 @@ const follow = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {| `target` | Entity | `-1` | Entity to follow (`-1` = none). || `offsetX` | number | `0` | World-space X offset from the target. || `offsetY` | number | `0` | World-space Y offset from the target. |-| `deadzone` | number | `0` | Radius (world units) the target may roam before the camera moves. |+| `offsetZ` | number | `0` | World-space Z offset from the target (used by 3D follow). |+| `followZ` | boolean | `false` | Follow the target's depth too. Off for a flat scene, where the camera's z is how far back it stands. |+| `deadzone` | number | `0` | Radius (world units; a sphere in 3D) the target may roam before the camera moves. || `damping` | number | `0.25` | Smoothing time-constant in seconds (larger = slower; `0` = snap). |The data shape is exported as the `FollowTargetData` type. The follow system writes@@ -189,8 +197,8 @@ const pick = defineSystem([Res(CameraView), Res(Input)], (view, input) => {| Method | Returns | Description ||---|---|---|-| `screenToWorld(sx, sy)` | `{x, y} \| null` | Screen pixel → world position. |-| `worldToScreen(wx, wy)` | `{x, y} \| null` | World position → screen pixel. |+| `screenToWorld(sx, sy, planeZ = 0)` | `{x, y} \| null` | Screen pixel → world position on the plane at `planeZ`. Orthographic cameras ignore the plane; under a perspective camera pass the z the target sits on. |+| `worldToScreen(wx, wy, wz = 0)` | `{x, y} \| null` | World position → screen pixel. `null` when there is no camera or the point is at or behind the eye; outside the viewport still returns coordinates. || `getWorldMousePosition()` | `{x, y} \| null` | The cursor in world space. || `getWorldBounds()` | `{left, right, bottom, top} \| null` | The visible world rectangle. |@@ -260,7 +268,7 @@ flight, with shakes applied on top of the rendered view only. Its state| `currentMain` | `CameraPOV \| null` | `null` | The last resolved main POV, **pre-shake** — also what screen↔world conversion uses. || `shakes` | `ActiveShake[]` | `[]` | Active transient shakes (pushed by `shakeCamera`, dropped when they decay out). |-The remaining fields (`hasPending`, `pendingTarget`, `pendingTime`, `pendingCurve`,+The remaining fields (`timelineShot`, `timelineOwner` — set by a playing timeline's camera track — `hasPending`, `pendingTarget`, `pendingTime`, `pendingCurve`,`from`, `startTime`, `shakeSeq`) are the director's internal request/blendbookkeeping written by `setViewTarget`.diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 5828fcc49..4df2a728c 100644--- a/docs/astro/src/content/docs/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/graphics/drawing.mdx@@ -21,6 +21,10 @@ Rule of thumb: if the visual belongs to the *scene* (sorted, saved, inspectable)make it a component; if it belongs to a *frame* (debug, HUD-ish overlays,procedural effects), draw it in a callback.+++*The Drawing demo example, one picture per API: **Draw** (the radar), **Graphics** (the star) and a **MeshRenderer** ribbon.*+## Draw callbacksRegister a callback and it runs inside the render pass every frame, with the@@ -197,14 +201,13 @@ layout, so they pair directly with fragment-only `.esshader` materials.## Offscreen targets: `RenderTexture`-For minimaps, portraits, mirrors — and as the backing of-[cache-as-bitmap](/docs/graphics/sprites/) — `RenderTexture` allocates an offscreen+For minimaps, portraits and mirrors, `RenderTexture` allocates an offscreenrender target. Wrap draw commands in `begin`/`end` to render into it; theresulting `texture` is an ordinary texture handle usable anywhere (a`Sprite.texture`, `Draw.texture`, a material texture param).A whole **scene** goes into one by pointing a camera at it: set-`Camera.renderTarget` to the target's handle and that camera draws there instead+`Camera.renderTarget` to the target's render-target handle (`rt._handle`, not the `rt.texture` you put on a sprite) and that camera draws there insteadof the screen, before the screen cameras and without competing to be the mainview. Its own sorting layers (`Camera.cullingMask`) decide what it sees, so aminimap camera and the player's camera can look at the same world and showdiff --git a/docs/astro/src/content/docs/graphics/foliage.mdx b/docs/astro/src/content/docs/graphics/foliage.mdxindex b4aaa5aa9..38e398232 100644--- a/docs/astro/src/content/docs/graphics/foliage.mdx+++ b/docs/astro/src/content/docs/graphics/foliage.mdx@@ -23,9 +23,10 @@ replaces it. Nothing is baked.| `count`, `seed` | Plants per cell, and the seed: another seed grows the same plants in other places. || `minScale`, `maxScale` | Each plant is given a size between these. || `minUp`, `heightMin`, `heightMax` | Where plants grow: the least a place may face up (lower lets them onto slopes), and a band of world heights. |+| `waterDepth` | How deep under water a plant may stand: `0` (the default) keeps them on dry ground, reeds stand in the shallows. || `bladeHeight`, `bladeWidth` | Grass only: the size of a blade at scale 1. || `lodDistance`, `drawDistance` | Past the first a cell is drawn as its far version; past the second it is not drawn. |-| `cardU0`, `cardV0`, `cardU1`, `cardV1` | A mesh's far version is two crossed cards showing this rectangle of its texture. |+| `cardU0`, `cardV0`, `cardU1`, `cardV1` | A mesh's far version is two crossed cards showing this rectangle of its texture (`cardTent` `1` cuts them as tents, a conifer's outline, instead of rectangles). |If the scene has a [Terrain](/docs/graphics/terrain/), plants stand on it, keep off what is too steep, and wait for it to be built; with none, thearea is flat at the entity's height.diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex 7f6fefbac..d3b5d5732 100644--- a/docs/astro/src/content/docs/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/graphics/lighting.mdx@@ -55,6 +55,18 @@ const addSun = defineSystem([Commands()], (cmds) => {| `outerAngle` | `45` | Spot cone outer angle, degrees (falls to zero by here). || `shadowSoftness` | `0` | Shadow edge softness (light-source size); `0` = hard edge. || `shadowDistance` | `0` | Directional shadow reach; `0` = no directional shadow. |+| `layerMin` / `layerMax` | `-128` / `127` | The sprite layers a Point / Spot / Directional light reaches (see [Which layers a light reaches](#which-layers-a-light-reaches)). |+| `sourceAngle` | `0.53` | Directional only: the angular diameter of the source in degrees (the sun is 0.53); `0` = hard edge. |+| `meshShadows` | `false` | Cast a shadow map over 3D meshes (Directional, Spot, Point). |+| `shadowExtent` | `0` | Directional only: radius the mesh shadow map covers, centred on the camera; `0` fits the view. |+| `followEnvironmentSun` | `false` | Directional only: take direction and strength from the environment's sun, and light the sky without it. |+| `aimFollowedSun` | `false` | With `followEnvironmentSun`: aim by this light's `Transform` instead of the panorama's sun. |+| `environment` | — | Ambient only: a baked `.esenv` environment. |+| `environmentRotation` | `0` | Ambient only: turn the environment about the up axis, in degrees. |+| `drawEnvironment` | `false` | Ambient only: also draw the environment as the sky behind the scene. |+| `reflectionScale` | `1` | Ambient only: scale what baked reflection probes show (`1` = as baked). |+| `reflectionSaturation` | `1` | Ambient only: how much colour baked reflection probes keep (`0` = grey). |+| `bakedTint` | `{1,1,1,1}` | Ambient only: multiplies baked indirect light (lightmaps, probe volumes) — a day or weather scales the bake here. || `enabled` | `true` | Turn the light off without removing it. |## Light types@@ -80,6 +92,10 @@ const addSun = defineSystem([Commands()], (cmds) => {.insert(Light, { type: LightType.Ambient, intensity: 0.25 });```+++*The 2D Lighting example: a light pooling on dark boxes, with the rest of the scene unlit.*+## Many lightsA frame carries **112 lights** at once: sixteen the lighting loop reads for every pixel, and up to 96 more that are **tiled**. A street at night with@@ -92,12 +108,16 @@ follows the lights near a pixel, not the lights in the scene — a hundred lampsWhat to keep in mind:-- **Tiled lights do not cast 3D shadows.** (2D lights are different: the 2D shadow mask serves tiled lights too, see [2D shadows](#2d-shadows).) A shadow-casting light that does not make the sixteen is turned away (the Light Status in the editor says so), since the loop is the only+- **Tiled lights do not cast 3D shadows.** (2D lights are different: the 2D shadow mask serves tiled lights too, see [Casting shadows](#casting-shadows).) A shadow-casting light that does not make the sixteen is turned away (the Light Status in the editor says so), since the loop is the onlyplace a shadow map is read. Give the lights that matter shadows and let the many be the glow.- **`radius` is the reach.** The tile masks are built from it; a light with a huge radius touches every tile and costs like it.- Planar reflections are drawn with the sixteen only: their camera is not the one the tiles were made for.- 2D lights ride the same set, so a 2D scene with fifty torches is lit too.+++*A directional **Light**: its status and how many lights reach the frame (1 of 112) sit above the fields.*+## Which layers a light reachesA light lights every sprite it reaches, whatever layer the sprite is on. That is wrong for a lamp inside a hut, which has no business lighting the roof drawn over it.@@ -355,6 +375,7 @@ cmds.spawn()| `ShadowCaster2D` field | Default | Description ||---|---|---|| `size` | `{32,32}` | The occluder's size in world units. |+| `path` | `[]` | The occluder's outline in local units (three points or more, in order round the shape); when set it replaces the `size` box. || `enabled` | `true` | Toggle shadow casting. |Shadow **quality** is controlled on the light, not the caster:diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdxindex 7ce4660a4..8edccb0cf 100644--- a/docs/astro/src/content/docs/graphics/materials.mdx+++ b/docs/astro/src/content/docs/graphics/materials.mdx@@ -36,13 +36,15 @@ creates a material from a built-in template — the same list ships in code as| **Model** | `model` | What a glTF material says beyond base color: `u_normalMap`, `u_emissive`(`Map`), `u_occlusionMap` + `u_occlusionStrength`, `u_alphaCutoff`, `u_metallic` / `u_roughness` (+ `u_metallicRoughnessMap`), and the [shading layers](#shading-layers) — clear coat, sheen, anisotropy, translucency, thin film, index of refraction, transmission. Written by model import. || **Toon** | `toon` | Lit in steps: each lamp's light is cut into `u_bands` flat bands (`u_bandSoftness` softens the step), `u_shadeColor` is the colour of what no lamp reaches, a flat highlight of `u_specColor` above `u_specThreshold` (`u_specSize` is how glossy), and a rim (`u_rimColor`, `u_rimWidth`, `u_rimStrength`). A lamp's shadow is part of its step. Uses the sixteen lamps of the frame, and carries the lamp loop as Model does. || **Matcap** | `matcap` | What a picture of a lit sphere (`u_matcap`) shows, looked up by which way the surface faces the camera. No lamp is asked and no shadow is read: one texture read, which is why it suits a phone. `u_baseBlend` multiplies the base colour in. |-| **Terrain** | `terrain` | Four texture layers (grass, dirt, snow, rock) weighted by the [Terrain](/docs/graphics/terrain/) component and tiled by world position. || **Foliage** | `foliage` | Plants that sway in the wind: a vertex bend by weights painted in the vertex colour, two-sided and translucent, with an optional cutout texture. See [Foliage](/docs/graphics/foliage/). || **Skin** | `skin` | Soft diffuse by colour, a warm terminator, light through thin places, two shine lobes and a fuzz — without blurring the picture. See [Skin and hair](#skin-and-hair). || **Hair** | `hair` | Strand lighting: Kajiya-Kay diffuse, two shifted highlights along a flow map, and light through the strands. See [Skin and hair](#skin-and-hair). |+| **Eye** | `eye` | An eye from a depth map and an iris normal map: refraction through the cornea, an iris with fibres, limbal ring and pupil, a wrapped sclera and lid shadow. See [Skin and hair](#skin-and-hair). || **Water** | `water` | A horizontal body of water: travelling waves and ripples, the scene behind it bent and tinted by how deep the water is, reflections, and foam. See [Water](/docs/graphics/water/). |+The Terrain, Foliage, Water, Hair, Skin and Eye templates belong to modules (`esengine/terrain`, `esengine/foliage`, `esengine/water`, `esengine/character-shaders`) and are listed once the project installs the module.+A new material **references** its template by id — it stores `shader: "builtin:sprite-unlit"`and writes **no shader file** to disk. The engine compiles the built-in from in-code source(the runtime loader, the cook step, and the editor all resolve `builtin:<id>` the same way),@@ -108,7 +110,7 @@ it. Reflectance, the index of refraction and the specular scale, has no switch.- **Translucency is a shading term, not a blur.** It wraps light past the terminator and lets a lamp behind show through, but the light that enters at a point leaves at that point. The spreading itself is the Subsurface Scattering effect's, and it blurs the whole lit colour of the marked surface, so a sharp highlight on it is softened too.- **A layer's textures are not read.** Each layer is a constant for the whole material (the Model shader has no texture unit left for more); a glTF extension's maps are reported at import and its factors are kept.- **Sheen and thin film are fits.** Sheen's energy loss and the film's interference are analytic approximations in place of the lookup tables a production renderer bakes.-- **Not provided:** hair (a Marschner-style strand model), eyes, a separate normal map for the coat, layered materials beyond one coat.+- **Not provided:** a Marschner-style strand model, a separate normal map for the coat, layered materials beyond one coat.### In your own shader@@ -290,10 +292,11 @@ const v = Material.getUniform(tintMat, 'u_intensity');| `depthTest` | `false` | Test against the depth buffer. || `depthWrite` | `true` | Write to the depth buffer. || `cull` | `CullMode.None` | Triangle culling mode. |+| `depthBias` | `0` | Depth-buffer units toward the eye — decides which of two coplanar surfaces wins (a decal on a wall). || `switches` | `{}` | Enabled `#pragma switch` names — the static permutation this material was compiled for. |Each state field also has a runtime setter — `setBlendMode`, `setDepthTest`,-`setDepthWrite`, `setCull` — and `Material.createInstance(source)` builds a cheap+`setDepthWrite`, `setDepthBias`, `setCull` — and `Material.createInstance(source)` builds a cheapvariant that inherits everything from a parent material and stores only the diffsyou set on it.diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdxindex 24dd3ad80..4a0b1cffc 100644--- a/docs/astro/src/content/docs/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx@@ -54,6 +54,10 @@ several can stack in one frame at no extra target cost beyond the passes.| `edgeOutline` | A coloured line at silhouettes **and** creases: where the camera distance steps, and where the surface normal turns (needs surfaces that write a normal: lit meshes, Model, Toon) | `intensity`, `depthThreshold`, `normalThreshold`, `thickness`, colour `lineColor` || `grayscale` | Desaturate | `intensity` |+++*The Post-process Effects example: **Bloom** makes bright pixels bleed a soft glow.*+### Anti-aliasing before the chainGeometry edges are smoothed by **MSAA on the scene itself**, not by an effect: 4×@@ -197,7 +201,7 @@ blurred background does not bleed into it, while a blurred foreground spreads ovshift along their spiral by a different fraction at each pixel, which leaves a fine grain that `taa` averages away.**The bokeh** is the shape of the lens: `blades` of 3 or more makes the aperture a polygon of that many sides (0 is round), turned-by `bladeRotation`, and a bright point out of focus becomes that shape. `highlight` makes bright taps count for more, so a lamp+by `bokehRotation`, and a bright point out of focus becomes that shape. `highlight` makes bright taps count for more, so a lampout of focus is a bright shape and not a dim smear.### The G-buffer@@ -371,11 +375,12 @@ the camera's answer, clipped into the colours around the pixel. TAA needs sceneit cannot run with multisampling on a scene that has no depth resolve.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`, `outline`, and-`tonemap` (the ACES curve always applies) — so enable those only when you want them.+(`u_intensity`, `u_exposure`, …). A few effects are identity at their defaults+(`colorGrade`, `lensDistortion`, `lutGrade` with no table bound),+so adding them changes nothing until you dial them in. Most are visible the moment+you add them — `grayscale` (full desaturation), `vignette`, `bloom`, `blur` (intensity 2),+`chromaticAberration` (3), `pixelate` (4), `outline`, and `tonemap` (the ACES curve always+applies) — so enable those only when you want them.## HDR (linear color space)@@ -436,10 +441,10 @@ volume) or fade them in over a transition.| Property | Type | Default | Description ||---|---|---|---|-| `effects` | list | `[]` | `{ type, enabled, uniforms }` per effect. |+| `effects` | list | `[]` | `{ type, enabled, uniforms, textures?, colors? }` per effect — `textures` carries texture refs (LUTs, masks), `colors` colour params. || `isGlobal` | boolean | `true` | Apply everywhere vs. only inside the volume shape. || `shape` | `'box' \| 'sphere'` | `'box'` | Bounds shape for a local volume. |-| `size` | Vec2 | `{5, 5}` | Volume extents (local volumes). |+| `size` | Vec2 | `{5, 5}` | Half-extents of a local volume (a sphere uses `x` as its radius). An optional `z` is a box's half-depth; `0` or absent is unbounded in depth. || `priority` | number | `0` | Higher-priority volumes win where they overlap. || `weight` | number | `1` | Blend weight, 0..1 (fade the whole volume). || `blendDistance` | number | `0` | Falloff distance at the volume edge. |@@ -502,12 +507,12 @@ package carries only when its content uses one:| Group | Subpath | Effects ||---|---|---|-| Basic | `esengine/fx-basic` | blur, bloom, vignette, grayscale, colorGrade, lutGrade, agx, chromaticAberration, tonemap, fxaa, sharpen, lensDistortion, pixelate, outline, depthOutline, edgeOutline, filmGrain, motionBlur, lensFlare |-| Atmosphere | `esengine/fx-atmosphere` | mist2d, rain2d, skyAtmosphere, heightFog, distanceFog, rain |+| Basic | `esengine/fx-basic` | blur, bloom, vignette, grayscale, colorGrade, lutGrade, agx, chromaticAberration, tonemap, fxaa, sharpen, lensDistortion, pixelate, palette, outline, depthOutline, edgeOutline, filmGrain, motionBlur, lensFlare |+| Atmosphere | `esengine/fx-atmosphere` | mist2d, rain2d, fog2d, skyAtmosphere, heightFog, distanceFog, rain || Lighting | `esengine/fx-lighting` | ssao, gtao, ssr, ssgi, voxelGI, contactShadows, lightShafts, autoExposure, depthOfField, subsurface, taa |The export reads the effects a `PostProcessVolume` names (and a `Weather` or `TimeOfDay` component, which drive the atmosphere group) and imports-the groups they need. An effect you add **from a script** — `PostProcess.add('bloom')` — leaves no trace in the content, so import its group+the groups they need. An effect you add **from a script** — `getEffectDef('bloom')!.factory()` — leaves no trace in the content, so import its group(`import 'esengine/fx-basic'`) or set the module to **Include** in Project Settings; otherwise the effect says which group it needs when it isfirst used. The editor, and any entry that is not lean, carries all three.diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxindex f2a646c89..cf101bb2f 100644--- a/docs/astro/src/content/docs/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/graphics/sprites.mdx@@ -1,6 +1,6 @@---title: Sprites & Rendering-description: Draw 2D images with the Sprite component — textures, tint and transparency, size and pivot, flipping, sorting layers and draw order, y-sort and depth layers (2.5D), parallax — plus texture filtering, hit-testing, cache-as-bitmap, ShapeRenderer primitives, sprite filters, motion trails, and world-space bitmap text.+description: Draw 2D images with the Sprite component — textures, tint and transparency, size and pivot, flipping, sorting layers and draw order, y-sort and depth layers (2.5D), parallax — plus texture filtering, hit-testing, ShapeRenderer primitives, sprite filters, motion trails, and world-space bitmap text.---import { Aside } from '@astrojs/starlight/components';@@ -31,6 +31,10 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)(`assets.loadTexture(ref)`). In the editor you don't write this: drag an image from theContent Browser onto an entity, or set the Sprite's texture field in Details.+++*The Sprite Lab example: one white texture, eight tints, flips, and a sorting group.*+## Sprite fields| Field | Default | Description |@@ -40,6 +44,9 @@ Content Browser onto an entity, or set the Sprite's texture field in Details.| `size` | `{100,100}` | Rendered size in world units. || `pivot` | `{0.5,0.5}` | Anchor point the sprite rotates and scales about, as a fraction of its `size`. Values outside 0–1 sit off the sprite. || `layer` | `0` | Sorting layer — controls draw order (see below). |+| `order` | `0` | Order inside the sorting layer, −128…127 — higher draws on top (see below). |+| `maskInteraction` | `None` | Whether a [`SpriteMask`](#sprite-masks) cuts this sprite: `None` / `VisibleInside` / `VisibleOutside`. |+| `drawMode` | `Auto` | `Auto` infers from `tileSize` and the texture's 9-slice border; `Simple`, `Tiled` and `NineSlice` force one. || `flipX` / `flipY` | `false` | Mirror horizontally / vertically. || `material` | `0` | A custom [material](/docs/graphics/materials/) handle (`0` = the default sprite shader). || `lit` | `false` | Receive 2D lights with a flat normal — the one-flag path to lit sprites (a custom `material` overrides it). |@@ -208,7 +215,7 @@ that alpha do not mask, so a round mask cuts a circle.A mask reaches **forward** — it cuts what is drawn after it, in the order you alreadyarrange by layer and order. That is the order its stencil is written in, so a sprite atthe same layer *and* order as the mask is not cut at all. Turn on `limitRange` to stop-the reach at a stated layer and order.+the reach at the layer `rangeEndLayer` and order `rangeEndOrder` (inclusive).<Aside type="caution">Where two masks overlap, the **nearer** one decides — it wrote last, and that is what@@ -444,6 +451,10 @@ To make a sprite respond to `Light` lights, the simplest path is to setnormal maps or a fully custom look, use a **Lit-2D material** instead. Either way,see [2D Lighting & Shadows](/docs/graphics/lighting/).+++*The Effects Gallery example: the same sprite with different **SpriteFilter** effects applied.*+### Sprite filters (outline, glow, drop shadow)For the most common per-sprite effects you don't need to write a shader —@@ -484,6 +495,10 @@ cmds.spawn()`ShapeRenderer` shares the sorting `layer` and `color` conventions with `Sprite`.+++*The Trail Renderer example: the comet's long additive trail follows its path.*+## Motion trails**`TrailRenderer`** draws a world-space ribbon along an entity's recent path —diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdxindex 18f190681..08f009dc7 100644--- a/docs/astro/src/content/docs/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/graphics/terrain.mdx@@ -58,6 +58,10 @@ Infinite ground has no edge for rain to run off, so its erosion is the noise's ooctaves under it are already steep. That leaves smooth valleys between sharp ridges, much as rain would, at no cost beyond the noise.It paints no dirt channels.+++*The Terrain & Water example: layered ground, a river and the sea, all from the Terrain and Water components.*+## Terrain layersA terrain layer (a `.esterrainlayer` file; **New → New Terrain Layer** in the editor) is one kind of ground — grass, a path's dirt,@@ -87,6 +91,10 @@ What an artist delivers, per layer: the three textures, square, a power of two (layer's size, at most 1024, 512 on a minigame), tiling seamlessly, the normal and mask saved as data (not colour-managed). A layer'stextures are packed into texture arrays when the terrain is built, and again whenever a layer file or one of its textures is saved.+++*The **Terrain** component: its layers, then the shape of the ground and where its heights come from.*+## Layers and the Terrain materialThe four layers are grass, dirt, snow and rock. Every point of ground has a weight of each layer, from the splatmap or from how high@@ -264,7 +272,11 @@ to switch between.| `radius` | The planet's radius in metres. The planet stands at its entity, unrotated and unscaled. || `provider`, `world`, `generatorVersion`, `seed` | The generator the ground is made by (`registerPlanetProvider`), the world it belongs to as the game names it, its version and its seed. The same four are the same ground everywhere. || `cellSize`, `detail` | The finest cell of the ground's mesh in metres, and how far out the finest cells reach (above 1 is further). |-| `layerColor0`–`3`, `macroScale`, `macroVariation` | The four layers' colours (grass, dirt, snow, rock), and the wander in brightness laid over them. |+| `layerColor0`–`3`, `macroScale`, `macroVariation` | The four layers' colours (grass, dirt, snow, rock), and the wander in brightness laid over them: `macroScale` is its size in metres, `macroVariation` its strength (0 to 1). |+| `layers` | Up to four `.esterrainlayer` files the ground is drawn with; empty draws the four colours. |+| `collision`, `collisionDistance`, `collisionLayer`, `friction` | As on a flat terrain: whether bodies collide, how far round each moving body the ground is built, its layer and its grip. |+| `gravity` | How hard the planet pulls what is on it, in metres a second squared at the surface; `0` (the default) pulls nothing. |+| `sea`, `seaLevel`, `seaColor`, `seaOpacity` | Whether the planet has a sea, its height above the radius, its colour and how much of it covers what is under it (0 to 1). |A planet's provider answers for **directions**, not positions: it is handed unit directions from the planet's centre and the radius they are on, and gives back each one's height above the radiusand, if it paints, four layer weights. A sphere has no x and z, so a generator reads three-dimensional noise at the point's place, which has no seam and no pole.diff --git a/docs/astro/src/content/docs/graphics/time-of-day.mdx b/docs/astro/src/content/docs/graphics/time-of-day.mdxindex 23fc7643a..e7e225516 100644--- a/docs/astro/src/content/docs/graphics/time-of-day.mdx+++ b/docs/astro/src/content/docs/graphics/time-of-day.mdx@@ -15,12 +15,16 @@ Add a `TimeOfDay` component to one entity.| Field | What it does ||---|---|-| `hour` | The hour, 0–24 (12 is noon). The game advances it; set it in the editor to preview an hour. |-| `daySeconds` | Seconds a whole day takes while the game runs. 0 holds the hour where it is. |-| `latitude` | Where on the planet, in degrees (positive is north): how high the noon sun climbs. |-| `declination` | The season, −23.5 to 23.5: positive is summer in the north. |-| `north` | How far the world is turned from compass north (+Z) toward +X, in degrees — which way the sun rises. |-| `drive` | What the time drives: Lights, Sky, Fog, Exposure, Reflections. |+| `hour` | The hour, 0–24 (12 is noon, default 12). The game advances it; set it in the editor to preview an hour. |+| `daySeconds` | Seconds a whole day takes while the game runs. 0 (the default) holds the hour where it is. |+| `latitude` | Where on the planet, in degrees (positive is north): how high the noon sun climbs (default 40). |+| `declination` | The season, −23.5 to 23.5: positive is summer in the north (default 15). |+| `north` | How far the world is turned from compass north (+Z) toward +X, in degrees — which way the sun rises (default 0). |+| `drive` | What the time drives: Lights, Sky, Fog, Exposure, Reflections. All five by default. |++++*The **Time Of Day** component: the daylight curve with the hour marked, live readouts of the sun, and the bits it drives.*## In the editor@@ -74,4 +78,4 @@ The baked lighting and the baked reflection probes are one moment's: the bake is**not** from lights (lightmaps, probe volumes) does not move with the sun. A scene that is meant to pass through a whole day wantsits sun and its sky live — a lit-by-lights scene, or a baked one whose bake is mostly the sky's soft light — and the dimmingand tinting above do the rest. Windows and lamps do not light themselves at night; give them an emissive material or a light you-turn on with `currentTimeOfDay().daylight`.+turn on with `currentTimeOfDay()?.daylight`.diff --git a/docs/astro/src/content/docs/graphics/video.mdx b/docs/astro/src/content/docs/graphics/video.mdxindex 7e4f58841..e6b404435 100644--- a/docs/astro/src/content/docs/graphics/video.mdx+++ b/docs/astro/src/content/docs/graphics/video.mdx@@ -117,7 +117,8 @@ const playIntro = defineSystem([Res(VideoPlayer)], (video) => {| `onReady` / `onEnded` / `onError` | callback | Lifecycle hooks. |`video.play(source, options)` takes the same options as the component-(`autoplay`, `loop`, `muted`, `volume`, `playbackRate`); `video.stop(handle)` ends+(`autoplay`, `loop`, `muted`, `volume`, `playbackRate`) but with its own defaults:+`autoplay: true`, `loop: false`, `muted: false`, `volume: 1`, `playbackRate: 1`; `video.stop(handle)` endsone stream and `video.stopAll()` ends every stream.## Import settings & cooked videodiff --git a/docs/astro/src/content/docs/graphics/weather.mdx b/docs/astro/src/content/docs/graphics/weather.mdxindex 90f40d4ee..a5649fc31 100644--- a/docs/astro/src/content/docs/graphics/weather.mdx+++ b/docs/astro/src/content/docs/graphics/weather.mdx@@ -21,17 +21,21 @@ Add a `Weather` component to one entity.| Field | What it does ||---|---|-| `preset` | The weather the scene is in: Clear, Mist, Overcast, Rain, Storm. |-| `target` | The weather it is turning into; None for none. |-| `progress` | How far along that turn it is (0–1). The game advances it; set it in the editor to preview a half-turn. |-| `duration` | Seconds a turn takes. |-| `sequence` | Presets to cycle through by themselves, comma separated — `clear,mist,rain,clear`. Empty stays put. |-| `hold` | Seconds each weather of the sequence holds before the next turn. |-| `drive` | What the weather drives: Lights, Fog, Rain, Grade, Exposure, Reflections, Sound. |+| `preset` | The weather the scene is in: Clear, Mist, Overcast, Rain, Storm. Default Clear. |+| `target` | The weather it is turning into; None for none (the default). |+| `progress` | How far along that turn it is (0–1, default 0). The game advances it; set it in the editor to preview a half-turn. |+| `duration` | Seconds a turn takes (default 6). |+| `sequence` | Presets to cycle through by themselves, comma separated — `clear,mist,rain,clear`. Empty (the default) stays put. |+| `hold` | Seconds each weather of the sequence holds before the next turn (default 20). |+| `drive` | What the weather drives: Lights, Fog, Rain, Grade, Exposure, Reflections, Sound, Wind. All by default. || `soundSource` | An entity with a looping `AudioSource` — the sound of the rain. The weather raises its `playing` while it rains and sets its volume to the authored one times how hard it rains. |A turn is eased, so it starts and ends gently, and a finished turn lands on its target and clears itself.+++*The **Weather** component: the five weathers to switch between, and the transition below them.*+## In the editorThe Details panel shows the five built-in weathers as buttons (a project's own preset id still works and shows as Custom), the@@ -56,6 +60,7 @@ Post Process Volume, which the panel says.The ambient light carries `reflectionScale` and `reflectionSaturation` for exactly this: what baked probes show ismultiplied by the first and drained of colour by the second, and the weather turns both down.- **Sky.** A Sky Atmosphere effect takes the preset's `overcast` as cloud coverage and haze: the clouds thicken and join up, and the sun, moon and stars behind them are hidden by the same transmittance.+- **Wind.** The preset's `wind` scales how far plants sway (a Foliage material's `u_windStrength`, a Sway sprite's `u_swayWind`) and `waves` scales the height of the waves on every body of water, in what is drawn and in what the surface answers.- **Grade and exposure.** Colour Grade's saturation and contrast are scaled, and Auto Exposure's compensation raised.The effects are applied after the scene's volumes have blended, so a scene that fogs itself thinly stays thinner thandiff --git a/docs/astro/src/content/docs/performance/level-of-detail.mdx b/docs/astro/src/content/docs/performance/level-of-detail.mdxindex 3da44c7e1..7df3814cb 100644--- a/docs/astro/src/content/docs/performance/level-of-detail.mdx+++ b/docs/astro/src/content/docs/performance/level-of-detail.mdx@@ -36,6 +36,10 @@ world.insert(rock, LODGroup, {Remove the component and the full-detail mesh comes back — nothing else about therenderer changes.+++*A **LOD Group** in the editor: the level in use, the projected size of the entity, and the table of thresholds.*+## The sizes are fractions of the screen, not distances`lod1Size` and its siblings are the fraction of the **viewport's height** the@@ -97,6 +101,7 @@ A field at three levels reaches the GPU as roughly three draws, not as one per p- **Fill the slots in order** — `lod1`, then `lod2`, then `lod3`. A slot left emptyends the ladder, and anything after it is never reached (the engine warns).+- **Defaults.** `lod1Size` 0.5, `lod2Size` 0.25, `lod3Size` 0.1, `cullSize` 0.02, `hysteresis` 0.1 (0 to 1); the component's `enabled` switch, when off, always draws the renderer's own mesh.- **The sizes must descend.** `lod2Size` below `lod1Size`, and so on.- **`cullSize: 0`** disables culling entirely, so the group is never invisible.- **A group may have no stand-in at all.** With only a `cullSize` it draws the renderer's own mesh while it is big enough and nothing once it is smaller: the right group for a tuft of grass, which has no cheaper version and is not worth drawing past a distance.diff --git a/docs/astro/src/content/docs/performance/occlusion-culling.mdx b/docs/astro/src/content/docs/performance/occlusion-culling.mdxindex e41498d47..e222598ab 100644--- a/docs/astro/src/content/docs/performance/occlusion-culling.mdx+++ b/docs/astro/src/content/docs/performance/occlusion-culling.mdx@@ -35,7 +35,7 @@ counter reports and no test catches.Placing it:-- `halfExtents` is in **world units**, measured from the entity's position, and+- `halfExtents` (default 50 on each axis) is in **world units**, measured from the entity's position, andthe entity's **rotation** turns it. Scale is not read, the same as every otherextent in the engine.- The editor draws the box in the viewport, so you can size it against the walldiff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdxindex 161001b52..865a47b6c 100644--- a/docs/astro/src/content/docs/performance/profiling.mdx+++ b/docs/astro/src/content/docs/performance/profiling.mdx@@ -69,7 +69,7 @@ the render counters are the current frame's):| `triangles` | number | Triangles submitted this frame. || `sprites` | number | Sprites rendered this frame. || `text` | number | Text entities rendered this frame. |-| `spine` | number | Spine skeletons rendered this frame. |+| `skeletal` | number | Triangles posed by a skeletal runtime this frame (Spine and DragonBones both count here). || `meshes` | number | Meshes rendered this frame. || `culled` | number | Entities culled (not submitted) this frame. |@@ -109,7 +109,7 @@ addSystem(feedOverlay);The render counters in `FrameStats` come from `Renderer.getStats()`, which youcan also call directly (no stats plugin needed) — it returns a `RenderStats`with the same seven fields: `drawCalls`, `triangles`, `sprites`, `text`,-`spine`, `meshes`, `culled`.+`skeletal`, `meshes`, `culled`.```typescriptimport { Renderer } from 'esengine';@@ -415,32 +415,34 @@ if (Renderer.hasCapturedData()) {for (const dc of capture!.drawCalls) {console.log(`#${dc.index} ${RenderType[dc.type]} tex=${dc.textureId} ` +- `tris=${dc.triangleCount} entities=${dc.entityCount} ` ++ `tris=${dc.triangleCount} entities=${dc.entities.length} ` +`break=${BatchBreak[dc.breakReason]}`);}- console.log(`${capture!.cameraCount} camera pass(es)`);+ console.log(`${capture!.passCount} pass(es)`);}```-`FrameCaptureData` is `{ drawCalls: DrawCallInfo[], cameraCount }`. Each+`FrameCaptureData` is `{ drawCalls: DrawCallInfo[], passCount }`. Each`DrawCallInfo`:| `DrawCallInfo` field | Description ||---|---|| `index` | Draw call index within the frame (submission order). |-| `cameraIndex` | Which camera pass issued it. |+| `pass` / `passKind` | Which pass of the frame drew it, in the order the passes ran, and whether it is a camera's scene (`CapturePass.Scene`) or the screen-space overlay (`CapturePass.Overlay`). || `stage` | Render stage (`RenderStage`: Background / Opaque / Transparent / Overlay). || `type` | What kind of content (`RenderType`, below). || `blendMode` | Blend mode id in effect. || `textureId` / `materialId` / `shaderId` | GPU resources bound for the call. |-| `vertexCount` / `triangleCount` | Geometry submitted. |-| `entityCount` / `entityOffset` / `entities` | The entity ids batched into this call. |+| `indexCount` / `triangleCount` | Geometry submitted. |+| `instanceCount` | Instances in the call; 0 for a draw that is not instanced. |+| `entities` | The entity ids the draw was made from, in draw order; an item with no entity (a glyph run, a gizmo) is not listed. || `layer` | Render layer of the batch. || `breakReason` | Why this call started instead of joining the one before it (`BatchBreak`, below). || `scissorX/Y/W/H`, `scissorEnabled` | Scissor rect state (UI masks). || `stencilWrite` / `stencilTest` / `stencilRef` | Stencil state (mask writers/readers). || `textureSlotUsage` | Texture slots the batch consumed. |+| `textures` | Every texture the draw bound, slot 0 first; `textureId` is the first. |`RenderType` tells you what a call drew: `Sprite`, `Spine`, `Mesh`,`ExternalMesh`, `Text`, `Particle`, `Shape`, `UIElement`.diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdxindex a93770369..f7ae3a86d 100644--- a/docs/astro/src/content/docs/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx@@ -29,9 +29,10 @@ to.| Group | Settings ||---|---|-| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance |-| Shadows | Atlas size, Cell size, Cascades, Distance |+| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, 2D rain shelter mask |+| Shadows | Atlas size, Cell size, Cascades, Distance, 2D soft-shadow samples || Reflections and particles | Planar reflection scale, max size and updates per second, Particle limit |+| Water | Water waves (1 to 4), Water ripple cells, and the Displacement, Mirror and Caustics switches. Shown once the level is not Off and the water module is in the build || Post-processing | A master switch, and a tick for each effect that runs at this level |Each level starts from the engine's own values for it, and **only what you change is saved** in `project.esproject`@@ -42,7 +43,7 @@ touched it, and a row set back to its level's default is not a difference.far cheaper at 1080p and somewhat softer, it needs a post-process volume on the camera, and the MSAA row is hidden while itis chosen. **Depth pre-pass** draws the opaque scene twice, depth alone first, so each pixel is shaded once for the surface infront. It pays where surfaces overlap (a wood, a crowd of foliage) on a GPU that shades what it rasterises; on one that defers-shading to the end of a tile it is geometry paid for twice. It is off at Low and on at Medium and High. The pre-pass and the colour pass declare the vertex position invariant on both WebGL2 and WebGPU, so a surface's colour always passes the equal-depth test against its own depth, including on Metal; a Mac that showed dark triangles on terrain with the pre-pass on needs nothing but an up-to-date build.+shading to the end of a tile it is geometry paid for twice. It is off at Low and on at Medium and High. The default anti-aliasing is MSAA at Low (one sample) and High (4), and Temporal at Medium. The pre-pass and the colour pass declare the vertex position invariant on both WebGL2 and WebGPU, so a surface's colour always passes the equal-depth test against its own depth, including on Metal; a Mac that showed dark triangles on terrain with the pre-pass on needs nothing but an up-to-date build.<Aside type="note">A row's "default" is the default of the level it is showing, so the same number can be a change at Low and the default@@ -63,7 +64,7 @@ Occlusion or Auto Exposure, is removed whole. The manifest holds the effects lef"quality": { "mode": "auto", "profiles": { "low": { "skipEffects": ["ssr", "taa", "depthOfField"] } } }```-By default Low leaves out reflections, temporal anti-aliasing, depth of field and light shafts; Medium leaves out+By default Low leaves out reflections, temporal anti-aliasing, depth of field, light shafts, motion blur, lens flare, GTAO, subsurface scattering and voxel GI; Medium leaves outreflections and depth of field; High leaves out nothing. These defaults follow the work each effect does per pixel; theyare **not** measured on weak devices. The editor's `fx-cost` check measures each effect's cost on the machine it runs on,which is a way to find out what yours costs before choosing what a level skips.diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdxindex 7000be355..84e54504c 100644--- a/docs/astro/src/content/docs/performance/static-batching.mdx+++ b/docs/astro/src/content/docs/performance/static-batching.mdx@@ -24,7 +24,7 @@ In the editor, select the meshes and choose **Static Batch** from the outliner'slayer, culling and lighting flags — and by the optional **group** on the component, so tworooms can be kept apart.- Each group is cut into cells of the world, so a batch is a neighbourhood and culling still- has something to cull. A cell never holds more than 262,144 vertices.+ has something to cull. A cell is 1,600 world units on a side by default and never holds more than 262,144 vertices.- The marked entities stay as authored: scripts find them, colliders collide and the editorpicks them. Only their drawing moves to the merged mesh, which is an entity of its own.- A marked mesh **does not move** after it has been merged. Destroying one is supported (its@@ -43,6 +43,9 @@ runs, and in the profiler's **Static batch** section.| Blended | Its result depends on drawing order, and merging is the loss of order. || Moves | A dynamic body or a character controller: a batch bakes where a mesh stands. || Baked light | The scene has probes or a bake, and a merged mesh cannot keep each part's own. |+| No mesh yet | Nothing is behind the handle (still loading, or the mesh failed), so there is nothing to copy. |+| Switched off | Nothing is drawn, so there is nothing to merge. |+| Vertex layout | Positions or normals that are not 32-bit floats, which the merge cannot transform. || Alone in its group | Merging one mesh saves nothing and costs memory. |## What it costsdiff --git a/docs/astro/src/content/docs/scripting/events.mdx b/docs/astro/src/content/docs/scripting/events.mdxindex 8425eda5f..b18b3f881 100644--- a/docs/astro/src/content/docs/scripting/events.mdx+++ b/docs/astro/src/content/docs/scripting/events.mdx@@ -62,7 +62,7 @@ world.insert(button, EventBinding, {| `params` | The action's declared parameters by name. || `arg` | The same input in canonical string form (`"tabs:settings"`). Either form runs. || `guard` | Registered condition that must pass for the row to run. |-| `once` | Run at most once per play session. |+| `once` | Run at most once, then stay inert until the scene reloads. || `enabled` | `false` keeps the row inert without deleting it. |Wires fire in play mode only — the editor never runs your actions while you author.@@ -93,9 +93,12 @@ These ship with the engine:|---|---|| `ui.setPage` | Switch a [UI controller](/docs/ui/controllers/) to a page. || `ui.setVisible` | Show/hide a UI subtree (`UINode.display`). |-| `property.set` | Write any component field, addressed as `Component.dot.path`. |+| `property.set` | Write any component field, addressed as `Component.dot.path`; an optional `entity` parameter writes another entity. || `fsm.fire` | Fire a trigger on the target's state machine. |-| `blackboard.set` | Set a blackboard value. |+| `blackboard.set` | Set a blackboard value (`key=value`; the value is read as JSON when it parses). |+| `scene.load` · `scene.reload` | Switch to a named scene, or restart the current one, with an optional fade in seconds. |+| `audio.play` · `audio.stop` | Drive the target's `AudioSource`; `audio.play` can name another clip. |+| `soundEvent.trigger` · `soundEvent.stop` | Drive the target's sound event source. || `timeline.play` · `timeline.pause` | Drive a [timeline](/docs/animation/timeline/) on the target. || `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | Drive a sprite flipbook. |@@ -139,7 +142,7 @@ hears its buttons:Every pointer event (`press`, `release`, `click`, `pointer_move`, `press_cancel`) carries a `UiPointerEventData`:which pointer (`pointer`, -1 for the mouse), where it is in the world (`worldX`, `worldY`) and on the surface-(`screenX`, `screenY`, counted up from the bottom-left). The entity that was pressed is the one that hears+(`screenX`, `screenY`, in pixels counted up from the bottom-left) and in UI layout space (`layoutX`, `layoutY`). The entity that was pressed is the one that hears`pointer_move` for as long as the pointer is held, wherever it goes. A hold can be given up with`UIControlPointers.cancelHold(pointer, to?)`: the holder hears `press_cancel`, nothing clicks, and with `to` another entitytakes the rest of the gesture. An entity that is only a `ContentRect` plus an `Interactable` can be pressed.diff --git a/docs/astro/src/content/docs/scripting/input.mdx b/docs/astro/src/content/docs/scripting/input.mdxindex 1c48707c4..462a27973 100644--- a/docs/astro/src/content/docs/scripting/input.mdx+++ b/docs/astro/src/content/docs/scripting/input.mdx@@ -118,7 +118,9 @@ if (Controls.pressed('Jump')) { /* this-frame edge */ }| `axis2d(name)` | `{ x, y }` direction (normalized when longer than 1). |An action is `Button(…)`, `Axis1D(…)`, or `Axis2D(…)`; each takes any number of-bindings, and multiple bindings sum (then clamp), so keyboard and gamepad coexist:+bindings, so keyboard and gamepad coexist. A `Button` takes the strongest binding+(clamped to `0..1`); `Axis1D` and `Axis2D` sum their bindings, then clamp (to `-1..1`, or to+length 1):| Binding | Feeds | Meaning ||---|---|---|@@ -184,14 +186,19 @@ families the capture listens to: `keyboard` and `gamepad` default **on**,itself captured. Axis sources are never captured; rebinding targets discreteinputs.-`getBindings` / `setBindings` inspect and edit bindings programmatically, and+`getBindings` / `setBindings` inspect and edit bindings programmatically, `actions()` lists+the action names, `isListening()` says whether a capture is pending, and`cancelListen()` aborts a pending capture (it resolves with `null`).### Data-driven maps (`.inputmap`)A whole map also serializes as an asset: create a **New Input Map** in the-editor's Content Browser, then build the live map with `loadInputMapAsset(json)`-instead of `defineInputMap`. `toAsset()` produces the same format from code.+editor's Content Browser, then build the live map with `loadInputMapAsset(asset)` (the+parsed `InputMapAsset`) instead of `defineInputMap`. `toAsset()` produces the same format from code.++++*The Mobile Controls example: a **VirtualJoystick** and a **VirtualButton** drive the same input actions as the keyboard.*## Touch gestures@@ -283,9 +290,9 @@ consuming, so a broken tool can't swallow all input.| Group | Methods ||---|---|| Keyboard | `isKeyDown(code)`, `isKeyPressed(code)`, `isKeyReleased(code)`. |-| Mouse | `isMouseButtonDown(b)`, `isMouseButtonPressed(b)`, `isMouseButtonReleased(b)`; `mouseX` / `mouseY`, `scrollDeltaY`. |-| Touch | `isTouchActive(id)`, the `touches` map of active points. |-| Gamepad | `isGamepadConnected(pad?)`, `isGamepadButtonDown(btn, pad?)`, `isGamepadButtonPressed`/`Released(btn, pad?)`, `getGamepadAxis(axis, pad?)`. |+| Mouse | `isMouseButtonDown(b)`, `isMouseButtonPressed(b)`, `isMouseButtonReleased(b)`; `mouseX` / `mouseY` (or `getMousePosition()`), `scrollDeltaX` / `scrollDeltaY` (or `getScrollDelta()`). |+| Touch | `isTouchActive(id)`, `getTouches()` / `getTouch(id)` / `getTouchCount()`, the `touches` map of active points, and `touchesStarted` / `touchesEnded` for this frame's edges. |+| Gamepad | `isGamepadConnected(pad?)`, `isGamepadButtonDown(btn, pad?)`, `isGamepadButtonPressed`/`Released(btn, pad?)`, `getGamepadButtonValue(btn, pad?)` (analog `0..1`), `getGamepadAxis(axis, pad?)`, `getGamepads()`. || Pointer | `isPointerOverUI()` — the cursor is over a UI element. |Each `*Down` reads held state; `*Pressed` / `*Released` are the this-frame edges.@@ -313,6 +320,8 @@ the physical sensor or vibration motor. Requests return `ok`, `unavailable`,exceptions.```ts+import { Device } from 'esengine';+const off = Device.motion.onChange(sample => {if (sample.gravity) console.log(sample.gravity);});diff --git a/docs/astro/src/content/docs/scripting/math.mdx b/docs/astro/src/content/docs/scripting/math.mdxindex 5b28aa93a..a2345669e 100644--- a/docs/astro/src/content/docs/scripting/math.mdx+++ b/docs/astro/src/content/docs/scripting/math.mdx@@ -55,7 +55,8 @@ col.multiply(base, tint); // per-channel tint```- Build: `create`, `rgb`, `from255`, `fromHex` (throws on malformed input), `clone`.-- Blend: `lerp`, `withAlpha`, `multiply`, `scaleRgb`; serialize with `toHex`.+- HSV: `fromHsv(h, s, v, a?)` (hue in degrees, the rest `0..1`) and `toHsv`.+- Blend: `lerp`, `withAlpha`, `multiply`, `scaleRgb`; serialize with `toHex(c, withAlpha = false)`; compare with `equals`.## Scalars@@ -119,7 +120,7 @@ const delta = normalizeAngle(targetAngle - facing);| `quaternionToAngle2D(rz, rw)` | Z angle in radians from a quaternion's `z`/`w` (`2 * atan2(z, w)`). || `normalizeAngle(a)` | Wrap any angle to `(-π, π]` for shortest-turn comparisons. |-For full 3D rotations, the `q` namespace has `create`, `mul`, `axis(axis, rad)`, `normalize`, `conjugate`, `rotate(q, v)`, `fromEuler` / `toEuler`, `rotationTo(from, to)`, `setAngleZ` / `angleZ` and more.+For full 3D rotations, the `q` namespace has `create`, `mul`, `axis(axis, rad)`, `normalize`, `conjugate`, `rotate(q, v)`, `fromEuler` / `toEuler` (Euler angles in **degrees**), `rotationTo(from, to)`, `setAngleZ(q, deg)` (degrees) / `angleZ(q)` (radians) and more.For direction *vectors* instead of rotations, stay in `v2`: `fromAngle` /`angle` / `rotate`. A full worked example (turrets facing the cursor) is indiff --git a/docs/astro/src/content/docs/scripting/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdxindex 01d795463..948e77b5f 100644--- a/docs/astro/src/content/docs/scripting/networking.mdx+++ b/docs/astro/src/content/docs/scripting/networking.mdx@@ -37,6 +37,8 @@ socket.connect();| `readyState` | `'connecting' \| 'open' \| 'closing' \| 'closed'`. || `on(event, fn)` | Subscribe to `'open'` / `'message'` / `'close'` / `'error'`; returns an unsubscribe function. |+`createSocket` takes `{ url, protocols? }` (`protocols` is the WebSocket sub-protocol string or list).+## Typed messages & RPC — `NetChannel``NetChannel` wraps a transport with **routed, typed messages** and **request/response**,@@ -63,7 +65,8 @@ const stats = await channel.request<{ hp: number }>('getStats', { id: 'p1' }, 50| `on(type, handler)` | Subscribe to a message type; returns an unsubscribe fn. || `send(type, payload)` | Send a typed event. || `handle(type, handler)` | Register an RPC handler; returns an unsubscribe fn. |-| `request(type, payload, timeoutMs?)` | Send an RPC; resolves with the reply. |+| `request(type, payload, options?)` | Send an RPC; resolves with the reply. `options` is a timeout in ms, or `{ timeoutMs, idempotencyKey, codec }`. The default timeout is 10 s (`requestTimeoutMs` on the channel); `0` disables it. |+| `sendBinary(channel, bytes)` / `onBinary(channel, handler)` | Raw binary frames on a numbered channel. || `dispose(reason?)` | Tear down the channel and reject pending requests. |## State replication — multiplayer entities@@ -331,7 +334,8 @@ as JSON in a debugger.- **Use `NetChannel`** for anything beyond a trivial socket — routed types and RPCbeat a giant `'message'` handler switch.-- **Set an RPC timeout** so a lost reply rejects instead of hanging forever.+- **Mind the RPC timeout**: a lost reply rejects after 10 s by default; pass a shorter+ `timeoutMs` where the player is waiting, and avoid `0` (no timeout).- **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 `app.getResource(Net).role` (`'server'` /diff --git a/docs/astro/src/content/docs/scripting/overview.mdx b/docs/astro/src/content/docs/scripting/overview.mdxindex df6ab7b02..57e114ce0 100644--- a/docs/astro/src/content/docs/scripting/overview.mdx+++ b/docs/astro/src/content/docs/scripting/overview.mdx@@ -293,8 +293,22 @@ export const Thruster = defineBehavior('Thruster', {});```-Available phases include `Startup`, `PreUpdate`, `Update`, `PostUpdate`, and the fixed-trio `FixedPreUpdate` / `FixedUpdate` / `FixedPostUpdate`.+Available phases include `Startup`, `First`, `PreUpdate`, `Update`, `PostUpdate`, `Last`, and+the fixed trio `FixedPreUpdate` / `FixedUpdate` / `FixedPostUpdate`.++### Declaring what you touch++A behavior reaches other components through `ctx.get` / `ctx.set`, which the scheduler+cannot see. Left undeclared, it is treated as opaque and conflicts with every other+system. Pass `touches` (component names) so it can be ordered and parallelised:++```typescript+export const Drifter = defineBehavior('Drifter', {+ state: { speed: 60 },+ touches: { reads: ['Transform'], writes: ['Transform'] },+ update(ctx, dt) { /* … */ },+});+```## Timers@@ -332,15 +346,15 @@ builtin `Velocity` component instead of writing a movement system. The engineintegrates it into `Transform` every update in play mode:```typescript-import { Velocity } from 'esengine';--world.spawn()- .insert(Transform, { position: { x: 0, y: 0, z: 0 } })- .insert(Sprite, { texture: bulletTex })- .insert(Velocity, {- linear: { x: 240, y: 0, z: 0 }, // units per second- angular: { x: 0, y: 0, z: Math.PI }, // radians per second (z = 2D spin)- });+import { Velocity, Transform, Sprite } from 'esengine';++const bullet = world.spawn();+world.insert(bullet, Transform, { position: { x: 0, y: 0, z: 0 } });+world.insert(bullet, Sprite, { texture: bulletTex });+world.insert(bullet, Velocity, {+ linear: { x: 240, y: 0, z: 0 }, // units per second+ angular: { x: 0, y: 0, z: Math.PI }, // radians per second (z = 2D spin)+});```Entities with a `RigidBody2D` are skipped — the physics solver owns their transform,diff --git a/docs/astro/src/content/docs/scripting/save.mdx b/docs/astro/src/content/docs/scripting/save.mdxindex e2210b25a..10a81a5d1 100644--- a/docs/astro/src/content/docs/scripting/save.mdx+++ b/docs/astro/src/content/docs/scripting/save.mdx@@ -64,7 +64,8 @@ gap is caught immediately instead of silently corrupting data.The migration chain is also exported as a pure function — `migrateSaveData(version,data, currentVersion, migrations)` — for migrating data outside a `SaveManager`(e.g. in a unit test or a one-off import). `SaveManager` also accepts `storage`- and `now` options you can inject for deterministic tests.+ and `now` options you can inject for deterministic tests, and a `keyPrefix`+ (default `save:`) that namespaces its slots in the store.</Aside>## Plain key/value storagediff --git a/docs/astro/src/content/docs/ui/controllers.mdx b/docs/astro/src/content/docs/ui/controllers.mdxindex 4a4cd96e2..0dfce1d47 100644--- a/docs/astro/src/content/docs/ui/controllers.mdx+++ b/docs/astro/src/content/docs/ui/controllers.mdx@@ -36,7 +36,8 @@ getControllerPage(world, anyDescendant, 'tab'); // → 'shop'first page). `setControllerPage` / `getControllerPage` resolve the nearest controller ofthat name walking **self → ancestors**, so a gear on a leaf finds the controller on theroot. `setControllerPage` is a no-op on an unknown controller, an unknown page, or the-current page (it guards typos rather than failing).+current page (it guards typos rather than failing) and returns `true` only when it+actually switched.| `ControllerState` field | Description ||---|---|@@ -97,12 +98,12 @@ tween is in flight costs nothing, so a still screen with thousands of gears stay## A button, without bespoke stateThe built-in controller name **`$interaction`** is driven by pointer state-(`normal` / `hover` / `pressed` / `disabled`). Give an element an `$interaction`+(`normal` / `hover` / `pressed` / `disabled` / `focused`). Give an element an `$interaction`controller + an `Interactable` + a gear, and it gets its button states through thesame mechanism as everything else — this is what `createButton` itself is made of:```typescript-import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';+import { UIController, UIGear, Interactable, interactionController, gearBinding, EasingType } from 'esengine';world.insert(btn, UIController, { controllers: [interactionController()] });world.insert(btn, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });@@ -116,9 +117,13 @@ world.insert(btn, UIGear, {});```-`interactionController(pages?)` defaults to the four canonical pages. Because a gear can-drive *any* field, the same button can also gear its scale, a child icon's tint, or a-label — all four states, one mechanism.+`interactionController(pages?)` defaults to the five canonical pages. The driver picks+`disabled` (the `Interactable` is off), else `pressed`, else `hover`, else `focused`+(keyboard focus only — a click does not leave the button lit), else `normal`, and only+ever writes a page the controller lists; a page it does not own (say `'loading'`) is+left alone until your code switches back. Because a gear can drive *any* field, the same+button can also gear its scale, a child icon's tint, or a label — every state, one+mechanism.## Authoring in the editor@@ -131,7 +136,7 @@ Everything above can be authored visually — no code. Select any UI entity andits own plus each ancestor's (inherited rows carry the owner's name), so theroot's controllers stay switchable while you work on a geared leaf:-- **Add a controller** (the pointer-button preset adds `$interaction` with its four+- **Add a controller** (the pointer-button preset adds `$interaction` with its fivepages in one click), then manage **pages** as chips: click to preview, double-clickto rename, drag to reorder, and the hover × deletes — renames cascade into everygear binding that resolves to the controller, and deleting a page clears its@@ -173,6 +178,9 @@ runs `ui.setPage` when it is clicked, targeting the entity that owns the control{ "event": "click", "action": "ui.setPage", "params": { "controller": "tab", "page": "shop" } }```+(`params` also takes the two halves — `{ controller, page }` — which is what the editor's+two dropdowns write; `ui.setVisible` with `{ visible }` shows or hides a subtree the same way.)+**From a state machine** — the `ui.setPage` action lets a data-driven[FSM / behavior tree](/docs/gameplay/ai/overview/) (`.esfsm` / `.esbt`) switch a page with no code.Its argument is `"controller:page"`:diff --git a/docs/astro/src/content/docs/ui/data-binding.mdx b/docs/astro/src/content/docs/ui/data-binding.mdxindex 3e760d4cc..2bfceac66 100644--- a/docs/astro/src/content/docs/ui/data-binding.mdx+++ b/docs/astro/src/content/docs/ui/data-binding.mdx@@ -109,13 +109,15 @@ bindWidgetValue(world, events, entity, Component, field, signal, payloadKey?)auto-disposes on despawn).`payloadKey` names the value inside the `change` payload and defaults to the-field name:+field name (a text input has no value in its payload — read `TextInput.value`+from the `change` handler instead):| Widget | Component / field | `payloadKey` ||---|---|---|| Slider | `UISlider.value` | `'value'` (the default) || Toggle | `UIToggle.isOn` | `'isOn'` (the default) || Dropdown | `UIDropdown.selectedIndex` | `'index'` (pass explicitly) |+| Tab view | `UITabView.selectedIndex` | `'index'` (pass explicitly; the payload is `{ index, page }`) |A volume row — slider and label, both bound to one signal:diff --git a/docs/astro/src/content/docs/ui/debugger.mdx b/docs/astro/src/content/docs/ui/debugger.mdxindex b90307742..616acdcc9 100644--- a/docs/astro/src/content/docs/ui/debugger.mdx+++ b/docs/astro/src/content/docs/ui/debugger.mdx@@ -3,8 +3,6 @@ title: UI Debuggerdescription: Inspect a UI tree live — pick an element, record the events it receives, check text for overflow and pseudo-localization, and walk the Tab order.----import { Aside } from '@astrojs/starlight/components';-The **UI Debugger** is the editor's inspector for the UI tree. Where Details edits anentity's components, the Debugger answers *why a control looks or behaves the way itdoes*: what size layout gave it, what input reaches it, whether its text fits, and@@ -43,10 +41,10 @@ Every `Text` in the scene with its **measured** size next to its **box** and ovemode, so clipped or overflowing labels stand out. Counts for **texts**, **overflow**and **to review** sit at the top; **Issues only** hides the rest.-The **Preview** menu re-renders all text as **accent** (letters become accented-look-alikes — catches fonts missing those glyphs) or **long** (expanded so strings run-noticeably longer — catches layouts that only fit English). Preview never writes the-scene's text.+The **Preview** menu re-renders all text as **Original**, **Accents + 35%** (letters+become accented look-alikes and strings run about a third longer — catches fonts missing+those glyphs) or **Accents + 100%** (the same, doubled in length — catches layouts that+only fit English). Preview never writes the scene's text.## Focus order@@ -57,9 +55,3 @@ is a visible (keyboard) focus. Selecting a row only inspects the entity; it nevefocus.If nothing is listed, add `Focusable` to the controls and capture again.--<Aside>-The layout readout reports input *candidates*, not hit verdicts: an ancestor mask or an-occluding sibling can still stop input, so verify clipping and occlusion when a control-that looks reachable does not respond.-</Aside>diff --git a/docs/astro/src/content/docs/ui/interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdxindex 8addf0ab7..a2c432041 100644--- a/docs/astro/src/content/docs/ui/interaction.mdx+++ b/docs/astro/src/content/docs/ui/interaction.mdx@@ -28,7 +28,7 @@ and is **read-only for your logic**: query it, never mutate it.| `UIInteraction` field | Description ||---|---|| `hovered` | The pointer is over the node. |-| `pressed` | The primary button is held down on the node. |+| `pressed` | A pointer (mouse button or touch) is held down on the node. || `justPressed` | Became pressed this frame (one-frame edge). || `justReleased` | Released this frame on the node that was pressed (one-frame edge — a click). |@@ -53,20 +53,28 @@ guard that keeps a button click from also firing a world click.The `UIEvents` resource is a pub/sub queue with DOM-like bubbling. Widgets andthe interaction systems emit the standard set; the type space is **open** —-emit any string you like (a ListView emits `'item_selected'`).+emit any string you like.| `UIEventType` constant | String | Emitted when | Bubbles ||---|---|---|---|| `Click` | `'click'` | Press and release on the same node. Keyboard Enter/Space also emits it (on the target only, no bubble). | Yes |-| `Press` / `Release` | `'press'` / `'release'` | Primary button down / up on a node. | Yes |+| `Press` / `Release` | `'press'` / `'release'` | A pointer (mouse button or touch) goes down / up on a node. `data` is a `UiPointerEventData` (`pointer` id plus `worldX/Y`, `layoutX/Y`, `screenX/Y`). | Yes |+| `PointerMove` | `'pointer_move'` | A pointer holding the node moved; same `data`. | Yes |+| `PressCancel` | `'press_cancel'` | A pointer's hold ended without a release — the system cancelled it, or something (a scroll area deciding a drag is a drag) took the gesture over. No click follows. | Yes || `HoverEnter` / `HoverExit` | `'hover_enter'` / `'hover_exit'` | The hit node changed. | No |+| `Shown` / `Hidden` | `'shown'` / `'hidden'` | The node (or an ancestor) stopped / started being `display: None`. Only watched while something listens for them. | No || `Focus` / `Blur` | `'focus'` / `'blur'` | Keyboard focus moved (see [Focus](#focus--keyboard)). | No || `Change` | `'change'` | A widget's value changed (toggle, slider, dropdown…). | No || `Submit` | `'submit'` | A text input confirmed (Enter). | No || `DragStart` / `DragMove` / `DragEnd` | `'drag_start'` / `'drag_move'` / `'drag_end'` | The drag system (see [Drag](#drag--drop)). | No |-| `Scroll` / `Select` / `Deselect` | `'scroll'` / `'select'` / `'deselect'` | Scroll views and list selection. | No |-Bubbling events climb the parent chain, revisiting every **enabled**+`Scroll`, `Select` and `Deselect` (`'scroll'` / `'select'` / `'deselect'`) are reserved+names — no built-in widget emits them, so emit them yourself if you want them+(`createListView` has no selection model; scroll changes arrive through the+handle's `scroll.onScroll` / `onScroll` option). The tree view emits `change` and+`drop_request`.++Bubbling events (`click`, `press`, `release`, `pointer_move`, `press_cancel`) climb the parent chain, revisiting every **enabled**`Interactable` ancestor; an ancestor with `blockRaycast` ends the walk, and anyhandler can call `stopPropagation()`. Each `UIEvent` carries:@@ -127,7 +135,8 @@ layout pass), else translating the `Transform`.| `enabled` | `true` | Master switch. || `dragThreshold` | `5` | Screen px of travel before the drag starts (keeps clicks clickable). || `lockX` / `lockY` | `false` | Freeze an axis (a horizontal-only slider card). |-| `constraintMin` / `constraintMax` | `null` | World-space clamp corners, or `null` for unbounded. |+| `constrainMin` / `constrainMax` | `false` | Turn the lower / upper clamp on. A flag, not a `null` bound, because `0` is a usable limit. |+| `constraintMin` / `constraintMax` | `{0, 0}` | World-space clamp corners (`Vec2`), applied to both axes while the matching `constrain*` flag is on. |While dragging, the transient `DragState` component carries the live geometry(all world-space):@@ -183,7 +192,7 @@ focused entity; `Focusable.isFocused` mirrors it per entity, and `focus` /| Interaction | Behavior ||---|---|-| Click a focusable | Focuses it. |+| Click a focusable | Focuses it — but not *visibly*: the control keeps the look the pointer left it. Only Tab (keyboard) focus puts the control on its `focused` page, and shows tab-view and tooltip focus hints. || Click empty space / press `Escape` | Clears focus. || `Tab` / `Shift+Tab` | Cycles the focus ring — sorted by `tabIndex` (ties in discovery order), skipping disabled `Interactable`s and anything hidden by `display: none` up its tree. || `Enter` / `Space` on the focused control | Emits `click` — activates buttons, toggles, dropdowns. Text inputs keep these keys for editing. |@@ -227,7 +236,7 @@ const tooltip = defineSystem([GetWorld(), Res(UICameraInfo)], (world, camera) =>| Helper | Returns | Use ||---|---|---|-| `uiHitTestWorld(world, x, y)` | Topmost **interactable** entity or `null` | The runtime raycast — same rules the interaction system uses. |+| `uiHitTestWorld(world, ray, screenRay?)` | Topmost **interactable** entity or `null` | The runtime raycast — same rules the interaction system uses. Takes a `WorldRay` (`{ origin, dir }`), not x/y; for a plain point use `uiPickWorld`. || `uiPickWorld(world, x, y)` | Topmost UI entity or `null` | Editor-style pick, ignores `Interactable`. || `uiPickAllWorld(world, x, y)` | All UI entities under the point, most specific first | Pick-through menus, debug overlays. || `screenToUiWorld(camera, glX, glY)` | `{ x, y }` world point | Project a GL-oriented screen point through the UI camera. |diff --git a/docs/astro/src/content/docs/ui/layout.mdx b/docs/astro/src/content/docs/ui/layout.mdxindex cbd962460..951900262 100644--- a/docs/astro/src/content/docs/ui/layout.mdx+++ b/docs/astro/src/content/docs/ui/layout.mdx@@ -64,6 +64,8 @@ isAuto(d) // true when d is the auto length|---|---|---|---|| `position` | `UIPositionType` | `Relative` | `Relative` = in the flex flow; `Absolute` = out of flow, placed by insets. || `display` | `UIDisplay` | `Flex` | `None` removes this node **and its whole subtree** from layout, rendering, and hit-testing — the hierarchical show/hide. Contrast `UIVisual.enabled`, which hides only this entity's visual. |+| `opacity` | number | `1` | Subtree opacity, multiplied down the tree like CSS `opacity` (it multiplies into each descendant's own alpha; the subtree is not composited offscreen). |+| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` makes this node **and its subtree** transparent to the pointer: still drawn, hits pass through. || `width` / `height` | `Dimension` | `auto()` | Box size; `auto` = content-/flex-driven. || `minWidth` / `minHeight` | `Dimension` | `auto()` | Lower size bounds; `auto` = unconstrained. || `maxWidth` / `maxHeight` | `Dimension` | `auto()` | Upper size bounds; `auto` = unconstrained. |diff --git a/docs/astro/src/content/docs/ui/lists.mdx b/docs/astro/src/content/docs/ui/lists.mdxindex abe336005..21814f5f3 100644--- a/docs/astro/src/content/docs/ui/lists.mdx+++ b/docs/astro/src/content/docs/ui/lists.mdx@@ -55,7 +55,7 @@ satisfies it).| `data` | — | A `DataSource<T>`, or a raw array (wrapped in an `ArrayDataSource` — the array is **copied**, so mutate the source afterwards, not your original array). || `layout` | — | Layout sugar (`itemHeight` / `itemWidth` / `columns`, below) or a full [`LayoutProvider`](#layout-providers). || `item` | — | One [item template](#the-item-template), or a map of item type → template for heterogeneous rows. |-| `direction` | from layout | Scroll axis: `'vertical'` \| `'horizontal'` \| `'both'`. Column and grid layouts default to vertical, row layouts to horizontal. |+| `direction` | from layout | Scroll axis: `'vertical'` \| `'horizontal'` \| `'both'`. Column and grid layouts default to vertical, row layouts to horizontal; a custom `LayoutProvider` always defaults to vertical, so pass `direction` for a horizontal one. || `recycleBuffer` | `2` | Extra indices kept mounted on each side of the visible range. For grids, think in rows: `columns * 2` keeps two extra rows. || `wheelSpeed` | `1` | Wheel delta multiplier. || `dragScroll` | `true` | Pointer/touch drag scrolling with a kinetic fling. |@@ -293,9 +293,10 @@ createListView<Message>({`measureText(text, { fontSize, maxWidth?, fontFamily?, bold?, italic?, letterSpacing?, lineHeight? })`returns `{ width, lineCount, height }` measured off the **same Canvas2D metricsthe glyph atlas draws from**, so a measured height matches what actually renders-— no clipped or overflowing rows. `lineHeight` defaults to `fontSize * 1.2`,-the `Text` default ratio; omit `maxWidth` for a single unwrapped line. (A-DOM-less host falls back to an average-glyph estimate.)+— no clipped or overflowing rows. `fontFamily` defaults to Arial and `lineHeight`+to `fontSize * 1.2`, the `Text` default ratio; omit `maxWidth` for a single+unwrapped line. (On a device the metrics come from the platform's own glyph+rasterizer; only a headless host falls back to an average-glyph estimate.)## How virtualization works@@ -406,7 +407,10 @@ after ~0.8 s of stillness. Thumb length tracks the viewport/content ratio,it's out of flow (no layout impact), not interactable (no input surface), andtheme-tagged with the `text` role so it re-skins on a live theme swap. Thefactories always leave scrollbars on; opting out (`showScrollbar: false`) is a-`ScrollContainer` construction option, for manual compositions.+`ScrollContainer` construction option, for manual compositions. The same+constructor takes `initialOffset`, `elastic` (default `false`: let a drag pull the+content past either end, rubber-banded, and spring back) and `bounceTime`+(seconds the spring takes to settle, default `0.5`).## Clipping — `UIMask`diff --git a/docs/astro/src/content/docs/ui/overview.mdx b/docs/astro/src/content/docs/ui/overview.mdxindex 10750c487..b04def95c 100644--- a/docs/astro/src/content/docs/ui/overview.mdx+++ b/docs/astro/src/content/docs/ui/overview.mdx@@ -141,7 +141,7 @@ disappear at the edge of their viewport rather than spilling over the rest of thAdd `UIMask` to a node and its children are clipped to that node. By default the clip isthe node's **box** — a rectangle. That is enough for a list viewport, but it is why acircular avatar frame used to still cut a square: the mask graphic was round, the clip-was not. `alphaCutoff` above 0 switches the clip to the shape the mask actually draws.+was not. With `mode: MaskMode.Stencil`, `alphaCutoff` above 0 switches the clip to the shape the mask actually draws (the default mode, `Scissor`, is always the box).@@ -161,7 +161,8 @@ it — adapting to the box is their whole job.mask's *rectangle*, so a circular avatar frame still cut a square. Above `0` it clips tothe shape the mask actually draws, testing the **sprite's** alpha (not the tinted result,because a mask graphic is routinely tinted to near-zero alpha so it masks without being-seen). `0` stays the default, so scenes authored against box clipping are unchanged.+seen). It only applies in `MaskMode.Stencil`; `Scissor` (the default mode) always clips to+the rectangle. `0` stays the default, so scenes authored against box clipping are unchanged.### `ContentRect` — a rectangle for world content@@ -195,6 +196,8 @@ or stretch with it. `RectAnchors` pins an entity — placed by its `Transform`,- With no parent `ContentRect`, the entity aligns to the **screen**, which is centred on theworld origin.+`alignFlags` is a bit set of `AnchorFlag` (`TOP`, `MID`, `BOTTOM`, `LEFT`, `CENTER`, `RIGHT`); the default `0` pins nothing, so the component does nothing until a flag is set.+`alignMode` says when it aligns: `ONCE`, `ON_RESIZE` (the default: when enabled, when its ownsettings change, and whenever the screen changes) or `ALWAYS` (every frame). Parents arealigned before the children that depend on their size, in the editor's edit mode as well as in@@ -263,6 +266,7 @@ does not move, so the component is inert until there is something to scroll.| Field | Default | Meaning ||---|---|---|+| `enabled` | `true` | Switches the scroller off without removing the component. || `content` | first child | The child that moves. || `horizontal` / `vertical` | `false` / `true` | Which axes scroll. || `movement` | `Clamped` | `Elastic` overshoots at the ends and springs back. |diff --git a/docs/astro/src/content/docs/ui/text.mdx b/docs/astro/src/content/docs/ui/text.mdxindex 22e27c312..4373fd11f 100644--- a/docs/astro/src/content/docs/ui/text.mdx+++ b/docs/astro/src/content/docs/ui/text.mdx@@ -74,7 +74,8 @@ Defaults below are the component defaults (what the inspector shows).|---|---|---|---|| `content` | string | `''` | The string to display. `\n` hard-breaks lines. || `i18nKey` | string | `''` | Localization key. Non-empty ⇒ `content` becomes **derived**: resolved from the Localization catalogs every frame (see [below](#localization)). |-| `fontFamily` | string | `'Arial'` | Font family, resolved by the platform's Canvas2D (see [Custom fonts](#custom-fonts)). |+| `font` | font asset | none | A font file the project ships (`.ttf` / `.otf` / `.woff` / `.woff2`, or a bitmap `.fnt`). Wins over `fontFamily` when set (see [Custom fonts](#custom-fonts)). |+| `fontFamily` | string | `''` | A font family the host already has, resolved by the platform's text stack (see [Custom fonts](#custom-fonts)). Empty uses the project's default font family (Settings → Runtime → Text; `Arial` unless changed). || `fontSize` | number | `24` | Size in **design px** — the same units as `UINode` `px()` sizes. The design-resolution fit and device pixel ratio are compensated at rasterization. || `color` | Color | `{1,1,1,1}` | Fill color (per-channel `0..1`). || `align` | `TextAlign` | `Left` | Horizontal alignment: `Left` / `Center` / `Right`. |@@ -93,6 +94,7 @@ Defaults below are the component defaults (what the inspector shows).| `shadowBlur` | number | `0` | Softens the shadow, in px. `0` is a hard offset copy; above that the shadow spreads into a ring, so it reads as a soft mass under the glyphs rather than a second stamp of them. A blur with no offset is a halo. || `richText` | boolean | `false` | Parse inline [rich-text markup](#rich-text). || `renderMode` | `TextRenderMode` | `Auto` | Glyph pipeline: `Auto` / `Bitmap` / `Sdf` (see above). |+| `layer` | number | `0` | Draw layer of a `Text` with **no** `UINode`, read like `Sprite.layer`, so a world label can sit in front of or behind the content around it. Ignored under a `UINode`, where the UI render order decides. || `enabled` | boolean | `true` | Render toggle (the editor's eye icon uses it too). |<Aside type="note">@@ -151,6 +153,10 @@ around it, with each tap's alpha inverted out of the compositing equation so thestack lands at the alpha you asked for. Unlike the outline it *softens* the edgerather than moving it, which is why the two are separate fields.+++*The Rich Text playground: edit the markup and the rendered text above it updates.*+## Rich textSet `richText: true` and mark up `content` with inline tags. Styles nest as adiff --git a/docs/astro/src/content/docs/ui/theming.mdx b/docs/astro/src/content/docs/ui/theming.mdxindex 20e4a6690..886bd4b07 100644--- a/docs/astro/src/content/docs/ui/theming.mdx+++ b/docs/astro/src/content/docs/ui/theming.mdx@@ -31,7 +31,7 @@ interface ThemeTokens {### Color roles (`ThemeColors`)-Every role, in display order (this is also the runtime list `THEME_COLOR_ROLES`+Every role (13), in display order (this is also the runtime list `THEME_COLOR_ROLES`— the array a theme editor or config validator iterates):| Role | Purpose |@@ -41,6 +41,7 @@ Every role, in display order (this is also the runtime list `THEME_COLOR_ROLES`| `control` | Interactive control resting fill (button, option). || `controlHover` | Control fill while hovered. || `controlActive` | Control fill while pressed. |+| `controlFocus` | Control fill while it has keyboard focus (shown only for focus that arrived by keyboard, so it stays distinct from `controlHover`). || `track` | Slider / progress track. || `primary` | Accent — slider fill, progress fill, selected option. || `primaryHover` | Accent while hovered. |@@ -135,6 +136,8 @@ Two shared functions carry those settings to every runtime:(`'dark' | 'light'`) with the partial overrides into effective`ThemeTokens`, so a project that overrides `primary` alone re-tints theaccent while inheriting everything else.+ `ThemeOverrides` is `{ colors?, type? }`; the project manifest carries only colors,+ so a custom type scale (`label` / `body` / `title`) is set from code.```typescriptimport { resolveThemeTokens, parseThemeOverrides, switchTheme } from 'esengine';diff --git a/docs/astro/src/content/docs/ui/widgets.mdx b/docs/astro/src/content/docs/ui/widgets.mdxindex ca4b5a087..0c38ba348 100644--- a/docs/astro/src/content/docs/ui/widgets.mdx+++ b/docs/astro/src/content/docs/ui/widgets.mdx@@ -71,6 +71,7 @@ const btn = createButton({| `disabled` | `false` | Start disabled. || `focusable` / `tabIndex` | `true` / `0` | Keyboard reachability and Tab order. || `onClick(entity)` | — | Click callback (gated on the enabled state). |+| `userGesture` | `false` | Run `onClick` inside the host's own release event instead of on the next frame — for a call a host accepts only from a player's gesture (sharing a recording on WeChat). |**Handle:** `entity`, `setDisabled(disabled)`, `dispose()`.@@ -310,11 +311,12 @@ const name = createTextInput({|---|---|---|| `node` | 220×32 | The field's `UINode` layout (the one factory that doesn't default to fill-parent). || `value` / `placeholder` | `''` | Content / hint shown while empty. |+| `placeholderI18nKey` | `''` | Catalog key for the empty-field hint; needs a `Localization` resource. The authored `placeholder` stays the fallback. || `maxLength` | `0` | Character cap (`0` = unlimited). || `multiline` | `false` | Enter inserts a newline instead of submitting. || `password` | `false` | Mask the characters. || `readOnly` | `false` | Focusable but not editable. |-| `fontSize` / `fontFamily` | theme label size / `'Arial'` | Text style. |+| `fontSize` / `fontFamily` | theme label size / `''` (the project's default font) | Text style. || `color` / `backgroundColor` / `placeholderColor` | theme `text` / `control` / faded `text` | Color overrides — theme roles when omitted. || `padding` | `6` | Inner horizontal padding in px. || `renderMode` | `Auto` | Glyph pipeline for the field text — `Auto` (crisp bitmap when unscaled, SDF once scaled), always `Bitmap`, or always `Sdf`. |@@ -419,8 +421,8 @@ Axis locks and range clamps included. See## Keyboard focusEntities with a `Focusable` participate in keyboard focus: Tab / Shift+Tab cycle-by `tabIndex`, Enter/Space activate, sliders take the arrow keys, and a focused-control shows its `focused` interaction page. Widget factories add `Focusable`+by `tabIndex`, Enter/Space activate, sliders take the arrow keys, and a control+focused from the keyboard shows its `focused` interaction page. Widget factories add `Focusable`automatically (`focusable: false` opts out); the `FocusManager` resource givesprogrammatic control. Details in **[UI Interaction](/docs/ui/interaction/)**.@@ -494,6 +496,9 @@ const stick = createVirtualJoystick({ world, parent: canvas, inputId: 'move',const actions = defineInputMap({ Move: Axis2D(Virtual('move')) });```+Defaults: `inputId` `'move'`, `mode` Fixed, `radius` 50 px, `deadZone` 0.15 (0 to 0.99)+and `returnSpeed` 18. A Follow joystick defaults to a 240×160 touch area.+The editor's Create entity picker's UI category includes the same generated prefab. Mouse dragin Play uses the same capture as touch. Disable, hide, remove, cancel or backgrounda control to release its own contribution; other controls keep their outputs.@@ -502,7 +507,9 @@ Custom base/handle visuals are supported.## VirtualButton`createVirtualButton({ world, events, parent: canvas, inputId: 'fire', text: 'Fire' })`-uses the normal button appearance and publishes a held scalar to `Virtual('fire')`.+uses the normal button appearance and publishes a held scalar to `Virtual('fire')`+(`inputId` defaults to `'fire'`; `value` is the published scalar, default `1`; the+button is never keyboard-focusable).It supports independent fingers, multiple fingers on the same button, and tapscompleted between frames. Multiple controls can share a binding without onecontrol's removal clearing the others. Use an explicit stable owner with@@ -536,6 +543,12 @@ const settings = createTabView({ world, events, parent: canvas,settings.select(1);```+`createTabView` also takes `selectedIndex` (initial tab, default `0`), `tabHeight`+(default `36` px) and `onChange(index, page)`. `UITabView` additionally carries+`vertical` (arrows follow the vertical axis, default `false`), `loopNavigation`+(default `true`), `selectOnFocus` (default `true`) and `allowSwitchOff` (default+`false`).+The `tabs` and `pages` entity lists are remapped when a scene/prefab is instantiatedor copied. `labels` provides captions for the tab's direct Text child. Deleting aselected target chooses another valid binding; removing a binding restores that@@ -558,7 +571,9 @@ attachTooltip(world, musicVolume, {});```-`side` is Bottom (0), Top (1), Left (2) or Right (3). Placement prefers that side,+The defaults are `hover: true`, `focus: true`, `longPress: true`, `hoverDelay: 0.5` s,+`longPressDelay: 0.6` s, `side: 0`, `gap: 8` px, `avoidEdges: true` and `maxWidth: 240` px;+`hover` / `focus` / `longPress` switch each trigger on or off. `side` is Bottom (0), Top (1), Left (2) or Right (3). Placement prefers that side,tries the opposite, then clamps inside the screen safe area. `maxWidth` is textwidth in layout pixels. The empty `stylePrefab` uses the project's live UI theme;a custom `.esprefab` needs a UINode root and a Text child. Its colors and font style@@ -636,6 +651,10 @@ const picker = createColorPicker({ world, events, parent: canvas,picker.setColor(project.accent);```+Other options: `alphaEnabled` (default `true`), `format` (`0` HSV + HEX, `1` RGB + HEX),+`history` (initial recent colors), `historyLimit` (default `8`, at most `32`) and+`rememberColors` (default `true`). The default size is 280×412.+`UIColorPicker.color` is the canonical `{ r, g, b, a }` shape, with 0..1 channels.`change` carries `{ color }`; `history_change` carries `{ colors }`. The pickernever selects a Sprite or Material target itself and does not perform an implicitdiff --git a/docs/astro/src/content/docs/world/generation.mdx b/docs/astro/src/content/docs/world/generation.mdxindex d96daaae3..ed6696e74 100644--- a/docs/astro/src/content/docs/world/generation.mdx+++ b/docs/astro/src/content/docs/world/generation.mdx@@ -18,7 +18,8 @@ them, what is reserved for a home or a road. The **artists** make the recipes: a| `rules` | The rules the world is laid out by: a `.esworld` file, or the id of rules the game registered with `registerWorldRules`. || `version` | The version of the rules the world was made with. A saved world keeps it; rules that no longer have it fail the world (its status says why) rather than laying out another one. || `world`, `seed` | The world (a planet, a level) as the game names it, and its seed. Another seed lays out another world by the same rules. |-| `paintGround` | Whether the biomes paint the terrain. |+| `paintGround` | Whether the biomes paint the terrain (default on). |+| `surface`, `seaLevel` | `Plane` (the default) lays the world out over a `Terrain`; `Planet` means the entity is also a `Planet` and the world is laid out over its six faces. `seaLevel` (shown for `Planet`) is the height of the sea above the planet's radius: ground lower than it is under water. |What the rules place is published as the entity's children, round the [streaming sources](/docs/world/streaming/) (or the camera):see [procedural chunks](/docs/world/streaming/#procedural-chunks).@@ -112,17 +113,21 @@ drawn for it. Of two candidates whose groups would overlap, the higher priorityof the layers before it, so a fern does not grow through a trunk and a stone does not sit inside a boulder. A layer is published inchunks of `chunkSize` out to `drawDistance`. `occupies: false` makes a layer that later ones may overlap (ground cover). `farSpacing` (default 1) plans the far versions of a layer's plants that much further apart: ground cover whose far versions keep a quarter of the plants is planned at 2, so a quarter of the candidates are worked out and none is made only to be thrown away.+++*The **World Gen** component of the Terrain & Water example: the rules asset, the seed and the surface.*+## Zones-A zone plans an area by hand: a home, a road, a landing site, a building's footprint, a view kept open.+A zone (the `WorldZone` component) plans an area by hand: a home, a road, a landing site, a building's footprint, a view kept open. It follows its entity's position and its turn about the vertical.| Field | What it does ||---|---|-| `kind` | What it is for, in the game's own words. |-| `shape`, `radius`, `sizeX`, `sizeZ` | A circle, or a box turned with the entity about the vertical. The editor draws its outline. |-| `falloff` | Over how many world units past the outline it fades out: what it excludes thins there instead of stopping on a line. |+| `kind` | What it is for, in the game's own words (default `reserve`). |+| `shape`, `radius`, `sizeX`, `sizeZ` | A circle (default; `radius` 10), or a box (`sizeX` × `sizeZ`, 20 × 20) turned with the entity about the vertical. The editor draws its outline. |+| `falloff` | Over how many world units past the outline it fades out (default 4): what it excludes thins there instead of stopping on a line. || `priority` | Where zones overlap, the higher holds the biome. |-| `excludes` | The tags of what it keeps out, separated by commas: a layer, a recipe, a recipe's or member's tags, `decor`, `interactive`; `*` is everything. |+| `excludes` | The tags of what it keeps out, separated by commas: a layer, a recipe, a recipe's or member's tags, `decor`, `interactive`; `*` is everything (the default); empty keeps nothing out. || `biome` | A biome it holds over its area. || `flatten` | Levels the terrain under it to the ground's height at its centre, blending back over `falloff`: a plot to build on. In code, `flatten` is a world height or `'ground'`. |@@ -136,6 +141,10 @@ gens.zones().set({ id: 'house 1', kind: 'building', shape: { type: 'rect', x, z,Only the chunks the zone reaches are made again, each keeping its old version until the new one replaces it.+++*A **World Zone**: a circle that tells the generator which biome to grow inside it.*+## Interactive placements and changesA member with `interactive` (`'ore'`, `'tree'`) is an entity of its own, carrying a `PlacedObject` with its placement id and kind;diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex 763878cec..dc3c8dd60 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -38,6 +38,10 @@ curve by default, or a full **gradient/curve** for precise control (see below).(duration, bursts, looping) restart the emitter; re-toggling replays from t=0.</Aside>+++*The Particle demo example: a campfire made of two emitters, smoke and sparks.*+## SetupThe particle system ships in the main bundle. In the editor and the web runtime@@ -138,7 +142,7 @@ Where particles spawn and their initial direction. See [Emitter shapes](#emitter| `noiseStrength` | number | `0` | Peak flow speed (px/s) the turbulence pushes particles at. `0` = module off. || `noiseFrequency` | number | `0.01` | Spatial scale of the field — larger = tighter, busier swirls. || `noiseScrollSpeed` | number | `0` | How fast the field drifts over time (`0` = a static field). |-| `noiseOctaves` | number | `1` | Fractal detail layers. `1` = smooth flow; more = finer turbulence. |+| `noiseOctaves` | number | `1` | Fractal detail layers (1..8). `1` = smooth flow; more = finer turbulence. |See [Noise & turbulence](#noise--turbulence-1) below.@@ -199,7 +203,7 @@ See [Noise & turbulence](#noise--turbulence-1) below.| Property | Type | Default | Description ||---|---|---|---|| `subEmitter` | entity | none | Child emitter entity fired when a particle triggers. `0`/unset = off. |-| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | Fire on each particle's `Death` or `Birth`. |+| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | Fire on each particle's `Death` or `Birth`, or when it hits something (`Collision`, see [Scene collisions](#scene-collisions)). || `subEmitterChance` | number | `1` | Probability (0..1) a triggering particle fires the child. || `subEmitterInheritVelocity` | number | `0` | Fraction of the parent particle's velocity passed to the sub-burst. |@@ -216,6 +220,29 @@ See [Sub-emitters](#sub-emitters) below.See [Per-particle trails](#per-particle-trails) below.+++*The **Particle Emitter** Details, with the **Collision** group at the top (off here) above the emission fields.*++### Collision++Shown once `collisionEnabled` is on. See [Floor collision](#floor-collision) and [Scene collisions](#scene-collisions).++| Property | Type | Default | Description |+|---|---|---|---|+| `collisionEnabled` | boolean | `false` | Turn collision on. |+| `collisionMode` | `ParticleCollisionMode` | `Floor` | `Floor` (a horizontal plane), `Physics2D` or `Physics3D` (cast through the physics world). |+| `collisionFloor` | number | `0` | World height of the floor plane. |+| `collisionBounce` | number | `0.5` | 0 = stop dead, 1 = fully elastic. |+| `collisionFriction` | number | `0.1` | Horizontal speed shed per bounce, 0..1. |+| `collisionLifetimeLoss` | number | `0` | Fraction of life burned per bounce, 0..1. |+| `collisionMask` | bitmask | all (`65535`) | Physics layers the scene modes hit; zero selects none. |+| `collisionQueryBudget` | number | `128` | Most queries this emitter makes per update, 0..4096. |+| `collisionMaxDistance` | number | `0` | Distance from the nearest active camera beyond which collision is skipped; `0` = no distance culling. |+| `collisionFallback` | `ParticleCollisionFallback` | `Floor` | `Floor` or `Skip`, when physics is unavailable, the budget is spent or a particle is too far away. |+| `collisionEvents` | boolean | `false` | Emit `ParticleCollisionEvent`s. |+| `collisionEventBudget` | number | `32` | Most events this emitter raises per update, 0..1024. |+## Emitter shapes@@ -421,6 +448,8 @@ cmds.spawn()});```+The component's other defaults: `type` `Directional`, `strength` `200`, `radius` `0`, `direction` `{1, 0, 0}`, `falloff` on, `enabled` on.+| Type | Effect ||---|---|| `Directional` | A constant push along `direction` — wind, updrafts, a current. |@@ -492,6 +521,9 @@ simulation draws; an emitter simulated on the GPU draws as `Billboard`.| `Multiply` | Darkens — smoke, shadow. || `Screen` | Brightens, softer than additive. || `PremultipliedAlpha` | For textures with premultiplied alpha. |+| `PmaAdditive` | Additive with a premultiplied-alpha source. |+| `Lighten` | Takes the brighter of particle and scene pixel. |+| `Darken` | Takes the darker of the two. |## Controlling playback — `Res(Particle)`@@ -517,6 +549,9 @@ const control = defineSystem([Res(Particle)], (particles) => {| `getAliveCount(entity)` | Number of currently live particles. || `setColorLut(entity, lut \| null)` | Upload a baked color LUT (see above), or clear. || `setSizeLut(entity, lut \| null)` | Upload a baked size LUT, or clear. |+| `setSpeedLut(entity, lut \| null)` | Upload a baked speed-over-life multiplier; it scales how fast a particle travels along its trajectory, and does not replace gravity or noise. |+| `setBursts(entity, bursts \| null)` | Set the burst schedule (`{ time, count }[]`) from code, or clear. |+| `setCollisionBudget({ queries?, events? })` | Change the shared per-App collision caps. |<Aside type="tip">The per-frame `update` is driven automatically by the particle system — youdiff --git a/docs/astro/src/content/docs/world/prefabs.mdx b/docs/astro/src/content/docs/world/prefabs.mdxindex dfa31f79c..dc84d8c29 100644--- a/docs/astro/src/content/docs/world/prefabs.mdx+++ b/docs/astro/src/content/docs/world/prefabs.mdx@@ -130,14 +130,14 @@ const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {## Parent it & reach its childrenNest the instance under another entity, and use the returned `entities` map to reach-children by their prefab-local id:+the spawned children:```typescriptconst { root, entities } = await prefabs.instantiate('assets/prefabs/turret.esprefab', {parent: mountPointEntity,});// root → the instance root-// entities → Map<prefab-local id, spawned Entity>, for reaching children+// entities → Map<number, spawned Entity>, keyed by the id the spawn gave each entity```## Per-instance overrides@@ -156,8 +156,7 @@ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {```To reach a **child**, add its `prefabEntityId` — the entity's own **string** id,-a UUID for editor-authored prefabs. Read it from the `.esprefab`, or from the-`entities` map a previous instantiate returned.+a UUID for editor-authored prefabs. Read it from the `.esprefab` (an override that names no `prefabEntityId` aims at the root).:::caution[`prefabEntityId: '0'` no longer matches anything]`'0'` is the id every prefab had before stable ids, and it appears in older@@ -167,7 +166,7 @@ the ids that do exist — before, it was dropped in silence, and the only symptowas every instance appearing at the position the prefab was authored with.:::-Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'`,+Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'parent'`, `'component_added'`,`'component_replaced'`, `'component_removed'`, `'metadata_set'`, or `'metadata_removed'`(the metadata forms use `metadataKey` in place of `componentType`/`propertyName`).@@ -183,7 +182,7 @@ Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'| Result field | Description ||---|---|| `root` | The instance's root `Entity`. |-| `entities` | `Map<prefab-local id, Entity>` for reaching children. |+| `entities` | `Map<number, Entity>` of every spawned entity, root included, for reaching children. |## Best practicesdiff --git a/docs/astro/src/content/docs/world/scenes.mdx b/docs/astro/src/content/docs/world/scenes.mdxindex 4ccb27499..9dd3349bd 100644--- a/docs/astro/src/content/docs/world/scenes.mdx+++ b/docs/astro/src/content/docs/world/scenes.mdx@@ -188,7 +188,7 @@ leaking. With no cells registered, `update()` is a no-op.|---|---|| `configure({ loadRadius, unloadRadius, policy? })` | Set the radii (`unloadRadius` is clamped up to `loadRadius`) and the out-of-range policy — `'unload'` (default) or `'sleep'`. || `register(cell)` / `unregister(scene)` / `clear()` | Manage the cell set (`{ scene, x, y, radius }`). |-| `setFocus(x, y)` | Drive the focus point directly (call each frame). |+| `setFocus(x, y, z?)` | Drive the focus point directly (call each frame); distance is measured in 3D, with `z` defaulting to 0 and a cell's optional `z` to 0. || `setFocusEntity(entity)` / `getFocusEntity()` | Follow an entity instead — the streaming system reads its `Transform` each tick (play mode only). || `getActive()` | Scene names the controller currently holds in-range. || `update()` | Reconcile resident cells against the focus (`sceneManagerPlugin` calls this every frame). |@@ -216,6 +216,7 @@ ship the startup scene only. See|---|---|| `switchTo(name, options?)` | Replace the active scene (async; optional transition). || `loadAdditive(name, onProgress?)` | Load a scene on top; returns its context (async). |+| `reload(options?)` | Switch to the active scene again, from its file (async; optional transition). || `unload(name, options?)` | Unload a scene (async; optional transition). || `getScene(name)` | A loaded scene's `SceneContext` (`spawn` / `adopt` / `despawn` / `setPersistent` / draw callbacks / post-process binding), or `null`. || `getActive()` | The active scene name, or `null`. |@@ -283,7 +284,7 @@ const checkpoint = defineSystem([GetWorld(), Res(Assets)], async (world, assets)| `collectAssets` | Bookkeeping sets the load adds acquired asset keys to, so the caller (normally the scene manager) can release them on unload. |**Versioning.** Scene files carry a `version` (currently-`SCENE_FORMAT_VERSION = '1.0'`). `migrateSceneData(raw)` upgrades any older+`SCENE_FORMAT_VERSION = 4`). `migrateSceneData(raw)` upgrades any oldershape to the current one: it never mutates its input (it returns a migrated deepcopy), is idempotent, drops component types retired by engine upgrades, and**rejects data newer than the engine**. Every loader runs it internally — calldiff --git a/docs/astro/src/content/docs/world/streaming.mdx b/docs/astro/src/content/docs/world/streaming.mdxindex 73422f71a..9d1f7f6c8 100644--- a/docs/astro/src/content/docs/world/streaming.mdx+++ b/docs/astro/src/content/docs/world/streaming.mdx@@ -53,6 +53,8 @@ world.insert(player, WorldStreamingSource, {});```+The three radii are in world units and default to the values above; the component also has an `enabled` switch (default on) that takes a source out of the union without removing it. `StreamedWorld.cellSize` defaults to 1000.+Several sources may exist, and what they ask for is **unioned** — a cell any oneof them needs stays resident. That is what makes split screen, a spectatorcamera, a cinematic camera and an editor preview the same kind of thing ratherdiff --git a/docs/astro/src/content/docs/world/tilemaps.mdx b/docs/astro/src/content/docs/world/tilemaps.mdxindex 133355c0b..1f456bdfd 100644--- a/docs/astro/src/content/docs/world/tilemaps.mdx+++ b/docs/astro/src/content/docs/world/tilemaps.mdx@@ -190,7 +190,7 @@ tilemap.setTilesets(layer, [Optional `margin` (border before the first tile) and `spacing` (gap between tiles),both in pixels, describe atlases that pad their cells — each tile then samples itsown texels instead of bleeding toward its neighbour. They default to `0`, so a-gapless atlas needs neither; the Tiled/`.estileset` importer fills them in+gapless atlas needs neither (a slot also takes an `extrude`, also `0` by default); the Tiled/`.estileset` importer fills them inautomatically from the tileset's own margin/spacing.## Tile animation@@ -402,13 +402,13 @@ origin / pixels-per-unit / play-mode lifecycle as tile collision.| `fillRect(layer, x, y, w, h, id)` | Fill a rectangle with a tile id. || `flipTile(layer, x, y, h, v, d)` | Flip a tile (horizontal / vertical / diagonal). || `rotateTile(layer, x, y, degrees)` | Rotate a tile (90° steps). |-| `tileToWorld(layer, tx, ty, ox, oy)` / `worldToTile(layer, wx, wy, ox, oy)` | Convert coordinates. |+| `tileToWorld(layer, tx, ty, ox, oy, rotation?)` / `worldToTile(layer, wx, wy, ox, oy, rotation?)` | Convert coordinates; `ox`/`oy` is the layer's world origin and the optional `rotation` its world Z angle in radians. || `setTilesets(layer, slots)` | Assign a multi-tileset slot table. || `setTileAnimation(layer, tileId, frames)` | Animate a tile id. || `setChunkTiles(layer, cx, cy, tiles, w, h)` | Write a chunk (infinite layers). || `removeChunk(layer, cx, cy)` | Take a chunk out of the layer, its mesh with it. || `exportChunks(layer)` / `importChunks(layer, data)` | Serialize / restore chunk data. |-| `setTint(layer, color)` / `setVisible(layer, on)` / `setRenderProps(...)` | Live visual overrides. |+| `setTint(layer, r, g, b, a, opacity)` / `setVisible(layer, on)` / `setRenderProps(...)` | Live visual overrides. || `setTileProperty(...)` / `getTileProperty(...)` | Per-tile custom key/value properties. || `setGridType(layer, type)` / `setHexParams(...)` | Orientation (orthogonal / isometric / hex). || `destroyLayer(layer)` | Tear a layer down. |diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex 575e6011a..67915b5e2 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -393,6 +393,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `controller` | string | `''` | 一个 `.esanimator` 资产引用(编辑器写入的),或代码里传给 `registerController` 的名字。 || `avatar` | string | `''` | 一个 `.esavatar` 资产,说明这个骨架如何称呼片段所指名的关节(见[层、遮罩与 IK](#层遮罩与-ik))。 || `currentState` | string | `''` | 基础层的活动状态;嵌套状态机时是 `/` 分隔的路径(从控制器的初始状态种入)。 |+| `layerStates` | string[] | `[]` | 基础层之上每一层的活动状态,按层顺序排列(基础层的在 `currentState` 里)。 || `enabled` | boolean | `true` | 关掉即冻结状态机。 || `AnimatorController` 方法 | 说明 |diff --git a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx b/docs/astro/src/content/docs/zh-cn/animation/spine.mdxindex 4447ad14e..65e102c92 100644--- a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/spine.mdx@@ -39,6 +39,10 @@ Estella 内置 [Spine](https://esotericsoftware.com/) 骨骼动画:骨骼、网编辑器靠文件内部的标记认出它,它会和 `.skel` 一起出现在选择器里)。从内容浏览器**拖拽**到槽位上也行。</Aside>+++*Spine 示例:通过 **SpineAnimation** 组件播放的骨骼。*+## 图集Spine 导出的 `.atlas` 文件即用即好——包括**多页**图集(每页纹理随图集一起加载)和diff --git a/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx b/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdxindex 34699564c..d55a1e92a 100644--- a/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/spring-bones.mdx@@ -14,18 +14,18 @@ description: 骨骼链的次级运动(头发、尾巴、绳索):放在链根上| 字段 | 作用 ||---|---|| `enabled` | 关闭后,链完全保持动画摆出的姿势。 |-| `stiffness` | 每根骨头被拉回动画姿势的力度,按 60 Hz 每帧计,0 到 1。0 是自由悬垂。 |-| `drag` | 每帧骨头损失的速度比例,0 到 1。越高越快安定;默认值阻尼足够,不会来回晃。 |-| `gravity` | 世界单位每二次方秒(世界 y 向上)。默认是一米一百个单位。 |+| `stiffness` | 每根骨头被拉回动画姿势的力度,按 60 Hz 每帧计,0 到 1。0 是自由悬垂。默认 0.1。 |+| `drag` | 每帧骨头损失的速度比例,0 到 1。越高越快安定;默认值(0.5)阻尼足够,不会来回晃。 |+| `gravity` | 世界单位每二次方秒(世界 y 向上)。默认是 `{0, -980, 0}`:一米一百个单位。 || `wind` | 作用在链上的稳定风,世界单位每二次方秒。0 是无风。 || `windGust` | 阵风让风力强弱摆动的幅度,0 到 1。0 是稳定的风;1 让风力在无风到两倍强度之间变化。每根骨头比上一根晚一点遇到阵风,所以发丝会起伏。 |-| `windFrequency` | 每秒几阵风。 |+| `windFrequency` | 每秒几阵风(默认 0.5)。 || `endLength` | 末端骨头没有子骨头可以瞄准;这个值给它一段这么长的尖端。0 表示末端骨头不模拟。 || `radius` | 发丝的粗细,与碰撞体保持这个距离。 |-| `weight` | 用多少模拟,0 到 1。0 就是只有动画。 |+| `weight` | 用多少模拟,0 到 1(默认 1)。0 就是只有动画。 || `colliders` | 带 `SpringBoneCollider` 的实体,链被挡在它们之外。 |-`SpringBoneCollider` 是一个球,或者沿它自己实体 Y 轴的胶囊,位置由实体的变换(和它的 `offset`)决定。把它们放在头和肩膀的骨头上,头发就不会穿过身体。+`SpringBoneCollider` 是一个球(默认,`radius` 为 10),或者沿它自己实体 Y 轴的胶囊(`height` 为 20,即两端球心的距离),位置由实体的变换(和它的 `offset`)决定。把它们放在头和肩膀的骨头上,头发就不会穿过身体。## 从模型导入diff --git a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdxindex f1cf23d9a..f32adb5ab 100644--- a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx@@ -90,6 +90,8 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelin| Spine | `Spine` | 把 Spine 动画作为片段播放。 || 标记 | `Marker` | 命名时间标记。 || 自定义事件 | `CustomEvent` | 带 payload 的命名事件,供你自己的系统消费。 |+| 相机 | `Camera` | 逐镜头决定哪台相机是当前视图([见下文](#相机与子序列))。 |+| 子序列 | `Sequence` | 在本时间轴的一个时间窗里播放另一条时间轴。 |### 激活区间@@ -121,6 +123,21 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelin*曲线编辑器:每个关键帧通道变成一条可编辑曲线(这里 `position.x` 缓入、`position.y` 起伏),每个关键帧带切线手柄。*+### 相机与子序列++**相机轨道(镜头轨道)**存放镜头:每根条就是一台相机,在它的区间内充当视图。首尾相接的条是硬切;+把一根条拖到与前一根重叠,重叠部分就成了混合,由后一个镜头的混合曲线塑形。没有镜头的区间会把视图+还给场景自己的相机。每条时间轴只有一条相机轨道,它的相机必须位于时间轴根之下(每条轨道都是从该根+出发按名字路径找到目标的)。++**子序列轨道**在本时间轴的一个时间窗里,用它自己的时钟播放另一个 `.estimeline`:`speed` 缩放它,+`loop` 让它重复以填满整根条,而不是停在最后一帧。**绑定到**用来选嵌套时间轴的名字路径从哪个节点+开始,所以同一段问候序列可以在不同角色身上播放。一条时间轴不能播放自己,无论直接还是经由另一条;+嵌套最多四层;编辑器会拒绝这些选择,已加载的游戏则跳过它们并给出警告。++拖动预览时,切换画面显示在视口的相机预览窗里。拖动、跳转或倒放都是安全的:当前显示哪个镜头、+嵌套时间轴的哪一帧,只取决于时间本身。嵌套时间轴里的事件和其他事件一样,只在正向播放时触发。+### 预览动的是什么在 Sequencer 里拖播放头或按播放,动的是**活的视口**,不是另开一个预览窗——采样出的姿态写进当前@@ -146,7 +163,7 @@ import {} from 'esengine';const slideIn: TimelineAsset = {- version: '1.1',+ version: '1.3',type: 'timeline',duration: 2,wrapMode: WrapMode.Once,diff --git a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdxindex a924c49de..d9de785ea 100644--- a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx@@ -236,7 +236,7 @@ audio.setBusDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, releaudio.setBusDucking('music', null); // 移除```-`trigger` 总线有信号时,目标总线的闪避级压到 `amount`;静默后按 `release` 恢复到 1。+`attack`(默认 0.05 秒)和 `release`(默认 0.4 秒)是时间常数,`threshold`(默认 0.003,0 到 1 的 RMS 电平)是触发总线响到多大才算有信号。`trigger` 总线有信号时,目标总线的闪避级压到 `amount`;静默后按 `release` 恢复到 1。闪避是独立的增益级,不会与用户音量设置打架。无 WebAudio 图的后端(微信)上,两个 API 与音量调用一样优雅降级为空操作。@@ -248,8 +248,8 @@ audio.setBusDucking('music', null); // 移除### 导入设置与打包音频-选中音频资产会显示解码波形(可播放/点击跳转)和**导入设置**:`Compress` 与-`Bitrate` 控制打包时的 WAV → MP3 转码(在打包对话框勾选**压缩音频**)。+选中音频资产会显示解码波形(可播放/点击跳转)和**导入设置**:`Compress`(默认开)与+`Bitrate`(96、128 或 192 kbps,默认 128)控制打包时的 WAV → MP3 转码(在打包对话框勾选**压缩音频**)。已压缩格式原样通过。MP3 有少量编码器延迟——需要无缝循环的素材请关闭 `Compress`。**加载方式(Load Type)** 决定这个片段在 Web 上怎么持有:*自动*把 30 秒及以上的片段按压缩文件流式播放、较短的则解码,diff --git a/docs/astro/src/content/docs/zh-cn/assets/models.mdx b/docs/astro/src/content/docs/zh-cn/assets/models.mdxindex b50b34d45..4d011a70e 100644--- a/docs/astro/src/content/docs/zh-cn/assets/models.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/models.mdx@@ -189,6 +189,15 @@ chart,每片投影到自己的平面,再按**同一个**世界-纹素比打包模型的材质默认导入到 Model 着色器。在模型的导入设置里打开**角色材质**(`characterMaterials: auto`)后,名字里带 skin、face、head、hair 或 eye 的材质会改用 Skin、Hair 或 Eye 着色器,并绑上它的法线贴图和遮蔽/粗糙度贴图。头发的三角形还会按混合绘制需要的顺序重排,最靠近头发中心的发片排在最前,对围绕头部的一圈发片来说,从任何一侧看这都是由后向前(离开这一圈的马尾不受这个排序约束)。头发材质按 alpha 裁剪(`u_alphaCutoff`,源文件没说就取 0.5),并且不做混合绘制,边缘由覆盖率来柔化。名字是按单词读的,所以 `BodySkin`、`Hair_A` 会命中,`Eyelashes`、`Headband` 不会,颜色贴图的文件名也算。名字只是约定,不是事实:请看导入写出的材质选了什么,猜错的地方手动改着色器。眼睛的虹膜贴图(`u_depthMap`、`u_irisNormalMap`)需要手动指定,源文件里没有对应的位置。头发的流向图和高光偏移图在 glTF 里同样没有位置,所以头发材质在它的 extras 里写出它们(`flow_map`、`shift_map`,路径相对于模型,以及 `suggested_tipSoftness`),导入时绑定为 `u_flowMap`、`u_shiftMap` 和 `u_tipSoftness`。默认关闭,所以重新导入不会改动你没要求改的材质。+## 弹簧骨骼与高光贴图++模型还有两个导入设置,都在高级里:++| 设置 | 默认 | 作用 |+|---|---|---|+| **Spring Bones**(`springBones`) | 关 | 选 **From File Data and Names** 后,导入器根据模型已有的信息给头发加上次级运动:VRM 的 spring-bone 扩展或 `extras.estella.springBone` / `springCollider` 按所述使用;它们没覆盖到的部分,名为 `Hair_<region>_<chain>_00` 的骨骼会变成 `SpringBone`,名为 `SBC_Sphere_<name>_r<cm>` 或 `SBC_Capsule_<name>_r<cm>_h<cm>` 的空节点会变成碰撞体。见[弹簧骨骼](/docs/zh-cn/animation/spring-bones/)。 |+| **Specular Map**(`specularMap`) | Specular Color | 源文件的高光贴图里装的是什么。**Packed ORM** 把它按遮蔽、粗糙度、金属度绑定,适用于把这三者打包在那里的场景(Bistro、Sun Temple);默认把它当作高光染色读取,而金属/粗糙度着色没有这个槽位。仅 FBX。 |+## 动画源里的每个动画会在 mesh 旁边写出一个 `.estimeline`,prefab 的根挂一个 `TimelinePlayer`diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxindex e73b78be4..4b6df25aa 100644--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx@@ -57,11 +57,15 @@ const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets|---|---|| `loadTexture(ref)` | `{ handle, width, height }` || `loadAudio(ref)` | `{ bufferId }` |-| `loadFont(ref)` | `{ handle }` |+| `loadFont(ref)` | `{ handle, family? }`(矢量字体带 `family`) || `loadMaterial(ref)` | `{ handle, shaderHandle }` |-| `loadSpine(skeletonRef, atlasRef?)` | `{ skeletonHandle }` |+| `loadSpine(skeletonRef, atlasRef?)` | `{ skelData, atlasText, isBinary, textures }` —— 准备好的骨骼与图集,`Spine` 组件据此绘制 || `loadTilemap(ref)` / `loadTileset(ref)` | `{ sourceId }` / `{ tilesetId }` || `loadTimeline(ref)` | `{ timelineId }` |+| `loadAnimClip(ref)` | `{ clipId }` |+| `loadAnimatorController(ref)` | `{ controllerId }` |+| `loadStateMachine(ref)` / `loadBehaviorTree(ref)` | `{ fsmId }` / `{ btId }` |+| `loadLocaleTable(ref)` | `{ locale, keyCount }` || `loadPrefab(ref)` | `{ data }` || `loadJson<T>(ref)` | `{ data: T }` |@@ -181,8 +185,8 @@ const { failed } = await assets.preload(}```-它就是 Unity 的 `Resources` 文件夹、Unreal 的 additional cook directory,-只不过落在这个项目原本就有的模型里。**默认关闭**,这是刻意的。+它是文件夹级别对可达性判断的覆盖,+落在这个项目原本就有的模型里。**默认关闭**,这是刻意的。<Aside type="tip">`subpackages/` 下的资源即使触达不到也总会被包含——只是分组归属不同。diff --git a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx b/docs/astro/src/content/docs/zh-cn/assets/textures.mdxindex 8af1497fa..8421cec9e 100644--- a/docs/astro/src/content/docs/zh-cn/assets/textures.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/textures.mdx@@ -116,6 +116,9 @@ GPU 对象,所以分开缓存。除非你在喂一条本来就要求自下而| **sRGB Color** | `true` | 图片存的是 sRGB 编码的颜色(albedo、UI)。法线图、遮罩这类本来就是线性的数据要关掉。仅在项目按线性色渲染时有意义。 || **Mip Coverage Cutoff** | `0` | 用于镂空(树叶、草、栅栏):材质测试的 alpha 阈值。每一级 mip 都保留与完整图像相同比例的高于阈值的像素,镂空就不会随距离变稀。`0` = 关;对 UASTC 压缩贴图生效。 || **9-Slice Border** | `0,0,0,0` | 左/右/上/下边框,单位是**纹理像素**:图片的角在哪里结束。在这里授权一次,每个设成 Sliced 的 `UIVisual` 都继承。 |+| **Cell Width / Cell Height** | `0` | 精灵表里一个格子的大小,单位像素。`0` 表示这张图不是精灵表;设了之后,`Sprite` 可以选取图中的某一帧,而不是显示整张。 |+| **Margin** | `0` | 第一个格子之前的内边距,两个轴相同。 |+| **Spacing** | `0` | 相邻格子之间的间隙,只算在格子之间,最后一格之后不算。 |<Aside type="tip">**像素画**:Filter 设 `nearest`,Compression 设为 **Original image**(原图;自动模式下精灵本来就是原图)。线性过滤会把你画的像素糊掉,diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdxindex 2d4894d63..8882eccd4 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx@@ -43,13 +43,15 @@ await app.run();| `sideModules` | `SideModuleHost` | 由 `wasmBaseUrl` 构建,否则无 | 该 realm 的可选原生模块获取器。内联模块的 realm(Playable、微信)直接传 host 而不是 URL。 || `plugins` | `Plugin[]` | `[]` | 额外插件,追加在默认集合**之后**。 || `getViewportSize` | `() => { width, height }` | — | 视口尺寸回调,供相机系统使用(也是 WebGPU 初始化尺寸;缺省时为 `800×600`)。 |-| `glContextHandle` | `number` | — | 预注册的 WebGL2 上下文句柄;不传则模块通过 `initRenderer()` 自建上下文。 |-| `backend` | `'webgl2' \| 'webgpu'` | `'webgl2'` | `'webgpu'` 走注入设备路径——宿主必须先取得 `GPUDevice` 并在实例化前作为模块工厂的 `preinitializedWebGPUDevice` 传入。 |-| `canvasSelector` | `string` | `'#canvas'` | WebGPU 交换链画布的 CSS 选择器(必须已在 DOM 中)。WebGL 忽略它。 |+| `renderSurface` | `RenderSurfaceSource` | `{ kind: 'default' }` | 宿主如何提供渲染表面:`{ kind: 'gl-context', handle, glx? }` 渲染进预注册的 WebGL2 上下文句柄(`glx` 标明是微信的 EmscriptenGLX 上下文);`{ kind: 'webgpu', canvasSelector?, readback? }` 走注入设备路径——宿主必须先取得 `GPUDevice` 并在实例化前作为模块工厂的 `preinitializedWebGPUDevice` 传入,`canvasSelector` 默认 `'#canvas'`(必须已在 DOM 中),`readback` 让引擎能回读自己的帧(`captureFrame`);`{ kind: 'default' }` 由模块通过 `initRenderer()` 自建上下文。 || `colorSpace` | `'gamma' \| 'linear'` | `'gamma'` | 项目色彩空间。`'linear'` 在线性光下渲染(采样时 sRGB 解码、线性混合、最终 blit 显式编码)。必须**在创建应用时**声明——着色器按它编译。 || `randomSeed` | `number` | — | 给引擎的随机性播种,让这次运行可复现——回放、bug 复现、对某一帧下断言。不填则每次运行都不同,这对粒子正是玩家想要的。各子系统取的是按名字独立的流,所以新增一个发射器不会改变别处抽到的数。 || `ySortLayers` | `number` | `0` | 渲染层位掩码(bit 0–31):层内按世界 Y 排序(俯视遮挡)。 |-| `screenFit` | `ScreenScalingData` | 关(`scaleMode: -1`) | 项目相机适配:把设计分辨率 letterbox 进实际宽高比。仅当 `scaleMode` 为真实模式(≥ 0)时安装;`SCREEN_FIT_OFF`(-1)保持旧行为(有 Canvas 用 Canvas 适配,否则用原始 orthoSize)。 |+| `depthLayers` | `number` | `0` | 渲染层位掩码(bit 0–31):这些层按真实深度而非画家顺序解析——2.5D 的开关。不透明绘制写深度缓冲并由近到远排序;混合绘制只测试不写入。同时按 Y 排序的层保持 Y 排序。 |+| `outputTransform` | `'none' \| 'aces' \| 'neutral'` | `'none'` | 一帧在送往显示前统一、最后应用一次的曲线。`'aces'` 是受光 3D 场景想要的电影式肩部;`'neutral'`(Khronos PBR Neutral)保留色相与饱和度。 |+| `msaaSamples` | `number` | `4` | 场景目标的多重采样;`1` 关闭。设备会钳制它,所以这是项目的请求而非实际所得。 |+| `quality` | `QualityConfig` | — | 画质模式(`'off'`、`'auto'`、`'low'`、`'medium'`、`'high'`)、目标帧率、动态分辨率、按档位的配置、设备规则、异步着色器编译与按需渲染。仅在传入时安装。 |+| `screenFit` | `ScreenScalingData` | 关(`scaleMode: -1`) | 项目相机适配:把设计分辨率 letterbox 进实际宽高比。相机适配仅在 `scaleMode` 为真实模式(≥ 0)时生效;`SCREEN_FIT_OFF`(-1)保持旧行为(有 Canvas 用 Canvas 适配,否则用原始 orthoSize)。`renderPolicy` 不是 `Surface` 时该资源同样会被安装。 |### 它安装什么@@ -155,10 +157,10 @@ export const scorePlugin: Plugin = {拓扑排序,遇环抛错。若 `build()` 抛错,插件会被回滚,失败以 `error` 条目的形式留在子系统注册表里可见。-**`flushPendingSystems(app)`**——模块级的 `addSystem` / `addStartupSystem` /-`defineBehavior` 调用(在 import 时、任何插件之外发生)排队在环境上下文里,而-不是某个具体应用上。工厂对应的运行时会替你把队列灌进应用;当你手动搭一个裸-`App` 又想要这些模块级注册时,自己调用 `flushPendingSystems`。+**`flushPendingRegistrations(app)`**——模块级的 `addPlugin` / `addSystem` /+`addStartupSystem` / `defineBehavior` 调用(在 import 时、任何插件之外发生)排队在环境上下文里,而+不是某个具体应用上。工厂对应的运行时会替你把队列灌进应用(先插件、后系统);当你手动搭一个裸+`App` 又想要这些模块级注册时,自己调用 `flushPendingRegistrations`。## `App` 的接口@@ -370,7 +372,7 @@ import 你的 bundle,返回一个 `ProbedRegistrations`:手搓 `App.new()` 加插件列表是引擎嵌入方的事。- **给插件起名。**一个 `name` 零成本却买来可观测性:子系统注册表条目、插件系统的存活性归因、可用的依赖报错。-- **前置声明 `colorSpace` 和 `backend`。**两者都在创建时固化(着色器编译、设备+- **前置声明 `colorSpace` 和 `renderSurface`。**两者都在创建时固化(着色器编译、设备注入)——不能在存活应用上切换。- **别和生命周期自动暂停较劲。**用 `new LifecyclePlugin({ autoPause: false })`(或`lifecycle.autoPause = false`)关掉它,而不是在监听器里解除暂停;manager 只会diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdxindex 545e55631..8eb39de5f 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx@@ -38,6 +38,7 @@ Estella 的 2D 单位模型刻意保持简单:| `scaleMode` | `ScaleMode` | `FixedHeight` | 设计分辨率如何适配实际屏幕宽高比(见下)。 || `matchWidthOrHeight` | number | `0.5` | `Match` 模式的混合值,0–1:`0` = 适配宽度,`1` = 适配高度。其余模式忽略。 || `backgroundColor` | Color | `{r:0, g:0, b:0, a:1}` | 为设计盒之外的 letterbox/pillarbox 区域声明的背景色。 |+| `layer` | number | `0` | 该画布的 UI 所属的排序层——相机通过它包含或排除这块 UI(见下文 `Camera.cullingMask`)。 |```typescriptimport { defineSystem, GetWorld, Canvas } from 'esengine';@@ -130,8 +131,8 @@ const halfH = computeEffectiveOrthoSize(里另一个盒子"。<Aside type="caution">- 适配源生效期间,主相机自己写的 `orthoSize` **不会被使用**——可见半高完全来自设计分辨率- 与缩放模式。通过编辑/tween `orthoSize` 缩放,只在没有适配源时生效(场景无 `Canvas`+ 适配源生效期间,全屏正交场景相机自己写的 `orthoSize` **不会被使用**——可见半高完全来自设计分辨率+ 与缩放模式。子视口相机、渲染到纹理的相机和透视相机保留自己的缩放。通过编辑/tween `orthoSize` 缩放,只在没有适配源时生效(场景无 `Canvas`且项目适配关闭)。</Aside>@@ -149,8 +150,9 @@ const halfH = computeEffectiveOrthoSize(| `designHeight` | number | `1080` | 设计(参考)分辨率高度,像素。 || `scaleMode` | number | `SCREEN_FIT_OFF`(`-1`) | 真实的 `ScaleMode`(`0`–`4`)**开启**项目适配;`SCREEN_FIT_OFF` 保持旧行为(有 Canvas 用 Canvas 适配,否则原始 `orthoSize`)。 || `matchWidthOrHeight` | number | `0.5` | `Match` 模式混合值 0–1(`0` = 适配宽度,`1` = 适配高度);其余模式忽略。 |+| `renderPolicy` | `RenderResolution`(可选) | `RenderResolution.Surface`(`0`) | 场景用什么分辨率绘制。`Surface` 直接画到屏幕;`Design`(`1`)按相机世界高度要求的尺寸绘制(1 世界单位 = 1 渲染像素),再把这一整张图缩放到屏幕——精灵之间没有缝,非整数比例下略软;`IntegerMultiple`(`2`)以整数倍呈现,整数倍铺不满的地方留黑边。与 `scaleMode` 相互独立。 |-`DEFAULT_SCREEN_SCALING` 就是这个默认关闭的值,`SCREEN_FIT_OFF`(`-1`)是哨兵值。项目+`DEFAULT_SCREEN_SCALING` 就是这个默认关闭的值,`SCREEN_FIT_OFF`(`-1`)是哨兵值。`scaleMode` 为真实模式**或** `renderPolicy` 不是 `Surface` 时,该资源都会被安装;相机适配本身只看前者。项目适配开启时它就是**权威**——相机和 UI 布局盒都一样,因为两者解析适配源的方式相同。各发布运行时从项目配置安装它(`createWebApp` 的 `screenFit` 选项)。游戏代码可以实时读取@@ -274,10 +276,12 @@ feed();| `applyBottom` | boolean | `true` | 底部 inset 同理。 || `applyLeft` | boolean | `true` | 左侧 inset 同理。 || `applyRight` | boolean | `true` | 右侧 inset 同理。 |+| `avoidHostMenu` | boolean | `false` | 同时避开宿主自己的悬浮层——微信的胶囊菜单,它位于安全区*之内*。顶部 inset 取安全区 inset 与胶囊底边中的较大者。只对胶囊确实够得着的节点开启:整个节点都会下移。 |平台 inset 在写入前会从设备像素换算到 UI 设计像素,布局保持分辨率无关:- **微信:**自动从 `wx.getSystemInfoSync().safeArea` 读取。+- **原生(iOS / Android):**每帧读取平台缓存的系统 inset。- **Web:**从根元素上的 `--sat` / `--sab` / `--sal` / `--sar` CSS 自定义属性读取——在宿主页面里用 `env(safe-area-inset-*)` 定义它们即可启用(否则读到 `0`)。@@ -321,21 +325,9 @@ const buildHudRoot = defineSystem([GetWorld()], (world) => {| 方向 | `packaging.orientation`(`'portrait'` \| `'landscape'`;缺省 = 由设计宽高比推导) | 微信 `game.json`、web/playable 旋转提示、桌面窗口宽高比、编辑器设备预览。 || 相机适配 | `features.rendering.cameraScaleMode`(`'none'`、`'fixed-width'`、`'fixed-height'`、`'expand'`、`'shrink'`、`'match'`;缺省 = `'none'`) | 映射到 `ScreenScaling.scaleMode`(`'none'` → `SCREEN_FIT_OFF`)。 || 相机适配 match | `features.rendering.cameraMatch`(0–1,默认 `0.5`) | `ScreenScaling.matchWidthOrHeight`。 |+| 渲染分辨率 | `features.rendering.renderResolution`(`'surface'`、`'design'`、`'integer'`;缺省 = `'surface'`) | `ScreenScaling.renderPolicy`(`Surface` / `Design` / `IntegerMultiple`)。 |-另外,两个 `RuntimeConfig` 旋钮设置**新建 `Canvas` 组件的默认 `scaleMode`**(不影响场景中-已保存的 canvas):`RuntimeConfig.canvasScaleMode`(默认 `1` = `FixedHeight`)与-`RuntimeConfig.canvasMatchWidthOrHeight`(默认 `0.5`)。构建配置通过-`applyBuildRuntimeConfig` 按名字设置——规范的 `CanvasScaleMode` 名字加上 `ShowAll` /-`NoBorder` 别名;未知名字回退到 `FixedHeight`:--```typescript-import { applyBuildRuntimeConfig } from 'esengine';--applyBuildRuntimeConfig(app, {- canvasScaleMode: 'Expand', // name-based: 'FixedWidth' … 'Match', 'ShowAll', 'NoBorder'- canvasMatchWidthOrHeight: 0.5,-});-```+新建的 `Canvas` 以 `scaleMode` `FixedHeight`(`1`)和 `matchWidthOrHeight` `0.5` 起步——即组件默认值。场景中已保存的 canvas 保持它们保存的值。## 最佳实践diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdxindex ce278fdf4..cc416964a 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx@@ -38,7 +38,7 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {});```-`position.x/y/z`、`rotation.z`、`scale.x/y/z` 是可动画字段([Sequencer](/docs/zh-cn/animation/timeline/)+`position.x/y/z`、`rotation.x/y/z/w`、`rotation.angle`(Z 轴转角,弧度,不影响另外两个轴)、`scale.x/y/z` 是可动画字段([Sequencer](/docs/zh-cn/animation/timeline/)和[补间](/docs/zh-cn/animation/overview/#补间tween)可以打关键帧),而 `position` /`rotation` / `scale` 会被[网络](/docs/zh-cn/scripting/networking/)的状态复制同步。@@ -49,8 +49,8 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {</Aside><Aside type="tip">- 编辑器的 Details 面板为了方便,把旋转显示为单个**以度为单位的 Z 角度**,但底层- 存储的数据始终是四元数。+ 编辑器的 Details 面板把旋转显示为**以度为单位的 X / Y / Z 欧拉角**(先 X、再 Y、后 Z;+ 2D 内容只绕 Z 转),但底层存储的数据始终是四元数。</Aside>## 坐标系@@ -173,7 +173,7 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],```想动画化旋转,`TweenTarget.RotationZ` 以**弧度**驱动 Z 角度(引擎每步重建四元数),-Sequencer 给 `rotation.z` 打关键帧也是同样的语义——见+Sequencer 给 `rotation.angle` 打关键帧也是同样的语义——见[动画](/docs/zh-cn/animation/overview/#补间tween)。<Aside type="tip">@@ -239,8 +239,9 @@ world = parentWorld × T(position) × R(rotation) × S(scale)父实体的 `Children` 列表会失去同步——而引擎的一半(布局、渲染、销毁)都在遍历`Children`。永远用 `world.setParent`。- **兄弟顺序在移除后不稳定。**摘除一个子实体是对 `Children` 做 swap-remove,会打乱- 剩余兄弟的次序。不要在 `Children` 顺序里编码含义;绘制顺序用 `position.z` 或- 排序层表达。+ 剩余兄弟的次序。UI 的布局与绘制顺序、层级顺序层(`Renderer.setTreeSortLayers`)都按+ `Children` 顺序来,所以这些要在编辑器的大纲里调整,而不是靠摘下再挂回去。普通 2D 绘制顺序+ 则不要在 `Children` 顺序里编码含义,用 `position.z` 或排序层表达。## 缩放diff --git a/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdxindex 0122e17f7..c2d54481a 100644--- a/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/scenes.mdx@@ -21,7 +21,7 @@ Outliner 是场景的层级。你可以:- 把实体拖到彼此上重设父子,并用**文件夹**归类。- **按名跳转** — 树聚焦时,输入名字的前几个字母即可跳到匹配的实体。-- 用 `F2` **重命名**、`mod + D` **复制**、`Delete` **删除**。+- 用 `F2` **重命名**、Ctrl/⌘ + D **复制**、`Delete` **删除**。- **隐藏/显示**和**锁定/解锁**实体(与组件在运行时是否 enabled 解耦)。隐藏是把实体从编辑视口里拿掉——精灵、骨架、瓦片图、粒子、灯光一概如此——而不改动游戏真正加载的场景。锁定则仍然可见、可选中,只是不再有把手:视口不会拾取它,变换 Gizmo 也不会为它出现。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdxindex f0abd50a4..e3a2d9fb7 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/advanced.mdx@@ -21,24 +21,25 @@ const grid = new NavGrid({ width: 32, height: 24, cellSize: 32 });const path = findPath(grid,- grid.worldToCell(hero.x, hero.y), // Cell — integer grid coordinates- grid.worldToCell(chest.x, chest.y),+ grid.worldToCell(hero), // Cell — integer grid coordinates+ grid.worldToCell(chest),{ diagonal: false },);if (path) {- const waypoints = pathToWorld(grid, path); // Vec2[] — cell centers, world pixels+ const waypoints = pathToWorld(grid, path); // Vec3[] — cell centers, world pixels}````findPath(grid, start, goal, opts?)` 返回含首尾两端的 `Cell[]` 路径,不可达时返回`null`。`Cell` 是整数网格坐标 `{ x, y }`(与 `Vec2` 刻意区分,以标示格子空间);用-`grid.worldToCell` / `grid.cellToWorld` 互转,或用 `pathToWorld` 把整条路径转成+`grid.worldToCell(point)` / `grid.cellToWorld(gx, gy)` 互转,或用 `pathToWorld` 把整条路径转成世界空间路点。| `PathfindOptions` 字段 | 默认 | 说明 ||---|---|---|| `diagonal` | `true` | 允许 8 连通的对角移动。 || `snapRadius` | `8` | 起点/终点落在被阻挡格子上时,先在此环半径内吸附到最近的可走格子再搜索;`0` 关闭吸附。 |+| `clearance` | `0` | 身体每一步需要的余量(格数,`0` 按一个点规划)。`NavAgent` 的 `radius` 会自动换算成它。 |`navGridFromTiles` 从任意瓦片读取器构建可走掩码——它是 `navGridFromTilemapLayer`底下的核心,后者只是接上了 `TilemapAPI.getTile`:diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/authoring.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/authoring.mdxindex 63e1c49df..c20c59417 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/authoring.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/authoring.mdx@@ -5,7 +5,7 @@ description: "推荐工作流:叶子逻辑在代码里注册一次,图本身在设想的工作流是图本身**用数据、不用代码**——你注册一次叶子逻辑,然后可视化地构建并调优机器/树:-1. 在**内容浏览器**里,新建一个**状态机**(`.esfsm`)或**行为树**(`.esbt`)资产,双击它打开+1. 在**内容浏览器**的新建菜单里选**新建状态机**或**新建行为树**,得到一个 `.esfsm` 或 `.esbt` 资产,双击它打开节点图编辑器。2. 添加状态/节点,拖拽连线,把每个叶子的**动作**或**条件**填成你注册的某个名字。在检视面板里设置转移的条件、触发器和黑板守卫。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/behavior-trees.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/behavior-trees.mdxindex e6ce97194..f30227dbc 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/behavior-trees.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/behavior-trees.mdx@@ -46,16 +46,20 @@ registerBt('guard', {});```+这棵树是**响应式**的:组合节点每个 tick 都从第一个子节点重新求值,不记得上次运行到哪个子节点,所以+条件刚变真的高优先级分支会抢占正在 `Running` 的低优先级分支。只有 `wait` 和 `repeater` 保存逐节点的+状态(已过时间、已完成次数)。+节点类型:| 类别 | 类型 | 行为 ||---|---|---|-| 组合 | `sequence` | 按序 tick 子节点;第一个失败即失败,全部成功才成功。 |-| | `selector` | 按序 tick 子节点;第一个成功即成功,全部失败才失败。 |-| | `parallel` | tick 全部子节点;`policy: 'one'` 任一成功即成功,`'all'`(默认)全部成功才成功。 |-| 装饰器 | `inverter` | 反转子节点的成功/失败。 |-| | `succeeder` | 总是报告 Success。 |-| | `repeater` | 把子节点重跑 `count` 次(`0` = 永远)。 |-| | `wait` | 运行 `seconds` 秒后报告 Success。 |-| 叶子 | `action` | 运行已注册动作 `name`;它的 `Status`(void 则为 `Success`)向上传播。 |+| 组合 | `sequence` | 按序 tick 子节点;第一个失败即失败,全部成功才成功,遇到第一个 `Running` 的子节点就停在那里。 |+| | `selector` | 按序 tick 子节点;第一个成功即成功,全部失败才失败,遇到第一个 `Running` 的子节点就停在那里。 |+| | `parallel` | 每帧 tick 全部子节点。`policy: 'all'`(默认)任一失败即失败、全部成功才成功;`'one'` 任一成功即成功、全部失败才失败;其余情况报告 `Running`。 |+| 装饰器 | `inverter` | 反转子节点的成功/失败;`Running` 原样透传。 |+| | `succeeder` | 子节点一结束就报告 Success;`Running` 原样透传。 |+| | `repeater` | 把子节点重跑 `count` 次(`0` = 永远)。每次跑完(无论成败)算一次;两次之间报告 `Running`,最后一次之后报告 `Success`。 |+| | `wait` | 在 `seconds` 秒内报告 `Running`(它是叶子,没有子节点),之后报告 `Success`。 |+| 叶子 | `action` | 运行已注册动作 `name`;它的 `Status`(void 则为 `Success`)向上传播。名字未注册则失败。 || | `condition` | 已注册条件 `name` 为真时返回 `Success`,否则 `Failure`。 |diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/blackboard.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/blackboard.mdxindex 1657806ed..40a1ef623 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/blackboard.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/blackboard.mdx@@ -20,6 +20,23 @@ registerAction('takeDamage', (ctx) => {| `has(key)` / `delete(key)` | 测试 / 删除一个 key。 || `fire(trigger)` | fire 一个一次性事件;以它为键的转移在被采用前保持启用。 || `isFired(trigger)` / `consume(trigger)` | 测试 / 清除一个触发器。 |+| `clearTriggers()` | 清掉所有待处理的触发器。 |黑板的值支撑 FSM 转移上的 `guard` 比较,而 `trigger` 机制就是 Unity 式的边事件:fire 一次,被采用它的那条转移消费。++叶子之外的游戏代码通过两个资源访问某个 agent 的黑板,也可以在 agent 首次 tick 之前先写入初值或 fire+触发器。黑板与实体同生命周期,不会被序列化:++```typescript+import { AiFsm, AiBt } from 'esengine/ai';++const fsm = app.getResource(AiFsm);+fsm.blackboard(enemy).set('health', 100);+fsm.fire(enemy, 'alarm'); // 被该 agent 下一条启用的转移消费+fsm.state(enemy); // 当前激活状态名;首次 tick 之前为 null++const bt = app.getResource(AiBt);+bt.blackboard(enemy); // 行为树 agent 的黑板+bt.status(enemy); // 上一次根状态+```diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdxindex cee7e4ad5..47473cff7 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx@@ -37,8 +37,8 @@ export const setupNav = defineSystem([Res(Nav)], (nav) => {| `width` | number | 格子列数。 || `height` | number | 格子行数。 || `cellSize` | number | 每格的世界像素(正方形)。 |-| `origin` | `Vec3` | 格子 `(0,0)` 中心的世界坐标。它的 `z` 就是每个路点返回时所在的深度。默认 `(0,0,0)`。 |-| `walkable` | `Uint8Array` | 可选的行主序 `width*height` 掩码,`1` = 可走,`0` = 阻挡。省略则全部可走。 |+| `origin` | `{ x, y, z? }` | 格子 `(0,0)` 中心的世界坐标。它的 `z` 就是每个路点返回时所在的深度。默认 `(0,0,0)`。 |+| `walkable` | `ArrayLike<number>` | 可选的行主序 `width*height` 掩码,`1` = 可走,`0` = 阻挡。省略则全部可走。会被拷贝进去,不保留引用。 |若想从已绘制的瓦片地图推导网格,而不是手写掩码,用 `navGridFromTilemapLayer`(把某图层的实心瓦片视作阻挡)或 `navGridFromTiles`。`grid.setWalkable(x, y, false)` 随时可以关掉一格@@ -112,7 +112,7 @@ async function replaceTerrain(nav: Navigation, load: () => Promise<NavGridOption每个体积只烘焙一次,在它的几何可用的第一帧——网格碰撞体在资产加载完之前贡献不了任何三角面,烘焙会等它。想按自己的方式烘焙的游戏可以直接调 `buildNavMesh(verts, indices, options)`,-而 `collectNavGeometry(world, box)` 就是收集三角面的那一步。+而 `collectNavGeometry(world, { min, max, layers? })` 就是收集三角面的那一步。<Aside type="caution">**一张网格只对应一种 agent 尺寸。**`agentRadius` 是烘进去的,不是查询时才应用的:这张网格@@ -200,6 +200,10 @@ world.set(entity, NavObstacle, door);会移动的物体该交给和它碰撞的角色控制器,不是交给烘焙。</Aside>+++*烘焙出的可走面,由**视图 ▸ 显示导航网格**在视口里填色并描边。*+### 看见烘出来的东西体积的线框说的是烘焙**往哪看**。想在还在编排场景的时候就看见它**找到了什么**,打开@@ -210,12 +214,16 @@ world.set(entity, NavObstacle, door);同一张图在运行中的游戏里由 `NavDebugDraw` 资源给出:```typescript+import { NavDebugDraw } from 'esengine/ai';+app.getResource(NavDebugDraw).enabled = true;```+`showFaces`、`showBorders`、`showLinks`(默认都是 `true`)分别开关面轮廓、红色的终止边和 `NavLink` 连线。+每个可走的面都画在它实际所在的位置——网格画在地面高度上,格子画在场景自己的平面上——而可走世界**终止**的每一条边都标成红色。那些边是唯一能解释「路线为什么绕远」的东西。默认关闭-(一个 surface 是每帧几千个环),而且画到几千个面就停:想看清更大的世界,调 `cellSize`。+(一个 surface 是每帧几千个环),而且画到 4096 个面就停:想看清更大的世界,调 `cellSize`。<Aside type="tip">`Nav` 资源也能直接回答一次性查询:`nav.findWorldPath(from, to)` 返回一组世界空间路点,@@ -238,8 +246,9 @@ app.getResource(NavDebugDraw).enabled = true;| `partial` / `disconnected` | 路线止于断开的区域或关闭通道的可达一侧。 || `partial` / `insufficient-clearance` | 点能通过格子,但指定宽度的角色无法通过。 || `unavailable` / `no-surface` | 尚未安装导航面。 |+| `unavailable` / `building` | 有一次导航面替换正在进行(`nav.surfaceUpdatePending`)。 || `unavailable` / `start-unavailable` | 找不到可用起点。 |-| `target-unavailable` | 找不到可用终点;网格仍可能给出靠近它的部分路线。 |+| `unavailable`(格子)或 `partial`(网格)/ `target-unavailable` | 找不到可用终点;网格仍会给出靠近它的部分路线。 || `unavailable` / `radius-mismatch` | 角色半径超过导航网格烘焙时的半径。 || `unknown` / `diagnostics-unavailable` | 自定义导航面仅实现了原有路径接口。 |@@ -273,6 +282,10 @@ node tools/navigation-rebuild-benchmark.mjs output/navigation-reference.json --s对照只替换旧寻路实现,两侧均使用当前的动态障碍净空。报告包含源码与 bundle 标识、原始构建/查询耗时和帧间隔。该计时不含物理几何收集、避让、渲染及完整游戏帧的其余工作。+++*一个 **Nav Agent**:它怎么移动,然后是它要去哪里。*+### 移动 agent`NavAgentSystem` 按先进先出顺序,跨帧处理规划请求。默认每帧最多 **16 次查询**,@@ -328,9 +341,9 @@ stopNavAgent(world, entity);| `radius` | `0` | 身体有多宽(像素)。在格子上,寻路会绕开它挤不过去的地方;在网格上,这件事由体积的 `agentRadius` 决定。 || `arriveRadius` | `6` | 距最终目标的停止距离。 || `repathInterval` | `0.5` | 周期重规划间隔;`0` 关闭周期刷新,目标/拓扑变化和受阻恢复仍会重规划。 |-| `hasTarget` | `false` | 是否已设目的地(自动管理)。 |+| `hasTarget` | `false` | 是否已设目的地。由 `setNavDestination` 置真;到达时和调用 `stopNavAgent` 时清除。 || `targetX`、`targetY`、`targetZ` | `0` | 当前目的地(世界像素)。 |-| `arrived` | `false` | agent 到达目标的那一帧被置真。 |+| `arrived` | `false` | agent 到达目标时被置真,直到下一次 `setNavDestination` 才清除。 |`setNavDestination` 每帧调用都安全,可用于追一个移动的目标——只有当目标真的移动、或`repathInterval` 到点,或拓扑变化/受阻恢复时,agent 才重新规划。读 `agent.arrived`(或 `Perception`)来判断何时diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdxindex e00e8c03d..171e27997 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/overview.mdx@@ -62,11 +62,17 @@ registerAction('chase', (ctx) => {| `ctx.dt` | `number` | 帧间隔(秒)。 || `ctx.world` | `World` | 完整世界访问,用于跨实体读取。 || `ctx.commands` | `Commands` | 延迟的 spawn/despawn,tick 中调用安全。 |+| `ctx.input` | `InputState` | 运行时输入——和 `defineBehavior` 读到的是同一份状态。宿主没有输入设备时为空(什么都没按下)。 || `ctx.blackboard` | `Blackboard` | 该 agent 的 AI 数据面(见[黑板](/docs/zh-cn/gameplay/ai/blackboard/))。 || `ctx.get(Comp)` | `ComponentData` | 读取**本**实体上的另一个组件。 || `ctx.set(Comp, data)` | `void` | 写入**本**实体上的一个组件。 || `ctx.has(Comp)` | `boolean` | 本实体是否拥有 `Comp`。 |+动作的调用形式是 `(ctx, blackboard, arg?, params?, out?)`,条件是 `(ctx, blackboard)`;+`registerAction` 也接受一个规格对象(`{ run, params, outputs, pure, touches, separator }`)来+声明带类型的参数,编辑器随之把它渲染成真正的控件而不是一个文本框。+`registerValue(name, spec)` 注册一个只回答问题的纯名字,供脚本图读取。+<Aside type="tip">在模块加载时(顶层,或在一个 `Schedule.Startup` 系统里)注册你的动作和条件,好让它们在任何agent 开始 tick 之前就已存在。注册表是进程级的,在多个 `App` 实例间共享。@@ -126,15 +132,17 @@ export enum Status { Success = 'success', Failure = 'failure', Running = 'runnin| `audio.stop` | 动作 | 放下 `AudioSource` 的播放旗标。 || `audio.finished` | 条件 | 非循环剪辑播完且已停止播放时为真。 || `soundEvent.trigger` / `soundEvent.stop` | 动作 | 触发 / 停止该实体的 `SoundEventSource`。 |-| `property.set` | 动作 | 按 `Component.field` 路径与取值写入代理实体(或另一实体)的任意组件字段,例如 `UIVisual.color.a`。 |+| `property.set` | 动作 | 按 `Component.field` 路径与取值写入代理实体(或通过可选的 `entity` 参数指定的另一实体)的任意组件字段,例如 `UIVisual.color.a`。字符串参数形式为 `path=value`;取值能按 JSON 解析时按 JSON 读(`3`、`true`、`{"r":1}`),否则当作字符串。 |动作可携带一个可选**字符串参数**——在 FSM 状态检查器的动作名旁(或 BT 动作节点上)填写。内置动作用它承载组件无法按状态携带的数据,比如 `spriteAnim.play` 要切换到哪个剪辑;-你自己注册的动作在第三个参数收到它:`(ctx, blackboard, arg) => …`。+你自己注册的动作在第三个参数收到它:`(ctx, blackboard, arg) => …`。声明了 `params` 的动作还会在第四个参数里按名字收到同样的值。三者组合出一个**零代码的过场状态**:进入状态即播放片段,片段播完即驱动转移:```typescript+import { registerFsm } from 'esengine/ai';+registerFsm('intro', {initial: 'Cutscene',states: [@@ -188,12 +196,16 @@ enemy.add(MeleeAttack, { radius: 110, damage: 20, anchor: swordSocket });enemy.add(Health, { current: 50, max: 50 });```-| 字段 | 作用 |-|---|---|-| `attackRange` | 地平面上靠近到多远才挥击。 |-| `attackInterval` | 两次挥击之间的秒数。 |-| `rotationSpeed` | 转身速度,度/秒。 |-| `idleThreshold` | 低于这个速度就告诉动画器它站着不动。 |+`Hunter` 是 3D 组件:它在 x/z 地平面上量距离,通过 `CharacterController3D` 移动,并设置名为+`attack` 的动画器触发器,所以该实体需要一个能响应这个触发器的 `Animator`。++| 字段 | 默认值 | 作用 |+|---|---|---|+| `attackRange` | `110` | 地平面上靠近到多远才挥击。 |+| `attackInterval` | `1.6` | 两次挥击之间的秒数。 |+| `rotationSpeed` | `540` | 转身速度,度/秒。 |+| `idleThreshold` | `8` | 低于这个速度就告诉动画器它站着不动。 |+| `enabled` | `true` | 关闭后这个猎手被整个跳过。 || `state` | 引擎写入:`idle` / `chase` / `attack` / `dead`。 || `cooldown` | 引擎写入:还有多少秒才能再挥。 |diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdxindex ab4b7db1f..cab8baff7 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/perception.mdx@@ -4,7 +4,12 @@ description: "Perceiver 在视锥内感知附近目标,并把看到的写进 Per---`Perceiver` 每帧扫描最近的、可见的 `PerceptionTarget`,把结果写进同一实体上的 `Perception`-组件。决策读 `Perception`;感知只是 ECS 数据,而不是一条旁路。+组件(实体上没有时会自动加一个)。`Perceiver` 不会感知自己。决策读 `Perception`;感知只是 ECS 数据,+而不是一条旁路。这一步在 `PreUpdate` 里运行、只在运行模式下执行,所以决策系统同一帧就能读到新结果。++++***Perceiver**(上)和它写入的 **Perception**(下,运行前是关闭的)。*```typescriptimport { Perceiver, PerceptionTarget, Perception } from 'esengine/ai';@@ -24,7 +29,7 @@ cmds.spawn()| 组件 | 字段 | 默认 | 说明 ||---|---|---|---|| **`Perceiver`** | `range` | `220` | 视野范围(世界像素)。 |-| | `fovDegrees` | `360` | 视野锥角度(`360` = 全向)。 |+| | `fovDegrees` | `360` | 视野锥角度,范围 `0`–`360`(`360` = 全向)。 || | `facingAxis` | `'x'` | 视野锥沿实体自身哪根轴指向:`'x'` 是屏幕右方(平面场景),`'-z'` 是导入 3D 模型的朝向。 || | `losLayers` | `0` | 仅 3D:视线射线可命中的物理层(`0` = 所有层)。 || **`Perception`** | `visible` | `false` | 当前是否看见一个目标。 |diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/state-machines.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/state-machines.mdxindex 6be14da65..9f96ec5a8 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/state-machines.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/state-machines.mdx@@ -49,7 +49,10 @@ registerFsm('guard', {});```-每个状态最多带三个具名钩子——`onEnter`、`onUpdate`、`onExit`——以及一组 `transitions`。当一条+每个状态最多带三个具名钩子——`onEnter`、`onUpdate`、`onExit`——以及一组 `transitions`。钩子是一个已注册的动作名,+需要参数时写成 `{ name, arg?, params? }`。`onEnter` 在该状态激活后的第一个 tick 运行(也就是转移进入它之后的+下一个 tick),`onExit` 在转移被采用时运行,`onUpdate` 在没有转移触发的 tick 上运行。每个 tick 最多采用一条转移。+指名了一个未注册条件的转移永远不会启用。当一条转移所指定的机制**全部**成立时它才被启用;一条什么都不指定的转移是无条件的:| 转移字段 | 说明 |@@ -60,4 +63,5 @@ registerFsm('guard', {| `guard` | 一个或多个黑板比较,按 AND 组合。 |守卫用 `==`、`!=`、`<`、`<=`、`>`、`>=`、`truthy`、`falsy` 比较一个黑板 key——例如-`{ key: 'health', op: '<', value: 20 }`。+`{ key: 'health', op: '<', value: 20 }`。`truthy` / `falsy` 忽略 `value`;key 不存在时读作 `undefined`,+大小比较按数值进行。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdxindex 7e105d42d..099e80ee0 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx@@ -62,7 +62,8 @@ app.addPlugin(new Physics2DPlugin('physics.js'));```typescriptimport { defineSystem, Commands, Query, Marker, Transform } from 'esengine';-// 只跑一次:找到每个 spawn 标记,把玩家放到第一个上。+// 找到每个 spawn 标记,把玩家放到第一个上。+// 用 app.addSystemToSchedule(Schedule.Startup, placePlayer) 注册,它就只跑一次。const placePlayer = defineSystem([Commands(), Query(Marker, Transform)], (cmds, markers) => {for (const [entity, marker, transform] of markers) {if (marker.type !== 'spawn') continue;@@ -117,7 +118,8 @@ const onTrigger = defineSystem([Res(Physics2DEvents), Query(Marker)], (events, m在繁忙的世界里让传感器保持廉价:把触发区和应当感知它们的刚体放到专门的[碰撞层](/docs/zh-cn/gameplay/physics/#碰撞过滤)上,让每个传感器的掩码收窄它要考虑的范围。完整-事件面见 [碰撞与传感事件](/docs/zh-cn/gameplay/physics/#碰撞与传感事件)。+事件面见 [碰撞与传感事件](/docs/zh-cn/gameplay/physics/#碰撞与传感事件)。同样的穿越还会按实体发出+`trigger_enter` / `trigger_exit` 事件,挂在触发区上的[事件绑定](/docs/zh-cn/scripting/events/)不写代码就能响应。## 从 Tiled 导入@@ -127,12 +129,12 @@ const onTrigger = defineSystem([Res(Physics2DEvents), Query(Marker)], (events, m| Tiled 对象 | 变成 ||---|---|| **点(Point)** | 一个 `Marker`(它的 `type` = Tiled 的 class,它的自定义属性 → `Marker.properties`)。 |-| **矩形 / 椭圆 / 多边形 / 折线** | 一块触发 **Region**——一个 `Marker` 加一个匹配的传感器碰撞体(当对象组名为 `collision` 时则是实心几何体)。 |+| **矩形 / 椭圆 / 多边形 / 折线** | 一块触发 **Region**——一个 `Marker`(它的 `type` = Tiled 的 class)加一个静态刚体和与形状匹配的碰撞体:盒、圆、最多 8 个顶点的多边形(更多则退回它的包围盒)或开放的链。它是传感器;当对象组名为 `collision` 时则是实心几何体。 || **瓦片对象**(带 gid) | 地图的一个精灵子实体。 |于是一条 `Query(Marker)` 就能读到出生点,无论你是在 Estella 编辑器里放的还是在 Tiled 里画的。(导入的对象在每次加载时从 `.tmj` 重新派生,因此只在播放模式存在;手工创建的 Marker 是普通的-序列化实体。)如果你需要某个形状的精确顶点,原始的对象组数据仍可经 `getTilemapSource` 取得。+序列化实体。)如果你需要某个形状的精确顶点,原始的对象组数据仍可经 `tilemapSource(assets, ref)`(来自 `esengine/tilemap`)取得。## 找出离得最近的@@ -145,7 +147,7 @@ const near = nearestMarkers(world, { x: player.x, y: player.y }, { radius: 60, tif (near[0]) promptFor(world.get(near[0].entity, Marker).type); // 按钮上写什么,由游戏决定```-`type` 可以给一个或多个类型,`has` 只保留 `properties` 里带有全部给定键值的标记,`radius` 和 `limit` 限定结果范围,`plane: 'xz'` 表示在地面上量距离。`nearestEntities(world, Component, from, options)` 对任何组件都一样,并可用 `filter` 按组件数据过滤。被 `Disabled` 关掉的实体找不到。每次询问都是对带该组件的实体过一遍,按一次按钮,或每帧刷新一次提示,在一个村子里几百个东西的规模下完全负担得起。+`type` 可以给一个或多个类型,`has` 只保留 `properties` 里带有全部给定键值的标记,`radius` 和 `limit` 限定结果范围,`plane: 'xz'` 表示在地面上量距离(此时 `from.y` 就是地面的 z)。每个结果形如 `{ entity, distance, x, y }`。`nearestEntities(world, Component, from, options)` 对任何组件都一样,并可用 `filter` 按组件数据过滤。被 `Disabled` 关掉的实体找不到。每次询问都是对带该组件的实体过一遍,按一次按钮,或每帧刷新一次提示,在一个村子里几百个东西的规模下完全负担得起。## 最佳实践diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdxindex ea54ca8d4..917d01d83 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics-3d.mdx@@ -14,8 +14,8 @@ import { Aside } from '@astrojs/starlight/components';## 配置与 2D 侧模块一样,在编辑器和 Web 运行时里,场景用到 3D 刚体时 3D 世界会自动加载。自定义应用则自己加插件,-所有选项都可省略(重力默认 `{ x: 0, y: -9.81, z: 0 }`,`fixedTimestep` 默认 `1/60`,`pixelsPerUnit` 默认 `100`,-`maxBodies` 默认 `1024`):+所有选项都可省略(重力默认 `{ x: 0, y: -9.81, z: 0 }`,`fixedTimestep` 默认 `1/60`,`collisionSteps` 默认 `1`,`pixelsPerUnit` 默认 `100`,+`maxBodies` 默认 `1024`;`layerMasks` 见[碰撞层](#碰撞层)):```typescriptimport { Physics3DPlugin } from 'esengine/physics3d';@@ -39,7 +39,7 @@ cmds.spawn()|---|---|| `bodyType` | `Static` 从不移动,`Kinematic` 由你搬动,`Dynamic` 由求解器解。 || `gravityScale` | 这个刚体分担的重力比例。`0` 是失重,不是「掉得慢」。 |-| `linearDamping` / `angularDamping` | 运动衰减的快慢。 |+| `linearDamping` / `angularDamping` | 运动衰减的快慢(默认都是 `0.05`;2D 刚体默认是 `0`)。 || `fixedRotation` | 冻结刚体被给定的朝向——让角色不会倒下的那个开关。它不会把一个一开始就歪的刚体扶正。 || `layer` | 刚体所在的十六个[碰撞层](#碰撞层)之一。 || `continuousCollision` | 检查这一步走过的整条路径,而不只是它最后停在哪。子弹需要它;默认关闭,因为它更贵。 |@@ -52,6 +52,9 @@ cmds.spawn()| `SphereCollider3D` | `radius`。 || `CapsuleCollider3D` | 一个直立胶囊:`halfHeight` 是圆柱段的一半,两端各扣一个 `radius` 的半球,所以总高是 `2 * (halfHeight + radius)`。 |+默认值:`halfExtents` `{ 0.5, 0.5, 0.5 }`,`radius` `0.5`(胶囊为 `0.3`),`halfHeight` `0.5`——都是世界单位,+所以新加的形状很小,要自己调大。三者还都有 `friction`(`0.3`)、`restitution`(`0`)和 `isSensor`(`false`)。+这三种碰撞体都还有可选的 `center`:形状相对实体原点的位置,单位为世界单位(默认 `{ 0, 0, 0 }`)。刚体仍位于实体处,所以动态刚体绕自己的原点转动,偏离中心的形状会绕着它甩动。@@ -90,6 +93,10 @@ cmds.spawn().insert(ConvexCollider3D, { mesh: 'assets/models/rock.esmesh' });```+++*3D 物理示例开着物理调试绘制:每个碰撞体都被描出轮廓。*+## 看见形状视口把每个 3D 碰撞体画成线框,并跟着实体一起转——屏幕上没有任何别的东西@@ -137,18 +144,25 @@ app.getResource(Physics3DDebugDraw).enabled = true;和自己扫掠的角色,是「这个实体在哪」的两个答案。每步从游戏逻辑设 `velocity`,再把结果读回来。```typescript-const c = world.get(player, CharacterController3D);-c.velocity.x = input.axis('move') * 200;-if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;+const drive = defineSystem([Query(Mut(CharacterController3D)), Res(Input)], (q, input) => {+ for (const [, c] of q) {+ c.velocity.x = (input.isKeyDown('KeyD') ? 200 : 0) - (input.isKeyDown('KeyA') ? 200 : 0);+ if (input.isKeyPressed('Space') && c.isOnFloor) c.velocity.y = 500;+ }+});+app.addSystemToSchedule(Schedule.FixedUpdate, drive);```| 字段 | 作用 ||---|---|| `velocity` | 期望速度,世界单位/秒。`y` 为正就是跳。 |-| `stepHeight` | 能迈上去而不是被挡住的最高台阶。`0` 就什么都迈不上。 |-| `snapDown` | 过坡顶时向下够多远以贴住地面。`0` 是关掉。 |-| `maxSlope` | 能站住的最陡地面;比这更陡就会滑下去。 |-| `pushForce` | 撞上动态刚体时能推多用力。`0` 什么都推不动。 |+| `radius` / `halfHeight` | 被扫掠的直立胶囊(默认 `0.3` / `0.5`,世界单位),形状与 `CapsuleCollider3D` 相同。 |+| `stepHeight` | 能迈上去而不是被挡住的最高台阶(默认 `0.4`)。`0` 就什么都迈不上。 |+| `snapDown` | 过坡顶时向下够多远以贴住地面(默认 `0.5`)。`0` 是关掉。 |+| `maxSlope` | 能站住的最陡地面,弧度(默认 `0.87`,约 50°);比这更陡就会滑下去。 |+| `mass` | 角色质量,千克(默认 `70`),推东西时用。 |+| `pushForce` | 撞上动态刚体时能推多用力(默认 `5000`)。`0` 什么都推不动。 |+| `layer` | 所在的[碰撞层](#碰撞层)(0–15)。 || `isOnFloor` / `floorNormal` / `realVelocity` | 输出,步进之后读。 |<Aside>@@ -161,6 +175,10 @@ if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;更重的要给更多,而 `0` 会让它把所有东西都当成墙。</Aside>+++*第三人称示例里玩家的 **Character Controller 3D** 和 **Third Person Controller**。*+## 第三人称`ThirdPersonController` 与 `ThirdPersonCamera` 是角色之上的 gameplay 层:输入@@ -168,8 +186,8 @@ if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;```typescript// 不需要写脚本,两者都是场景声明的组件。-player.add(ThirdPersonController, { moveSpeed: 320, jumpSpeed: 520 });-rig.add(ThirdPersonCamera, { target: player, distance: 420 });+world.insert(player, ThirdPersonController, { moveSpeed: 320, jumpSpeed: 520 });+world.insert(rig, ThirdPersonCamera, { target: player, distance: 420 });```摇杆是在相机的**地面**平面里读的,所以镜头再怎么俯视,角色仍然沿地面走。俯仰@@ -177,12 +195,27 @@ rig.add(ThirdPersonCamera, { target: player, distance: 420 });| 字段 | 作用 ||---|---|-| `moveSpeed` | 地面上的最高速度,世界单位/秒。 |-| `acceleration` / `deceleration` | 加速到该速度的快慢,以及减速的快慢。 |-| `rotationSpeed` | 转向「实际去过的方向」的角速度,度/秒。 |-| `jumpSpeed` | 起跳的初始向上速度。`0` 表示不能跳。 |-| `airControl` | 离地时 `acceleration` 生效的比例,0..1。 |-| `camera` | 摇杆以谁的前方为准。 |+| `moveSpeed` | 地面上的最高速度,世界单位/秒(默认 `320`)。 |+| `acceleration` / `deceleration` | 加速到该速度的快慢,以及减速的快慢,单位/秒²(默认 `2400` / `3200`)。 |+| `rotationSpeed` | 转向「实际去过的方向」的角速度,度/秒(默认 `720`)。 |+| `jumpSpeed` | 起跳的初始向上速度。`0`(默认)表示不能跳。 |+| `airControl` | 离地时 `acceleration` 生效的比例,0..1(默认 `0.3`)。 |+| `cameraRelative` | 在相机的地面平面里读摇杆(默认 `true`),而不是世界的。 |+| `camera` | 摇杆以谁的前方为准;`0`(默认)表示找到的第一个 `ThirdPersonCamera`。 |+| `idleThreshold` | 低于这个速度,就告诉动画角色是站着的(默认 `8`)。 |++`ThirdPersonCamera` 在指针控制下绕 `target` 旋转:++| 字段 | 作用 |+|---|---|+| `target` | 它绕着转的实体;`0` 让相机不动。 |+| `distance` | 没有东西挡路时它在后方多远,世界单位(默认 `420`)。 |+| `yaw` / `pitch` | 绕世界上方向的转角,以及高出地平线的角度(正值向下看),度(默认 `0` / `15`)。 |+| `minPitch` / `maxPitch` | 俯仰限位,度(默认 `-30` / `70`)。 |+| `sensitivity` | 指针每移动一像素转多少度(默认 `0.2`)。 |+| `followDamping` | 位置追上的快慢,每秒;`0` 为刚性(默认 `12`)。 |+| `targetOffset` | 把支点从目标原点抬高,让镜头框住胸口而不是脚(默认 `{ 0, 90, 0 }`)。 |+| `obstruction` / `obstructionRadius` / `obstructionLayers` | 支点与眼睛之间有实体时拉近(默认开)、探针的粗细(默认 `15`)、能撞到的层(`0` 为所有层)。 |<Aside>告诉动画的是角色**实际达到**的速度,而不是它请求的速度。顶着墙的角色摇杆推满@@ -207,14 +240,14 @@ rig.add(ThirdPersonCamera, { target: player, distance: 420 });——`attack-start`、`hit`、`attack-end`:```typescript-player.add(MeleeAttack, { radius: 70, damage: 25, anchor: swordSocket });-dummy.add(Health, { current: 100, max: 100 });+world.insert(player, MeleeAttack, { radius: 70, damage: 25, anchor: swordSocket });+world.insert(dummy, Health, { current: 100, max: 100 });```| 字段 | 作用 ||---|---|-| `radius` | `hit` 节拍测试的球半径,世界单位。 |-| `damage` | 一次落地的攻击扣掉多少。 |+| `radius` | `hit` 节拍测试的球半径,世界单位(默认 `60`)。 |+| `damage` | 一次落地的攻击扣掉多少(默认 `25`)。 || `layers` | 这一刀能够到的物理层;`0` 表示所有层。 || `anchor` | 查询以哪个实体的**世界**位置为中心。 || `attackId` | 引擎写入:正在进行的那一刀,没有时为 `0`。 |@@ -251,7 +284,7 @@ const hitSparks = defineSystem();```-一次攻击携带 `target`、`source`、`amount` 和它落在哪个点——这个点事后是找不回来的,+一次攻击携带 `target`、`source`、`amount` 和它落在哪个点(`x`、`y`、`z`)——这个点事后是找不回来的,等火花画出来的时候,那一刀早就挥过去了。总线是双缓冲的,本帧发出的攻击在下一帧落地。<Aside type="tip">@@ -303,6 +336,10 @@ cmds.spawn()需要两个关节的实体就挂一个子实体给第二个,这也正好让场景说清楚哪个是哪个。</Aside>+++*3D 物理示例里门上的 **Hinge Joint 3D**:连接的门框、铰链轴和角度限制。*+## 问世界「那里有什么」`Physics3D` 资源用世界单位回答空间问题。@@ -323,9 +360,11 @@ const occupants = q.overlapSphere(spawnPoint, 50);| 查询 | 回答 ||---|---|-| `raycast` | 一条线上最近的刚体。 |-| `sphereCast` | 一个运动的球最先撞上的刚体。 |-| `overlapSphere` / `overlapBox` | 已经在某个体积里的所有刚体。 |+| `raycast(origin, direction, layerMask?)` | 一条线上最近的刚体,形如 `{ entity, fraction, x, y, z, normalX, normalY, normalZ }`,没有则为 `null`。`direction` 自带射线长度。 |+| `sphereCast(origin, radius, direction, layerMask?)` | 一个运动的球最先撞上的刚体,形状同上,没有则为 `null`。 |+| `overlapSphere(centre, radius, layerMask?)` / `overlapBox(centre, halfExtents, layerMask?)` | 已经在某个体积里的所有刚体,形如 `{ entity, x, y, z }[]`。 |++物理模块加载完成之前 `Physics3D` 是 `null`,所以在最初几帧里询问的系统要先判断。<Aside>层掩码为 `0` 表示**所有层**,不是「一个都不要」:没有要求过滤的调用者是在要全部,diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdxindex 7bf6516e5..14693e641 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx@@ -20,6 +20,20 @@ import { Physics2DPlugin } from 'esengine/physics';app.addPlugin(new Physics2DPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));```+第二个参数是 `Physics2DPluginConfig`,字段全部可选:++| 字段 | 默认 | 说明 |+|---|---|---|+| `gravity` | `{ x: 0, y: -9.81 }` | 世界重力,m/s²。 |+| `fixedTimestep` | `1/30` | 物理步长(秒)。插件同时把应用的固定步长设成它,所以 `FixedUpdate` 系统也以 30 Hz 运行。 |+| `subStepCount` | `4` | 每步的求解器子步数。 |+| `contactHertz` / `contactDampingRatio` / `contactSpeed` | `30` / `10` / `3` | 接触的软度,以及最大推出速度(m/s)。 |+| `collisionLayerMasks` | 无 | 按层的碰撞掩码(下标 = 层 0–15),取代每个碰撞体自己的 `maskBits`;编辑器用碰撞矩阵填它。 |+| `enableSleep` | `true` | 允许静止刚体休眠。 |+| `enableContinuous` | `true` | 对快速刚体做连续碰撞。 |+| `restitutionThreshold` | Box2D 默认 | 产生反弹的最小撞击速度(m/s);`0` 或更小则保持默认。 |+| `maxLinearSpeed` | Box2D 默认 | 刚体速度上限;`0` 或更小则保持默认。 |+<Aside type="note">物理的类型从 **`esengine/physics`** 导入(API、插件、事件),而组件(`RigidBody2D`、各碰撞体、`CharacterController2D`)来自主 `esengine` barrel。@@ -37,6 +51,9 @@ Box2D 以**米**模拟;引擎其余部分以**世界像素**工作。二者的| 面向求解器的方法——`applyForce` / `applyImpulse`、`setLinearVelocity` / `getLinearVelocity`、`setGravity`…… | **米**(m/s、m/s²)。 || 空间查询——`raycast`、`shapeCast*`、`overlapCircle` / `overlapAABB`、`moveCharacter` | **世界像素**,按当前 PPU 缩放。 || `CharacterController2D.velocity`、`MotorJoint2D.linearVelocity` | 世界像素/秒。 |+| 关节组件的 `anchorA` / `anchorB`、`length`、`minLength` / `maxLength`、`lowerTranslation` / `upperTranslation`;以及取像素的关节方法(`setDistanceJointLength`、`setDistanceJointLimits`、`setPrismaticJointLimits`、`setWheelJointLimits`……)和对应的读取方法 | **世界像素。** 角度(铰链的 `lowerAngle`、`motorSpeed`)是弧度。 |+| 接触事件的位置与速度——`contactX/Y`、`pointX/Y`、`approachSpeed` | 世界像素、像素/秒。 |+| `createRevoluteJoint` 的 `anchorA` / `anchorB` | **米**——原样交给求解器,与关节组件的像素锚点不同。 |`physics.getPixelsPerUnit()` 返回当前 PPU(每帧从 `Canvas` 推送),换算永远不用写死 `100`:@@ -88,7 +105,7 @@ const spawnBall = defineSystem([Commands()], (cmds) => {### 碰撞体-所有碰撞体共享这些字段,各自再加自己的形状参数。尺寸以米计。+碰撞体共享这些字段,各自再加自己的形状参数(例外见下表)。尺寸以米计。| 共享属性 | 类型 | 默认 | 说明 ||---|---|---|---|@@ -105,10 +122,10 @@ const spawnBall = defineSystem([Commands()], (cmds) => {|---|---|| `BoxCollider2D` | `halfExtents`(`{0.5, 0.5}`)、`radius`(圆角,`0.05`)。 || `CircleCollider2D` | `radius`(`0.5`)。 |-| `CapsuleCollider2D` | `radius`、`halfHeight`。 |-| `SegmentCollider2D` | `point1`、`point2`(单边)。 |-| `PolygonCollider2D` | `vertices: Vec2[]`(任意形状,可以是凹的)、`radius`(圆角)。 |-| `ChainCollider2D` | `points: Vec2[]`、`isLoop`(静态边链;无 `density`/`isSensor`)。 |+| `CapsuleCollider2D` | `radius`(`0.25`)、`halfHeight`(`0.5`)。 |+| `SegmentCollider2D` | `point1`(`{-0.5, 0}`)、`point2`(`{0.5, 0}`)——单边;没有 `offset`。 |+| `PolygonCollider2D` | `vertices: Vec2[]`(任意形状,可以是凹的;默认一个单位正方形)、`radius`(圆角,`0`);没有 `offset`。 |+| `ChainCollider2D` | `points: Vec2[]`(至少 4 个)、`isLoop`(`true`)——静态边链;`friction` 默认 `0.6`,没有 `offset`、`density`、`isSensor`。 |#### 凹多边形,以及你能画多少个顶点@@ -215,15 +232,15 @@ for (const hit of hits) {const nearby = physics.overlapCircle(center, 64); // Entity[]const inBox = physics.overlapAABB(min, max); // Entity[]-const swept = physics.shapeCastCircle(/* … */); // sweep a shape+const swept = physics.shapeCastCircle(center, 16, { x: 100, y: 0 }); // ShapeCastHit[]```| 方法 | 返回 | 说明 ||---|---|---|-| `raycast(origin, dir, dist, maskBits?)` | 命中列表 | 射线上所有命中,最近优先。 |+| `raycast(origin, dir, dist, maskBits?)` | `RaycastHit[]` | 射线上所有命中,最近优先。`dir` 是方向,`dist` 以像素计。 || `overlapCircle(center, radius, maskBits?)` | `Entity[]` | 与圆重叠的碰撞体。 || `overlapAABB(min, max, maskBits?)` | `Entity[]` | 与盒重叠的碰撞体。 |-| `shapeCastCircle` / `shapeCastBox` / `shapeCastCapsule` | 命中 | 扫掠一个形状并得到它会撞到什么。 |+| `shapeCastCircle(center, radius, translation, maskBits?)` / `shapeCastBox(center, halfExtents, angle, translation, maskBits?)` / `shapeCastCapsule(center1, center2, radius, translation, maskBits?)` | `ShapeCastHit[]` | 沿 `translation` 扫掠一个形状,得到它会撞到的所有东西。 |各种 cast 都返回 `RaycastHit`(`ShapeCastHit` 是同一个形状):@@ -275,6 +292,12 @@ const onHit = defineSystem([Res(Physics2DEvents)], (events) => {});```+事件里的位置是世界像素(`contactX/Y`、`pointX/Y`),速度是像素/秒(`approachSpeed`)。+这个资源每渲染帧发布一次,包含该帧内所有固定步的全部接触。同样的事件还会按实体再发一份:+`collision_enter`、`collision_exit`、`collision_hit`、`trigger_enter`、`trigger_exit`+(即 `Physics2DEventType` 常量)——双方各收到一条,把对方实体放在 `other` 里,+所以创作出来的事件绑定不写代码就能响应触发区。+| 事件列表 | 触发时机 ||---|---|| `collisionEnters` / `collisionExits` | 两个实心碰撞体开始 / 停止接触。 |@@ -344,15 +367,15 @@ physics.setMotorJointLinearVelocity(crate, { x: -200, y: 0 }); // 运行时反```typescriptimport { OneWayPlatform2D } from 'esengine/physics';-world.spawn(- Transform, { position: { x: 0, y: 0 } },- RigidBody2D, { bodyType: BodyType.Static },- BoxCollider2D, { halfExtents: { x: 2, y: 0.2 } },- OneWayPlatform2D, { normal: { x: 0, y: 1 } }, // 实心顶面:从上落下、从下穿过-);+const platform = world.spawn('ledge');+world.insert(platform, Transform, { position: { x: 0, y: 0 } });+world.insert(platform, RigidBody2D, { bodyType: BodyType.Static });+world.insert(platform, BoxCollider2D, { halfExtents: { x: 2, y: 0.2 } });+world.insert(platform, OneWayPlatform2D, { normal: { x: 0, y: 1 } }); // 实心顶面:从上落下、从下穿过```-`normal` 是世界空间里的实心侧方向;`{ x: 0, y: 1 }`(默认)= "实心顶面"。设 `enabled: false`+`normal` 是世界空间里的实心侧方向;`{ x: 0, y: 1 }`(默认)= "实心顶面"。设+`localSpace: true`(默认 `false`)则法线随刚体旋转,包含父级的旋转。设 `enabled: false`让平台恢复为普通实心体。在编辑器里,单向平台的碰撞体 gizmo 会沿实心侧法线多画一支箭头,朝向一眼可辨。@@ -372,7 +395,8 @@ physics.setMouseTarget(cursorWorld);physics.destroyMouseJoint();```-同一时刻只有一个拖拽在生效。传 `{ hertz, dampingRatio, maxForce }` 调弹簧的刚度与抓力。+同一时刻只有一个拖拽在生效。传 `{ hertz, dampingRatio, maxForce }` 调弹簧的刚度(`hertz`,默认 `7.5`)、阻尼(`dampingRatio`,默认 `1`)+与抓力(`maxForce`,默认按刚体重量自动取值)。`cursorWorld` 是世界像素坐标。## 角色控制器@@ -382,14 +406,15 @@ physics.destroyMouseJoint();干净地移动和起跳,而不是粘在地面上。它把结果写回,并报告碰到了什么:```typescript-import { defineSystem, Query, Mut, CharacterController2D } from 'esengine';+import { defineSystem, Query, Mut, Res, Time, Schedule, CharacterController2D } from 'esengine';-const drive = defineSystem([Query(Mut(CharacterController2D))], (q) => {+const drive = defineSystem([Query(Mut(CharacterController2D)), Res(Time)], (q, time) => {for (const [entity, cc] of q) {- cc.velocity = { x: input.moveX * 240, y: cc.velocity.y - 900 * dt }; // gravity+ cc.velocity = { x: moveX * 240, y: cc.velocity.y - 900 * time.fixedDelta }; // gravityif (cc.isOnFloor && jumpPressed) cc.velocity.y = 480;}});+app.addSystemToSchedule(Schedule.FixedUpdate, drive); // moveX / jumpPressed:你自己的输入```给实体加一个碰撞体(mover 形状由它推导——盒子会内接成沿长轴的胶囊);若希望别的刚体能撞到角色,@@ -447,7 +472,8 @@ gizmo(见[关节——在编辑器里](#在编辑器里));两者互相独立。<## 最佳实践-- **固定时间步**:*每帧*施加持续力、读 `Physics2DEvents`,因为物理独立于帧 delta 做子步。+- **固定时间步**:在 `FixedUpdate` 系统里施加持续力,*每帧*读 `Physics2DEvents`——这个资源每帧发布一次,+ 包含该帧内所有固定步的接触。- 快速细小刚体(子弹、薄平台)用 **`bullet: true`** 防穿透。- 角色用 **`fixedRotation: true`** 免得翻倒。- **碰撞体与求解器用米,查询和角色控制器用像素**——混用是最常见的 bug;用diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdxindex 93b21fd3f..bb890a6d1 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/script-graphs.mdx@@ -49,6 +49,15 @@ description: 用节点和连线可视化编写玩法逻辑,保存为 .esgraph| **取值** | 只产出值的节点(没有执行引脚):`math.*`(add、subtract、multiply、divide、min、max、abs、clamp、lerp、random)、`compare.*`(equal、less、greater)、`logic.*`(and、or、not)、`string.concat`、`property.get`、`entity.self`、`entity.byName`、`input.down` / `pressed` / `axis` / `pointer`——以及所有已注册的条件。 || **图** | 项目里其他可调用的图,用**调用图**节点来调用(在有图声明了入参之前为空)。 |+有几个节点带着值得知道的数据:++- **每帧更新**输出 `dt`,即这一帧的时间增量(秒)。+- **监听事件**按类型监听实体事件(例如 [触发区](/docs/zh-cn/gameplay/markers/)发出的 `trigger_enter`,或按钮的 `click`),+ 输出 `target` 和 `other`——事件发给的实体,以及它另外点名的那个(接触的另一方刚体;没有点名则为 `0`)。+- **顺序**有 1–16 个引脚(默认 2)。**循环**有 `body` 和 `done` 两个引脚。+- **延迟**等待 `seconds` 秒再继续。进入一个已在计时的延迟节点什么也不做,所以高频调用方无法让它一直重启。+ 被别的图调用的图里不能放延迟(一次调用在一步内完成),这张图会把它报告为问题。+菜单按注册名列出这些动词;放到画布上之后,节点会用易读的标题(**按名称找实体**、**按键按下**、**设置属性**……),下面附上注册名。你用 `registerAction` / `registerCondition` 注册的动作和条件——状态机、行为树用的是同一批——会按它们的声明带着对应端口出现在这里。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdxindex 3754234c6..745ae33b3 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx@@ -56,6 +56,8 @@ SDK 默认值为 2D 调好(正交、活动、`orthoSize` 540)。移动相机就| `viewport` | Vec4 | `{0,0,1,1}` | 屏幕矩形 `x, y, w, h`(0–1,分屏/画中画)。 || `clearFlags` | `ClearFlags` | `ColorAndDepth` | 渲染前清什么:`Nothing` / `Color` / `Depth` / `ColorAndDepth`。 || `pixelPerfect` | boolean | `false` | 吸附到世界像素网格,让像素画清晰(正交)。 |+| `cullingMask` | number | 全部层 | 这台相机渲染的排序层位掩码(第 *i* 位 = 第 *i* 层)。 |+| `renderTarget` | number | `0` | 这台相机绘制到的 `RenderTexture` 句柄,而不是屏幕(`0` = 屏幕)——小地图、镜子;运行时由脚本设置。 || `showFrustum` | boolean | `false` | 仅编辑器:画出这台相机的整个视锥体(近面到远面)。关闭时 gizmo 只勾出它在内容平面上取景的范围——相机朝向别处时那里是空的。 |## 缩放与投影@@ -95,6 +97,10 @@ const zoomIn = defineSystem([Res(Tween)], (tween) => {下一致。缩放模式、letterbox 实例与 `ScreenScaling` 字段详见[屏幕与设计分辨率](/docs/zh-cn/core-concepts/screen/)。+++*第三人称示例:相机从角色身后跟随。*+## 跟随目标给相机加一个 `FollowTarget` 并指向一个实体。跟随是帧率无关的阻尼移动,带一个死区,所以相机@@ -122,7 +128,9 @@ const follow = defineSystem([Query(Camera), Commands()], (cameras, cmds) => {| `target` | Entity | `-1` | 要跟随的实体(`-1` = 无)。 || `offsetX` | number | `0` | 相对目标的世界空间 X 偏移。 || `offsetY` | number | `0` | 相对目标的世界空间 Y 偏移。 |-| `deadzone` | number | `0` | 目标可漫游而相机不动的半径(世界单位)。 |+| `offsetZ` | number | `0` | 相对目标的世界空间 Z 偏移(3D 跟随使用)。 |+| `followZ` | boolean | `false` | 同时跟随目标的深度。平面场景保持关闭,因为那里相机的 z 是它退后的距离。 |+| `deadzone` | number | `0` | 目标可漫游而相机不动的半径(世界单位,3D 中为球体)。 || `damping` | number | `0.25` | 平滑时间常数(秒,越大越慢;`0` = 立即吸附)。 |数据形状导出为 `FollowTargetData` 类型。跟随系统直接写相机的 `Transform`(所以 director@@ -173,8 +181,8 @@ const pick = defineSystem([Res(CameraView), Res(Input)], (view, input) => {| 方法 | 返回 | 说明 ||---|---|---|-| `screenToWorld(sx, sy)` | `{x, y} \| null` | 屏幕像素 → 世界位置。 |-| `worldToScreen(wx, wy)` | `{x, y} \| null` | 世界位置 → 屏幕像素。 |+| `screenToWorld(sx, sy, planeZ = 0)` | `{x, y} \| null` | 屏幕像素 → `planeZ` 平面上的世界位置。正交相机忽略该平面;透视相机下请传目标所在的 z。 |+| `worldToScreen(wx, wy, wz = 0)` | `{x, y} \| null` | 世界位置 → 屏幕像素。没有相机或点在眼睛处/身后时为 `null`;在视口之外仍返回坐标。 || `getWorldMousePosition()` | `{x, y} \| null` | 世界空间里的光标。 || `getWorldBounds()` | `{left, right, bottom, top} \| null` | 可见的世界矩形。 |@@ -239,7 +247,7 @@ setViewTarget(app, cutsceneCamera, { time: 1.5, curve: BlendCurve.EaseInOut });| `currentMain` | `CameraPOV \| null` | `null` | 最后解析出的主 POV,**未加震屏**——也是屏幕↔世界转换所用的视图。 || `shakes` | `ActiveShake[]` | `[]` | 活动的瞬时震屏(由 `shakeCamera` 压入,衰减完即丢弃)。 |-其余字段(`hasPending`、`pendingTarget`、`pendingTime`、`pendingCurve`、`from`、+其余字段(`timelineShot`、`timelineOwner`(由播放中的时间线相机轨道写入)、`hasPending`、`pendingTarget`、`pendingTime`、`pendingCurve`、`from`、`startTime`、`shakeSeq`)是 `setViewTarget` 写入的 director 内部请求/混合簿记。```typescriptdiff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex 963231e50..a6667984f 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx@@ -20,6 +20,10 @@ import { Aside } from '@astrojs/starlight/components';经验法则:视觉属于*场景*(参与排序、保存、可检视)就做成组件;属于*某一帧*(调试、类 HUD 覆盖、程序化效果)就在回调里画。+++*绘制示例,每种 API 一幅:**Draw**(雷达)、**Graphics**(星形)和 **MeshRenderer** 彩带。*+## 绘制回调注册一个回调,它每帧在渲染通道内执行,相机的 view-projection 已经就位——无需任何@@ -184,12 +188,11 @@ registerDrawCallback('custom-mesh', () => {## 离屏目标:`RenderTexture`-小地图、头像、镜面——以及[位图缓存](/docs/zh-cn/graphics/sprites/)的底层——-`RenderTexture` 分配一个离屏渲染目标。把绘制命令包在 `begin`/`end` 之间即渲染+小地图、头像、镜面——`RenderTexture` 分配一个离屏渲染目标。把绘制命令包在 `begin`/`end` 之间即渲染进去;得到的 `texture` 是普通纹理句柄,哪里都能用(`Sprite.texture`、`Draw.texture`、材质纹理参数)。-要把**整个场景**画进去,让一台相机指向它:把 `Camera.renderTarget` 设成目标的句柄,+要把**整个场景**画进去,让一台相机指向它:把 `Camera.renderTarget` 设成目标的渲染目标句柄(`rt._handle`,不是放到精灵上的 `rt.texture`),那台相机就画到那里而不是屏幕——在屏幕相机之前渲染,也不参与「谁是主视图」的竞争。它看见什么由自己的排序层(`Camera.cullingMask`)决定,所以小地图相机和玩家相机可以看同一个世界、显示不同的部分。渲染目标在两个后端上都能交给 `Sprite`;这条路径的diff --git a/docs/astro/src/content/docs/zh-cn/graphics/foliage.mdx b/docs/astro/src/content/docs/zh-cn/graphics/foliage.mdxindex 3b8188111..bc3f2a96c 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/foliage.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/foliage.mdx@@ -17,9 +17,10 @@ description: 一个 Foliage 组件,把草或网格散布到一片区域或地形| `count`、`seed` | 每格的植物数,以及种子:换一个种子就在别处长出同样的植物。 || `minScale`、`maxScale` | 每棵植物的大小在这两者之间。 || `minUp`、`heightMin`、`heightMax` | 植物在哪里生长:一个地方最少要朝上多少(调低能让植物长上斜坡),以及一段世界高度范围。 |+| `waterDepth` | 植物能站在水下多深:`0`(默认)让它们只长在干地上,芦苇则站在浅水里。 || `bladeHeight`、`bladeWidth` | 只对草:缩放为 1 时一根草叶的大小。 || `lodDistance`、`drawDistance` | 超过前者,格子用它的远景版本绘制;超过后者就不画。 |-| `cardU0`、`cardV0`、`cardU1`、`cardV1` | 网格的远景版本是两张交叉的卡片,显示它纹理的这个矩形。 |+| `cardU0`、`cardV0`、`cardU1`、`cardV1` | 网格的远景版本是两张交叉的卡片,显示它纹理的这个矩形(`cardTent` 为 `1` 时卡片裁成帐篷形,即针叶树的轮廓,而不是矩形)。 |如果场景里有 [Terrain](/docs/zh-cn/graphics/terrain/),植物就站在它上面,避开太陡的地方,并等它构建完;没有地形时,区域是实体所在高度的平地。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex b1dc9036b..52608ea12 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx@@ -44,10 +44,27 @@ const addSun = defineSystem([Commands()], (cmds) => {| `color` | `{1,1,1,1}` | 光颜色,RGBA 0..1。 || `intensity` | `1` | 亮度倍数。 || `radius` | `200` | 衰减半径,世界单位(Point / Spot)。 |+| `innerRadius` | `0` | 衰减开始前保持满强度的半径(Point / Spot)。 |+| `falloff` | `1` | 衰减形状:`1` 为线性,更大则光集中在光源附近,更小则照得更远。 |+| `shadowStrength` | `1` | 这盏灯的阴影能去掉多少光;`0.6` 让阴影暗而不黑。 |+| `cookie` | — | 一张纹理,它的 **alpha** 就是这盏灯的形状(Point / Spot)。 |+| `cookieSize` | `{0,0}` | cookie 绘制的大小,世界单位;`0` 覆盖灯自己的照射范围。 || `innerAngle` | `30` | 聚光锥内角,度(内部全亮)。 || `outerAngle` | `45` | 聚光锥外角,度(到这里衰减为零)。 || `shadowSoftness` | `0` | 阴影边缘柔和度(光源尺寸);`0` = 硬边。 || `shadowDistance` | `0` | 方向光阴影延伸距离;`0` = 无方向光阴影。 |+| `layerMin` / `layerMax` | `-128` / `127` | Point / Spot / Directional 灯能照到的精灵层范围(见[灯照到哪些层](#灯照到哪些层))。 |+| `sourceAngle` | `0.53` | 仅 Directional:光源的角直径,度(太阳是 0.53);`0` = 硬边。 |+| `meshShadows` | `false` | 在 3D mesh 上投射阴影图(Directional、Spot、Point)。 |+| `shadowExtent` | `0` | 仅 Directional:mesh 阴影图覆盖的半径,以相机为中心;`0` 表示贴合视野。 |+| `followEnvironmentSun` | `false` | 仅 Directional:方向和强度取自环境里的太阳,天空光则不再带太阳。 |+| `aimFollowedSun` | `false` | 配合 `followEnvironmentSun`:按这盏灯自己的 `Transform` 定向,而不是全景图里的太阳。 |+| `environment` | — | 仅 Ambient:烘焙好的 `.esenv` 环境。 |+| `environmentRotation` | `0` | 仅 Ambient:绕向上轴转动环境,度。 |+| `drawEnvironment` | `false` | 仅 Ambient:同时把环境画成场景背后的天空。 |+| `reflectionScale` | `1` | 仅 Ambient:缩放烘焙反射探针显示的内容(`1` = 烘焙原样)。 |+| `reflectionSaturation` | `1` | 仅 Ambient:烘焙反射探针保留多少颜色(`0` = 灰)。 |+| `bakedTint` | `{1,1,1,1}` | 仅 Ambient:乘到烘焙间接光(光照图、探针体积)上——一天或天气的变化通过它缩放烘焙。 || `enabled` | `true` | 不移除也能关掉光源。 |## 光源类型@@ -73,6 +90,10 @@ const addSun = defineSystem([Commands()], (cmds) => {.insert(Light, { type: LightType.Ambient, intensity: 0.25 });```+++*2D 光照示例:光落在暗色方块上,场景其余部分不受光。*+## 大量光源一帧可以同时携带 **112 盏光**:光照循环对每个像素都读取的 16 盏,以及最多 96 盏**分块(tiled)**光。夜晚每隔几米一盏路灯的街道、一条霓虹走廊、@@ -89,6 +110,10 @@ const addSun = defineSystem([Commands()], (cmds) => {- 平面反射只用那 16 盏绘制:它的相机不是分块所对应的那个相机。- 2D 光也走同一个集合,所以有五十支火把的 2D 场景同样被照亮。+++*一盏平行光的 **Light**:字段上方是它的状态和进入本帧的灯光数(1 / 112)。*+## 灯照到哪些层一盏灯会照亮它够得着的每一个精灵,不管精灵在哪一层。这对小屋里的灯就不对了:它不该照亮盖在头顶的屋顶。给灯设置 **Layer Min** 和 **Layer Max**(`layerMin`、`layerMax`),它就只照亮 `layer` 在这个范围内的精灵:@@ -105,6 +130,46 @@ world.insert(lamp, Light, { type: 0, color: { r: 1, g: 0.78, b: 0.45, a: 1 }, in- **方向光**也能设范围,所以太阳可以不照某个室内层。- 每盏灯每个像素多一次比较;没有灯设范围时没有别的开销。+## 塑造衰减++Point 或 Spot 灯从自己的中心起,沿一条直线衰减,到 `radius` 处归零。有两个字段可以把这条线掰弯,+而且都不会改变灯照到哪里为止:++- **`innerRadius`** 让灯在自己的这个半径之内保持满强度,衰减只发生在剩下的那一圈里。带明亮灯芯的+ 灯,就是把 `innerRadius` 设到接近 `radius`;不设就是以前那条直线。+- **`falloff`** 是对剩下那段斜坡取的幂。`1` 是线性。大于 1 时,光集中在光源附近,外圈很快变暗——更接近+ 光的真实行为。小于 1 时,光在大半距离内都保持明亮,然后才结束,这正是风格化 2D 场景常想要的样子。++```ts+// 一盏提灯:明亮的灯芯,然后快速衰减。+entity.insert(Light, {+ type: LightType.Point, radius: 400, innerRadius: 120, falloff: 2.5, intensity: 1.4,+});+```++两者默认都是那条直线,所以在它们出现之前写的场景渲染结果与以前完全一致。++## 给灯一个形状++灯是一个圆,或者一个锥。真实的灯两者都不是:提灯投出参差的光晕,窗户投出一道光柱,火把以衰减曲线描述不+了的形状闪烁。给灯一个 **`cookie`**——一张 alpha 就是形状的纹理——它就照出那个形状。++```ts+entity.insert(Light, {+ type: LightType.Point, radius: 300, intensity: 1.6,+ cookie: 'assets/textures/lantern-glow.png',+});+```++- **alpha 就是形状。** cookie 的颜色不会被读取:灯的颜色属于灯,设色的地方有两处就多了一处。+- **它画在灯所在的位置**,随实体的旋转转动,大小由 `cookieSize` 决定——为零时,则覆盖灯自己的照射范围。+- 它是**乘到**衰减上,而不是替换衰减,所以有形状的灯仍然在 `radius` 处淡出,也仍然遵守 `innerRadius`+ 和 `falloff`。+- **一帧能容纳四盏有形状的灯。** 超过之后,灯照亮场景但不再有形状,就像第五个投影者仍然照亮而不再投影。++形状被画进一张屏幕空间的遮蔽图,每盏有形状的灯占一个通道——和 2D 阴影用的是同一套机器,所以一个 cookie+花的是一个四边形,而不是每盏灯一个纹理槽位。+## 让渲染器接受光照默认情况下,一个 `Sprite` 用**不受光**材质绘制,会忽略每一盏灯。让它受光最简单的方式是@@ -282,6 +347,7 @@ cmds.spawn()| `ShadowCaster2D` 字段 | 默认 | 说明 ||---|---|---|| `size` | `{32,32}` | 遮挡体尺寸,世界单位。 |+| `path` | `[]` | 遮挡体的局部轮廓(三个及以上的点,沿形状顺序排列);设置后取代 `size` 方块。 || `enabled` | `true` | 开关阴影投射。 |阴影**质量**在光源上控制,而非遮挡体:@@ -289,6 +355,7 @@ cmds.spawn()- **`shadowSoftness`** — 光源尺寸。`0` 是锐利硬边;更大的值给出柔和半影(更大、更近的光投出更软的阴影)。半影是这么多个轮廓叠加出来的,所以它多平滑、花多少,是一个画质设置:档位的 `shadowSoftSamples`(1 到 32;低 8、中 12、高 16;在**项目设置 → 渲染 → 画质**里改)。更少更便宜,边缘会显出条带;十六是条带不再被看成一道道独立阴影的位置。- **`shadowDistance`** — 对 **Directional** 光,阴影延伸多远;`0` 让方向光不产生阴影。+- **`shadowStrength`** — 阴影从光里拿走多少,`0..1`。2D 场景通常不想拿走全部:真实的阴影处也被各种反弹光照亮,而 `1` 恰恰是唯一不可能出现的值。### 能放多少,代价是什么diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxindex 5274991d3..4f4597cce 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx@@ -32,13 +32,15 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一| **Model** | `model` | glTF 材质在 base color 之外说的东西:`u_normalMap`、`u_emissive`(`Map`)、`u_occlusionMap` + `u_occlusionStrength`、`u_alphaCutoff`、`u_metallic` / `u_roughness`(以及 `u_metallicRoughnessMap`),还有[着色层](#着色层)——清漆、绒面、各向异性、半透、薄膜干涉、折射率、透射。模型导入会写出它。 || **Toon** | `toon` | 分档受光:每盏灯的光被切成 `u_bands` 个平坦的档(`u_bandSoftness` 让档与档的交界变软),`u_shadeColor` 是灯照不到处的颜色,亮度超过 `u_specThreshold` 画一块平的高光(`u_specColor`,`u_specSize` 是光滑度),再加一圈边缘光(`u_rimColor`、`u_rimWidth`、`u_rimStrength`)。灯的阴影算进它的那一档。用帧里的 16 盏灯,和 Model 一样带着灯的循环。 || **Matcap** | `matcap` | 用一张"打好光的球"的图(`u_matcap`)按表面朝向相机的方向查色。不问任何灯、不读阴影,只读一次纹理,所以适合手机。`u_baseBlend` 把底色乘进去。 |-| **Terrain** | `terrain` | 四个纹理图层(草、泥土、雪、岩石),由 [Terrain](/docs/zh-cn/graphics/terrain/) 组件加权并按世界位置平铺。 || **Foliage** | `foliage` | 在风里摆动的植物:按顶点颜色里画好的权重做顶点弯曲,双面、半透光,可选镂空纹理。见[植被](/docs/zh-cn/graphics/foliage/)。 || **Skin** | `skin` | 按颜色分开的柔和漫反射、偏暖的明暗交界、薄处透光、两层高光和一层绒毛光,不模糊画面。见[皮肤与头发](#皮肤与头发)。 || **Hair** | `hair` | 发丝光照:Kajiya-Kay 漫反射、沿流向图错开的两条高光,以及透过发丝的光。见[皮肤与头发](#皮肤与头发)。 |+| **Eye** | `eye` | 用深度图和虹膜法线图做出的眼睛:角膜折射、带纤维/角膜缘环/瞳孔的虹膜、有包裹光的巩膜与眼睑阴影。见[皮肤与头发](#皮肤与头发)。 || **Water** | `water` | 水平的水体:传播的波浪和涟漪、被折射并按水深染色的背后场景、反射与泡沫。见[水](#水)。 |+Terrain、Foliage、Water、Hair、Skin、Eye 这几个模板属于各自的模块(`esengine/terrain`、`esengine/foliage`、`esengine/water`、`esengine/character-shaders`),项目装了对应模块才会出现在列表里。+新建材质是**按 id 引用**其模板的——它存的是 `shader: "builtin:sprite-unlit"`,并**不会**在磁盘上写出 shader 文件。引擎从内置源码编译该模板(运行时加载器、cook 步骤、编辑器三处以同样方式解析`builtin:<id>`),所以新材质立即就能绘制,无需额外管理。只有当你把材质**转为独立着色器**(见下文)@@ -85,7 +87,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一- **半透是着色项,不是模糊。** 它让光越过明暗交界线向背光侧延伸,并让背后的灯透出来,但从某一点进入的光仍在这一点出去。真正的扩散是次表面散射效果的事,它会模糊被标记表面的整个受光颜色,所以表面上锐利的高光也会被一并变软。- **不读取层的贴图。** 每一层对整个材质是一个常量(Model shader 已经没有多余的纹理单元);glTF 扩展的贴图在导入时会报告,其系数会保留。- **绒面和薄膜是拟合。** 绒面的能量损失和薄膜的干涉是解析近似,代替了生产级渲染器烘焙的查找表。-- **不提供:** 头发(Marschner 式的发丝模型)、眼睛、清漆单独的法线贴图、超过一层清漆的分层材质。+- **不提供:** Marschner 式的发丝模型、清漆单独的法线贴图、超过一层清漆的分层材质。### 在你自己的 shader 里@@ -253,10 +255,11 @@ const v = Material.getUniform(tintMat, 'u_intensity');| `depthTest` | `false` | 对深度缓冲做测试。 || `depthWrite` | `true` | 写入深度缓冲。 || `cull` | `CullMode.None` | 三角形剔除模式。 |+| `depthBias` | `0` | 朝眼睛方向的深度缓冲单位——决定两个共面表面谁胜出(墙上的贴花)。 || `switches` | `{}` | 启用的 `#pragma switch` 名——该材质编译时选定的静态排列。 |每个状态字段都有运行时 setter——`setBlendMode`、`setDepthTest`、`setDepthWrite`、-`setCull`——而 `Material.createInstance(source)` 构建一个廉价变体:从父材质继承+`setDepthBias`、`setCull`——而 `Material.createInstance(source)` 构建一个廉价变体:从父材质继承一切,只存储你之后在它上面设置的差异。### `CullMode`diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxindex 52f60920b..ea4402a11 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx@@ -53,6 +53,10 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess| `edgeOutline` | 轮廓**和**折痕处画一条有颜色的线:相机距离跳变处,以及表面法线转折处(需要写法线的表面:受光网格、Model、Toon) | `intensity`、`depthThreshold`、`normalThreshold`、`thickness`、颜色 `lineColor` || `grayscale` | 去色 | `intensity` |+++*后处理示例:**Bloom** 让明亮的像素溢出柔和的光晕。*+### 链路之前的抗锯齿几何边缘由**场景本身的 MSAA** 抹平,不是某个效果做的:默认 4×,WebGL2 与 WebGPU 都有——@@ -140,7 +144,7 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess每个像素在自己的圆里收集邻居,只在邻居自己的模糊够得着这里时才计入:清晰的前景物体不会渗进模糊的背景,而模糊的前景会铺到它后面的东西上。六十四个采样沿螺旋按像素不同的小数偏移,留下一层细颗粒,由 `taa` 平均掉。-**散景**就是镜头的形状:`blades` 为 3 或更大时光圈是那么多边的多边形(0 为圆形),按 `bladeRotation` 转动,失焦的亮点就成了那个形状。+**散景**就是镜头的形状:`blades` 为 3 或更大时光圈是那么多边的多边形(0 为圆形),按 `bokehRotation` 转动,失焦的亮点就成了那个形状。`highlight` 让亮的采样权重更大,所以失焦的灯是一个明亮的形状而不是暗淡的一团。### G-buffer@@ -190,10 +194,10 @@ import { registerEffect } from 'esengine';registerEffect({type: 'myInvert',- label: '反相',+ label: 'Invert',compute: { source: INVERT_WGSL, workgroupSize: [8, 8] },// 参数块:这些,按这个顺序,作为 f32。- uniforms: [{ name: 'u_amount', label: '强度', min: 0, max: 1, step: 0.01, defaultValue: 1 }],+ uniforms: [{ name: 'u_amount', label: 'Amount', min: 0, max: 1, step: 0.01, defaultValue: 1 }],});```@@ -271,10 +275,10 @@ registerEffect({骨骼上一次画时的姿态。不跟随的有混合表面,以及材质顶点钩子加上的运动——它们退回相机的答案,并被夹进像素周围的颜色里。TAA 和 SSAO 一样要读场景深度,因此在 WebGPU 上,没有深度解析的多重采样场景里无法运行。-上面是友好标签;**在代码里它们带 `u_` 前缀**(`u_intensity`、`u_exposure`……)。多数效果-在默认值下是恒等(`colorGrade`、`blur`、`chromaticAberration`、`fxaa`、`lensDistortion`、-`lutGrade`),加进去不调参不改画面。少数一加就可见——`grayscale`(完全去色)、`vignette`、-`bloom`、`outline`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。+上面是友好标签;**在代码里它们带 `u_` 前缀**(`u_intensity`、`u_exposure`……)。少数效果+在默认值下是恒等(`colorGrade`、`lensDistortion`、没绑定查找表的 `lutGrade`),加进去不调参不改画面。+多数一加就可见——`grayscale`(完全去色)、`vignette`、`bloom`、`blur`(强度 2)、+`chromaticAberration`(3)、`pixelate`(4)、`outline`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。## HDR(线性色彩空间)@@ -323,10 +327,10 @@ registerEffect({| 属性 | 类型 | 默认 | 说明 ||---|---|---|---|-| `effects` | list | `[]` | 每个效果的 `{ type, enabled, uniforms }`。 |+| `effects` | list | `[]` | 每个效果的 `{ type, enabled, uniforms, textures?, colors? }`——`textures` 放纹理引用(查找表、遮罩),`colors` 放颜色参数。 || `isGlobal` | boolean | `true` | 全局应用 vs 仅在体积形状内。 || `shape` | `'box' \| 'sphere'` | `'box'` | 局部体积的边界形状。 |-| `size` | Vec2 | `{5, 5}` | 体积范围(局部体积)。 |+| `size` | Vec2 | `{5, 5}` | 局部体积的半尺寸(球体用 `x` 当半径)。可选的 `z` 是盒体的半深度;`0` 或省略表示深度上不设限。 || `priority` | number | `0` | 重叠处优先级高者胜。 || `weight` | number | `1` | 混合权重,0..1(淡化整个体积)。 || `blendDistance` | number | `0` | 体积边缘的衰减距离。 |@@ -385,12 +389,12 @@ stack.addPass('lutGrade', getEffectDef('lutGrade')!.factory())| 组 | 子路径 | 效果 ||---|---|---|-| 基础 | `esengine/fx-basic` | blur、bloom、vignette、grayscale、colorGrade、lutGrade、chromaticAberration、tonemap、fxaa、sharpen、lensDistortion、pixelate、outline、depthOutline、edgeOutline、filmGrain、motionBlur、lensFlare |-| 大气 | `esengine/fx-atmosphere` | mist2d、rain2d、skyAtmosphere、heightFog、distanceFog、rain |+| 基础 | `esengine/fx-basic` | blur、bloom、vignette、grayscale、colorGrade、lutGrade、agx、chromaticAberration、tonemap、fxaa、sharpen、lensDistortion、pixelate、palette、outline、depthOutline、edgeOutline、filmGrain、motionBlur、lensFlare |+| 大气 | `esengine/fx-atmosphere` | mist2d、rain2d、fog2d、skyAtmosphere、heightFog、distanceFog、rain || 光照 | `esengine/fx-lighting` | ssao、gtao、ssr、ssgi、voxelGI、contactShadows、lightShafts、autoExposure、depthOfField、subsurface、taa |导出会读 `PostProcessVolume` 里写了哪些效果(以及驱动大气组的 `Weather`、`TimeOfDay` 组件),并导入它们需要的组。**从脚本里**加的效果——-`PostProcess.add('bloom')`——在内容里没有痕迹,所以要自己导入对应的组(`import 'esengine/fx-basic'`),或在项目设置里把该模块设为**包含**;否则这个效果第一次+`getEffectDef('bloom')!.factory()`——在内容里没有痕迹,所以要自己导入对应的组(`import 'esengine/fx-basic'`),或在项目设置里把该模块设为**包含**;否则这个效果第一次被用到时会告诉你它需要哪一组。编辑器和任何非精简入口三组都带。## 最佳实践diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxindex a21e62116..acd52bcdd 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx@@ -1,6 +1,6 @@---title: 精灵与渲染-description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、尺寸与轴心、翻转、排序层与绘制顺序、Y 排序与深度层(2.5D)、视差——外加纹理过滤、点击检测、位图缓存、ShapeRenderer 图元、精灵滤镜、拖尾与世界空间位图文字。+description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、尺寸与轴心、翻转、排序层与绘制顺序、Y 排序与深度层(2.5D)、视差——外加纹理过滤、点击检测、ShapeRenderer 图元、精灵滤镜、拖尾与世界空间位图文字。---import { Aside } from '@astrojs/starlight/components';@@ -28,6 +28,10 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)`sprite.texture` 是一个纹理**句柄**,而不是路径——你从加载器(`assets.loadTexture(ref)`)拿到它。在编辑器里你不用写这个:从内容浏览器把一张图拖到实体上,或在 Details 里设精灵的 texture 字段。+++*Sprite Lab 示例:同一张纹理、八种着色、翻转和一个排序组。*+## Sprite 字段| 字段 | 默认 | 说明 |@@ -37,6 +41,9 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)| `size` | `{100,100}` | 渲染尺寸,世界单位。 || `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点,取值是相对 `size` 的比例。超出 0–1 就落在精灵外面。 || `layer` | `0` | 排序层——控制绘制顺序(见下)。 |+| `order` | `0` | 排序层内的顺序,−128…127——越大越靠上(见下)。 |+| `maskInteraction` | `None` | [`SpriteMask`](#精灵遮罩) 是否裁切这个精灵:`None` / `VisibleInside` / `VisibleOutside`。 |+| `drawMode` | `Auto` | `Auto` 按 `tileSize` 与纹理的九宫格边界自动推断;`Simple`、`Tiled`、`NineSlice` 强制指定。 || `flipX` / `flipY` | `false` | 水平 / 垂直镜像。 || `material` | `0` | 自定义[材质](/docs/zh-cn/graphics/materials/)句柄(`0` = 默认精灵着色器)。 || `lit` | `false` | 用平面法线接收 2D 光照——让精灵变"受光"的一键路径(自定义 `material` 会覆盖它)。 |@@ -184,7 +191,7 @@ world.update(fog, Sprite, (s) => {遮罩**向前生效** —— 它裁切在它之后绘制的东西,也就是你已经用层和层内次序安排好的那个顺序。那正是它的模板被写入的时刻,所以与遮罩处在**同层同次序**的精灵完全不会被裁。打开 `limitRange`-可以让它的作用范围停在指定的层与次序上。+可以让它的作用范围停在 `rangeEndLayer` 层、`rangeEndOrder` 次序(含)上。<Aside type="caution">两个遮罩重叠的地方,由**更近的那个**说了算 —— 它写在后面,模板里留下的是它。被更远那个遮罩裁切的@@ -378,6 +385,10 @@ setTextureParams(tex.handle, TextureFilter.Nearest, TextureFilter.Nearest,(用平面法线受光)。需要法线贴图或完全自定义的观感时,改用 **Lit-2D 材质**。两种方式都见[2D 光照与阴影](/docs/zh-cn/graphics/lighting/)。+++*效果画廊示例:同一个精灵套上不同的 **SpriteFilter** 效果。*+### 精灵滤镜(描边、发光、投影)最常见的逐精灵效果不用写着色器——`SpriteFilter` 直接构建一个现成材质,赋给@@ -416,6 +427,10 @@ cmds.spawn()`ShapeRenderer` 与 `Sprite` 共享排序 `layer` 和 `color` 约定。+++*拖尾示例:彗星的长叠加拖尾跟随它的轨迹。*+## 拖尾**`TrailRenderer`** 沿实体最近的路径画一条世界空间条带——刀光、冲刺、弹道diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex a40d3c7ff..aaf978225 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx@@ -44,6 +44,10 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是无限地面没有让雨水流走的边缘,所以它的侵蚀是噪声自己的:噪声的每个八度在它下面的八度已经很陡的地方被压低。这样会在尖锐的山脊之间留下平缓的山谷,和雨水的效果很像,除了噪声本身之外不花额外代价。它不画泥土水道。+++*地形与水面示例:分层的地面、河流和海面,全部来自 Terrain 和 Water 组件。*+## 地形层地形层(`.esterrainlayer` 文件;编辑器里 **新建 → 新建地形层**)是一种地面——草、土路、沙、岩石——由美术为它制作的贴图组成。Terrain 列出它所用的地形层(`layers`,最多八个),地表图给出权重:第一张的红、绿、蓝、透明通道是第 1 到 4 层,第二张是第 5 到 8 层。没有地表图时,前四层按高度和坡度作为草、土、雪、岩上色;[生成世界](/docs/zh-cn/world/generation/)的群落可以为全部八层上色。@@ -63,6 +67,10 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是美术每层交付:三张贴图,正方形,边长为 2 的幂(1024 足够;打包时取最大一层的尺寸,最大 1024,小游戏上 512),四方连续,法线和遮罩按数据保存(不做色彩管理)。地形构建时各层贴图会打包成纹理数组,地形层文件或其贴图保存后会重新打包。+++***Terrain** 组件:先是图层,然后是地面的形状和高度的来源。*+## 图层与 Terrain 材质四个图层是草、泥土、雪和岩石。地面每一点在每个图层上都有一个权重,来自 splatmap 或来自那里有多高多陡,**Terrain** 着色器(`builtin:terrain`)把它们画出来。纹理按*世界位置*平铺,所以不管地面怎么切分,图层都连续不断;岩石从三个方向投影,所以悬崖不会被拉成一团。@@ -189,10 +197,27 @@ registerTerrainProvider(planet);| `radius` | 星球半径,单位米。星球立在它的实体处,不旋转、不缩放。 || `provider`、`world`、`generatorVersion`、`seed` | 生成地面的生成器(`registerPlanetProvider`)、游戏给它起的世界名、版本和种子。这四个相同,各处的地面就相同。 || `cellSize`、`detail` | 地面网格最细的格子,单位米;以及最细的格子往外延伸多远(大于 1 更远)。 |-| `layerColor0`–`3`、`macroScale`、`macroVariation` | 四个图层的颜色(草、土、雪、岩),以及盖在上面的亮度起伏。 |+| `layerColor0`–`3`、`macroScale`、`macroVariation` | 四个图层的颜色(草、土、雪、岩),以及盖在上面的亮度起伏:`macroScale` 是它的尺寸(米),`macroVariation` 是它的强度(0 到 1)。 |+| `layers` | 最多四个用来绘制地面的 `.esterrainlayer` 文件;为空则画四种颜色。 |+| `collision`、`collisionDistance`、`collisionLayer`、`friction` | 与平面地形相同:物体是否与地面碰撞、围绕每个运动物体构建地面的范围、地面的层与摩擦。 |+| `gravity` | 星球对其上物体的吸引力,单位米每二次方秒(表面处);`0`(默认)表示不吸引。 |+| `sea`、`seaLevel`、`seaColor`、`seaOpacity` | 星球是否有海、海面高出半径的高度、海的颜色,以及它盖住下方景物的程度(0 到 1)。 |星球的提供器回答的是**方向**,不是位置:它拿到从星球中心出发的单位方向和它们所在的半径,给出每个方向上高出半径的高度,如果上色,再给出四个图层权重。球面没有 x 和 z,所以生成器读三维噪声,没有接缝也没有极点。+```typescript+registerPlanetProvider({+ id: 'my-game:planet',+ versions: [1],+ range: () => [-40, 200],+ sample({ seed, radius, directions, count }) {+ const heights = new Float32Array(count);+ for (let i = 0; i < count; i++) heights[i] = myHeight(seed, radius, directions[i * 3]!, directions[i * 3 + 1]!, directions[i * 3 + 2]!);+ return { heights };+ },+});+```+星球回答圆形世界向站在上面的一切提出的问题,通过 `PlanetRegistryRes` 资源:`up(planet, x, y, z)` 是背离球心的单位方向,`altitude` 是高出半径的高度,`groundHeight` 是生成器自己在某位置下的地面高度(提供器稍后才回答时为 null),`groundPoint` 是它下面地面上的那个点。`nearest(x, y, z)` 给出表面最近的星球。设置 `gravity`(表面处的米每二次方秒),3D 物理就把每个动态刚体拉向最近的、有引力的星球中心:世界唯一的重力从刚体上拿掉,换上星球的,每个固定步长作为一个力施加;世界重力设为 0 时,刚体就是朝星球落下。生成的世界可以铺在星球上:在 `Planet` 所在的实体上放一个 `surface` 设为 Planet 的 `WorldGen`。立方体的六个面各按米制平面,用和平面世界一样的规则(字段之上的群落、配方、图层)铺设;一个方向由它落在的那个面来规划,放出来的东西被带到星球上,沿着当地的"上"站立。字段是星球自己的:地面高度、坡度、在三维里读的噪声(所以字段越过两个面之间的边没有接缝)、星球每个图层的 `paint.<层名>`,以及提供器用 `fields` 命名的字段(比如生态)。群落同时给地面上色(`paintGround`),画出来的和长出来的是同一张图。`seaLevel` 是海平面高度,比它低的地面在水下。区域(`WorldZone`)站在世界里的一个位置上,归它落在的那个面。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/time-of-day.mdx b/docs/astro/src/content/docs/zh-cn/graphics/time-of-day.mdxindex a873516be..44e16842e 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/time-of-day.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/time-of-day.mdx@@ -13,12 +13,16 @@ description: 一个 TimeOfDay 组件,让太阳和月亮在天空中运行,调暗| 字段 | 作用 ||---|---|-| `hour` | 钟点,0–24(12 是正午)。游戏运行时自行推进;在编辑器里设置它可以预览某个钟点。 |-| `daySeconds` | 游戏运行时一整天持续多少秒。0 表示钟点停住。 |-| `latitude` | 在星球上的位置,单位度(正为北):正午的太阳升多高。 |-| `declination` | 季节,−23.5 到 23.5:正值是北半球的夏天。 |-| `north` | 世界相对罗盘正北(+Z)朝 +X 转了多少度——太阳从哪边升起。 |-| `drive` | 时间驱动什么:灯光、天空、雾、曝光、反射。 |+| `hour` | 钟点,0–24(12 是正午,默认 12)。游戏运行时自行推进;在编辑器里设置它可以预览某个钟点。 |+| `daySeconds` | 游戏运行时一整天持续多少秒。0(默认)表示钟点停住。 |+| `latitude` | 在星球上的位置,单位度(正为北):正午的太阳升多高(默认 40)。 |+| `declination` | 季节,−23.5 到 23.5:正值是北半球的夏天(默认 15)。 |+| `north` | 世界相对罗盘正北(+Z)朝 +X 转了多少度——太阳从哪边升起(默认 0)。 |+| `drive` | 时间驱动什么:灯光、天空、雾、曝光、反射。默认全部五项。 |++++***Time Of Day** 组件:标出当前时刻的日照曲线、太阳的实时读数,以及它所驱动的各项。*## 在编辑器里@@ -62,4 +66,4 @@ world.insert(clockEntity, TimeOfDay, { hour: 6, daySeconds: 600 });烘焙光照和烘焙反射探针只对应某一个时刻:烘焙的是白天的天空,所以**不来自灯**的那部分光照(光照贴图、探针体)不会随太阳移动。要走完一整天的场景,应让太阳和天空是实时的——由灯光照亮的场景,或者烘焙内容主要是天空柔光的场景——上面的调暗与染色会做其余的事。-窗户和路灯不会在夜里自己亮起来:给它们自发光材质,或一盏用 `currentTimeOfDay().daylight` 来开关的灯。+窗户和路灯不会在夜里自己亮起来:给它们自发光材质,或一盏用 `currentTimeOfDay()?.daylight` 来开关的灯。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx b/docs/astro/src/content/docs/zh-cn/graphics/video.mdxindex 78bfc5f5f..a0a5d8da6 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/video.mdx@@ -107,7 +107,8 @@ const playIntro = defineSystem([Res(VideoPlayer)], (video) => {| `onReady` / `onEnded` / `onError` | 回调 | 生命周期钩子。 |`video.play(source, options)` 接受与组件相同的选项(`autoplay`、`loop`、`muted`、-`volume`、`playbackRate`);`video.stop(handle)` 结束一条流,`video.stopAll()` 结束所有流。+`volume`、`playbackRate`),但默认值不同:+`autoplay: true`、`loop: false`、`muted: false`、`volume: 1`、`playbackRate: 1`;`video.stop(handle)` 结束一条流,`video.stopAll()` 结束所有流。## 导入设置与烹饪后的视频diff --git a/docs/astro/src/content/docs/zh-cn/graphics/weather.mdx b/docs/astro/src/content/docs/zh-cn/graphics/weather.mdxindex 8adfd4e35..2dbbf990e 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/weather.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/weather.mdx@@ -18,17 +18,21 @@ description: 一个 Weather 组件,让场景处于晴、薄雾、阴天、雨或| 字段 | 作用 ||---|---|-| `preset` | 场景所处的天气:晴、薄雾、阴天、雨、暴风雨。 |-| `target` | 正在转向的天气;无则为 None。 |-| `progress` | 这次转变走了多远(0–1)。游戏会推进它;在编辑器里设置它可以预览转到一半。 |-| `duration` | 一次转变用多少秒。 |-| `sequence` | 自己循环经过的预设,逗号分隔——`clear,mist,rain,clear`。为空则不动。 |-| `hold` | 序列里每种天气停留多少秒再开始下一次转变。 |-| `drive` | 天气驱动什么:灯光、雾、雨、调色、曝光、反射、声音。 |+| `preset` | 场景所处的天气:晴、薄雾、阴天、雨、暴风雨。默认晴。 |+| `target` | 正在转向的天气;无则为 None(默认)。 |+| `progress` | 这次转变走了多远(0–1,默认 0)。游戏会推进它;在编辑器里设置它可以预览转到一半。 |+| `duration` | 一次转变用多少秒(默认 6)。 |+| `sequence` | 自己循环经过的预设,逗号分隔——`clear,mist,rain,clear`。为空(默认)则不动。 |+| `hold` | 序列里每种天气停留多少秒再开始下一次转变(默认 20)。 |+| `drive` | 天气驱动什么:灯光、雾、雨、调色、曝光、反射、声音、风。默认全部。 || `soundSource` | 一个带循环 `AudioSource` 的实体——雨声。下雨时天气会抬起它的 `playing`,并把音量设为创作时的音量乘以雨的大小。 |转变带缓动,开始和结束都平缓,完成的转变落在目标上并清空自己。+++***Weather** 组件:可切换的五种天气,以及下面的过渡。*+## 在编辑器里Details 面板把五种内建天气显示为按钮(项目自己的预设 id 仍然有效,显示为自定义),把向下一种天气的过渡显示为可拖动的进度,还有循环、它驱动的内容,以及它此刻对画面做了什么的读数——主光的缩放、雾的缩放、潮湿和降雨。雨和雾通过 Post Process Volume 进入画面,面板里会这样说明。@@ -45,6 +49,7 @@ Details 面板把五种内建天气显示为按钮(项目自己的预设 id 仍- **反射。** 烘焙的反射探针显示的是它烘焙时的天空,所以下雨的街道会映出晴天的街道。环境光带有 `reflectionScale` 和`reflectionSaturation` 就是为此:探针显示的内容乘以前者、按后者褪色,天气会把两者调低。- **天空。** Sky Atmosphere 特效把预设的 `overcast` 当作云量和雾霾:云变厚并连成一片,后面的太阳、月亮和星星被同一份透射率遮住。+- **风。** 预设的 `wind` 缩放植物摇摆的幅度(Foliage 材质的 `u_windStrength`、Sway 精灵的 `u_swayWind`),`waves` 缩放每片水体的浪高——画出来的和水面查询回答的都一起变。- **调色与曝光。** Colour Grade 的饱和度和对比度被缩放,Auto Exposure 的补偿被提高。这些效果在场景的体积混合之后才施加,所以在同一场雨里,雾设得薄的场景仍然比雾设得厚的场景薄。diff --git a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdxindex ff2b0ba6a..efb1dca9e 100644--- a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx@@ -31,6 +31,10 @@ world.insert(rock, LODGroup, {把这个组件去掉,最精细的网格就回来了 —— 渲染器的其他部分一点没变。+++*编辑器里的 **LOD Group**:正在使用的级别、实体的屏幕占比和各级阈值表。*+## 这些尺寸是屏幕占比,不是距离`lod1Size` 和它的兄弟们,是物体包围体覆盖**视口高度**的比例。`1.0` 表示物体正好一屏高,@@ -81,6 +85,7 @@ world.insert(rock, LODGroup, {- **槽位按顺序填** —— 先 `lod1`,再 `lod2`,再 `lod3`。留空的槽位就是梯子的终点,它后面的一律到不了(引擎会告警)。- **尺寸必须递减。** `lod2Size` 小于 `lod1Size`,依此类推。+- **默认值。** `lod1Size` 0.5、`lod2Size` 0.25、`lod3Size` 0.1、`cullSize` 0.02、`hysteresis` 0.1(取值 0 到 1);组件的 `enabled` 关闭时始终画渲染器自己的网格。- **`cullSize: 0`** 完全关掉剔除,于是这一组永远不会消失。- **各级可以在导入时生成。** 在模型的导入设置里把 **Generate LODs** 设为 1–3 级(或给 `import-model` 传 `--lods <n>`):每个网格会被塌缩成约 50%、20%、7% 三角形的副本,写成 `<mesh>_lod<n>.esmesh`,并在实体上加一个 `LODGroup`。蒙皮和变形网格,以及三角形少于 **LOD Minimum Triangles**(256)的网格,只保留一级。- **蒙皮的一组必须共用一副骨架。** 蒙皮网格的每一级都要有相同的关节数;对不上的那一级会diff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdxindex 1ccd73d94..116eb32c6 100644--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx@@ -66,7 +66,7 @@ addSystem(watchPerf);| `triangles` | number | 本帧提交的三角形数。 || `sprites` | number | 本帧渲染的精灵数。 || `text` | number | 本帧渲染的文本实体数。 |-| `spine` | number | 本帧渲染的 Spine 骨骼数。 |+| `skeletal` | number | 本帧由骨骼运行时摆好姿态的三角形数(Spine 和 DragonBones 都计在这里)。 || `meshes` | number | 本帧渲染的网格数。 || `culled` | number | 本帧被剔除(未提交)的实体数。 |@@ -101,7 +101,7 @@ addSystem(feedOverlay);`FrameStats` 里的渲染计数来自 `Renderer.getStats()`,也可以直接调用(不需要stats 插件)——它返回一个 `RenderStats`,同样是那七个字段:`drawCalls`、-`triangles`、`sprites`、`text`、`spine`、`meshes`、`culled`。+`triangles`、`sprites`、`text`、`skeletal`、`meshes`、`culled`。```typescriptimport { Renderer } from 'esengine';@@ -368,32 +368,34 @@ if (Renderer.hasCapturedData()) {for (const dc of capture!.drawCalls) {console.log(`#${dc.index} ${RenderType[dc.type]} tex=${dc.textureId} ` +- `tris=${dc.triangleCount} entities=${dc.entityCount} ` ++ `tris=${dc.triangleCount} entities=${dc.entities.length} ` +`break=${BatchBreak[dc.breakReason]}`);}- console.log(`${capture!.cameraCount} camera pass(es)`);+ console.log(`${capture!.passCount} pass(es)`);}```-`FrameCaptureData` 是 `{ drawCalls: DrawCallInfo[], cameraCount }`。每个+`FrameCaptureData` 是 `{ drawCalls: DrawCallInfo[], passCount }`。每个`DrawCallInfo`:| `DrawCallInfo` 字段 | 说明 ||---|---|| `index` | 该 draw call 在帧内的序号(提交顺序)。 |-| `cameraIndex` | 由哪个相机 pass 发出。 |+| `pass` / `passKind` | 由帧内第几个 pass 画出(按 pass 运行顺序),以及它是相机的场景 pass(`CapturePass.Scene`)还是屏幕叠加 pass(`CapturePass.Overlay`)。 || `stage` | 渲染阶段(`RenderStage`:Background / Opaque / Transparent / Overlay)。 || `type` | 绘制的内容类型(`RenderType`,见下)。 || `blendMode` | 生效的混合模式 id。 || `textureId` / `materialId` / `shaderId` | 该调用绑定的 GPU 资源。 |-| `vertexCount` / `triangleCount` | 提交的几何量。 |-| `entityCount` / `entityOffset` / `entities` | 被批进该调用的实体 id。 |+| `indexCount` / `triangleCount` | 提交的几何量。 |+| `instanceCount` | 该调用的实例数;非实例化绘制为 0。 |+| `entities` | 该绘制所来自的实体 id,按绘制顺序;没有实体的项(文字、辅助图形)不列出。 || `layer` | 批次的渲染层。 || `breakReason` | 该调用为何没有并入前一个(`BatchBreak`,见下)。 || `scissorX/Y/W/H`、`scissorEnabled` | 裁剪矩形状态(UI 遮罩)。 || `stencilWrite` / `stencilTest` / `stencilRef` | 模板状态(遮罩写入/读取方)。 || `textureSlotUsage` | 批次占用的纹理槽数。 |+| `textures` | 该绘制绑定的所有纹理,0 号槽在前;`textureId` 即第一个。 |`RenderType` 说明一个调用画了什么:`Sprite`、`Spine`、`Mesh`、`ExternalMesh`、`Text`、`Particle`、`Shape`、`UIElement`。diff --git a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdxindex b55ae3dc3..faf3a61df 100644--- a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx@@ -27,15 +27,16 @@ import { Aside } from '@astrojs/starlight/components';| 分组 | 设置 ||---|---|-| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离 |-| 阴影 | 图集尺寸、单元尺寸、级联数、距离 |+| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、2D 雨遮罩尺寸 |+| 阴影 | 图集尺寸、单元尺寸、级联数、距离、2D 软阴影采样数 || 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 |+| 水体 | 水体波数(1 到 4)、水体涟漪格数,以及位移、镜面、焦散三个开关。档位不是关闭、且构建里带水体模块时才显示 || 后处理 | 总开关,以及在这个档位运行的每个效果的勾选框 |每个档位从引擎自己的值起步,**只有你改过的才会保存**到 `project.esproject` 的`features.rendering.quality.profiles.<档位>` 下。引擎以后改进的默认值会传给从没碰过它的项目;改回该档位默认值的行也不再算差异。-**抗锯齿方式**可选 MSAA 或时间性(TAA)。时间性按 1 个采样绘制,由 TAA 通道用之前的帧来平滑:1080p 下便宜得多,画面略软,需要相机上有后处理体积;选它时 MSAA 一行会隐藏。**深度预通道**把不透明场景画两遍,先只画深度,让每个像素只为最前面的表面着色一次。表面大量重叠(树林、成片植被)且 GPU 对光栅化出的像素立即着色时划算;对把着色推迟到分块末尾的 GPU,等于几何多付一遍。低档默认关,中、高档默认开。预通道和颜色通道在 WebGL2 与 WebGPU 上都把顶点位置声明为 invariant,所以表面的颜色总能通过与自己深度的等深测试,Metal 上也一样;Mac 上开着预通道时地形出现暗色三角形,只需更新到新的构建。+**抗锯齿方式**可选 MSAA 或时间性(TAA)。时间性按 1 个采样绘制,由 TAA 通道用之前的帧来平滑:1080p 下便宜得多,画面略软,需要相机上有后处理体积;选它时 MSAA 一行会隐藏。**深度预通道**把不透明场景画两遍,先只画深度,让每个像素只为最前面的表面着色一次。表面大量重叠(树林、成片植被)且 GPU 对光栅化出的像素立即着色时划算;对把着色推迟到分块末尾的 GPU,等于几何多付一遍。低档默认关,中、高档默认开。默认抗锯齿方式:低档 MSAA(1 个采样)、高档 MSAA(4 个采样)、中档时间性。预通道和颜色通道在 WebGL2 与 WebGPU 上都把顶点位置声明为 invariant,所以表面的颜色总能通过与自己深度的等深测试,Metal 上也一样;Mac 上开着预通道时地形出现暗色三角形,只需更新到新的构建。<Aside type="note">一行的"默认值"是它正显示的那个档位的默认值,所以同一个数字在低档可能是改动,在中档却是默认。@@ -52,7 +53,7 @@ import { Aside } from '@astrojs/starlight/components';"quality": { "mode": "auto", "profiles": { "low": { "skipEffects": ["ssr", "taa", "depthOfField"] } } }```-默认情况下,低档去掉反射、时间性抗锯齿、景深和光束;中档去掉反射和景深;高档什么都不去掉。这些默认值依据每个效果每像素的工作量,+默认情况下,低档去掉反射、时间性抗锯齿、景深、光束、运动模糊、镜头光斑、GTAO、次表面散射和体素 GI;中档去掉反射和景深;高档什么都不去掉。这些默认值依据每个效果每像素的工作量,**不是**在弱设备上量出来的。编辑器的 `fx-cost` 检查能量出每个效果在当前机器上的开销,可以在决定某个档位跳过什么之前先看看你的机器上它们要多少。## 设备规则diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdxindex abf8c7a46..57c1a0377 100644--- a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx@@ -22,7 +22,7 @@ world.insert(wall, StaticBatch, {});- 网格按一次绘制拥有的全部状态分组 —— 材质、贴图、法线贴图、颜色、层、剔除与光照开关 ——还可以用组件上的**分组**把两个房间分开。- 每一组再按世界里的格子切开,所以一个批是一小片区域,剔除仍然有东西可剔。- 一个格子里的顶点不超过 262,144 个。+ 格子默认边长 1600 世界单位,一个格子里的顶点不超过 262,144 个。- 被标记的实体保持原样:脚本照样能找到,碰撞体照样碰撞,编辑器照样能选中。只是它们的绘制移到了合并后的网格上,那是另一个实体。- 被合并之后,标记的网格**不能再动**。销毁是支持的(这个批会去掉它重新合并);移动不支持,@@ -41,6 +41,9 @@ world.insert(wall, StaticBatch, {});| 半透明 | 结果取决于绘制顺序,而合并就是丢掉顺序。 || 会动 | 动态刚体或角色控制器:合并把网格站的位置烘进了顶点。 || 烘焙光照 | 场景有探针或烘焙,合并后的网格留不住每个部件各自的那一份。 |+| 还没有网格 | 句柄后面还没有几何(仍在加载,或网格失败),没有东西可复制。 |+| 已关闭 | 本来就不画,没有东西可合并。 |+| 顶点布局 | 位置或法线不是 32 位浮点,合并无法变换。 || 同组只有一个 | 只合并一个网格什么也省不了,还多占内存。 |## 它的代价diff --git a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdxindex 2cb8d2af5..374e2cc84 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx@@ -196,6 +196,7 @@ const unsub = assets.onInvalidate((event) => {| `checkForUpdate(options)` | `Promise<UpdatePlan>` | 拉取候选清单,与活动清单 diff,并暂存。不下载任何资产。 || `applyUpdate(onProgress?)` | `Promise<ApplyUpdateResult>` | **原子地**应用暂存的更新:下载并校验每个变更资产,然后切换清单、重绑运行中的句柄、持久化。`onProgress(loaded, total)` 回报下载进度。 || `restorePersistedUpdate(key)` | `boolean` | 在启动时,恢复上一次 `applyUpdate` 以 `key` 持久化的清单。设了 `persistUpdateKey` 时运行时会替你调用。 |+| `updateStatus()` | `UpdateStatus` | `{ revision, persistedRevision, staged, applying }`——供诊断界面使用。 || `setRemoteRoot(url?)` | `void` | 把远端组解析指向某个 CDN 根地址(`undefined` 清除 → 同源)。运行时会从构建的 `remoteRoot` 设置它。 || `remoteRoot` | `string \| undefined` | 当前 CDN 根地址(getter)。 || `onInvalidate(listener)` | `() => void` | 订阅失效事件。监听器收到 `{ ref, type, oldValue }`(用于自定义重绑);返回一个取消订阅的函数。 |@@ -227,6 +228,22 @@ const unsub = assets.onInvalidate((event) => {| `ok` | `boolean` | 仅当每个变更资产都下载 + 校验通过且清单已切换时为真。 || `updated` | `number` | 应用了多少个资产(失败时为 `0`)。 || `failed` | `AssetDownloadFailure[]` | 为何回滚——每项 `{ path, reason: 'fetch' \| 'integrity' }`。 |+| `stages` | `UpdateStages` | 走到了哪一步——见下。光看 `ok` 并不能说明下次启动是否保留这次更新。 |+| `revision` | `string \| null` | 这次会话之后运行所处的修订号。 |+| `uncached` | `string[]` | 落盘缓存拒收的变更资产(按 url)——下次启动会再次拉取的那些。 |+| `reason` | `'nothing-staged'`(可选) | 什么都没尝试:没有暂存的更新(没检查过,或已被另一次 `applyUpdate` 取走)。 |++**`UpdateStages`**——每一项都是独立的答案:++| 字段 | 类型 | 说明 |+| --- | --- | --- |+| `verified` | `boolean` | 每个变更资产都已下载,且与其内容哈希相符。 |+| `applied` | `boolean` | 这次会话运行在新清单上,其资产也已在它上面稳定下来。 |+| `persisted` | `boolean \| null` | 下次启动从它开始:已存下并读回。存储拒绝时(配额已满)为 `false`;没有持久化键时为 `null`。 |+| `cached` | `boolean \| null` | 每个变更的远端资产都在落盘缓存里,下次启动无需网络即可读取。平台不设缓存的地方(Web)为 `null`。 |++`updateStatus()` 随时回答同样的问题:当前运行的修订号、下次启动所起始的修订号、暂存了什么以及它会下载什么,+以及是否正在应用。## 按需组(DLC)@@ -262,15 +279,21 @@ assets.releaseGroup('world2');## 持久化与离线-当设了 `persistUpdateKey` 时(导出会自动设置),`applyUpdate` 会把已应用的清单存入平台存储。下次启动时运行时调用 `restorePersistedUpdate(key)`,玩家便**直接从已更新的内容开始——哪怕没有网络**。在原生与小游戏目标上,校验过的字节还会写入一个内容寻址的**落盘缓存**,于是已更新的资产离线加载而无需再次访问 CDN。+当设了 `persistUpdateKey` 时(导出会自动设置),`applyUpdate` 会把已应用的清单存入平台存储。下次启动时运行时调用 `restorePersistedUpdate(key)`,玩家便**直接从已更新的内容开始**。在有落盘缓存的目标上,校验过的字节也会写进去,+于是已更新的资产**无需网络**即可加载;`stages.cached` 说明它们是否全部写入。++已存下的更新属于打出它的那个包。玩家安装更新的构建时(新的 Web 部署、应用商店更新),存下的更新比随包发布的更旧,+所以会被丢弃,游戏从新包开始。++应用一次只跑一个。另一次下载进行中发现的更新仍保持暂存,应用它时只下载第一次没带来的部分。## 平台支持| 目标 | 清单 + diff | CDN 拉取 | 持久化 | 落盘缓存 || --- | --- | --- | --- | --- |-| **Web** | ✅ | ✅(受 CORS/CSP 约束) | `localStorage` | 浏览器 HTTP 缓存 |+| **Web** | ✅ | ✅(受 CORS/CSP 约束) | `localStorage` | —(下次启动重新从 CDN 拉取) || **桌面** | ✅ | ✅ | ✅ | ✅(内容寻址) |-| **微信小游戏** | ✅ | ✅ | ✅ | ✅ |+| **小游戏**(微信、抖音……) | ✅ | ✅ | ✅ | ✅(宿主的用户数据目录) || **原生(iOS / Android)** | ✅ | ✅ | ✅ | ✅ |清单 diff 是纯粹且平台无关的;只有拉取、存储与落盘缓存原语按平台不同,运行时会挑选正确的那一个。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex 2ea574e2f..2f95cc3bd 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -105,7 +105,7 @@ playableCta();| **Unity Ads** | 5MB | `mraid.open()` | 运行时自动等待 MRAID ready 和 viewable,隐藏时暂停游戏及音频,退出时释放宿主监听。 || **AppLovin** | 5MB | `mraid.open()` | 要求所有资源内嵌——单文件试玩本来就是。 || **Mintegral** | 5MB | `window.install()` | 导出资源内嵌的 `index.html` 和同名 `index.zip`。等待宿主开始,关闭时暂停游戏和音频。 |-| **TikTok / 海外 Pangle** | ZIP <5MB | `window.openAppStore()` | 根目录包含 `config.json`,方向字段按平台区分;游戏脚本前注入官方 SDK。仍需广告管理平台预览验收,国内穿山甲另行适配。 |+| **TikTok / 海外 Pangle** | ZIP <5MB | `window.openAppStore()` | 根目录包含 `config.json`,方向字段按平台区分;游戏脚本前注入官方 SDK。仍需广告管理平台预览验收。 |上限会变,所以每条警告都指名它用的是哪一家的上限、以及这个数字出自哪里,而不是丢一个让你盲信的数字。@@ -134,7 +134,7 @@ pnpm verify:playable output/playable/index.html --report output/playable.json --请按自己的场景调整点击计划。版本 1 声明 `viewports` 和 `steps`:`click` 的 `x`/`y` 是相对 canvas 的归一化坐标;`expect` 指定 `store-click`、`game-end` 或 `game-retry` 的准确 `count`,以及可选 `userActivation`。`host` 发送 `ready`、`show`、`hide`;`frozen` 在 `ms` 间隔比较画面;`wait`、`snapshot` 记录等待及截图。步骤或期望可用 `networks` 明确限定,每个视口独立启动。示例覆盖横竖屏、CTA、完成/重玩及支持的隐藏生命周期;Google/Meta 生命周期保持待验证。-命令仅使用无头 Chromium,静音且不启动编辑器。`runtime-check.json` 记录原 HTML/交付文件、导出报告、场景计划、检查器和 mock 哈希,浏览器版本、事件及截图哈希。非预期请求(含 CSP 阻止的尝试)、页面错误、事件数量/激活状态不符、隐藏动画或输入、日志丢失、静态/导出失败及输入变更都使检查失败。Windows/POSIX 旧归档路径均按相邻 ZIP 文件名定位。结论仅为 **local-mock**,覆盖明确请求的观察;宿主 SDK 被替换,浏览器激活状态观察不能证明原 SDK 的同步调用规则。原 SDK 行为、音频生命周期、质量复核、官方工具和真机验收仍待完成。+命令仅使用无头 Chromium,静音且不启动编辑器。`runtime-check.json` 记录原 HTML/交付文件、导出报告、场景计划、检查器和 mock 哈希,浏览器版本、事件及截图哈希。非预期请求(含 CSP 阻止的尝试)、页面错误、事件数量/激活状态不符、隐藏动画或输入、截断、静态/导出失败及输入变更都使检查失败。Windows/POSIX 归档路径均按相邻 ZIP 文件名解析。结论仅为 **local-mock**,覆盖明确请求的观察;宿主 SDK 被替换,浏览器激活状态观察不能证明原 SDK 的同步调用规则。原 SDK 行为、音频生命周期、质量复核、官方工具和真机验收仍待完成。必需宿主 SDK 检查会核对真实的 script 标签及其位置:Google Exit API 位于 head,TikTok/Pangle 位于 body 且在游戏脚本之前。缺少脚本、位置错误或 TikTok/Pangle SDK 延迟加载都会使静态检查失败。真实 SDK 是否可用及 CTA 行为仍需运行验证。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdxindex 5e8886149..01280784e 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx@@ -72,6 +72,16 @@ node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码暂存的自定义扩展名(`.skel`、`.atlas`、`.bin` 等)生成 `packOptions.include`规则,让开发者工具打包并读取它们。+## 引擎二进制++引擎的 `.wasm` 是小游戏里最大的单个文件。**打包项目**微信页上的两个选项可以让它不占 4 MB 主包:++- **压缩 wasm 二进制**把引擎和每个侧模块都以 `.wasm.br` 发布,大小约为三分之一;微信在加载时解压。+ 这需要**基础库 2.14.0** 或更高。包里只带压缩后的文件,运行时也不会检查版本,所以打开它时,+ 请在微信后台把小游戏的最低基础库设为 2.14.0。+- **引擎放入分包**把二进制挪进一个启动时加载的分包。它不再计入主包;启动会等这次下载完成,+ 加载条显示其进度。+## EmscriptenGLX微信的 EmscriptenGLX 让引擎的 GL 调用在 wasm 内执行、批量交给宿主,而不必每一次都跨到diff --git a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdxindex f618d1879..6fcb3f15c 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx@@ -61,7 +61,7 @@ world.insert(button, EventBinding, {| `params` | 该动作声明的参数,按名字给。 || `arg` | 同一份输入的规范字符串形式(`"tabs:settings"`)。两种写法都能跑。 || `guard` | 必须通过才执行该行的具名条件。 |-| `once` | 每次运行最多执行一次。 |+| `once` | 最多执行一次,此后保持失效,直到场景重新加载。 || `enabled` | `false` 让该行失效但不删除。 |连线只在运行态触发——编辑时编辑器绝不会执行你的动作。@@ -89,9 +89,12 @@ world.insert(button, EventBinding, {|---|---|| `ui.setPage` | 把 [UI 控制器](/docs/zh-cn/ui/controllers/)切到某一页。 || `ui.setVisible` | 显示/隐藏一棵 UI 子树(`UINode.display`)。 |-| `property.set` | 写任意组件字段,按 `Component.dot.path` 寻址。 |+| `property.set` | 写任意组件字段,按 `Component.dot.path` 寻址;可选的 `entity` 参数写别的实体。 || `fsm.fire` | 向目标的状态机发一个触发器。 |-| `blackboard.set` | 设置一个黑板变量。 |+| `blackboard.set` | 设置一个黑板变量(`key=value`;值能按 JSON 解析时按 JSON 读)。 |+| `scene.load` · `scene.reload` | 切换到指定场景,或重启当前场景,可选淡入淡出秒数。 |+| `audio.play` · `audio.stop` | 驱动目标上的 `AudioSource`;`audio.play` 可指定另一个音频剪辑。 |+| `soundEvent.trigger` · `soundEvent.stop` | 驱动目标上的声音事件源。 || `timeline.play` · `timeline.pause` | 驱动目标上的[时间轴](/docs/zh-cn/animation/timeline/)。 || `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | 驱动精灵序列帧。 |@@ -132,8 +135,8 @@ registerAction('game.award', {`pointer_move` · `press_cancel` · `shown` · `hidden`每个指针事件(`press`、`release`、`click`、`pointer_move`、`press_cancel`)都带一个 `UiPointerEventData`:-是哪个指针(`pointer`,鼠标是 -1)、它在世界里的位置(`worldX`、`worldY`)和在表面上的位置(`screenX`、-`screenY`,从左下角向上数)。被按下的那个实体,在指针按住期间无论移到哪里,都由它收到 `pointer_move`。+是哪个指针(`pointer`,鼠标是 -1)、它在世界里的位置(`worldX`、`worldY`)、在表面上的位置(`screenX`、+`screenY`,单位像素,从左下角向上数)和 UI 布局空间里的位置(`layoutX`、`layoutY`)。被按下的那个实体,在指针按住期间无论移到哪里,都由它收到 `pointer_move`。一次按住可以放弃:`UIControlPointers.cancelHold(pointer, to?)`,持有者收到 `press_cancel`,不会触发点击;给了 `to`,这次手势的其余部分就交给那个实体。只有 `ContentRect` 加 `Interactable` 的实体也可以被按下。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdxindex d8a9a7b58..441975143 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx@@ -110,8 +110,8 @@ if (Controls.pressed('Jump')) { /* 本帧边沿 */ }| `value(name)` | button `0..1` · axis `-1..1` · axis2d 的幅度 `0..1`。 || `axis2d(name)` | `{ x, y }` 方向(超过 1 时归一化)。 |-动作是 `Button(…)`、`Axis1D(…)` 或 `Axis2D(…)`;各接任意数量的绑定,多个绑定-求和(再钳制),键盘与手柄自然共存:+动作是 `Button(…)`、`Axis1D(…)` 或 `Axis2D(…)`;各接任意数量的绑定,键盘与手柄自然共存。`Button` 取最强的那个绑定+(钳制到 `0..1`);`Axis1D` 与 `Axis2D` 把各绑定求和再钳制(到 `-1..1`,或长度 1):| 绑定 | 供给 | 含义 ||---|---|---|@@ -173,15 +173,19 @@ Controls.load('controls'); // 重新应用已存的绑定(如有)`keyboard` 和 `gamepad` 默认**开**,`mouse` 默认**关**——这样按下"改键"按钮的那次点击不会被捕获成绑定。轴类输入永远不会被捕获;改键只面向离散输入。-`getBindings` / `setBindings` 以编程方式查看和编辑绑定;`cancelListen()` 中止-挂起的捕获(以 `null` 解析)。+`getBindings` / `setBindings` 以编程方式查看和编辑绑定;`actions()` 列出动作名,+`isListening()` 告诉你是否有捕获挂起;`cancelListen()` 中止挂起的捕获(以 `null` 解析)。### 数据驱动的映射(`.inputmap`)-整张映射也能序列化为资产:在编辑器内容浏览器里**新建 Input Map**,然后用-`loadInputMapAsset(json)` 代替 `defineInputMap` 构建。`toAsset()` 从代码产出+整张映射也能序列化为资产:在编辑器内容浏览器里**新建输入映射**,然后用+`loadInputMapAsset(asset)`(传入解析后的 `InputMapAsset`)代替 `defineInputMap` 构建。`toAsset()` 从代码产出同样的格式。+++*移动端控制示例:**VirtualJoystick** 和 **VirtualButton** 驱动与键盘相同的输入动作。*+## 触摸手势`GestureDetector` 把原始触摸变成点按 / 长按 / 滑动 / 捏合回调。基于 `Input`@@ -266,9 +270,9 @@ key-up 边沿,处理器看到的它仍是按住的,与 DOM `event.shiftKey` 的| 分组 | 方法 ||---|---|| 键盘 | `isKeyDown(code)`、`isKeyPressed(code)`、`isKeyReleased(code)`。 |-| 鼠标 | `isMouseButtonDown(b)`、`isMouseButtonPressed(b)`、`isMouseButtonReleased(b)`;`mouseX` / `mouseY`、`scrollDeltaY`。 |-| 触摸 | `isTouchActive(id)`、活动触点的 `touches` map。 |-| 手柄 | `isGamepadConnected(pad?)`、`isGamepadButtonDown(btn, pad?)`、`isGamepadButtonPressed`/`Released(btn, pad?)`、`getGamepadAxis(axis, pad?)`。 |+| 鼠标 | `isMouseButtonDown(b)`、`isMouseButtonPressed(b)`、`isMouseButtonReleased(b)`;`mouseX` / `mouseY`(或 `getMousePosition()`)、`scrollDeltaX` / `scrollDeltaY`(或 `getScrollDelta()`)。 |+| 触摸 | `isTouchActive(id)`、`getTouches()` / `getTouch(id)` / `getTouchCount()`、活动触点的 `touches` map,以及本帧边沿 `touchesStarted` / `touchesEnded`。 |+| 手柄 | `isGamepadConnected(pad?)`、`isGamepadButtonDown(btn, pad?)`、`isGamepadButtonPressed`/`Released(btn, pad?)`、`getGamepadButtonValue(btn, pad?)`(模拟值 `0..1`)、`getGamepadAxis(axis, pad?)`、`getGamepads()`。 || 指针 | `isPointerOverUI()` —— 光标在 UI 元素上方。 |`*Down` 读按住状态;`*Pressed` / `*Released` 是本帧边沿。@@ -293,6 +297,8 @@ key-up 边沿,处理器看到的它仍是按住的,与 DOM `event.shiftKey` 的判断。```ts+import { Device } from 'esengine';+const off = Device.motion.onChange(sample => {if (sample.gravity) console.log(sample.gravity);});diff --git a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdxindex 850e6da3b..785b43111 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx@@ -53,7 +53,8 @@ col.multiply(base, tint); // per-channel tint```- 构造:`create`、`rgb`、`from255`、`fromHex`(格式非法时抛错)、`clone`。-- 混合:`lerp`、`withAlpha`、`multiply`、`scaleRgb`;用 `toHex` 序列化。+- HSV:`fromHsv(h, s, v, a?)`(色相为角度,其余 `0..1`)与 `toHsv`。+- 混合:`lerp`、`withAlpha`、`multiply`、`scaleRgb`;用 `toHex(c, withAlpha = false)` 序列化;用 `equals` 比较。## 标量@@ -115,7 +116,7 @@ const delta = normalizeAngle(targetAngle - facing);| `quaternionToAngle2D(rz, rw)` | 由四元数的 `z`/`w` 求 Z 角度(弧度,`2 * atan2(z, w)`)。 || `normalizeAngle(a)` | 把任意角度归一到 `(-π, π]`,用于最短转向比较。 |-完整的 3D 旋转用 `q` 命名空间:`create`、`mul`、`axis(axis, rad)`、`normalize`、`conjugate`、`rotate(q, v)`、`fromEuler` / `toEuler`、`rotationTo(from, to)`、`setAngleZ` / `angleZ` 等。+完整的 3D 旋转用 `q` 命名空间:`create`、`mul`、`axis(axis, rad)`、`normalize`、`conjugate`、`rotate(q, v)`、`fromEuler` / `toEuler`(欧拉角单位是**度**)、`rotationTo(from, to)`、`setAngleZ(q, deg)`(度)/ `angleZ(q)`(弧度)等。如果需要的是方向*向量*而不是旋转,留在 `v2` 里就好:`fromAngle` / `angle` /`rotate`。完整的工作示例(炮塔朝向光标)见diff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdxindex d4e9ca9e7..af28a594f 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx@@ -36,6 +36,8 @@ socket.connect();| `readyState` | `'connecting' \| 'open' \| 'closing' \| 'closed'`。 || `on(event, fn)` | 订阅 `'open'` / `'message'` / `'close'` / `'error'`;返回退订函数。 |+`createSocket` 接受 `{ url, protocols? }`(`protocols` 是 WebSocket 子协议字符串或列表)。+## 类型化消息与 RPC —— `NetChannel``NetChannel` 用**按类型路由的类型化消息**与**请求/响应**包裹一个传输,于是你按消息 `type`@@ -62,7 +64,8 @@ const stats = await channel.request<{ hp: number }>('getStats', { id: 'p1' }, 50| `on(type, handler)` | 订阅一个消息类型;返回取消订阅函数。 || `send(type, payload)` | 发送一个类型化事件。 || `handle(type, handler)` | 注册一个 RPC 处理器;返回取消订阅函数。 |-| `request(type, payload, timeoutMs?)` | 发送一个 RPC;以回复 resolve。 |+| `request(type, payload, options?)` | 发送一个 RPC;以回复 resolve。`options` 可以是毫秒超时,或 `{ timeoutMs, idempotencyKey, codec }`。默认超时 10 秒(通道的 `requestTimeoutMs`);`0` 表示不超时。 |+| `sendBinary(channel, bytes)` / `onBinary(channel, handler)` | 在编号通道上收发原始二进制帧。 || `dispose(reason?)` | 拆除通道并 reject 挂起的请求。 |## 状态复制——多人实体同步@@ -292,7 +295,8 @@ const { gold } = await api.client(session).buy({ item: 'sword' });## 最佳实践- 超出简单套接字的场景**用 `NetChannel`**——按类型路由和 RPC 胜过一个巨大的 `'message'` 处理器 switch。-- **设置 RPC 超时**,让丢失的回复 reject 而不是永远挂起。+- **留意 RPC 超时**:丢失的回复默认 10 秒后 reject;玩家在等的地方传更短的+ `timeoutMs`,并避免用 `0`(不超时)。- **把收到的状态推入组件**(用 `Commands`),让玩法留在 ECS。- **连接前排队是自动的**——`connect()` 之后就能立即 `send`。- **在系统里做权威门控**——检查 `app.getResource(Net).role`(`'server'` / `'client'` /diff --git a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdxindex e40e69e71..2ade535db 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx@@ -263,9 +263,22 @@ export const Thruster = defineBehavior('Thruster', {});```-可用的相位包括 `Startup`、`PreUpdate`、`Update`、`PostUpdate`,以及固定三件套+可用的相位包括 `Startup`、`First`、`PreUpdate`、`Update`、`PostUpdate`、`Last`,以及固定三件套`FixedPreUpdate` / `FixedUpdate` / `FixedPostUpdate`。+### 声明你会碰哪些组件++行为通过 `ctx.get` / `ctx.set` 访问其他组件,调度器看不到这一步。不声明时它被当作不透明,+与其他所有系统冲突。传 `touches`(组件名)后,它才能被正确排序与并行:++```typescript+export const Drifter = defineBehavior('Drifter', {+ state: { speed: 60 },+ touches: { reads: ['Transform'], writes: ['Transform'] },+ update(ctx, dt) { /* … */ },+});+```+## 计时器"2 秒后…" / "每 0.5 秒…"这类逻辑,用内置的**计时器**资源比手搓累计时间干净。@@ -299,15 +312,15 @@ const arm = defineSystem([Res(TimerRes)], (timers) => {不必手写移动系统。引擎在播放模式下每次 update 把它积分进 `Transform`:```typescript-import { Velocity } from 'esengine';--world.spawn()- .insert(Transform, { position: { x: 0, y: 0, z: 0 } })- .insert(Sprite, { texture: bulletTex })- .insert(Velocity, {- linear: { x: 240, y: 0, z: 0 }, // 单位/秒- angular: { x: 0, y: 0, z: Math.PI }, // 弧度/秒(z = 2D 自转)- });+import { Velocity, Transform, Sprite } from 'esengine';++const bullet = world.spawn();+world.insert(bullet, Transform, { position: { x: 0, y: 0, z: 0 } });+world.insert(bullet, Sprite, { texture: bulletTex });+world.insert(bullet, Velocity, {+ linear: { x: 240, y: 0, z: 0 }, // 单位/秒+ angular: { x: 0, y: 0, z: Math.PI }, // 弧度/秒(z = 2D 自转)+});```带 `RigidBody2D` 的实体会被跳过——物理求解器拥有它们的变换,两者永远不会争抢同一个实体。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/save.mdx b/docs/astro/src/content/docs/zh-cn/scripting/save.mdxindex a98dc38f7..835d77ac4 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/save.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/save.mdx@@ -59,7 +59,8 @@ const data = saves.load('slot1');<Aside type="tip">迁移链也作为纯函数导出——`migrateSaveData(version, data, currentVersion, migrations)`——用于在 `SaveManager` 之外迁移数据(比如单元测试或一次性导入)。`SaveManager` 还接受- 可注入的 `storage` 与 `now` 选项,便于写确定性的测试。+ 可注入的 `storage` 与 `now` 选项,便于写确定性的测试;另有 `keyPrefix`(默认 `save:`),+ 给槽位在存储里加命名空间前缀。</Aside>## 普通键值存储diff --git a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdxindex 27a79290e..0b1e825a7 100644--- a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx@@ -34,7 +34,7 @@ getControllerPage(world, anyDescendant, 'tab'); // → 'shop'`controllerState(name, pages, current?)` 构造一个控制器(current 默认取第一页)。`setControllerPage` / `getControllerPage` 会沿 **自身 → 祖先** 找到最近的同名控制器,所以叶子上的绑定能找到根上的控制器。`setControllerPage` 对未知控制器、未知页、或已是当前页-都是空操作(防拼写错,而不是报错)。+都是空操作(防拼写错,而不是报错),只有真的切了页才返回 `true`。| `ControllerState` 字段 | 说明 ||---|---|@@ -92,12 +92,12 @@ world.insert(card, UIGear, {## 无需专用状态的按钮内建控制器名 **`$interaction`** 由指针状态驱动-(`normal` / `hover` / `pressed` / `disabled`)。给元素配一个 `$interaction` 控制器 ++(`normal` / `hover` / `pressed` / `disabled` / `focused`)。给元素配一个 `$interaction` 控制器 +一个 `Interactable` + 一条绑定,它就通过与其他一切相同的机制获得按钮状态——`createButton`本身就是这样构成的:```typescript-import { UIController, UIGear, interactionController, gearBinding, EasingType } from 'esengine';+import { UIController, UIGear, Interactable, interactionController, gearBinding, EasingType } from 'esengine';world.insert(btn, UIController, { controllers: [interactionController()] });world.insert(btn, Interactable, { enabled: true, blockRaycast: true, raycastTarget: true });@@ -111,8 +111,11 @@ world.insert(btn, UIGear, {});```-`interactionController(pages?)` 默认给出这四个规范页。因为绑定能驱动 *任意* 字段,同一个按钮-还能把缩放、子图标的着色、或标签一并绑上——四态,一套机制。+`interactionController(pages?)` 默认给出这五个规范页。驱动器的取页顺序:`Interactable` 关闭则+`disabled`,否则 `pressed`,否则 `hover`,否则 `focused`(仅限键盘聚焦——点击不会让按钮一直亮着),+否则 `normal`;且只会写入控制器列出的页。驱动器不拥有的页(比如 `'loading'`)会被原样保留,+直到你的代码切回来。因为绑定能驱动 *任意* 字段,同一个按钮还能把缩放、子图标的着色、+或标签一并绑上——每种状态,一套机制。## 在编辑器里授权@@ -124,7 +127,7 @@ world.insert(btn, UIGear, {列出它能看到的所有控制器——自己的加上每个祖先的(继承行标注所有者名字),所以在被绑定的叶子上工作时,根上的控制器依然可见、可切页:-- **添加控制器**(指针按钮预设一键添加带四页的 `$interaction`),页以 **chip** 管理:+- **添加控制器**(指针按钮预设一键添加带五页的 `$interaction`),页以 **chip** 管理:单击预览、双击重命名、拖拽排序、悬停 × 删除——重命名会级联进所有解析到该控制器的绑定,删页会清掉该页已录的值。- 点击某个控制器使其 **活动**。在 [细节](/docs/zh-cn/editor/overview/) 面板里,每个字段旁便出现一个小的@@ -161,6 +164,9 @@ activeTab.set('shop'); // 翻页,所有被绑定的元素重排{ "event": "click", "action": "ui.setPage", "params": { "controller": "tab", "page": "shop" } }```+(`params` 也可以拆成 `{ controller, page }` 两半——编辑器里的两个下拉框写的就是这种;+`ui.setVisible` 配 `{ visible }` 同样可以显示 / 隐藏一棵子树。)+**从状态机** —— `ui.setPage` 动作让数据驱动的[FSM / 行为树](/docs/zh-cn/gameplay/ai/overview/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:diff --git a/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdxindex 3de773891..a288c44c5 100644--- a/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx@@ -98,13 +98,14 @@ bindWidgetValue(world, events, entity, Component, field, signal, payloadKey?)一次往返一跳即收敛。- 返回的 dispose 同时拆除两个方向(向下绑定在实体销毁时也会自动解除)。-`payloadKey` 指名 `change` payload 里承载值的字段,默认与组件字段同名:+`payloadKey` 指名 `change` payload 里承载值的字段,默认与组件字段同名(文本输入框的 payload 里没有值——在 `change` 处理器里读 `TextInput.value`):| 控件 | 组件 / 字段 | `payloadKey` ||---|---|---|| 滑杆 | `UISlider.value` | `'value'`(默认) || 开关 | `UIToggle.isOn` | `'isOn'`(默认) || 下拉框 | `UIDropdown.selectedIndex` | `'index'`(需显式传入) |+| 页签视图 | `UITabView.selectedIndex` | `'index'`(需显式传入;payload 为 `{ index, page }`) |一行音量控件——滑杆与标签绑到同一个信号:diff --git a/docs/astro/src/content/docs/zh-cn/ui/debugger.mdx b/docs/astro/src/content/docs/zh-cn/ui/debugger.mdxindex 9f6c0ada2..3f9e32c23 100644--- a/docs/astro/src/content/docs/zh-cn/ui/debugger.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/debugger.mdx@@ -3,8 +3,6 @@ title: UI 调试器description: 实时检查 UI 树——拾取元素、录制它收到的事件、检查文本溢出与伪本地化预览、走一遍 Tab 顺序。----import { Aside } from '@astrojs/starlight/components';-**UI 调试器**是编辑器里检查 UI 树的面板。细节面板负责改实体的组件,调试器回答的是*一个控件为什么长这样、为什么这样响应*:布局给了它多大、哪些输入能到达它、文字放不放得下、Tab 下一步去哪。从命令面板(**UI 调试器**)或窗口菜单打开。编辑时它读**编辑器世界**,@@ -35,8 +33,9 @@ Play 时读**运行中的世界**。场景里每个 `Text`,把**测量**尺寸和**容器**尺寸、溢出方式并排放,被裁掉或溢出的标签一眼可见。顶部有**文本**、**溢出**、**待复核**的计数,**只看问题**会隐藏其余行。-**预览**菜单把所有文本重新渲染为**重音**(字母换成带变音符号的形近字——能发现缺这些字形的字体)或**加长**-(字符串明显变长——能发现只适配英文的布局)。预览不会改写场景里的文本。+**预览**菜单把所有文本重新渲染为**原文**、**重音 + 35%**(字母换成带变音符号的形近字,字符串约长三分之一+——能发现缺这些字形的字体)或**重音 + 100%**(同样处理,长度翻倍——能发现只适配英文的布局)。+预览不会改写场景里的文本。## 焦点路径@@ -45,8 +44,3 @@ Play 时读**运行中的世界**。选中某一行只是检查该实体,不会移动焦点。如果什么都没列出,给控件加上 `Focusable` 再重新读取。--<Aside>-布局读数给出的是输入*候选*,不是命中判定:父级遮罩或遮挡的兄弟节点仍可能挡住输入,-所以当一个看起来能点到的控件没反应时,要自己核对裁剪和遮挡。-</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdxindex c671a0922..6e0f5ede7 100644--- a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx@@ -26,7 +26,7 @@ import { Aside } from '@astrojs/starlight/components';| `UIInteraction` 字段 | 说明 ||---|---|| `hovered` | 指针悬停在节点上。 |-| `pressed` | 主键在节点上按住。 |+| `pressed` | 有指针(鼠标键或触点)在节点上按住。 || `justPressed` | 本帧变为按下(单帧沿)。 || `justReleased` | 本帧在被按下的节点上释放(单帧沿——即一次点击)。 |@@ -49,20 +49,26 @@ const onTiles = defineSystem([Query(Interactable, UIInteraction)], (q) => {## `UIEvents` 总线`UIEvents` 资源是带 DOM 式冒泡的发布/订阅队列。控件与交互系统发出标准事件集;-类型空间是**开放的**——你可以发出任意字符串(ListView 就发 `'item_selected'`)。+类型空间是**开放的**——你可以发出任意字符串。| `UIEventType` 常量 | 字符串 | 触发时机 | 冒泡 ||---|---|---|---|| `Click` | `'click'` | 在同一节点上按下并释放。键盘 Enter/Space 也会发出(仅发到 target,不冒泡)。 | 是 |-| `Press` / `Release` | `'press'` / `'release'` | 主键在节点上按下 / 抬起。 | 是 |+| `Press` / `Release` | `'press'` / `'release'` | 某个指针(鼠标键或触点)在节点上按下 / 抬起。`data` 是 `UiPointerEventData`(`pointer` 编号加 `worldX/Y`、`layoutX/Y`、`screenX/Y`)。 | 是 |+| `PointerMove` | `'pointer_move'` | 按住该节点的指针移动了;`data` 同上。 | 是 |+| `PressCancel` | `'press_cancel'` | 指针的按住在没有松开的情况下结束——被系统取消,或被别的东西接管了手势(如滚动区域判定为拖动)。之后不会有 click。 | 是 || `HoverEnter` / `HoverExit` | `'hover_enter'` / `'hover_exit'` | 命中节点发生变化。 | 否 |+| `Shown` / `Hidden` | `'shown'` / `'hidden'` | 节点(或其祖先)不再 / 开始处于 `display: None`。只有存在监听者时才会监视。 | 否 || `Focus` / `Blur` | `'focus'` / `'blur'` | 键盘焦点移动(见[焦点](#焦点与键盘))。 | 否 || `Change` | `'change'` | 控件值变化(toggle、slider、dropdown……)。 | 否 || `Submit` | `'submit'` | 文本输入确认(Enter)。 | 否 || `DragStart` / `DragMove` / `DragEnd` | `'drag_start'` / `'drag_move'` / `'drag_end'` | 拖拽系统(见[拖放](#拖放))。 | 否 |-| `Scroll` / `Select` / `Deselect` | `'scroll'` / `'select'` / `'deselect'` | 滚动视图与列表选择。 | 否 |-冒泡事件沿父链上行,途经每个**启用的** `Interactable` 祖先;带 `blockRaycast`+`Scroll`、`Select`、`Deselect`(`'scroll'` / `'select'` / `'deselect'`)只是预留名字——没有任何内置控件+会发出它们,需要时自己发(`createListView` 没有选择模型;滚动变化通过句柄的 `scroll.onScroll` /+`onScroll` 选项获得)。树视图发出的是 `change` 和 `drop_request`。++冒泡事件(`click`、`press`、`release`、`pointer_move`、`press_cancel`)沿父链上行,途经每个**启用的** `Interactable` 祖先;带 `blockRaycast`的祖先终止走链,任何处理器都可调用 `stopPropagation()`。每个 `UIEvent` 携带:| `UIEvent` 字段 | 说明 |@@ -117,7 +123,8 @@ makeWidgetInteractable(world, myWidgetRoot, { tabIndex: 2 });| `enabled` | `true` | 总开关。 || `dragThreshold` | `5` | 拖拽启动前需移动的屏幕像素(保住点击手感)。 || `lockX` / `lockY` | `false` | 冻结某轴(仅水平拖动的卡片)。 |-| `constraintMin` / `constraintMax` | `null` | 世界空间夹取角点,`null` 为不限制。 |+| `constrainMin` / `constrainMax` | `false` | 打开下 / 上限夹取。用开关而不是 `null` 边界,因为 `0` 是合法的限制值。 |+| `constraintMin` / `constraintMax` | `{0, 0}` | 世界空间夹取角点(`Vec2`),对应的 `constrain*` 开关打开时对两个轴生效。 |拖拽期间,transient 组件 `DragState` 携带实时几何(均为世界空间):@@ -169,7 +176,7 @@ addStartupSystem(buildCard);| 交互 | 行为 ||---|---|-| 点击可聚焦控件 | 聚焦它。 |+| 点击可聚焦控件 | 聚焦它——但不是*可见*聚焦:控件保持指针离开时的外观。只有 Tab(键盘)获得的焦点才会让控件进入 `focused` 页,并显示页签与提示气泡的聚焦提示。 || 点击空白处 / 按 `Escape` | 清除焦点。 || `Tab` / `Shift+Tab` | 循环焦点环——按 `tabIndex` 排序(相同者按发现顺序),跳过禁用的 `Interactable` 和树上被 `display: none` 隐藏的一切。 || 焦点控件上按 `Enter` / `Space` | 发出 `click`——激活按钮、开关、下拉。文本输入保留这些键用于编辑。 |@@ -210,7 +217,7 @@ const tooltip = defineSystem([GetWorld(), Res(UICameraInfo)], (world, camera) =>| 辅助函数 | 返回 | 用途 ||---|---|---|-| `uiHitTestWorld(world, x, y)` | 最顶层**可交互**实体或 `null` | 运行时射线——与交互系统同一套规则。 |+| `uiHitTestWorld(world, ray, screenRay?)` | 最顶层**可交互**实体或 `null` | 运行时射线——与交互系统同一套规则。参数是 `WorldRay`(`{ origin, dir }`),不是 x/y;只有一个点时用 `uiPickWorld`。 || `uiPickWorld(world, x, y)` | 最顶层 UI 实体或 `null` | 编辑器式拾取,无视 `Interactable`。 || `uiPickAllWorld(world, x, y)` | 该点下全部 UI 实体,最具体的在前 | 穿透式菜单、调试叠层。 || `screenToUiWorld(camera, glX, glY)` | `{ x, y }` 世界点 | 把 GL 朝向的屏幕点经 UI 相机投到世界。 |diff --git a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx b/docs/astro/src/content/docs/zh-cn/ui/layout.mdxindex 4d97dc95a..deefaae56 100644--- a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/layout.mdx@@ -57,6 +57,8 @@ isAuto(d) // true when d is the auto length|---|---|---|---|| `position` | `UIPositionType` | `Relative` | `Relative` = 在 flex 流中;`Absolute` = 脱离流,由内偏移放置。 || `display` | `UIDisplay` | `Flex` | `None` 把该节点**连同整棵子树**从布局、渲染和命中测试中移除——层级式显示/隐藏。对比 `UIVisual.enabled`:后者只隐藏本实体的视觉。 |+| `opacity` | number | `1` | 子树不透明度,沿树向下相乘,同 CSS `opacity`(乘进每个后代自己的 alpha,不会把子树离屏合成)。 |+| `pointerEvents` | `UIPointerEvents` | `Auto` | `None` 让该节点**连同整棵子树**对指针透明:照常绘制,点击直接穿过。 || `width` / `height` | `Dimension` | `auto()` | 盒尺寸;`auto` = 内容/flex 驱动。 || `minWidth` / `minHeight` | `Dimension` | `auto()` | 尺寸下限;`auto` = 无约束。 || `maxWidth` / `maxHeight` | `Dimension` | `auto()` | 尺寸上限;`auto` = 无约束。 |diff --git a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx b/docs/astro/src/content/docs/zh-cn/ui/lists.mdxindex 8e81afc3c..1d5e7d6a3 100644--- a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/lists.mdx@@ -49,7 +49,7 @@ const list = createListView<Player>({| `data` | — | 一个 `DataSource<T>`,或裸数组(会被包成 `ArrayDataSource`——数组会被**拷贝**,之后请改数据源而不是你的原数组)。 || `layout` | — | 布局语法糖(`itemHeight` / `itemWidth` / `columns`,见下)或完整的[布局提供者](#布局提供者)。 || `item` | — | 一个[条目模板](#条目模板),或"条目类型 → 模板"的 map(异构行)。 |-| `direction` | 由布局推导 | 滚动轴:`'vertical'` \| `'horizontal'` \| `'both'`。列/网格布局默认竖向,行布局默认横向。 |+| `direction` | 由布局推导 | 滚动轴:`'vertical'` \| `'horizontal'` \| `'both'`。列/网格布局默认竖向,行布局默认横向;自定义 `LayoutProvider` 一律默认竖向,横向的要自己传 `direction`。 || `recycleBuffer` | `2` | 可见范围两侧各多保留挂载的索引数。网格按行思考:`columns * 2` 即多留两行。 || `wheelSpeed` | `1` | 滚轮增量倍率。 || `dragScroll` | `true` | 指针/触摸拖拽滚动,带惯性甩动。 |@@ -263,9 +263,9 @@ createListView<Message>({`measureText(text, { fontSize, maxWidth?, fontFamily?, bold?, italic?, letterSpacing?, lineHeight? })`返回 `{ width, lineCount, height }`,度量来源与**字形图集绘制所用的同一份 Canvas2D 指标**,-所以测出的高度与实际渲染一致——不再有被裁或溢出的行。`lineHeight` 默认-`fontSize * 1.2`(`Text` 的默认比例);不传 `maxWidth` 即单行不折行。-(无 DOM 的宿主回退到平均字宽估算。)+所以测出的高度与实际渲染一致——不再有被裁或溢出的行。`fontFamily` 默认 Arial,+`lineHeight` 默认 `fontSize * 1.2`(`Text` 的默认比例);不传 `maxWidth` 即单行不折行。+(设备上度量来自平台自己的字形光栅化器;只有无头宿主才回退到平均字宽估算。)## 虚拟化的工作方式@@ -357,7 +357,9 @@ UI 插件负责喂输入:thumb 出现,静止约 0.8 秒后淡出。thumb 长度跟随视口/内容比例,不占布局(脱离文档流)、不接输入(非交互),并以 `text` 主题角色标记,主题热切换时会重新上色。工厂始终开启滚动条;关闭(`showScrollbar: false`)是 `ScrollContainer`-的构造选项,供手动组合使用。+的构造选项,供手动组合使用。同一构造函数还接受 `initialOffset`、`elastic`+(默认 `false`:拖动可把内容拉过两端,带橡皮筋阻尼,松手后弹回)和 `bounceTime`+(弹回稳定所需秒数,默认 `0.5`)。## 裁剪 —— `UIMask`diff --git a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdxindex 647ced23d..bbefb12ca 100644--- a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx@@ -130,7 +130,7 @@ addStartupSystem(buildPauseMenu);给节点加上 `UIMask`,它的子项就会被裁剪到该节点。默认裁剪的是节点的**外框**——一个矩形。这对列表视口足够了,但也正是圆形头像框以前仍然裁出方形的原因:遮罩图形是圆的,裁剪范围不是。-`alphaCutoff` 大于 0 时,裁剪范围切换为遮罩实际绘制出的形状。+在 `mode: MaskMode.Stencil` 下,`alphaCutoff` 大于 0 时,裁剪范围切换为遮罩实际绘制出的形状(默认模式 `Scissor` 始终按外框裁剪)。@@ -146,7 +146,7 @@ addStartupSystem(buildPauseMenu);**`UIMask.alphaCutoff` —— 按形状裁剪,而不是按外框。** 模板遮罩裁剪的是遮罩的*矩形*,所以圆形头像框裁出来仍是方的。大于 `0` 时它按遮罩实际绘制的形状裁剪,判定用的是**精灵**的 alpha-(而非着色后的结果——遮罩图形常被调到接近全透明,好让它遮挡而不被看见)。默认仍是 `0`,因此+(而非着色后的结果——遮罩图形常被调到接近全透明,好让它遮挡而不被看见)。它只在 `MaskMode.Stencil` 下生效;`Scissor`(默认模式)始终按矩形裁剪。默认仍是 `0`,因此按外框裁剪创作的场景不受影响。### `ContentRect` —— 世界内容的矩形@@ -175,6 +175,8 @@ addStartupSystem(buildPauseMenu);- 边距可以是布局单位,也可以是父级尺寸的比例(每个边距各有一个 `isAbs…` 开关)。- 父级没有 `ContentRect` 时,对齐到**屏幕**,屏幕以世界原点为中心。+`alignFlags` 是 `AnchorFlag`(`TOP`、`MID`、`BOTTOM`、`LEFT`、`CENTER`、`RIGHT`)的位集合;默认 `0` 不钉任何边,设置标志之前这个组件什么都不做。+`alignMode` 决定何时对齐:`ONCE`、`ON_RESIZE`(默认:启用时、自身设置变化时、屏幕变化时)或 `ALWAYS`(每帧)。父级总是先于依赖其尺寸的子级对齐,编辑器的编辑模式下和运行时一样,所以场景在编辑器里看到的就是运行时的布局。@@ -237,6 +239,7 @@ world.set(dialog, UINode, { ...node, opacity: 0.3, pointerEvents: UIPointerEvent| 字段 | 默认 | 含义 ||---|---|---|+| `enabled` | `true` | 不移除组件而关掉滚动。 || `content` | 第一个子节点 | 被移动的那个子节点。 || `horizontal` / `vertical` | `false` / `true` | 哪些轴可滚。 || `movement` | `Clamped` | `Elastic` 会在两端过冲再弹回。 |diff --git a/docs/astro/src/content/docs/zh-cn/ui/text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdxindex 00cc3b812..42a6b0b13 100644--- a/docs/astro/src/content/docs/zh-cn/ui/text.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/text.mdx@@ -68,7 +68,8 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t|---|---|---|---|| `content` | string | `''` | 要显示的字符串。`\n` 硬换行。 || `i18nKey` | string | `''` | 本地化键。非空 ⇒ `content` 成为**派生值**:每帧从本地化目录解析([见下文](#本地化))。 |-| `fontFamily` | string | `'Arial'` | 字体族,由平台 Canvas2D 解析(见[自定义字体](#自定义字体))。 |+| `font` | 字体资源 | 无 | 项目随游戏发布的字体文件(`.ttf` / `.otf` / `.woff` / `.woff2`,或位图 `.fnt`)。设置后优先于 `fontFamily`(见[自定义字体](#自定义字体))。 |+| `fontFamily` | string | `''` | 宿主已有的字体族,由平台文字栈解析(见[自定义字体](#自定义字体))。留空则用项目的默认字体族(设置 → 运行时 → 文字;不改就是 `Arial`)。 || `fontSize` | number | `24` | 尺寸,单位**设计像素**——与 `UINode` 的 `px()` 同一单位。设计分辨率适配与设备像素比在栅格化时补偿。 || `color` | Color | `{1,1,1,1}` | 填充色(每通道 `0..1`)。 || `align` | `TextAlign` | `Left` | 水平对齐:`Left` / `Center` / `Right`。 |@@ -87,6 +88,7 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t| `shadowBlur` | number | `0` | 投影柔度(px)。`0` 是硬边偏移副本;大于 0 时投影摊成一圈,读起来是字下面一团柔和的暗,而不是又盖了一遍字。只给柔度不给偏移就是一圈光晕。 || `richText` | boolean | `false` | 解析内联[富文本标记](#富文本)。 || `renderMode` | `TextRenderMode` | `Auto` | 字形管线:`Auto` / `Bitmap` / `Sdf`(见上文)。 |+| `layer` | number | `0` | **没有** `UINode` 的 `Text` 的绘制层,读法同 `Sprite.layer`,世界里的文字因此能排到周围内容的前面或后面。有 `UINode` 时忽略,由 UI 渲染顺序决定。 || `enabled` | boolean | `true` | 渲染开关(编辑器的眼睛图标也用它)。 |<Aside type="note">@@ -132,6 +134,10 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t反解出来,使叠起来正好是你要的 alpha。与描边不同,它是把边缘**变柔**而不是挪动,这也是两者分成两个字段的原因。+++*富文本演示:改标记,上方的渲染结果随之更新。*+## 富文本设 `richText: true`,在 `content` 里写内联标签。样式按栈嵌套;闭合标签弹出最内层diff --git a/docs/astro/src/content/docs/zh-cn/ui/theming.mdx b/docs/astro/src/content/docs/zh-cn/ui/theming.mdxindex af1a4d20a..f1c7348ff 100644--- a/docs/astro/src/content/docs/zh-cn/ui/theming.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/theming.mdx@@ -30,7 +30,7 @@ interface ThemeTokens {### 颜色角色(`ThemeColors`)-全部角色按显示顺序列出(这也是运行时列表 `THEME_COLOR_ROLES`——主题编辑器或+全部 13 个角色按显示顺序列出(这也是运行时列表 `THEME_COLOR_ROLES`——主题编辑器或配置校验器迭代的那个数组):| 角色 | 用途 |@@ -40,6 +40,7 @@ interface ThemeTokens {| `control` | 交互控件的静止填充(按钮、选项)。 || `controlHover` | 悬停时的控件填充。 || `controlActive` | 按下时的控件填充。 |+| `controlFocus` | 控件获得键盘焦点时的填充(只在焦点由键盘到达时显示,因此与 `controlHover` 区分开)。 || `track` | 滑杆 / 进度条轨道。 || `primary` | 强调色——滑杆填充、进度填充、选中项。 || `primaryHover` | 悬停时的强调色。 |@@ -130,6 +131,8 @@ switchTheme(world, getTheme() === DARK_TOKENS ? LIGHT_TOKENS : DARK_TOKENS);- **`resolveThemeTokens(base, overrides?)`** —— 把基础主题名(`'dark' | 'light'`)与局部覆盖合并成有效的 `ThemeTokens`,于是只覆盖`primary` 的项目在继承其余角色的同时重染强调色。+ `ThemeOverrides` 形如 `{ colors?, type? }`;项目清单只带颜色,+ 自定义字号档位(`label` / `body` / `title`)只能在代码里设置。```typescriptimport { resolveThemeTokens, parseThemeOverrides, switchTheme } from 'esengine';diff --git a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdxindex 8bb5b5858..d229ea559 100644--- a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx@@ -66,6 +66,7 @@ const btn = createButton({| `disabled` | `false` | 以禁用态启动。 || `focusable` / `tabIndex` | `true` / `0` | 键盘可达性与 Tab 顺序。 || `onClick(entity)` | — | 点击回调(受启用态门控)。 |+| `userGesture` | `false` | 在宿主自己的松开事件内同步执行 `onClick`,而不是下一帧——用于宿主只接受玩家手势直接触发的调用(如在微信里分享录屏)。 |**句柄:** `entity`、`setDisabled(disabled)`、`dispose()`。@@ -296,11 +297,12 @@ const name = createTextInput({|---|---|---|| `node` | 220×32 | 输入框的 `UINode` 布局(唯一不默认填满父级的工厂)。 || `value` / `placeholder` | `''` | 内容 / 为空时的提示。 |+| `placeholderI18nKey` | `''` | 空输入框提示的文案键;需要 `Localization` 资源。写在 `placeholder` 里的原文作为回退。 || `maxLength` | `0` | 字符上限(`0` = 不限)。 || `multiline` | `false` | Enter 插入换行而不是提交。 || `password` | `false` | 掩码显示字符。 || `readOnly` | `false` | 可聚焦但不可编辑。 |-| `fontSize` / `fontFamily` | 主题 label 字号 / `'Arial'` | 文本样式。 |+| `fontSize` / `fontFamily` | 主题 label 字号 / `''`(项目默认字体) | 文本样式。 || `color` / `backgroundColor` / `placeholderColor` | 主题 `text` / `control` / 淡化 `text` | 颜色覆盖——省略时用主题角色。 || `padding` | `6` | 内部水平内边距(px)。 || `renderMode` | `Auto` | 输入框文字的字形管线——`Auto`(未缩放时清晰位图,缩放后 SDF)、恒 `Bitmap`、或恒 `Sdf`。 |@@ -376,7 +378,7 @@ world.insert(field, TextInput, { placeholder: 'Name', font: gameFont, textAlign:## 键盘焦点带 `Focusable` 的实体参与键盘焦点:Tab / Shift+Tab 按 `tabIndex` 轮换,-Enter/Space 激活,滑块接管方向键,聚焦的控件显示其 `focused` 交互页。+Enter/Space 激活,滑块接管方向键,经键盘聚焦的控件显示其 `focused` 交互页。控件工厂自动加 `Focusable`(`focusable: false` 退出);`FocusManager` 资源提供程序化控制。详见 **[UI 交互](/docs/zh-cn/ui/interaction/)**。@@ -440,6 +442,9 @@ const stick = createVirtualJoystick({ world, parent: canvas, inputId: 'move',const actions = defineInputMap({ Move: Axis2D(Virtual('move')) });```+默认值:`inputId` 为 `'move'`,`mode` 为 Fixed,`radius` 50 px,`deadZone` 0.15(范围 0 到 0.99),+`returnSpeed` 18。Follow 模式的摇杆默认触控区为 240×160。+编辑器的创建实体选择器里,UI 分类提供同一个生成预制体。Play 中的鼠标拖动和触控使用同一套捕获机制。禁用、隐藏、移除、取消或切后台会释放该控件自己的贡献,其他控件仍保持输出。可以提供自定义底座和手柄外观。@@ -447,7 +452,7 @@ const actions = defineInputMap({ Move: Axis2D(Virtual('move')) });## VirtualButton`createVirtualButton({ world, events, parent: canvas, inputId: 'fire', text: 'Fire' })`-复用普通按钮外观,向 `Virtual('fire')` 输出按住状态。不同按钮、同一按钮上的+复用普通按钮外观,向 `Virtual('fire')` 输出按住状态(`inputId` 默认 `'fire'`;`value` 是输出的标量,默认 `1`;该按钮不可键盘聚焦)。不同按钮、同一按钮上的多个触点,以及两帧之间完成的短按都能正常释放。多个控件共享绑定时,移除其中一个不会清空其他控件。自定义控件可使用固定 owner 的 `Input.setVirtualSource`,并在销毁时移除该 owner。@@ -477,6 +482,10 @@ const settings = createTabView({ world, events, parent: canvas,settings.select(1);```+`createTabView` 还接受 `selectedIndex`(初始页签,默认 `0`)、`tabHeight`(默认 `36` px)和+`onChange(index, page)`。`UITabView` 另有 `vertical`(方向键沿纵向,默认 `false`)、+`loopNavigation`(默认 `true`)、`selectOnFocus`(默认 `true`)和 `allowSwitchOff`(默认 `false`)。+场景、Prefab 实例化和复制会重映射 `tabs` / `pages` 实体数组。`labels` 提供页签直接 Text 子节点的文字。删除当前选择的目标后会选择其他有效绑定;移除绑定会恢复该内容页原本的 display。@@ -497,7 +506,7 @@ attachTooltip(world, musicVolume, {});```-`side` 的 0/1/2/3 对应下/上/左/右。定位会先尝试优先方向和相反方向,再限制在屏幕安全区内。+默认值:`hover: true`、`focus: true`、`longPress: true`、`hoverDelay: 0.5` 秒、`longPressDelay: 0.6` 秒、`side: 0`、`gap: 8` px、`avoidEdges: true`、`maxWidth: 240` px;`hover` / `focus` / `longPress` 分别开关三种触发方式。`side` 的 0/1/2/3 对应下/上/左/右。定位会先尝试优先方向和相反方向,再限制在屏幕安全区内。`maxWidth` 是布局像素单位的最大文本宽度。`stylePrefab` 留空时使用项目的实时 UI 主题;自定义 `.esprefab` 需要 UINode 根节点和 Text 子节点,保留其中的颜色和字体样式,浮层行为负责位置、文字和内边距。样式通过普通 Prefab 资源加载流程加载,需要 `PrefabsPlugin`。@@ -560,6 +569,10 @@ const picker = createColorPicker({ world, events, parent: canvas,});```+其他选项:`alphaEnabled`(默认 `true`)、`format`(`0` 为 HSV + HEX,`1` 为 RGB + HEX)、+`history`(初始最近颜色)、`historyLimit`(默认 `8`,最大 `32`)和 `rememberColors`(默认 `true`)。+默认尺寸 280×412。+`UIColorPicker.color` 使用引擎统一的 `{ r, g, b, a }`,通道范围 0..1。`change` 携带 `{ color }`,`history_change` 携带 `{ colors }`。目标绑定、业务修改和历史色持久化由项目控制;控件不内置 Sprite / Material 引用,也不隐式转换线性 / sRGB。diff --git a/docs/astro/src/content/docs/zh-cn/world/generation.mdx b/docs/astro/src/content/docs/zh-cn/world/generation.mdxindex 28c2f7704..8665878cc 100644--- a/docs/astro/src/content/docs/zh-cn/world/generation.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/generation.mdx@@ -14,7 +14,8 @@ description: 按规则在探索时布置世界——由环境场得出群落、| `rules` | 布置这个世界的规则:一个 `.esworld` 文件,或游戏用 `registerWorldRules` 注册的规则标识。 || `version` | 这个世界生成时使用的规则版本。存档会保留它;规则里已没有这个版本时,世界失败(状态里说明原因),而不是布置出另一个世界。 || `world`、`seed` | 游戏给这个世界(星球、关卡)起的名字,以及它的种子。换一个种子就是同一套规则下的另一个世界。 |-| `paintGround` | 群落是否给地形上色。 |+| `paintGround` | 群落是否给地形上色(默认开)。 |+| `surface`、`seaLevel` | `Plane`(默认)把世界铺在 `Terrain` 上;`Planet` 表示该实体同时是 `Planet`,世界铺在它的六个面上。`seaLevel`(`Planet` 时显示)是海面高出星球半径的高度,低于它的地面在水下。 |规则放置的东西作为这个实体的子实体发布,围绕[流送源](/docs/zh-cn/world/streaming/)(或摄像机):见[程序化区块](/docs/zh-cn/world/streaming/#程序化区块)。@@ -86,17 +87,21 @@ registerWorldRules({层是按顺序进行的几遍布置:先大后小。每层在间距为 `spacing` 的网格里每格取一个抖动后的候选点,并为它抽一个优先级。两个候选点的组会重叠时,优先级高的成立;每个候选点都避开前面各层的占地,所以蕨类不会长穿树干,石头不会嵌进巨石里。一层以 `chunkSize` 大小的区块发布到 `drawDistance`。`occupies: false` 让后面的层可以和它重叠(地被)。`farSpacing`(默认 1)让这一层植物的远景版本按更大的间距规划:远景只保留四分之一的地被设为 2,只需要算四分之一的候选点,不再先全算出来再丢掉。+++*地形与水面示例里的 **World Gen** 组件:规则资产、种子和表面。*+## 区域-区域是手工规划的一块地方:家园、道路、落点、建筑占地、保留的视线。+区域(`WorldZone` 组件)是手工规划的一块地方:家园、道路、落点、建筑占地、保留的视线。它跟随所在实体的位置和绕竖直轴的转向。| 字段 | 作用 ||---|---|-| `kind` | 它的用途,用游戏自己的词。 |-| `shape`、`radius`、`sizeX`、`sizeZ` | 圆形,或随实体绕竖直轴旋转的矩形。编辑器会画出它的轮廓。 |-| `falloff` | 在轮廓外多少世界单位内逐渐消失:被排除的东西在这里变稀,而不是停在一条线上。 |+| `kind` | 它的用途,用游戏自己的词(默认 `reserve`)。 |+| `shape`、`radius`、`sizeX`、`sizeZ` | 圆形(默认,`radius` 为 10),或随实体绕竖直轴旋转的矩形(`sizeX` × `sizeZ`,默认 20 × 20)。编辑器会画出它的轮廓。 |+| `falloff` | 在轮廓外多少世界单位内逐渐消失(默认 4):被排除的东西在这里变稀,而不是停在一条线上。 || `priority` | 区域重叠时,高的决定群落。 |-| `excludes` | 它排除的东西的标签,逗号分隔:层、配方、配方或成员的标签、`decor`、`interactive`;`*` 表示全部。 |+| `excludes` | 它排除的东西的标签,逗号分隔:层、配方、配方或成员的标签、`decor`、`interactive`;`*` 表示全部(默认);留空则什么都不排除。 || `biome` | 它在范围内强制的群落。 || `flatten` | 把它下面的地形压平到区域中心处原地面的高度,在 `falloff` 内平滑过渡回去:一块可以建造的地基。代码里 `flatten` 可以是世界高度,或 `'ground'`。 |@@ -110,6 +115,10 @@ gens.zones().set({ id: 'house 1', kind: 'building', shape: { type: 'rect', x, z,只有区域触及的区块会重新生成,每个区块的旧版本保留到新版本替换它为止。+++*一个 **World Zone**:一个圆,告诉生成器在其中生长哪种群落。*+## 可交互的放置物与变化带 `interactive`(如 `'ore'`、`'tree'`)的成员是独立的实体,带有记录放置 ID 与类型的 `PlacedObject`;其余都是装饰,按区块、按种类合并成一个网格绘制。`gens.objectOf(id)` 找到某个放置物对应的实体。diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex e4786e35d..aaddc20d9 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -32,6 +32,10 @@ CPU 模拟粒子,并按发射器**GPU 实例化**为单次 draw call 渲染,所burst、looping)会自动重启该发射器;重新切换开关 = 全部从 t=0 重播。</Aside>+++*粒子示例:由两个发射器(烟和火星)组成的篝火。*+## 安装粒子系统在主包里。编辑器和 Web 运行时会自动安装插件。在自定义 `App` 里手动加一次:@@ -129,7 +133,7 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {| `noiseStrength` | number | `0` | 湍流推动粒子的峰值流速(px/s)。`0` = 关闭该模块。 || `noiseFrequency` | number | `0.01` | 场的空间尺度 —— 越大漩涡越紧、越繁密。 || `noiseScrollSpeed` | number | `0` | 场随时间漂移的速度(`0` = 静止场)。 |-| `noiseOctaves` | number | `1` | 分形细节层数。`1` = 平滑流动;越多越细碎的湍流。 |+| `noiseOctaves` | number | `1` | 分形细节层数(1..8)。`1` = 平滑流动;越多越细碎的湍流。 |见下文[噪声与湍流](#噪声与湍流-1)。@@ -190,7 +194,7 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {| 属性 | 类型 | 默认 | 说明 ||---|---|---|---|| `subEmitter` | entity | 无 | 粒子触发时发射的子发射器实体。`0`/未设 = 关闭。 |-| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | 在每个粒子的 `Death`(死亡)或 `Birth`(出生)时触发。 |+| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | 在每个粒子的 `Death`(死亡)或 `Birth`(出生)时触发,或在粒子撞到东西时(`Collision`,见[场景碰撞](#场景碰撞))。 || `subEmitterChance` | number | `1` | 触发粒子发射子爆发的概率(0..1)。 || `subEmitterInheritVelocity` | number | `0` | 传给子爆发的父粒子速度比例。 |@@ -207,6 +211,29 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {见下文[逐粒子拖尾](#逐粒子拖尾)。+++***Particle Emitter** 的 Details:顶部是**碰撞**分组(这里关闭),下面是发射字段。*++### 碰撞 (Collision)++`collisionEnabled` 打开后才显示。见[地面碰撞](#地面碰撞)和[场景碰撞](#场景碰撞)。++| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `collisionEnabled` | boolean | `false` | 打开碰撞。 |+| `collisionMode` | `ParticleCollisionMode` | `Floor` | `Floor`(水平面)、`Physics2D` 或 `Physics3D`(穿过物理世界投射)。 |+| `collisionFloor` | number | `0` | 地面平面的世界高度。 |+| `collisionBounce` | number | `0.5` | 0 = 立即停住,1 = 完全弹性。 |+| `collisionFriction` | number | `0.1` | 每次反弹损失的水平速度,0..1。 |+| `collisionLifetimeLoss` | number | `0` | 每次反弹消耗的寿命比例,0..1。 |+| `collisionMask` | 位掩码 | 全部(`65535`) | 场景模式会命中的物理层;0 表示一层都不选。 |+| `collisionQueryBudget` | number | `128` | 该发射器每次更新最多做多少次查询,0..4096。 |+| `collisionMaxDistance` | number | `0` | 距最近活动相机超过此距离则跳过碰撞;`0` = 不做距离剔除。 |+| `collisionFallback` | `ParticleCollisionFallback` | `Floor` | 物理不可用、预算用完或粒子太远时的退路:`Floor` 或 `Skip`。 |+| `collisionEvents` | boolean | `false` | 发出 `ParticleCollisionEvent`。 |+| `collisionEventBudget` | number | `32` | 该发射器每次更新最多发出多少事件,0..1024。 |+## 发射器形状@@ -389,6 +416,8 @@ cmds.spawn()});```+组件其余字段的默认值:`type` 为 `Directional`,`strength` 为 `200`,`radius` 为 `0`,`direction` 为 `{1, 0, 0}`,`falloff` 开,`enabled` 开。+| 类型 | 效果 ||---|---|| `Directional` | 沿 `direction` 的恒定推力 —— 风、上升气流、水流。 |@@ -452,6 +481,9 @@ cmds.spawn()| `Multiply` | 变暗——烟雾、阴影。 || `Screen` | 提亮,比 additive 更柔和。 || `PremultipliedAlpha` | 用于预乘 alpha 的贴图。 |+| `PmaAdditive` | 预乘 alpha 来源的叠加。 |+| `Lighten` | 取粒子与场景像素中较亮的。 |+| `Darken` | 取两者中较暗的。 |## 控制播放 —— `Res(Particle)`@@ -477,6 +509,9 @@ const control = defineSystem([Res(Particle)], (particles) => {| `getAliveCount(entity)` | 当前存活的粒子数。 || `setColorLut(entity, lut \| null)` | 上传烘焙好的颜色 LUT(见上),或清空。 || `setSizeLut(entity, lut \| null)` | 上传烘焙好的尺寸 LUT,或清空。 |+| `setSpeedLut(entity, lut \| null)` | 上传烘焙好的速度随寿命倍率;它缩放粒子沿既有轨迹的速度,不取代重力和噪声。 |+| `setBursts(entity, bursts \| null)` | 从代码设置爆发时间表(`{ time, count }[]`),或清空。 |+| `setCollisionBudget({ queries?, events? })` | 修改整个 App 共享的碰撞上限。 |<Aside type="tip">每帧的 `update` 由粒子系统自动驱动——你不用调它。对于一次性特效,留着一个已停止的发射器,diff --git a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdxindex d96b934f6..5a3ecdcb9 100644--- a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx@@ -109,14 +109,14 @@ const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {## 设置父级并访问子项-把实例嵌套到另一个实体下,并用返回的 `entities` map 按预制体局部 id 访问子项:+把实例嵌套到另一个实体下,并用返回的 `entities` map 访问生成出来的子项:```typescriptconst { root, entities } = await prefabs.instantiate('assets/prefabs/turret.esprefab', {parent: mountPointEntity,});// root → the instance root-// entities → Map<prefab-local id, spawned Entity>, for reaching children+// entities → Map<number, spawned Entity>,按生成时给每个实体的 id 索引```## 逐实例覆盖@@ -133,8 +133,7 @@ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {```要作用到**子实体**,补上它的 `prefabEntityId`——即那个实体自己的**字符串** id,-编辑器创作的预制体里是 UUID。可以从 `.esprefab` 里读,也可以从上一次 instantiate-返回的 `entities` 映射里取。+编辑器创作的预制体里是 UUID。可以从 `.esprefab` 里读(不写 `prefabEntityId` 的覆盖作用到根实体)。:::caution[`prefabEntityId: '0'` 已经匹配不到任何东西]`'0'` 是稳定 id 之前所有预制体的 id,旧的示例代码里还留着它。此后由编辑器保存的预制体@@ -142,7 +141,7 @@ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {id——在此之前它是被静默丢弃的,唯一的症状就是每个实例都出现在预制体被创作时的那个位置。:::-除了 `'property'`,`type` 还可以是 `'name'`、`'visibility'`、`'component_added'`、+除了 `'property'`,`type` 还可以是 `'name'`、`'visibility'`、`'parent'`、`'component_added'`、`'component_replaced'`、`'component_removed'`、`'metadata_set'` 或 `'metadata_removed'`(metadata 两种用 `metadataKey` 代替 `componentType`/`propertyName`)。@@ -158,7 +157,7 @@ id——在此之前它是被静默丢弃的,唯一的症状就是每个实例| 结果字段 | 说明 ||---|---|| `root` | 实例的根 `Entity`。 |-| `entities` | `Map<prefab-local id, Entity>`,用于访问子项。 |+| `entities` | `Map<number, Entity>`,含根在内的所有生成实体,用于访问子项。 |## 最佳实践diff --git a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdxindex 976110ef5..2e1825083 100644--- a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx@@ -155,7 +155,7 @@ const setupStreaming = defineSystem([Res(SceneStreaming)], (streaming) => {|---|---|| `configure({ loadRadius, unloadRadius, policy? })` | 设置半径(`unloadRadius` 向上钳制到不小于 `loadRadius`)与出界策略——`'unload'`(默认)或 `'sleep'`。 || `register(cell)` / `unregister(scene)` / `clear()` | 管理单元集合(`{ scene, x, y, radius }`)。 |-| `setFocus(x, y)` | 直接驱动焦点(每帧调用)。 |+| `setFocus(x, y, z?)` | 直接驱动焦点(每帧调用);距离按三维量,`z` 默认 0,格子的可选 `z` 也默认 0。 || `setFocusEntity(entity)` / `getFocusEntity()` | 改为跟随一个实体——流送系统每 tick 读它的 `Transform`(仅 play 模式)。 || `getActive()` | 控制器当前认为在范围内的场景名。 || `update()` | 按当前焦点调和驻留单元(`sceneManagerPlugin` 每帧调用)。 |@@ -180,6 +180,7 @@ const setupStreaming = defineSystem([Res(SceneStreaming)], (streaming) => {|---|---|| `switchTo(name, options?)` | 替换活动场景(异步;可选过渡)。 || `loadAdditive(name, onProgress?)` | 在顶部加载一个场景;返回其上下文(异步)。 |+| `reload(options?)` | 用场景文件重新切换到当前活动场景(异步;可带过渡)。 || `unload(name, options?)` | 卸载一个场景(异步;可选过渡)。 || `getScene(name)` | 已加载场景的 `SceneContext`(`spawn` / `adopt` / `despawn` / `setPersistent` / draw 回调 / 后处理绑定),或 `null`。 || `getActive()` | 活动场景名,或 `null`。 |@@ -240,7 +241,7 @@ const checkpoint = defineSystem([GetWorld(), Res(Assets)], async (world, assets)| `abortOnMissingAssets` | 默认 `false`——缺失资源拿到句柄 `0`,场景照常加载。`true` 时在预加载之后、任何实体生成之前抛出 `MissingAssetsError`。 || `collectAssets` | 记账集合,加载把获取到的资源键加入其中,调用方(通常是场景管理器)卸载时据此释放。 |-**版本化。** 场景文件带 `version`(当前 `SCENE_FORMAT_VERSION = '1.0'`)。+**版本化。** 场景文件带 `version`(当前 `SCENE_FORMAT_VERSION = 4`)。`migrateSceneData(raw)` 把任何旧形态升级到当前格式:它从不改动输入(返回迁移后的深拷贝)、幂等、丢弃被引擎升级淘汰的组件类型,并**拒绝比引擎更新的数据**。每个加载器内部都会跑它——只有想检查 `migrated` / `fromVersion` 时才自己调用(比如提示重新保存升级后的文件):diff --git a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx b/docs/astro/src/content/docs/zh-cn/world/streaming.mdxindex d52cd37c3..9f8df1c3e 100644--- a/docs/astro/src/content/docs/zh-cn/world/streaming.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/streaming.mdx@@ -49,6 +49,8 @@ world.insert(player, WorldStreamingSource, {});```+三个半径的单位是世界单位,默认值就是上面的数字;组件还有一个 `enabled` 开关(默认开),关掉就把这个源从并集里拿掉而不必移除组件。`StreamedWorld.cellSize` 默认 1000。+可以同时存在多个源,它们的请求是**并集**——只要任意一个源需要,格子就继续常驻。这正是分屏、观战相机、过场相机和编辑器预览可以是同一类东西、而不是四个特例的原因。这里不会把多个源折叠成一个焦点:折叠意味着最后写入的那个说了算,于是第二个相机出现的下一帧,它就diff --git a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdxindex 6cc74e90b..39a7a7e41 100644--- a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx@@ -174,7 +174,7 @@ tilemap.setTilesets(layer, [可选的 `margin`(第一个 tile 前的边距)和 `spacing`(tile 之间的间隙)以像素为单位,用于描述单元之间留白的图集——这样每个 tile 只采样自己的纹素,不会渗到相邻 tile。两者默认为 `0`,所以-无间隙图集无需设置;Tiled / `.estileset` 导入器会自动从图集自身的 margin/spacing 填入。+无间隙图集无需设置(每个槽位还可以带 `extrude`,默认同为 `0`);Tiled / `.estileset` 导入器会自动从图集自身的 margin/spacing 填入。## 瓦片动画@@ -306,7 +306,7 @@ Tiled 的**对象层**(出生点、触发器、区域形状)随地图一起加**Trigger Area** 区域——正是你手工创建的那些实体——于是一条查询就能读到对象,无论它来自Tiled 还是 Estella 编辑器。-原始的组数据仍可用地图的源路径经 `getTilemapSource` 查询——每个组携带它的对象,含位置、+原始的组数据仍可用地图的源路径经 `tilemapSource` 查询——每个组携带它的对象,含位置、尺寸、`type`(Tiled 的 class)、`shape` 和自定义 `properties`:```typescript@@ -345,13 +345,13 @@ origin / 每单位像素 / 播放模式生命周期。| `fillRect(layer, x, y, w, h, id)` | 用瓦片 id 填充一个矩形。 || `flipTile(layer, x, y, h, v, d)` | 翻转一个瓦片(水平 / 垂直 / 对角)。 || `rotateTile(layer, x, y, degrees)` | 旋转一个瓦片(90° 步进)。 |-| `tileToWorld(layer, tx, ty, ox, oy)` / `worldToTile(layer, wx, wy, ox, oy)` | 坐标转换。 |+| `tileToWorld(layer, tx, ty, ox, oy, rotation?)` / `worldToTile(layer, wx, wy, ox, oy, rotation?)` | 坐标转换;`ox`/`oy` 是层的世界原点,可选的 `rotation` 是层绕世界 Z 轴的角度(弧度)。 || `setTilesets(layer, slots)` | 指定多图集 slot 表。 || `setTileAnimation(layer, tileId, frames)` | 动画化一个瓦片 id。 || `setChunkTiles(layer, cx, cy, tiles, w, h)` | 写一个块(无限图层)。 || `removeChunk(layer, cx, cy)` | 把一个块从图层里拿掉,连同它画出来的网格。 || `exportChunks(layer)` / `importChunks(layer, data)` | 序列化 / 恢复分块数据。 |-| `setTint(layer, color)` / `setVisible(layer, on)` / `setRenderProps(...)` | 实时视觉覆盖。 |+| `setTint(layer, r, g, b, a, opacity)` / `setVisible(layer, on)` / `setRenderProps(...)` | 实时视觉覆盖。 || `setTileProperty(...)` / `getTileProperty(...)` | 逐瓦片自定义键值属性。 || `setGridType(layer, type)` / `setHexParams(...)` | 朝向(正交 / 等距 / 六边形)。 || `destroyLayer(layer)` | 销毁图层。 |diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex 9f30c446d..ba5bcd01d 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -53,7 +53,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {// ── Core ───────────────────────────────────────────────────────────────────Transform: { category: 'core', summary: 'Position, rotation and scale — plus the read-only world-space values the engine composes down the parent chain.', doc: 'core-concepts/transforms', anchor: 'the-transform-component', anchorZh: 'transform-组件' },Parent: { category: 'core', summary: 'The entity this one hangs under. The engine keeps it and `Children` in step; set it through the hierarchy API.', doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },- Children: { category: 'core', summary: "The entity's children, maintained by the engine alongside `Parent`. Its order is the order children draw in.", doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },+ Children: { category: 'core', summary: "The entity's children, maintained by the engine alongside `Parent`. Its order is the order UI lays out and draws children in, and what hierarchy-order layers stack by.", doc: 'core-concepts/transforms', anchor: 'parenting--hierarchy', anchorZh: '父子层级' },Name: { category: 'core', summary: "The entity's display name — what the World Outliner shows and what name lookups resolve against.", doc: 'core-concepts/components', anchor: 'the-ones-the-engine-reads-about-your-entities', anchorZh: '引擎用来描述实体的那几个' },Velocity: { category: 'core', summary: 'Constant linear and angular motion applied every frame, with no physics body involved.', doc: 'scripting/overview', anchor: 'constant-motion-the-velocity-component', anchorZh: '匀速运动velocity-组件' },SceneOwner: { category: 'core', summary: 'Which additively-loaded scene owns the entity, and whether it survives that scene being unloaded.', doc: 'world/scenes', anchor: 'persistent-entities', anchorZh: '持久化实体' },