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: 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.mjsindex 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.mdxnew file mode 100644index 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 environmentdiff --git a/docs/astro/src/content/docs/guides/physics/colliders.mdx b/docs/astro/src/content/docs/guides/physics/colliders.mdxindex 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 colliderdiff --git a/docs/astro/src/content/docs/guides/physics/index.mdx b/docs/astro/src/content/docs/guides/physics/index.mdxindex 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.mdxindex 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 Codediff --git a/docs/astro/src/content/docs/guides/project-settings.mdx b/docs/astro/src/content/docs/guides/project-settings.mdxindex 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, phyOpen 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 SDKThe 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.mdxnew file mode 100644index 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 effectsdiff --git a/docs/astro/src/content/docs/guides/ui-interaction.mdx b/docs/astro/src/content/docs/guides/ui-interaction.mdxindex 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 PipelineUI 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.mdxindex 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxnew file mode 100644index 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.mdxindex 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.mdxindex 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 互斥: