Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: add v0.8.2 docs for ShapeRenderer, collision layers, contact solver, and UI updates

esengine4950ea8d2e1b
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index b6706cc8f..f32aff2fe 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -78,6 +78,7 @@ export default defineConfig({
{ label: 'Post-Processing', translations: { 'zh-CN': '后处理效果' }, slug: 'guides/post-processing' },
{ label: 'Render Texture', translations: { 'zh-CN': '渲染纹理' }, slug: 'guides/render-texture' },
{ label: 'Particles', translations: { 'zh-CN': '粒子系统' }, slug: 'guides/particles' },
+ { label: 'Shape Renderer', translations: { 'zh-CN': '形状渲染器' }, slug: 'guides/shape-renderer' },
],
},
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scenes' },
@@ -148,6 +149,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.8.2', slug: 'changelog-v082' },
{ label: 'v0.8.1', slug: 'changelog-v081' },
{ label: 'v0.8.0', slug: 'changelog-v080' },
{ label: 'v0.7.0', slug: 'changelog-v070' },
diff --git a/docs/astro/src/content/docs/changelog-v082.mdx b/docs/astro/src/content/docs/changelog-v082.mdx
new file mode 100644
index 000000000..f6be10a15
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v082.mdx
@@ -0,0 +1,88 @@
+---
+title: v0.8.2
+description: ESEngine v0.8.2 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.2 adds the ShapeRenderer component, collision layer system, new collider types, contact solver tuning, UI interaction improvements, and an enhanced settings dialog.
+</Aside>
+
+## ShapeRenderer Component
+
+New builtin component for drawing GPU-accelerated 2D shapes using signed distance fields. See the [Shape Renderer guide](/microes/guides/shape-renderer/) for details.
+
+- **Three shape types** — Circle, Capsule, and RoundedRect with configurable size, color, corner radius, and render layer
+- **SDF rendering** — antialiased edges at any scale via fragment shader distance functions
+- **Editor support** — shape type dropdown, color picker, and live preview in the Scene View
+
+## New Collider Types
+
+Three new collider shapes for the physics system, each with dedicated documentation:
+
+- [**SegmentCollider**](/microes/guides/physics/segment-collider/) — line segment for thin walls and one-way platforms
+- [**PolygonCollider**](/microes/guides/physics/polygon-collider/) — convex polygon with up to 8 vertices
+- [**ChainCollider**](/microes/guides/physics/chain-collider/) — chain of line segments for terrain and complex static boundaries
+
+All colliders support the full property set including density, friction, restitution, sensor mode, and collision layer assignment. Editor inspector schemas and debug draw are included.
+
+## Collision Layer System
+
+A 16-layer bitmask collision filtering system with editor integration. See [Colliders — Collision Filtering](/microes/guides/physics/colliders/#collision-filtering).
+
+- **Named layers** — define up to 16 collision layers (e.g., "Player", "Enemy", "Ground") in project settings
+- **Collision matrix** — visual matrix widget in Settings → Physics to configure which layers interact
+- **Inspector dropdown** — collider `categoryBits` displayed as a named layer selector instead of raw bitmask
+- **Project sync** — layer names and masks saved to project config and shared across team
+
+## Contact Solver Parameters
+
+Box2D contact solver parameters are now exposed in project settings:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Contact Hertz | `30` | Contact stiffness (cycles/sec) |
+| Contact Damping Ratio | `10` | Contact bounciness damping |
+| Contact Speed | `3` | Max overlap resolution speed (m/s) |
+
+## UI Interaction Improvements
+
+- **Default tinting** — buttons and toggles without explicit `ColorTransition` now apply automatic state-based tinting (hover 1.15x, pressed 0.75x, disabled 0.5x brightness)
+- **Toggle colors** — new `onColor` and `offColor` properties on Toggle for customizing colors without a full transition definition
+- **Drag UIRect support** — `Draggable` now works with anchored UI elements by adjusting layout offsets instead of Transform position
+- **Slider handle centering** — slider handles are now centered on the perpendicular axis regardless of track dimensions
+
+## Stats Overlay
+
+- System timings now display as **average / peak** over a 500ms window instead of per-frame values, providing stable readability without losing spike information
+
+## Enhanced Settings Dialog
+
+The project settings dialog has been redesigned:
+
+- **Search** — filter settings by name, description, or tag
+- **Collapsible groups** — related settings organized into collapsible sections
+- **Modified indicators** — dot markers on navigation items showing non-default values
+- **Reset per section** — restore all settings in a section to defaults
+- **New sections** — Rendering (sprite defaults, pixels per unit), Asset Loading (timeout, cooldown), and Network (HTTP proxy)
+- **Conditional visibility** — settings that only apply in certain modes (e.g., Canvas Match W/H) appear/hide automatically
+
+## Performance
+
+- **Material batching** — sprites sharing the same material are now batched together
+- **Shader loading** — shaders use embedded `.esshader` format instead of inline strings
+- **ECS optimization** — improved view iteration, sort, and render pipeline performance
+
+## Example Projects
+
+16 example projects now ship with the engine, covering core features: sprite, animation, physics, UI controls, audio, input, tilemap, particles, tween, post-processing, storage, custom draw, materials, and more. Browse them from the launcher's example panel.
+
+## Bug Fixes
+
+- Fix Image component disappearing after exiting play mode
+- Fix preview server serving stale project after switching projects
+- Fix audio URL resolution in editor play mode
+- Fix startup systems flush timing and animation in editor non-play mode
+- Fix anim-clip UUID mismatch and add first-frame preview in editor
+- Fix editor tests failing in jsdom environment
diff --git a/docs/astro/src/content/docs/guides/physics/colliders.mdx b/docs/astro/src/content/docs/guides/physics/colliders.mdx
index 3c3bd6cfc..1b2f93113 100644
--- a/docs/astro/src/content/docs/guides/physics/colliders.mdx
+++ b/docs/astro/src/content/docs/guides/physics/colliders.mdx
@@ -70,6 +70,30 @@ A capsule shape (rectangle with semicircle caps on top and bottom).
Plus all [common properties](#common-properties).
+## Collision Filtering
+
+Collision layers let you control which objects can collide with each other. The system uses 16 named layers with bitmask filtering.
+
+### How It Works
+
+Each collider has a `categoryBits` field that assigns it to a layer. The collision matrix in **Settings → Physics → Collision Matrix** determines which layers interact.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `categoryBits` | number | `1` | Layer this collider belongs to (bitmask, one bit per layer) |
+
+Collision occurs when both colliders' layers are allowed to interact in the collision matrix.
+
+### Editor Setup
+
+1. **Name your layers** in **Settings → Physics → Collision Layers** (up to 16 layers, e.g., "Player", "Enemy", "Ground", "Projectile")
+2. **Configure the matrix** in **Settings → Physics → Collision Matrix** — check which layer pairs should collide
+3. **Assign layers** in the Inspector — each collider's `categoryBits` dropdown shows the named layers
+
+<Aside type="note">
+Collision layers are configured entirely through the editor settings. The physics plugin reads the layer names and collision matrix from the project config automatically — no code setup is needed.
+</Aside>
+
## See Also
- [Segment Collider](./segment-collider/) — line segment collider
diff --git a/docs/astro/src/content/docs/guides/physics/index.mdx b/docs/astro/src/content/docs/guides/physics/index.mdx
index 618d7ff14..d3d5521f6 100644
--- a/docs/astro/src/content/docs/guides/physics/index.mdx
+++ b/docs/astro/src/content/docs/guides/physics/index.mdx
@@ -19,9 +19,9 @@ Configure the simulation parameters in the same panel:
| Gravity Y | `-9.81` | Vertical gravity (negative = downward) |
| Fixed Timestep | `1/60` | Physics step interval in seconds |
| Sub-Step Count | `4` | Sub-steps per physics step for accuracy |
-| Contact Hertz | `120` | Contact stiffness (cycles/sec). Higher = less overlap but more jitter |
-| Contact Damping Ratio | `10` | Contact bounciness damping. Lower = faster overlap recovery but more energetic |
-| Contact Speed | `10` | Max overlap resolution speed (m/s) |
+| Contact Hertz | `30` | Contact stiffness (cycles/sec). Higher = less overlap but more jitter. Range: 1–500 |
+| Contact Damping Ratio | `10` | Contact bounciness damping. Lower = faster overlap recovery but more energetic. Range: 0.1–100 |
+| Contact Speed | `3` | Max overlap resolution speed (m/s). Range: 1–100 |
<Aside type="note">
The physics WASM module is loaded automatically by the editor preview and build pipeline. No manual plugin initialization is needed in your game scripts.
diff --git a/docs/astro/src/content/docs/guides/profiler.mdx b/docs/astro/src/content/docs/guides/profiler.mdx
index 013a2227c..9aba2b87d 100644
--- a/docs/astro/src/content/docs/guides/profiler.mdx
+++ b/docs/astro/src/content/docs/guides/profiler.mdx
@@ -57,7 +57,8 @@ The overlay displays:
- **Entities** — total entity count
**Systems**
-- Top 5 slowest systems with execution time in milliseconds
+- Top 5 slowest systems with average and peak execution time in milliseconds (displayed as `avg / max ms`)
+- Stats are throttled to 500ms updates for stable readability without losing peak information
## Reading Stats in Code
diff --git a/docs/astro/src/content/docs/guides/project-settings.mdx b/docs/astro/src/content/docs/guides/project-settings.mdx
index e39847a6f..39da55248 100644
--- a/docs/astro/src/content/docs/guides/project-settings.mdx
+++ b/docs/astro/src/content/docs/guides/project-settings.mdx
@@ -11,6 +11,8 @@ Project settings provide centralized control over engine runtime parameters, phy
Open the settings dialog from the menu bar via **Edit → Settings...** or with the keyboard shortcut `Ctrl+,` (`Cmd+,` on macOS). The left sidebar lists all setting categories; click a category to switch the content area on the right.
+Use the **search bar** at the top to filter settings by name, description, or tag. Settings with non-default values show a **dot indicator** on the sidebar navigation. Each section provides a **Reset** button to restore all its settings to defaults.
+
## General
| Property | Type | Default | Description |
@@ -46,6 +48,18 @@ Open the settings dialog from the menu bar via **Edit → Settings...** or with
| Show Stats | boolean | `false` | Display frame rate and render statistics in the top-left corner of the scene view |
| Grid Size | number | `50` | Grid cell size in pixels. Range: 5–500 |
+### Gizmo Appearance
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| Gizmo Color X | color | red | X-axis gizmo color |
+| Gizmo Color Y | color | green | Y-axis gizmo color |
+| Gizmo Color XY | color | blue | XY-plane gizmo color |
+| Gizmo Hover Color | color | yellow | Gizmo hover highlight color |
+| Selection Color | color | blue | Selected entity outline color |
+| Handle Size | number | `10` | Transform handle size in pixels |
+| Gizmo Size | number | `100` | Transform gizmo length in pixels |
+
## Physics
| Property | Type | Default | Description |
@@ -55,6 +69,21 @@ Open the settings dialog from the menu bar via **Edit → Settings...** or with
| Gravity Y | number | `-9.81` | Vertical gravity component (negative = downward) |
| Fixed Timestep | number | `1/60` | Physics step interval in seconds. Minimum: 0.001 |
| Sub-Step Count | number | `4` | Number of sub-steps per physics step. Range: 1–16. Higher values improve accuracy at the cost of performance. |
+| Contact Hertz | number | `30` | Contact stiffness (cycles/sec). Higher = less overlap but more jitter. Range: 1–500 |
+| Contact Damping Ratio | number | `10` | Contact bounciness damping. Lower = faster overlap recovery but more energetic. Range: 0.1–100 |
+| Contact Speed | number | `3` | Max overlap resolution speed (m/s). Range: 1–100 |
+
+### Collision Layers
+
+Define up to 16 named collision layers (e.g., "Player", "Enemy", "Ground") and configure the collision matrix to control which layers interact. See [Colliders — Collision Filtering](/microes/guides/physics/colliders/#collision-filtering) for details.
+
+## Rendering
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| Default Sprite Width | number | `100` | Default width for new Sprite components |
+| Default Sprite Height | number | `100` | Default height for new Sprite components |
+| Pixels Per Unit | number | `100` | Pixel-to-physics-unit conversion ratio |
## Build
@@ -92,6 +121,19 @@ Runtime settings control engine behavior during actual gameplay and take effect
| **Shrink** | Uses the smaller of the width and height scale factors, ensuring the screen is completely filled |
| **Match** | Interpolates between the width and height scale factors, controlled by the Canvas Match W/H weight |
+## Asset Loading
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| Load Timeout | number | `30000` | Maximum time (ms) to wait for a single asset to load before marking it as failed |
+| Failure Cooldown | number | `5000` | Time (ms) before a failed asset can be retried |
+
+## Network
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| HTTP Proxy | string | empty | Proxy URL for editor HTTP requests (update downloads, etc.) |
+
## Using RuntimeConfig in the SDK
The editor's runtime settings are written into the project configuration at build time. In scripts you can read or override these values through the `RuntimeConfig` object:
diff --git a/docs/astro/src/content/docs/guides/shape-renderer.mdx b/docs/astro/src/content/docs/guides/shape-renderer.mdx
new file mode 100644
index 000000000..2b575d335
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/shape-renderer.mdx
@@ -0,0 +1,131 @@
+---
+title: Shape Renderer
+description: Draw circles, capsules, and rounded rectangles with the ShapeRenderer component
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The `ShapeRenderer` component draws GPU-accelerated 2D shapes using signed distance fields (SDF). It supports circles, capsules, and rounded rectangles with antialiased edges at any scale.
+
+## Usage
+
+Add `ShapeRenderer` to an entity alongside `Transform`:
+
+```typescript
+import { Commands, Transform, ShapeRenderer, ShapeType } from 'esengine';
+
+commands.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Circle,
+ size: { x: 80, y: 80 },
+ color: { r: 1, g: 0.5, b: 0, a: 1 },
+ });
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `shapeType` | number | `0` (Circle) | Shape to render (see [Shape Types](#shape-types)) |
+| `color` | Color | `{r:1, g:1, b:1, a:1}` | Fill color (RGBA, 0–1) |
+| `size` | Vec2 | `{x:100, y:100}` | Width and height in pixels |
+| `cornerRadius` | number | `0` | Corner rounding for `RoundedRect` |
+| `layer` | number | `0` | Render layer for depth sorting (-1000 to 1000) |
+| `enabled` | boolean | `true` | Visibility toggle |
+
+## Shape Types
+
+```typescript
+import { ShapeType } from 'esengine';
+```
+
+| Type | Value | Description |
+|------|-------|-------------|
+| `ShapeType.Circle` | `0` | Circle inscribed in `size` |
+| `ShapeType.Capsule` | `1` | Stadium shape — rectangle with hemispherical ends |
+| `ShapeType.RoundedRect` | `2` | Rectangle with rounded corners controlled by `cornerRadius` |
+
+### Circle
+
+Uses `size` as the bounding box. The circle radius is `min(size.x, size.y) / 2`.
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Circle,
+ size: { x: 60, y: 60 },
+ color: { r: 0, g: 0.8, b: 1, a: 1 },
+ });
+```
+
+### Capsule
+
+A rounded rectangle where the shorter axis determines the cap radius. The longer axis defines the overall length.
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 100, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Capsule,
+ size: { x: 30, y: 80 },
+ color: { r: 0, g: 1, b: 0.5, a: 1 },
+ });
+```
+
+### Rounded Rectangle
+
+A rectangle with rounded corners. The `cornerRadius` is clamped to half the shorter side.
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 200, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.RoundedRect,
+ size: { x: 120, y: 80 },
+ cornerRadius: 12,
+ color: { r: 1, g: 0.3, b: 0.6, a: 1 },
+ });
+```
+
+## Modifying at Runtime
+
+Query and modify `ShapeRenderer` like any other component:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, ShapeRenderer } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(ShapeRenderer))],
+ (query) => {
+ for (const [entity, shape] of query) {
+ shape.color = { r: 0, g: 1, b: 0, a: 0.5 };
+ shape.enabled = false;
+ }
+ }
+));
+```
+
+## Rendering Details
+
+- **SDF rendering** — shapes are rendered using signed distance field functions in a fragment shader, producing clean antialiased edges regardless of zoom level
+- **Transform integration** — respects position, rotation, and scale from the entity's `Transform`
+- **Layer sorting** — shapes are sorted by `layer`, then by depth (z-position), matching the same ordering as sprites
+- **Frustum culling** — shapes outside the camera view are automatically skipped
+
+<Aside type="tip">
+ShapeRenderer is useful for physics prototyping — add it to entities with colliders to visualize them without importing textures. The `physics-playground` example uses this approach.
+</Aside>
+
+## Editor Integration
+
+- **Hierarchy** — right-click → Add Component → ShapeRenderer
+- **Inspector** — dropdown for shape type, color picker, size vector, and corner radius input
+- **Scene View** — shapes render in both edit mode and play mode
+
+## Next Steps
+
+- [Sprite](/microes/guides/sprite/) — texture-based rendering
+- [Custom Draw](/microes/guides/custom-draw/) — low-level draw API
+- [Particles](/microes/guides/particles/) — particle effects
diff --git a/docs/astro/src/content/docs/guides/ui-interaction.mdx b/docs/astro/src/content/docs/guides/ui-interaction.mdx
index 019f64840..cd3a4ae45 100644
--- a/docs/astro/src/content/docs/guides/ui-interaction.mdx
+++ b/docs/astro/src/content/docs/guides/ui-interaction.mdx
@@ -116,6 +116,8 @@ Enables drag-to-move on a UI element.
| `constraintMin` | `{x, y}` \| null | `null` | Minimum position constraint |
| `constraintMax` | `{x, y}` \| null | `null` | Maximum position constraint |
+Draggable supports both Transform-based and UIRect-based (anchored) elements. When an entity has `UIRect`, dragging adjusts the layout offsets; otherwise it moves the Transform position directly.
+
When dragging is active, the engine adds a `DragState` component to the entity:
| Property | Type | Description |
@@ -127,6 +129,19 @@ When dragging is active, the engine adds a `DragState` component to the entity:
| `deltaWorld` | `{x, y}` | Movement this frame |
| `totalDeltaWorld` | `{x, y}` | Total movement since drag start |
+## Default Tinting
+
+When a `Button` or `Toggle` has no explicit `transition`, the UI system applies automatic state-based tinting to the entity's `Sprite` or `Image` color:
+
+| State | Effect |
+|-------|--------|
+| Normal | No change |
+| Hovered | 1.15x brightness |
+| Pressed | 0.75x brightness |
+| Disabled | 0.5x brightness, 0.6 alpha |
+
+This provides visual feedback without requiring explicit `ColorTransition` definitions.
+
## Processing Pipeline
UI interaction systems run in a fixed order each frame:
diff --git a/docs/astro/src/content/docs/guides/ui-widgets.mdx b/docs/astro/src/content/docs/guides/ui-widgets.mdx
index 68689f21f..ab714fac4 100644
--- a/docs/astro/src/content/docs/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/guides/ui-widgets.mdx
@@ -172,6 +172,8 @@ Checkbox with optional group for mutual exclusion.
| `graphicEntity` | Entity | `0` | Child entity to show/hide (checkmark) |
| `group` | Entity | `0` | ToggleGroup entity for radio-button behavior |
| `transition` | ColorTransition \| null | `null` | Color transition |
+| `onColor` | Color | `{r:0.2, g:0.6, b:1, a:1}` | Color when on (used if no transition) |
+| `offColor` | Color | `{r:0.4, g:0.4, b:0.4, a:1}` | Color when off (used if no transition) |
**ToggleGroup** — attach to a parent entity to make child toggles mutually exclusive:
diff --git a/docs/astro/src/content/docs/zh/changelog-v082.mdx b/docs/astro/src/content/docs/zh/changelog-v082.mdx
new file mode 100644
index 000000000..f4ee8a8d1
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v082.mdx
@@ -0,0 +1,88 @@
+---
+title: v0.8.2
+description: ESEngine v0.8.2 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.2 新增 ShapeRenderer 组件、碰撞层系统、新碰撞器类型、接触求解器调参、UI 交互改进和增强的设置对话框。
+</Aside>
+
+## ShapeRenderer 组件
+
+新增内置组件,使用 GPU 加速的有符号距离场绘制 2D 形状。详见 [形状渲染器指南](/microes/zh/guides/shape-renderer/)。
+
+- **三种形状类型** — 圆形、胶囊和圆角矩形,可配置尺寸、颜色、圆角半径和渲染层级
+- **SDF 渲染** — 通过片段着色器距离函数实现任意缩放下的抗锯齿边缘
+- **编辑器支持** — 形状类型下拉框、颜色拾取器和 Scene View 实时预览
+
+## 新碰撞器类型
+
+物理系统新增三种碰撞器形状,各有独立文档:
+
+- [**SegmentCollider**](/microes/zh/guides/physics/segment-collider/) — 线段碰撞器,适用于薄墙和单向平台
+- [**PolygonCollider**](/microes/zh/guides/physics/polygon-collider/) — 最多 8 个顶点的凸多边形碰撞器
+- [**ChainCollider**](/microes/zh/guides/physics/chain-collider/) — 线段链碰撞器,适用于地形和复杂静态边界
+
+所有碰撞器支持完整属性集,包括密度、摩擦力、弹性、传感器模式和碰撞层分配。编辑器 Inspector 和调试绘制均已支持。
+
+## 碰撞层系统
+
+16 层位掩码碰撞过滤系统,带编辑器集成。详见[碰撞体 — 碰撞过滤](/microes/zh/guides/physics/colliders/#碰撞过滤)。
+
+- **命名层** — 在项目设置中定义最多 16 个碰撞层(如 "Player"、"Enemy"、"Ground")
+- **碰撞矩阵** — Settings → Physics 中的可视化矩阵控件,配置哪些层之间可以交互
+- **Inspector 下拉框** — 碰撞体的 `categoryBits` 显示为命名层选择器,而非原始位掩码
+- **项目同步** — 层名称和掩码保存到项目配置中,团队共享
+
+## 接触求解器参数
+
+Box2D 接触求解器参数现已在项目设置中暴露:
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| Contact Hertz | `30` | 接触刚度(周期/秒) |
+| Contact Damping Ratio | `10` | 接触弹性阻尼 |
+| Contact Speed | `3` | 最大重叠修正速度(米/秒) |
+
+## UI 交互改进
+
+- **默认着色** — 没有显式 `ColorTransition` 的按钮和开关现在自动应用基于状态的着色(悬停 1.15 倍、按下 0.75 倍、禁用 0.5 倍亮度)
+- **开关颜色** — Toggle 新增 `onColor` 和 `offColor` 属性,无需完整 transition 定义即可自定义颜色
+- **拖拽 UIRect 支持** — `Draggable` 现在支持锚点布局的 UI 元素,通过调整布局偏移量而非 Transform 位置
+- **滑块手柄居中** — 滑块手柄现在在垂直于滑动方向的轴上自动居中
+
+## 统计叠加面板
+
+- 系统计时现在显示为 500ms 窗口内的**平均 / 峰值**,而非每帧值,在保持稳定可读性的同时不丢失尖峰信息
+
+## 增强的设置对话框
+
+项目设置对话框已重新设计:
+
+- **搜索** — 按名称、描述或标签筛选设置
+- **可折叠分组** — 相关设置组织为可折叠区域
+- **修改指示器** — 导航项上的圆点标记显示非默认值
+- **分区重置** — 将某个分区的所有设置恢复为默认值
+- **新分区** — Rendering(精灵默认值、像素单位比)、Asset Loading(超时、冷却)和 Network(HTTP 代理)
+- **条件可见性** — 仅在特定模式下适用的设置(如 Canvas Match W/H)自动显示/隐藏
+
+## 性能优化
+
+- **材质批处理** — 共享相同材质的精灵现在合并渲染
+- **着色器加载** — 着色器使用内嵌 `.esshader` 格式,替代内联字符串
+- **ECS 优化** — 改进视图迭代、排序和渲染管线性能
+
+## 示例项目
+
+引擎现在附带 16 个示例项目,覆盖核心功能:精灵、动画、物理、UI 控件、音频、输入、瓦片地图、粒子、补间、后处理、存储、自定义绘制、材质等。可在启动器的示例面板中浏览。
+
+## Bug 修复
+
+- 修复退出播放模式后 Image 组件消失的问题
+- 修复切换项目后预览服务器提供旧项目内容
+- 修复编辑器播放模式下音频 URL 解析
+- 修复启动系统刷新时机和编辑器非播放模式下的动画
+- 修复 anim-clip UUID 不匹配并在编辑器中添加首帧预览
+- 修复 jsdom 环境下编辑器测试失败
diff --git a/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx b/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx
index deb1b5bed..ddd86263b 100644
--- a/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx
+++ b/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx
@@ -70,6 +70,30 @@ import { Aside } from '@astrojs/starlight/components';
加上所有[通用属性](#通用属性)。
+## 碰撞过滤
+
+碰撞层让你控制哪些对象可以互相碰撞。系统使用 16 个命名层和位掩码过滤。
+
+### 工作原理
+
+每个碰撞体有一个 `categoryBits` 字段将其分配到一个层。**Settings → Physics → Collision Matrix** 中的碰撞矩阵决定哪些层之间可以交互。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `categoryBits` | number | `1` | 碰撞体所属层(位掩码,每层一个位) |
+
+当两个碰撞体的层在碰撞矩阵中被允许交互时,碰撞才会发生。
+
+### 编辑器设置
+
+1. 在 **Settings → Physics → Collision Layers** 中**命名层**(最多 16 层,如 "Player"、"Enemy"、"Ground"、"Projectile")
+2. 在 **Settings → Physics → Collision Matrix** 中**配置矩阵**——勾选需要碰撞的层对
+3. 在 Inspector 中**分配层**——每个碰撞体的 `categoryBits` 下拉菜单显示已命名的层
+
+<Aside type="note">
+碰撞层完全通过编辑器设置配置。物理插件会自动从项目配置中读取层名称和碰撞矩阵,无需编写代码。
+</Aside>
+
## 参见
- [线段碰撞器](./segment-collider/) — 线段碰撞体
diff --git a/docs/astro/src/content/docs/zh/guides/physics/index.mdx b/docs/astro/src/content/docs/zh/guides/physics/index.mdx
index 1bf482cf0..359bfda5e 100644
--- a/docs/astro/src/content/docs/zh/guides/physics/index.mdx
+++ b/docs/astro/src/content/docs/zh/guides/physics/index.mdx
@@ -19,9 +19,9 @@ import { Aside } from '@astrojs/starlight/components';
| Gravity Y | `-9.81` | 垂直重力(负数 = 向下) |
| Fixed Timestep | `1/60` | 物理步进间隔(秒) |
| Sub-Step Count | `4` | 每次物理步进的子步数,用于提高精度 |
-| Contact Hertz | `120` | 接触刚度(周期/秒)。越高穿透越少但抖动越明显 |
-| Contact Damping Ratio | `10` | 接触弹性阻尼。越低重叠恢复越快但弹性越强 |
-| Contact Speed | `10` | 最大重叠修正速度(米/秒) |
+| Contact Hertz | `30` | 接触刚度(周期/秒)。越高穿透越少但抖动越明显。范围:1–500 |
+| Contact Damping Ratio | `10` | 接触弹性阻尼。越低重叠恢复越快但弹性越强。范围:0.1–100 |
+| Contact Speed | `3` | 最大重叠修正速度(米/秒)。范围:1–100 |
<Aside type="note">
物理 WASM 模块由编辑器预览和构建流程自动加载,无需在游戏脚本中手动初始化插件。
diff --git a/docs/astro/src/content/docs/zh/guides/profiler.mdx b/docs/astro/src/content/docs/zh/guides/profiler.mdx
index 2f1662552..32f3fd16c 100644
--- a/docs/astro/src/content/docs/zh/guides/profiler.mdx
+++ b/docs/astro/src/content/docs/zh/guides/profiler.mdx
@@ -57,7 +57,8 @@ new StatsPlugin({
- **实体** — 总实体数量
**系统**
-- 前 5 个最慢系统及其执行时间(毫秒)
+- 前 5 个最慢系统的平均和峰值执行时间(显示为 `avg / max ms`)
+- 统计数据每 500ms 更新一次,既保持稳定可读性又不丢失峰值信息
## 在代码中读取统计数据
diff --git a/docs/astro/src/content/docs/zh/guides/project-settings.mdx b/docs/astro/src/content/docs/zh/guides/project-settings.mdx
index 1739f19b4..644c3ad4f 100644
--- a/docs/astro/src/content/docs/zh/guides/project-settings.mdx
+++ b/docs/astro/src/content/docs/zh/guides/project-settings.mdx
@@ -11,6 +11,8 @@ import { Aside } from '@astrojs/starlight/components';
通过菜单栏 **Edit → Settings...** 或快捷键 `Ctrl+,`(macOS 为 `Cmd+,`)打开设置对话框。左侧导航栏列出所有设置分类,点击分类切换右侧内容区域。
+使用顶部的**搜索栏**按名称、描述或标签筛选设置。有非默认值的设置会在导航栏显示**圆点标记**。每个分类提供**重置**按钮,可将所有设置恢复为默认值。
+
## General
| 属性 | 类型 | 默认值 | 说明 |
@@ -46,6 +48,18 @@ import { Aside } from '@astrojs/starlight/components';
| Show Stats | boolean | `false` | 在场景视图左上角显示帧率和渲染统计 |
| Grid Size | number | `50` | 网格单元大小(像素),范围 5–500 |
+### Gizmo 外观
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| Gizmo Color X | color | 红色 | X 轴 Gizmo 颜色 |
+| Gizmo Color Y | color | 绿色 | Y 轴 Gizmo 颜色 |
+| Gizmo Color XY | color | 蓝色 | XY 平面 Gizmo 颜色 |
+| Gizmo Hover Color | color | 黄色 | Gizmo 悬停高亮颜色 |
+| Selection Color | color | 蓝色 | 选中实体轮廓颜色 |
+| Handle Size | number | `10` | 变换手柄大小(像素) |
+| Gizmo Size | number | `100` | 变换 Gizmo 长度(像素) |
+
## Physics
| 属性 | 类型 | 默认值 | 说明 |
@@ -55,6 +69,21 @@ import { Aside } from '@astrojs/starlight/components';
| Gravity Y | number | `-9.81` | 垂直重力分量(负数 = 向下) |
| Fixed Timestep | number | `1/60` | 物理步进间隔(秒),最小值 0.001 |
| Sub-Step Count | number | `4` | 每次物理步进的子步数,范围 1–16。值越大精度越高,性能开销越大。 |
+| Contact Hertz | number | `30` | 接触刚度(周期/秒)。越高穿透越少但抖动越明显。范围:1–500 |
+| Contact Damping Ratio | number | `10` | 接触弹性阻尼。越低重叠恢复越快但弹性越强。范围:0.1–100 |
+| Contact Speed | number | `3` | 最大重叠修正速度(米/秒)。范围:1–100 |
+
+### 碰撞层
+
+可定义最多 16 个命名碰撞层(如 "Player"、"Enemy"、"Ground"),通过碰撞矩阵控制哪些层之间可以交互。详见[碰撞体 — 碰撞过滤](/microes/zh/guides/physics/colliders/#碰撞过滤)。
+
+## Rendering
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| Default Sprite Width | number | `100` | 新建 Sprite 组件的默认宽度 |
+| Default Sprite Height | number | `100` | 新建 Sprite 组件的默认高度 |
+| Pixels Per Unit | number | `100` | 像素到物理单位的换算比例 |
## Build
@@ -92,6 +121,19 @@ import { Aside } from '@astrojs/starlight/components';
| **Shrink** | 取宽度和高度中较小的缩放比,确保屏幕被完全填充 |
| **Match** | 在宽度和高度的缩放比之间插值,由 Canvas Match W/H 控制混合权重 |
+## Asset Loading
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| Load Timeout | number | `30000` | 单个资源加载超时时间(毫秒) |
+| Failure Cooldown | number | `5000` | 加载失败后允许重试的冷却时间(毫秒) |
+
+## Network
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| HTTP Proxy | string | 空 | 编辑器 HTTP 请求使用的代理地址(用于更新下载等) |
+
## SDK 中使用 RuntimeConfig
编辑器中的运行时设置会在构建时写入项目配置。在脚本中,可以通过 `RuntimeConfig` 对象直接读取或覆盖这些值:
diff --git a/docs/astro/src/content/docs/zh/guides/shape-renderer.mdx b/docs/astro/src/content/docs/zh/guides/shape-renderer.mdx
new file mode 100644
index 000000000..1f659060e
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/shape-renderer.mdx
@@ -0,0 +1,131 @@
+---
+title: 形状渲染器
+description: 使用 ShapeRenderer 组件绘制圆形、胶囊和圆角矩形
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+`ShapeRenderer` 组件使用 GPU 加速的有符号距离场(SDF)绘制 2D 形状。支持圆形、胶囊和圆角矩形,在任意缩放下都能保持抗锯齿边缘。
+
+## 使用方法
+
+将 `ShapeRenderer` 与 `Transform` 一起添加到实体上:
+
+```typescript
+import { Commands, Transform, ShapeRenderer, ShapeType } from 'esengine';
+
+commands.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Circle,
+ size: { x: 80, y: 80 },
+ color: { r: 1, g: 0.5, b: 0, a: 1 },
+ });
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `shapeType` | number | `0` (Circle) | 要渲染的形状(见[形状类型](#形状类型)) |
+| `color` | Color | `{r:1, g:1, b:1, a:1}` | 填充颜色(RGBA,0–1) |
+| `size` | Vec2 | `{x:100, y:100}` | 宽度和高度(像素) |
+| `cornerRadius` | number | `0` | `RoundedRect` 的圆角半径 |
+| `layer` | number | `0` | 渲染层级排序(-1000 到 1000) |
+| `enabled` | boolean | `true` | 可见性开关 |
+
+## 形状类型
+
+```typescript
+import { ShapeType } from 'esengine';
+```
+
+| 类型 | 值 | 说明 |
+|------|---|------|
+| `ShapeType.Circle` | `0` | 内切于 `size` 的圆形 |
+| `ShapeType.Capsule` | `1` | 跑道形——矩形两端为半圆 |
+| `ShapeType.RoundedRect` | `2` | 圆角矩形,由 `cornerRadius` 控制圆角大小 |
+
+### 圆形
+
+以 `size` 为边界框,圆的半径为 `min(size.x, size.y) / 2`。
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Circle,
+ size: { x: 60, y: 60 },
+ color: { r: 0, g: 0.8, b: 1, a: 1 },
+ });
+```
+
+### 胶囊
+
+短轴决定端部半径,长轴决定整体长度。
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 100, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.Capsule,
+ size: { x: 30, y: 80 },
+ color: { r: 0, g: 1, b: 0.5, a: 1 },
+ });
+```
+
+### 圆角矩形
+
+带圆角的矩形。`cornerRadius` 会被限制在短边的一半以内。
+
+```typescript
+commands.spawn()
+ .insert(Transform, { position: { x: 200, y: 0, z: 0 } })
+ .insert(ShapeRenderer, {
+ shapeType: ShapeType.RoundedRect,
+ size: { x: 120, y: 80 },
+ cornerRadius: 12,
+ color: { r: 1, g: 0.3, b: 0.6, a: 1 },
+ });
+```
+
+## 运行时修改
+
+像其他组件一样查询和修改 `ShapeRenderer`:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, ShapeRenderer } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(ShapeRenderer))],
+ (query) => {
+ for (const [entity, shape] of query) {
+ shape.color = { r: 0, g: 1, b: 0, a: 0.5 };
+ shape.enabled = false;
+ }
+ }
+));
+```
+
+## 渲染细节
+
+- **SDF 渲染** — 在片段着色器中使用有符号距离场函数渲染形状,无论缩放级别如何都能产生干净的抗锯齿边缘
+- **Transform 集成** — 响应实体 `Transform` 的位置、旋转和缩放
+- **层级排序** — 按 `layer` 排序,然后按深度(z 坐标)排序,与精灵相同
+- **视锥裁剪** — 摄像机视野外的形状自动跳过渲染
+
+<Aside type="tip">
+ShapeRenderer 适用于物理原型开发——将其添加到带碰撞体的实体上可以快速可视化,无需导入贴图。`physics-playground` 示例使用了这种方式。
+</Aside>
+
+## 编辑器集成
+
+- **Hierarchy** — 右键 → Add Component → ShapeRenderer
+- **Inspector** — 形状类型下拉框、颜色拾取器、尺寸矢量和圆角半径输入
+- **Scene View** — 编辑模式和播放模式下均可渲染
+
+## 下一步
+
+- [精灵](/microes/zh/guides/sprite/) — 基于纹理的渲染
+- [自定义绘制](/microes/zh/guides/custom-draw/) — 底层绘制 API
+- [粒子系统](/microes/zh/guides/particles/) — 粒子效果
diff --git a/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx b/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
index 4ec2b4fdf..005b6750d 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-interaction.mdx
@@ -116,6 +116,8 @@ const all = events.drain();
| `constraintMin` | `{x, y}` \| null | `null` | 拖拽范围最小值(世界坐标) |
| `constraintMax` | `{x, y}` \| null | `null` | 拖拽范围最大值(世界坐标) |
+Draggable 同时支持基于 Transform 和基于 UIRect(锚点布局)的元素。当实体拥有 `UIRect` 时,拖拽会调整布局偏移量;否则直接移动 Transform 位置。
+
拖拽激活时,引擎会自动为实体添加 `DragState` 组件:
| 属性 | 类型 | 说明 |
@@ -127,6 +129,19 @@ const all = events.drain();
| `totalDeltaWorld` | `{x, y}` | 从拖拽开始的总移动量 |
| `pointerStartWorld` | `{x, y}` | 拖拽开始时的指针世界位置 |
+## 默认着色
+
+当 `Button` 或 `Toggle` 没有显式 `transition` 时,UI 系统会自动为实体的 `Sprite` 或 `Image` 颜色应用基于状态的着色:
+
+| 状态 | 效果 |
+|------|------|
+| 正常 | 无变化 |
+| 悬停 | 1.15 倍亮度 |
+| 按下 | 0.75 倍亮度 |
+| 禁用 | 0.5 倍亮度,0.6 透明度 |
+
+无需显式定义 `ColorTransition` 即可获得视觉反馈。
+
## 处理管线
UI 交互系统每帧按固定顺序执行:
diff --git a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
index c7fc1af96..5a7c1e769 100644
--- a/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
+++ b/docs/astro/src/content/docs/zh/guides/ui-widgets.mdx
@@ -172,6 +172,8 @@ cmds.entity(button).insert(Button, {
| `graphicEntity` | Entity | `0` | 显示/隐藏的子实体(勾选标记) |
| `group` | Entity | `0` | ToggleGroup 实体,实现单选按钮行为 |
| `transition` | ColorTransition \| null | `null` | 颜色过渡 |
+| `onColor` | Color | `{r:0.2, g:0.6, b:1, a:1}` | 开启时的颜色(无 transition 时使用) |
+| `offColor` | Color | `{r:0.4, g:0.4, b:0.4, a:1}` | 关闭时的颜色(无 transition 时使用) |
**ToggleGroup** — 挂载到父实体使子级 Toggle 互斥: