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: split physics guide into per-topic pages
esengined3836e7aab25
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex ad9b49311..b6706cc8f 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -94,7 +94,21 @@ export default defineConfig({{ label: 'Masking & SafeArea', translations: { 'zh-CN': '遮罩与安全区' }, slug: 'guides/ui-masking' },],},- { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },+ {+ label: 'Physics',+ translations: { 'zh-CN': '物理' },+ items: [+ { label: 'Overview', translations: { 'zh-CN': '概述' }, slug: 'guides/physics' },+ { label: 'RigidBody', translations: { 'zh-CN': '刚体' }, slug: 'guides/physics/rigidbody' },+ { label: 'Colliders', translations: { 'zh-CN': '碰撞器' }, slug: 'guides/physics/colliders' },+ { label: 'Segment Collider', translations: { 'zh-CN': '线段碰撞器' }, slug: 'guides/physics/segment-collider' },+ { label: 'Polygon Collider', translations: { 'zh-CN': '多边形碰撞器' }, slug: 'guides/physics/polygon-collider' },+ { label: 'Chain Collider', translations: { 'zh-CN': '链条碰撞器' }, slug: 'guides/physics/chain-collider' },+ { label: 'Events', translations: { 'zh-CN': '碰撞事件' }, slug: 'guides/physics/events' },+ { label: 'API', translations: { 'zh-CN': '物理 API' }, slug: 'guides/physics/api' },+ { label: 'Debug Draw', translations: { 'zh-CN': '调试绘制' }, slug: 'guides/physics/debug-draw' },+ ],+ },{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },{ label: 'Tilemap', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },{diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdxdeleted file mode 100644index 3cac7f2bf..000000000--- a/docs/astro/src/content/docs/guides/physics.mdx+++ /dev/null@@ -1,244 +0,0 @@-----title: Physics-description: 2D physics simulation with Box2D in ESEngine------import { Aside } from '@astrojs/starlight/components';--The physics system provides 2D rigid body simulation powered by a standalone Box2D WASM module. The editor and build pipeline handle loading automatically — you only need to enable it in settings and add components to entities.--## Setup--Enable physics in the editor: **Settings → Physics → Enable Physics**.--Configure the simulation parameters in the same panel:--| Setting | Default | Description |-|---------|---------|-------------|-| Gravity X | `0` | Horizontal gravity |-| 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) |--<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.-</Aside>--### Coordinate Conversion (PPU)--Collider dimensions (`halfExtents`, `radius`, `halfHeight`) are specified in **physics units (meters)**. The Canvas component's `pixelsPerUnit` (default `100`) determines the conversion ratio between pixel coordinates and physics coordinates.--Position conversion is handled automatically — entity positions (in pixels) are divided by PPU when sent to Box2D, and multiplied by PPU when read back. Physics API values (`force`, `velocity`, `impulse`, `gravity`) also operate in physics units. You do not need to perform any manual conversion.--## Components--Add physics components to entities in the scene editor alongside `Transform`.--### RigidBody--Every physics entity needs a `RigidBody` component. It defines the body type and physical properties.--| Property | Type | Default | Description |-|----------|------|---------|-------------|-| `bodyType` | number | `2` (Dynamic) | 0=Static, 1=Kinematic, 2=Dynamic |-| `gravityScale` | number | `1.0` | Gravity multiplier |-| `linearDamping` | number | `0.0` | Linear velocity damping |-| `angularDamping` | number | `0.0` | Angular velocity damping |-| `fixedRotation` | boolean | `false` | Lock rotation |-| `bullet` | boolean | `false` | CCD for fast objects |-| `enabled` | boolean | `true` | Enable physics body |--### Colliders--Each entity also needs a collider shape. Choose one:--- **BoxCollider** — `halfExtents` (Vec2), `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`-- **CircleCollider** — `radius`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`-- **CapsuleCollider** — `radius`, `halfHeight`, `offset` (Vec2), `density`, `friction`, `restitution`, `isSensor`, `enabled`--See [Components](/microes/core-concepts/components/#physics) for the full property tables.--## Body Types--### Static (0)--Does not move. Used for walls, floors, and platforms.--```typescript-rigidBody.bodyType = 0;-```--### Kinematic (1)--Moved by code (transform), not by physics forces. Other bodies collide with it but don't push it. Used for moving platforms and elevators.--```typescript-rigidBody.bodyType = 1;-```--### Dynamic (2)--Fully simulated. Responds to gravity, forces, and collisions. Used for players, projectiles, and physics objects.--```typescript-rigidBody.bodyType = 2;-```--## Collision Events--Read collision and sensor events from the `PhysicsEvents` resource:--```typescript-import { defineSystem, addSystem, Res } from 'esengine';-import { PhysicsEvents } from 'esengine/physics';--addSystem(defineSystem(- [Res(PhysicsEvents)],- (events) => {- for (const e of events.collisionEnters) {- // e.entityA, e.entityB, e.normalX, e.normalY, e.contactX, e.contactY- }- for (const e of events.collisionExits) {- // e.entityA, e.entityB- }- for (const e of events.sensorEnters) {- // e.sensorEntity, e.visitorEntity- }- for (const e of events.sensorExits) {- // e.sensorEntity, e.visitorEntity- }- }-));-```--<Aside type="tip">- Set `isSensor = true` on a collider to create a trigger zone that detects overlaps without physical response.-</Aside>--## Example: Simple Platformer--Set up a ground, player, and coin sensor in the editor, then handle events in code:--```typescript-import { defineSystem, addSystem, Res, Input, Query, Mut, Transform } from 'esengine';-import { RigidBody, PhysicsEvents } from 'esengine/physics';-import { Player, Coin } from './components';--addSystem(defineSystem(- [Res(PhysicsEvents)],- (events) => {- for (const e of events.sensorEnters) {- // Coin collected- }- }-));-```--**Editor setup:**-- **Ground**: `Transform` + `RigidBody` (bodyType=0 Static) + `BoxCollider` (halfExtents=`{x:10, y:0.5}`) + `Sprite`-- **Player**: `Transform` + `RigidBody` (bodyType=2 Dynamic, fixedRotation=true) + `BoxCollider` + `Sprite` + `Player` tag-- **Coin**: `Transform` + `RigidBody` (bodyType=0 Static) + `CircleCollider` (isSensor=true) + `Sprite` + `Coin` tag--## Physics API (Advanced)--The `Physics` class provides runtime force/velocity control. It is automatically registered as a `PhysicsAPI` resource when the physics plugin loads, so you can access it from any system via `Res(PhysicsAPI)`:--```typescript-import { defineSystem, addSystem, Res } from 'esengine';-import { PhysicsAPI } from 'esengine/physics';--addSystem(defineSystem(- [Res(PhysicsAPI)],- (physics) => {- physics.applyForce(entity, { x: 0, y: 10 });- }-));-```--| Method | Description |-|--------|-------------|-| `applyForce(entity, force)` | Apply a continuous force (Vec2) |-| `applyImpulse(entity, impulse)` | Apply an instant impulse (Vec2) |-| `setLinearVelocity(entity, velocity)` | Set linear velocity directly |-| `getLinearVelocity(entity)` | Get current linear velocity (Vec2) |-| `setAngularVelocity(entity, omega)` | Set angular velocity (number) |-| `getAngularVelocity(entity)` | Get current angular velocity |-| `applyTorque(entity, torque)` | Apply rotational torque |-| `applyAngularImpulse(entity, impulse)` | Apply instant angular impulse |-| `setGravity(gravity)` | Change world gravity at runtime |-| `getGravity()` | Get current world gravity (Vec2) |--## Debug Draw--The physics debug draw overlay renders wireframe outlines for all colliders, velocity arrows, and contact points. It uses the engine's `Draw` API and works in both the editor and at runtime.--### Enabling Debug Draw--```typescript-import { Physics } from 'esengine/physics';--// Toggle debug draw on/off-Physics.setDebugDraw(app, true);-```--### Configuration--Control which elements are visualized:--```typescript-import { Physics } from 'esengine/physics';--Physics.setDebugDrawConfig(app, {- enabled: true,- showColliders: true, // wireframe collider outlines- showVelocity: true, // velocity arrows on dynamic bodies- showContacts: false, // contact point markers-});-```--| Property | Type | Default | Description |-|----------|------|---------|-------------|-| `enabled` | boolean | `false` | Master toggle for debug drawing |-| `showColliders` | boolean | `true` | Draw collider wireframes |-| `showVelocity` | boolean | `false` | Draw velocity arrows on dynamic bodies |-| `showContacts` | boolean | `false` | Draw contact points on collision enter |--### Color Coding--Collider outlines are color-coded by body type:--| Body Type | Color |-|-----------|-------|-| Static | Blue |-| Dynamic | Green |-| Kinematic | Cyan |-| Sensor | Yellow (semi-transparent) |--Velocity arrows are drawn in red. Contact points are shown as red dots.--<Aside type="tip">- Debug draw is registered as a custom draw callback named `'physics-debug-draw'`. It is automatically set up when the physics plugin initializes — you only need to enable it.-</Aside>--### PhysicsDebugDraw Resource--For advanced control, access the `PhysicsDebugDraw` resource directly:--```typescript-import { PhysicsDebugDraw } from 'esengine/physics';--const config = app.getResource(PhysicsDebugDraw);-config.enabled = true;-config.showVelocity = true;-app.insertResource(PhysicsDebugDraw, config);-```--## Next Steps--- [Components](/microes/core-concepts/components/#physics) — full physics component property tables-- [Systems](/microes/core-concepts/systems/) — creating systems to handle physics logic-- [Custom Draw](/microes/guides/custom-draw/) — debug visualization of colliders-- [Tilemap](/microes/guides/tilemap/) — tile-based collision generationdiff --git a/docs/astro/src/content/docs/guides/physics/api.mdx b/docs/astro/src/content/docs/guides/physics/api.mdxnew file mode 100644index 000000000..c575bb560--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/api.mdx@@ -0,0 +1,46 @@+---+title: Physics API+description: Runtime force, velocity, and gravity control+---++The `Physics` class provides runtime force/velocity control. It is automatically registered as a `PhysicsAPI` resource when the physics plugin loads, so you can access it from any system via `Res(PhysicsAPI)`.++## Accessing the API++```typescript+import { defineSystem, addSystem, Res } from 'esengine';+import { PhysicsAPI } from 'esengine/physics';++addSystem(defineSystem(+ [Res(PhysicsAPI)],+ (physics) => {+ physics.applyForce(entity, { x: 0, y: 10 });+ }+));+```++## Methods++| Method | Description |+|--------|-------------|+| `applyForce(entity, force)` | Apply a continuous force (Vec2) |+| `applyImpulse(entity, impulse)` | Apply an instant impulse (Vec2) |+| `setLinearVelocity(entity, velocity)` | Set linear velocity directly |+| `getLinearVelocity(entity)` | Get current linear velocity (Vec2) |+| `setAngularVelocity(entity, omega)` | Set angular velocity (number) |+| `getAngularVelocity(entity)` | Get current angular velocity |+| `applyTorque(entity, torque)` | Apply rotational torque |+| `applyAngularImpulse(entity, impulse)` | Apply instant angular impulse |+| `setGravity(gravity)` | Change world gravity at runtime |+| `getGravity()` | Get current world gravity (Vec2) |++## Force vs Impulse++- **Force** is applied continuously each frame. The effect depends on the body's mass and is integrated over the physics timestep. Use for sustained push (e.g., rocket thrust, wind).+- **Impulse** is applied instantly. It directly changes velocity, independent of frame rate. Use for one-time events (e.g., jump, explosion knockback).++## See Also++- [Physics Overview](./index.mdx) — setup, PPU, and body types+- [RigidBody](./rigidbody/) — body properties+- [Events](./events/) — collision and sensor eventsdiff --git a/docs/astro/src/content/docs/guides/physics/chain-collider.mdx b/docs/astro/src/content/docs/guides/physics/chain-collider.mdxnew file mode 100644index 000000000..354022bf8--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/chain-collider.mdx@@ -0,0 +1,83 @@+---+title: Chain Collider+description: Chain of line segments for terrain and static boundaries+---++import { Aside } from '@astrojs/starlight/components';++The `ChainCollider` defines a chain of connected line segments. It is designed for static terrain surfaces and complex boundaries that would be impractical to build from individual box or segment colliders.++<Aside type="caution">+ Chain colliders can only be used with **static bodies** (bodyType=0). They do not support density or sensor mode.+</Aside>++## Properties++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `points` | Vec2[] | `[]` | Chain vertices in physics units (local space) |+| `isLoop` | boolean | `false` | Connect the last point back to the first, forming a closed loop |+| `friction` | number | `0.6` | Surface friction |+| `restitution` | number | `0.0` | Bounciness |+| `categoryBits` | number | `1` | Collision filter category bits |++## Point Editing in Scene View++When an entity with a `ChainCollider` is selected in the editor, point handles appear in the Scene View:++- **Drag a handle** to move a point+- **Double-click on a segment** to insert a new point+- **Right-click a handle** to remove a point++## isLoop++When `isLoop` is `false`, the chain is an open path — objects can pass around the endpoints. When `isLoop` is `true`, the last point connects back to the first point, forming a closed boundary.++**Open chain** — useful for terrain surfaces:++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ ChainCollider.with({+ points: [+ { x: -10, y: 0 },+ { x: -5, y: 2 },+ { x: 0, y: 0 },+ { x: 5, y: 1 },+ { x: 10, y: 0 },+ ],+ isLoop: false,+ }),+);+```++**Closed loop** — useful for enclosed areas:++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ ChainCollider.with({+ points: [+ { x: -5, y: -5 },+ { x: 5, y: -5 },+ { x: 5, y: 5 },+ { x: -5, y: 5 },+ ],+ isLoop: true,+ }),+);+```++## Tips++- Chain colliders have no volume, so they only collide on one side. Place points in counter-clockwise order for outward-facing normals.+- Unlike [PolygonCollider](./polygon-collider/), chain colliders have no vertex limit — use as many points as needed to define your terrain.+- For dynamic collision shapes, use [PolygonCollider](./polygon-collider/) or the basic collider types instead.++## See Also++- [Colliders Overview](./colliders/) — all collider types+- [Segment Collider](./segment-collider/) — single line segment+- [Polygon Collider](./polygon-collider/) — convex polygon shapesdiff --git a/docs/astro/src/content/docs/guides/physics/colliders.mdx b/docs/astro/src/content/docs/guides/physics/colliders.mdxnew file mode 100644index 000000000..3c3bd6cfc--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/colliders.mdx@@ -0,0 +1,78 @@+---+title: Colliders+description: Overview of collider shapes for physics entities+---++import { Aside } from '@astrojs/starlight/components';++Each physics entity needs at least one collider shape alongside its [RigidBody](./rigidbody/). The collider defines the physical shape used for collision detection.++## Collider Types++| Collider | Shape | Use Case |+|----------|-------|----------|+| [BoxCollider](#boxcollider) | Axis-aligned rectangle | Crates, platforms, walls |+| [CircleCollider](#circlecollider) | Circle | Balls, coins, rounded objects |+| [CapsuleCollider](#capsulecollider) | Capsule (rectangle with rounded ends) | Characters, pills |+| [SegmentCollider](./segment-collider/) | Line segment | Thin walls, one-way platforms |+| [PolygonCollider](./polygon-collider/) | Convex polygon (up to 8 vertices) | Custom convex shapes |+| [ChainCollider](./chain-collider/) | Chain of line segments | Terrain, complex static boundaries |++## Common Properties++All colliders (except ChainCollider) share these properties:++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `density` | number | `1.0` | Mass density. Affects total body mass |+| `friction` | number | `0.6` | Surface friction (0 = ice, 1 = rubber) |+| `restitution` | number | `0.0` | Bounciness (0 = no bounce, 1 = full bounce) |+| `isSensor` | boolean | `false` | Trigger zone — detects overlap without physical response |+| `categoryBits` | number | `1` | Collision filter category bits |+| `enabled` | boolean | `true` | Enable/disable the collider |++<Aside type="tip">+ Set `isSensor = true` to create a trigger zone that fires [sensor events](./events/) without blocking movement.+</Aside>++## BoxCollider++An axis-aligned rectangular collider.++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `halfExtents` | Vec2 | `{x: 0.5, y: 0.5}` | Half-width and half-height in physics units |+| `offset` | Vec2 | `{x: 0, y: 0}` | Offset from entity center in physics units |+| `radius` | number | `0.0` | Corner rounding radius. Creates a rounded rectangle when > 0 |++Plus all [common properties](#common-properties).++## CircleCollider++A circular collider.++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `radius` | number | `0.5` | Circle radius in physics units |+| `offset` | Vec2 | `{x: 0, y: 0}` | Offset from entity center in physics units |++Plus all [common properties](#common-properties).++## CapsuleCollider++A capsule shape (rectangle with semicircle caps on top and bottom).++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `radius` | number | `0.5` | Capsule radius in physics units |+| `halfHeight` | number | `0.5` | Half-height of the rectangular center section in physics units |+| `offset` | Vec2 | `{x: 0, y: 0}` | Offset from entity center in physics units |++Plus all [common properties](#common-properties).++## See Also++- [Segment Collider](./segment-collider/) — line segment collider+- [Polygon Collider](./polygon-collider/) — custom convex polygon collider+- [Chain Collider](./chain-collider/) — chain of line segments for terrain+- [Events](./events/) — collision and sensor eventsdiff --git a/docs/astro/src/content/docs/guides/physics/debug-draw.mdx b/docs/astro/src/content/docs/guides/physics/debug-draw.mdxnew file mode 100644index 000000000..b388ea3cb--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/debug-draw.mdx@@ -0,0 +1,75 @@+---+title: Debug Draw+description: Physics debug visualization for colliders, velocity, and contacts+---++import { Aside } from '@astrojs/starlight/components';++The physics debug draw overlay renders wireframe outlines for all colliders, velocity arrows, and contact points. It uses the engine's `Draw` API and works in both the editor and at runtime.++## Enabling Debug Draw++```typescript+import { Physics } from 'esengine/physics';++// Toggle debug draw on/off+Physics.setDebugDraw(app, true);+```++## Configuration++Control which elements are visualized:++```typescript+import { Physics } from 'esengine/physics';++Physics.setDebugDrawConfig(app, {+ enabled: true,+ showColliders: true, // wireframe collider outlines+ showVelocity: true, // velocity arrows on dynamic bodies+ showContacts: false, // contact point markers+});+```++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `enabled` | boolean | `false` | Master toggle for debug drawing |+| `showColliders` | boolean | `true` | Draw collider wireframes |+| `showVelocity` | boolean | `false` | Draw velocity arrows on dynamic bodies |+| `showContacts` | boolean | `false` | Draw contact points on collision enter |++## Color Coding++Collider outlines are color-coded by body type:++| Body Type | Color |+|-----------|-------|+| Static | Blue |+| Dynamic | Green |+| Kinematic | Cyan |+| Sensor | Yellow (semi-transparent) |++Velocity arrows are drawn in red. Contact points are shown as red dots.++<Aside type="tip">+ Debug draw is registered as a custom draw callback named `'physics-debug-draw'`. It is automatically set up when the physics plugin initializes — you only need to enable it.+</Aside>++## PhysicsDebugDraw Resource++For advanced control, access the `PhysicsDebugDraw` resource directly:++```typescript+import { PhysicsDebugDraw } from 'esengine/physics';++const config = app.getResource(PhysicsDebugDraw);+config.enabled = true;+config.showVelocity = true;+app.insertResource(PhysicsDebugDraw, config);+```++## See Also++- [Physics Overview](./index.mdx) — setup and configuration+- [Colliders](./colliders/) — collider shapes+- [Custom Draw](/microes/guides/custom-draw/) — engine draw APIdiff --git a/docs/astro/src/content/docs/guides/physics/events.mdx b/docs/astro/src/content/docs/guides/physics/events.mdxnew file mode 100644index 000000000..46677f8ad--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/events.mdx@@ -0,0 +1,85 @@+---+title: Collision Events+description: Handling collision and sensor events in ESEngine physics+---++import { Aside } from '@astrojs/starlight/components';++Read collision and sensor events from the `PhysicsEvents` resource each frame.++## PhysicsEvents Resource++```typescript+import { defineSystem, addSystem, Res } from 'esengine';+import { PhysicsEvents } from 'esengine/physics';++addSystem(defineSystem(+ [Res(PhysicsEvents)],+ (events) => {+ for (const e of events.collisionEnters) {+ // e.entityA, e.entityB, e.normalX, e.normalY, e.contactX, e.contactY+ }+ for (const e of events.collisionExits) {+ // e.entityA, e.entityB+ }+ for (const e of events.sensorEnters) {+ // e.sensorEntity, e.visitorEntity+ }+ for (const e of events.sensorExits) {+ // e.sensorEntity, e.visitorEntity+ }+ }+));+```++## Event Types++### Collision Enter++Fired on the first frame two non-sensor colliders begin touching.++| Field | Type | Description |+|-------|------|-------------|+| `entityA` | Entity | First entity in the collision pair |+| `entityB` | Entity | Second entity in the collision pair |+| `normalX` | number | Collision normal X component |+| `normalY` | number | Collision normal Y component |+| `contactX` | number | Contact point X in world space |+| `contactY` | number | Contact point Y in world space |++### Collision Exit++Fired on the first frame two non-sensor colliders stop touching.++| Field | Type | Description |+|-------|------|-------------|+| `entityA` | Entity | First entity in the collision pair |+| `entityB` | Entity | Second entity in the collision pair |++### Sensor Enter++Fired when a non-sensor collider begins overlapping a sensor collider.++| Field | Type | Description |+|-------|------|-------------|+| `sensorEntity` | Entity | Entity with `isSensor = true` |+| `visitorEntity` | Entity | Entity that entered the sensor zone |++### Sensor Exit++Fired when a non-sensor collider stops overlapping a sensor collider.++| Field | Type | Description |+|-------|------|-------------|+| `sensorEntity` | Entity | Entity with `isSensor = true` |+| `visitorEntity` | Entity | Entity that left the sensor zone |++<Aside type="tip">+ Set `isSensor = true` on a collider to create a trigger zone that detects overlaps without physical response. See [Colliders](./colliders/) for details.+</Aside>++## See Also++- [Physics Overview](./index.mdx) — setup and configuration+- [Colliders](./colliders/) — collider shapes and sensor property+- [API](./api/) — runtime physics controldiff --git a/docs/astro/src/content/docs/guides/physics/index.mdx b/docs/astro/src/content/docs/guides/physics/index.mdxnew file mode 100644index 000000000..618d7ff14--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/index.mdx@@ -0,0 +1,96 @@+---+title: Physics+description: 2D physics simulation with Box2D in ESEngine+---++import { Aside } from '@astrojs/starlight/components';++The physics system provides 2D rigid body simulation powered by a standalone Box2D WASM module. The editor and build pipeline handle loading automatically — you only need to enable it in settings and add components to entities.++## Setup++Enable physics in the editor: **Settings → Physics → Enable Physics**.++Configure the simulation parameters in the same panel:++| Setting | Default | Description |+|---------|---------|-------------|+| Gravity X | `0` | Horizontal gravity |+| 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) |++<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.+</Aside>++### Coordinate Conversion (PPU)++Collider dimensions (`halfExtents`, `radius`, `halfHeight`) are specified in **physics units (meters)**. The Canvas component's `pixelsPerUnit` (default `100`) determines the conversion ratio between pixel coordinates and physics coordinates.++Position conversion is handled automatically — entity positions (in pixels) are divided by PPU when sent to Box2D, and multiplied by PPU when read back. Physics API values (`force`, `velocity`, `impulse`, `gravity`) also operate in physics units. You do not need to perform any manual conversion.++## Body Types++### Static (0)++Does not move. Used for walls, floors, and platforms.++```typescript+rigidBody.bodyType = 0;+```++### Kinematic (1)++Moved by code (transform), not by physics forces. Other bodies collide with it but don't push it. Used for moving platforms and elevators.++```typescript+rigidBody.bodyType = 1;+```++### Dynamic (2)++Fully simulated. Responds to gravity, forces, and collisions. Used for players, projectiles, and physics objects.++```typescript+rigidBody.bodyType = 2;+```++## Components++Add physics components to entities in the scene editor alongside `Transform`. Every physics entity needs a [RigidBody](./rigidbody/) and at least one [collider](./colliders/).++## Example: Simple Platformer++Set up a ground, player, and coin sensor in the editor, then handle events in code:++```typescript+import { defineSystem, addSystem, Res, Input, Query, Mut, Transform } from 'esengine';+import { RigidBody, PhysicsEvents } from 'esengine/physics';+import { Player, Coin } from './components';++addSystem(defineSystem(+ [Res(PhysicsEvents)],+ (events) => {+ for (const e of events.sensorEnters) {+ // Coin collected+ }+ }+));+```++**Editor setup:**+- **Ground**: `Transform` + `RigidBody` (bodyType=0 Static) + `BoxCollider` (halfExtents=`{x:10, y:0.5}`) + `Sprite`+- **Player**: `Transform` + `RigidBody` (bodyType=2 Dynamic, fixedRotation=true) + `BoxCollider` + `Sprite` + `Player` tag+- **Coin**: `Transform` + `RigidBody` (bodyType=0 Static) + `CircleCollider` (isSensor=true) + `Sprite` + `Coin` tag++## Next Steps++- [RigidBody](./rigidbody/) — rigid body properties+- [Colliders](./colliders/) — collider shapes overview+- [Events](./events/) — collision and sensor events+- [API](./api/) — runtime force and velocity control+- [Debug Draw](./debug-draw/) — debug visualizationdiff --git a/docs/astro/src/content/docs/guides/physics/polygon-collider.mdx b/docs/astro/src/content/docs/guides/physics/polygon-collider.mdxnew file mode 100644index 000000000..f40d4c877--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/polygon-collider.mdx@@ -0,0 +1,65 @@+---+title: Polygon Collider+description: Convex polygon collider with vertex editing+---++import { Aside } from '@astrojs/starlight/components';++The `PolygonCollider` defines a convex polygon shape with up to 8 vertices. It is useful for custom collision shapes that cannot be represented by boxes, circles, or capsules.++## Properties++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `vertices` | Vec2[] | `[]` | Polygon vertices in physics units (local space). Max 8 vertices |+| `radius` | number | `0.0` | Skin radius applied around the polygon. Creates a rounded polygon when > 0 |+| `density` | number | `1.0` | Mass density |+| `friction` | number | `0.6` | Surface friction |+| `restitution` | number | `0.0` | Bounciness |+| `isSensor` | boolean | `false` | Trigger zone without physical response |+| `categoryBits` | number | `1` | Collision filter category bits |++<Aside type="caution">+ Box2D enforces a maximum of **8 vertices** per polygon. Polygons with more vertices will be rejected. If you need more complex shapes, decompose them into multiple convex polygons or use a [ChainCollider](./chain-collider/) for static boundaries.+</Aside>++## Vertex Editing in Scene View++When an entity with a `PolygonCollider` is selected in the editor, vertex handles appear in the Scene View:++- **Drag a handle** to move a vertex+- **Double-click on an edge** to add a new vertex (if under the 8-vertex limit)+- **Right-click a handle** to remove a vertex++<Aside type="note">+ Vertices must form a **convex polygon**. The editor will enforce convexity — if a drag would create a concave shape, the vertex position is clamped.+</Aside>++## Usage++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 2 }),+ PolygonCollider.with({+ vertices: [+ { x: -0.5, y: -0.5 },+ { x: 0.5, y: -0.5 },+ { x: 0.3, y: 0.5 },+ { x: -0.3, y: 0.5 },+ ],+ }),+);+```++## Tips++- Keep polygons simple. Fewer vertices means better performance.+- The `radius` property adds a skin around the polygon, which can reduce collision jitter for stacking scenarios.+- For concave shapes, split them into multiple convex `PolygonCollider` entities and parent them under a single root entity.++## See Also++- [Colliders Overview](./colliders/) — all collider types+- [Segment Collider](./segment-collider/) — line segment shapes+- [Chain Collider](./chain-collider/) — chain of connected segmentsdiff --git a/docs/astro/src/content/docs/guides/physics/rigidbody.mdx b/docs/astro/src/content/docs/guides/physics/rigidbody.mdxnew file mode 100644index 000000000..9bbe137cb--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/rigidbody.mdx@@ -0,0 +1,57 @@+---+title: RigidBody+description: RigidBody component properties for physics entities+---++Every physics entity needs a `RigidBody` component. It defines the body type and physical properties.++## Properties++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `bodyType` | number | `2` (Dynamic) | 0=Static, 1=Kinematic, 2=Dynamic |+| `gravityScale` | number | `1.0` | Gravity multiplier |+| `linearDamping` | number | `0.0` | Linear velocity damping |+| `angularDamping` | number | `0.0` | Angular velocity damping |+| `fixedRotation` | boolean | `false` | Lock rotation |+| `bullet` | boolean | `false` | CCD for fast objects |+| `enabled` | boolean | `true` | Enable physics body |++## Body Types++### Static (0)++Does not move. Used for walls, floors, and platforms. Static bodies have infinite mass and do not respond to forces.++```typescript+rigidBody.bodyType = 0;+```++### Kinematic (1)++Moved by code (transform), not by physics forces. Other bodies collide with it but don't push it. Used for moving platforms and elevators.++```typescript+rigidBody.bodyType = 1;+```++### Dynamic (2)++Fully simulated. Responds to gravity, forces, and collisions. Used for players, projectiles, and physics objects.++```typescript+rigidBody.bodyType = 2;+```++## Usage Notes++- `gravityScale` allows per-body gravity adjustment. Set to `0` for zero-gravity objects, negative values for reverse gravity.+- `fixedRotation` is useful for character controllers that should not rotate on collision.+- `bullet` enables continuous collision detection (CCD), which prevents fast-moving objects from tunneling through thin colliders. Use sparingly as it has a performance cost.+- `linearDamping` and `angularDamping` simulate air resistance. Higher values slow the body faster.++## See Also++- [Physics Overview](./index.mdx) — setup and coordinate conversion+- [Colliders](./colliders/) — attaching collider shapes to rigid bodies+- [API](./api/) — runtime force and velocity controldiff --git a/docs/astro/src/content/docs/guides/physics/segment-collider.mdx b/docs/astro/src/content/docs/guides/physics/segment-collider.mdxnew file mode 100644index 000000000..784fdb75e--- /dev/null+++ b/docs/astro/src/content/docs/guides/physics/segment-collider.mdx@@ -0,0 +1,51 @@+---+title: Segment Collider+description: Line segment collider for thin walls and barriers+---++import { Aside } from '@astrojs/starlight/components';++The `SegmentCollider` defines a line segment between two points. It is useful for thin walls, one-way platforms, and invisible barriers that don't need volumetric shape.++## Properties++| Property | Type | Default | Description |+|----------|------|---------|-------------|+| `point1` | Vec2 | `{x: -0.5, y: 0}` | Start point in physics units (local space) |+| `point2` | Vec2 | `{x: 0.5, y: 0}` | End point in physics units (local space) |+| `density` | number | `1.0` | Mass density |+| `friction` | number | `0.6` | Surface friction |+| `restitution` | number | `0.0` | Bounciness |+| `isSensor` | boolean | `false` | Trigger zone without physical response |+| `categoryBits` | number | `1` | Collision filter category bits |++## Usage++Add a `SegmentCollider` component to any entity that also has a `RigidBody` and `Transform`.++**Thin walls:** Create invisible collision boundaries without using a full box shape.++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ SegmentCollider.with({+ point1: { x: 0, y: 0 },+ point2: { x: 0, y: 5 },+ }),+);+```++**One-way platforms:** Combine with static body type to create edges that objects can land on.++**Invisible barriers:** Define play area boundaries without visible collider geometry.++<Aside type="note">+ Segment colliders are single-sided. For two-sided collision boundaries, consider using a thin [BoxCollider](./colliders/#boxcollider) or a [ChainCollider](./chain-collider/) instead.+</Aside>++## See Also++- [Colliders Overview](./colliders/) — all collider types+- [Chain Collider](./chain-collider/) — chain of connected segments for terrain+- [Polygon Collider](./polygon-collider/) — convex polygon shapesdiff --git a/docs/astro/src/content/docs/zh/guides/physics.mdx b/docs/astro/src/content/docs/zh/guides/physics.mdxdeleted file mode 100644index 8b2a516bd..000000000--- a/docs/astro/src/content/docs/zh/guides/physics.mdx+++ /dev/null@@ -1,244 +0,0 @@-----title: 物理-description: ESEngine 中使用 Box2D 的 2D 物理模拟------import { Aside } from '@astrojs/starlight/components';--物理系统提供基于独立 Box2D WASM 模块的 2D 刚体模拟。编辑器和构建流程会自动处理模块加载——你只需在设置中启用物理并为实体添加组件。--## 设置--在编辑器中启用物理:**Settings → Physics → Enable Physics**。--在同一面板中配置模拟参数:--| 设置项 | 默认值 | 说明 |-|--------|--------|------|-| Gravity X | `0` | 水平重力 |-| Gravity Y | `-9.81` | 垂直重力(负数 = 向下) |-| Fixed Timestep | `1/60` | 物理步进间隔(秒) |-| Sub-Step Count | `4` | 每次物理步进的子步数,用于提高精度 |-| Contact Hertz | `120` | 接触刚度(周期/秒)。越高穿透越少但抖动越明显 |-| Contact Damping Ratio | `10` | 接触弹性阻尼。越低重叠恢复越快但弹性越强 |-| Contact Speed | `10` | 最大重叠修正速度(米/秒) |--<Aside type="note">- 物理 WASM 模块由编辑器预览和构建流程自动加载,无需在游戏脚本中手动初始化插件。-</Aside>--### 坐标转换 (PPU)--碰撞体尺寸(`halfExtents`、`radius`、`halfHeight`)以**物理单位(米)**设定。Canvas 组件的 `pixelsPerUnit`(默认 `100`)决定像素坐标与物理坐标之间的换算比例。--位置转换自动完成——实体位置(像素)在发送到 Box2D 时除以 PPU,读回时乘以 PPU。Physics API 的值(`force`、`velocity`、`impulse`、`gravity`)同样使用物理单位,无需手动换算。--## 组件--在场景编辑器中将物理组件与 `Transform` 一起添加到实体上。--### RigidBody--每个物理实体都需要 `RigidBody` 组件,定义刚体类型和物理属性。--| 属性 | 类型 | 默认值 | 说明 |-|------|------|--------|------|-| `bodyType` | number | `2`(Dynamic) | 0=静态,1=运动学,2=动态 |-| `gravityScale` | number | `1.0` | 重力倍率 |-| `linearDamping` | number | `0.0` | 线速度阻尼 |-| `angularDamping` | number | `0.0` | 角速度阻尼 |-| `fixedRotation` | boolean | `false` | 锁定旋转 |-| `bullet` | boolean | `false` | 高速物体连续碰撞检测 |-| `enabled` | boolean | `true` | 启用物理刚体 |--### 碰撞体--每个实体还需要一个碰撞体形状,选择其一:--- **BoxCollider** — `halfExtents`(Vec2)、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`-- **CircleCollider** — `radius`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`-- **CapsuleCollider** — `radius`、`halfHeight`、`offset`(Vec2)、`density`、`friction`、`restitution`、`isSensor`、`enabled`--详见[组件](/microes/zh/core-concepts/components/#物理)完整属性表。--## 刚体类型--### Static(0)--不移动。用于墙壁、地面和平台。--```typescript-rigidBody.bodyType = 0;-```--### Kinematic(1)--通过代码(变换)移动,不受物理力影响。其他刚体会与之碰撞但不会推动它。用于移动平台和电梯。--```typescript-rigidBody.bodyType = 1;-```--### Dynamic(2)--完全模拟。响应重力、力和碰撞。用于玩家、投射物和物理对象。--```typescript-rigidBody.bodyType = 2;-```--## 碰撞事件--从 `PhysicsEvents` 资源读取碰撞和传感器事件:--```typescript-import { defineSystem, addSystem, Res } from 'esengine';-import { PhysicsEvents } from 'esengine/physics';--addSystem(defineSystem(- [Res(PhysicsEvents)],- (events) => {- for (const e of events.collisionEnters) {- // e.entityA, e.entityB, e.normalX, e.normalY, e.contactX, e.contactY- }- for (const e of events.collisionExits) {- // e.entityA, e.entityB- }- for (const e of events.sensorEnters) {- // e.sensorEntity, e.visitorEntity- }- for (const e of events.sensorExits) {- // e.sensorEntity, e.visitorEntity- }- }-));-```--<Aside type="tip">- 将碰撞体的 `isSensor` 设为 `true` 可创建触发区域,检测重叠但不产生物理响应。-</Aside>--## 示例:简单平台跳跃--在编辑器中设置地面、玩家和金币传感器,然后用代码处理事件:--```typescript-import { defineSystem, addSystem, Res, Input, Query, Mut, Transform } from 'esengine';-import { RigidBody, PhysicsEvents } from 'esengine/physics';-import { Player, Coin } from './components';--addSystem(defineSystem(- [Res(PhysicsEvents)],- (events) => {- for (const e of events.sensorEnters) {- // 金币收集- }- }-));-```--**编辑器设置:**-- **地面**:`Transform` + `RigidBody`(bodyType=0 Static)+ `BoxCollider`(halfExtents=`{x:10, y:0.5}`)+ `Sprite`-- **玩家**:`Transform` + `RigidBody`(bodyType=2 Dynamic,fixedRotation=true)+ `BoxCollider` + `Sprite` + `Player` 标签-- **金币**:`Transform` + `RigidBody`(bodyType=0 Static)+ `CircleCollider`(isSensor=true)+ `Sprite` + `Coin` 标签--## Physics API(进阶)--`Physics` 类提供运行时力/速度控制。物理插件加载完成后会自动注册 `PhysicsAPI` 资源,可在任何系统中通过 `Res(PhysicsAPI)` 访问:--```typescript-import { defineSystem, addSystem, Res } from 'esengine';-import { PhysicsAPI } from 'esengine/physics';--addSystem(defineSystem(- [Res(PhysicsAPI)],- (physics) => {- physics.applyForce(entity, { x: 0, y: 10 });- }-));-```--| 方法 | 说明 |-|------|------|-| `applyForce(entity, force)` | 施加持续力(Vec2) |-| `applyImpulse(entity, impulse)` | 施加瞬时冲量(Vec2) |-| `setLinearVelocity(entity, velocity)` | 直接设置线速度 |-| `getLinearVelocity(entity)` | 获取当前线速度(Vec2) |-| `setAngularVelocity(entity, omega)` | 设置角速度(number) |-| `getAngularVelocity(entity)` | 获取当前角速度 |-| `applyTorque(entity, torque)` | 施加旋转扭矩 |-| `applyAngularImpulse(entity, impulse)` | 施加瞬时角冲量 |-| `setGravity(gravity)` | 运行时修改世界重力 |-| `getGravity()` | 获取当前世界重力(Vec2) |--## 调试绘制--物理调试绘制叠加层渲染所有碰撞体的线框轮廓、速度箭头和接触点。使用引擎的 `Draw` API,在编辑器和运行时均可使用。--### 启用调试绘制--```typescript-import { Physics } from 'esengine/physics';--// 开启/关闭调试绘制-Physics.setDebugDraw(app, true);-```--### 配置--控制显示哪些元素:--```typescript-import { Physics } from 'esengine/physics';--Physics.setDebugDrawConfig(app, {- enabled: true,- showColliders: true, // 碰撞体线框轮廓- showVelocity: true, // 动态刚体的速度箭头- showContacts: false, // 接触点标记-});-```--| 属性 | 类型 | 默认值 | 说明 |-|------|------|--------|------|-| `enabled` | boolean | `false` | 调试绘制主开关 |-| `showColliders` | boolean | `true` | 绘制碰撞体线框 |-| `showVelocity` | boolean | `false` | 绘制动态刚体的速度箭头 |-| `showContacts` | boolean | `false` | 绘制碰撞进入时的接触点 |--### 颜色编码--碰撞体轮廓按刚体类型着色:--| 刚体类型 | 颜色 |-|----------|------|-| Static | 蓝色 |-| Dynamic | 绿色 |-| Kinematic | 青色 |-| Sensor | 黄色(半透明) |--速度箭头为红色。接触点显示为红色圆点。--<Aside type="tip">- 调试绘制注册为名为 `'physics-debug-draw'` 的自定义绘制回调。物理插件初始化时自动设置——你只需启用它。-</Aside>--### PhysicsDebugDraw 资源--如需高级控制,可直接访问 `PhysicsDebugDraw` 资源:--```typescript-import { PhysicsDebugDraw } from 'esengine/physics';--const config = app.getResource(PhysicsDebugDraw);-config.enabled = true;-config.showVelocity = true;-app.insertResource(PhysicsDebugDraw, config);-```--## 下一步--- [组件](/microes/zh/core-concepts/components/#物理) — 完整物理组件属性表-- [系统](/microes/zh/core-concepts/systems/) — 创建系统处理物理逻辑-- [自定义绘制](/microes/zh/guides/custom-draw/) — 碰撞体调试可视化-- [瓦片地图](/microes/zh/guides/tilemap/) — 基于瓦片的碰撞生成diff --git a/docs/astro/src/content/docs/zh/guides/physics/api.mdx b/docs/astro/src/content/docs/zh/guides/physics/api.mdxnew file mode 100644index 000000000..b31ed71b1--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/api.mdx@@ -0,0 +1,46 @@+---+title: 物理 API+description: 运行时力、速度与重力控制+---++`Physics` 类提供运行时力/速度控制。物理插件加载完成后会自动注册 `PhysicsAPI` 资源,可在任何系统中通过 `Res(PhysicsAPI)` 访问。++## 访问 API++```typescript+import { defineSystem, addSystem, Res } from 'esengine';+import { PhysicsAPI } from 'esengine/physics';++addSystem(defineSystem(+ [Res(PhysicsAPI)],+ (physics) => {+ physics.applyForce(entity, { x: 0, y: 10 });+ }+));+```++## 方法++| 方法 | 说明 |+|------|------|+| `applyForce(entity, force)` | 施加持续力(Vec2) |+| `applyImpulse(entity, impulse)` | 施加瞬时冲量(Vec2) |+| `setLinearVelocity(entity, velocity)` | 直接设置线速度 |+| `getLinearVelocity(entity)` | 获取当前线速度(Vec2) |+| `setAngularVelocity(entity, omega)` | 设置角速度(number) |+| `getAngularVelocity(entity)` | 获取当前角速度 |+| `applyTorque(entity, torque)` | 施加旋转扭矩 |+| `applyAngularImpulse(entity, impulse)` | 施加瞬时角冲量 |+| `setGravity(gravity)` | 运行时修改世界重力 |+| `getGravity()` | 获取当前世界重力(Vec2) |++## 力 vs 冲量++- **力**每帧持续施加。效果取决于刚体质量,在物理时间步中积分。适用于持续推力(如火箭推进、风力)。+- **冲量**瞬间施加。直接改变速度,与帧率无关。适用于一次性事件(如跳跃、爆炸击退)。++## 参见++- [物理概述](./index.mdx) — 设置、PPU 与刚体类型+- [刚体](./rigidbody/) — 刚体属性+- [碰撞事件](./events/) — 碰撞与传感器事件diff --git a/docs/astro/src/content/docs/zh/guides/physics/chain-collider.mdx b/docs/astro/src/content/docs/zh/guides/physics/chain-collider.mdxnew file mode 100644index 000000000..6b097dcea--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/chain-collider.mdx@@ -0,0 +1,83 @@+---+title: 链条碰撞器+description: 用于地形和静态边界的线段链碰撞体+---++import { Aside } from '@astrojs/starlight/components';++`ChainCollider` 定义一条连接线段的链。专为静态地形表面和复杂边界设计,使用单个盒形或线段碰撞体难以实现的场景。++<Aside type="caution">+ 链条碰撞体只能用于**静态刚体**(bodyType=0)。不支持密度和传感器模式。+</Aside>++## 属性++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `points` | Vec2[] | `[]` | 链条顶点,以物理单位计(局部空间) |+| `isLoop` | boolean | `false` | 将最后一个点连接回第一个点,形成闭合环 |+| `friction` | number | `0.6` | 表面摩擦力 |+| `restitution` | number | `0.0` | 弹性 |+| `categoryBits` | number | `1` | 碰撞过滤类别位 |++## 场景视图中的点编辑++在编辑器中选中带有 `ChainCollider` 的实体时,场景视图中会显示点控制点:++- **拖拽控制点**移动点+- **双击线段**插入新点+- **右键点击控制点**删除点++## isLoop++当 `isLoop` 为 `false` 时,链条是开放路径——物体可以绕过端点。当 `isLoop` 为 `true` 时,最后一个点连接回第一个点,形成闭合边界。++**开放链条**——适用于地形表面:++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ ChainCollider.with({+ points: [+ { x: -10, y: 0 },+ { x: -5, y: 2 },+ { x: 0, y: 0 },+ { x: 5, y: 1 },+ { x: 10, y: 0 },+ ],+ isLoop: false,+ }),+);+```++**闭合环——适用于封闭区域:**++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ ChainCollider.with({+ points: [+ { x: -5, y: -5 },+ { x: 5, y: -5 },+ { x: 5, y: 5 },+ { x: -5, y: 5 },+ ],+ isLoop: true,+ }),+);+```++## 提示++- 链条碰撞体没有体积,因此只在一侧产生碰撞。按逆时针顺序排列点以获得朝外的法线。+- 与 [PolygonCollider](./polygon-collider/) 不同,链条碰撞体没有顶点数量限制——可以使用任意数量的点定义地形。+- 对于动态碰撞形状,请使用 [PolygonCollider](./polygon-collider/) 或基础碰撞体类型。++## 参见++- [碰撞体概览](./colliders/) — 所有碰撞体类型+- [线段碰撞器](./segment-collider/) — 单个线段+- [多边形碰撞器](./polygon-collider/) — 凸多边形形状diff --git a/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx b/docs/astro/src/content/docs/zh/guides/physics/colliders.mdxnew file mode 100644index 000000000..deb1b5bed--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/colliders.mdx@@ -0,0 +1,78 @@+---+title: 碰撞体+description: 物理实体的碰撞体形状概览+---++import { Aside } from '@astrojs/starlight/components';++每个物理实体需要在 [RigidBody](./rigidbody/) 旁附加至少一个碰撞体形状。碰撞体定义用于碰撞检测的物理形状。++## 碰撞体类型++| 碰撞体 | 形状 | 适用场景 |+|--------|------|----------|+| [BoxCollider](#boxcollider) | 轴对齐矩形 | 箱子、平台、墙壁 |+| [CircleCollider](#circlecollider) | 圆形 | 球、金币、圆形物体 |+| [CapsuleCollider](#capsulecollider) | 胶囊(矩形两端半圆) | 角色、药丸形物体 |+| [SegmentCollider](./segment-collider/) | 线段 | 薄墙、单向平台 |+| [PolygonCollider](./polygon-collider/) | 凸多边形(最多 8 顶点) | 自定义凸形状 |+| [ChainCollider](./chain-collider/) | 线段链 | 地形、复杂静态边界 |++## 通用属性++所有碰撞体(ChainCollider 除外)共享以下属性:++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `density` | number | `1.0` | 质量密度。影响刚体总质量 |+| `friction` | number | `0.6` | 表面摩擦力(0 = 冰面,1 = 橡胶) |+| `restitution` | number | `0.0` | 弹性(0 = 无弹性,1 = 完全弹性) |+| `isSensor` | boolean | `false` | 触发区域——检测重叠但不产生物理响应 |+| `categoryBits` | number | `1` | 碰撞过滤类别位 |+| `enabled` | boolean | `true` | 启用/禁用碰撞体 |++<Aside type="tip">+ 将 `isSensor` 设为 `true` 可创建触发区域,触发[传感器事件](./events/)而不阻挡移动。+</Aside>++## BoxCollider++轴对齐矩形碰撞体。++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `halfExtents` | Vec2 | `{x: 0.5, y: 0.5}` | 半宽和半高,以物理单位计 |+| `offset` | Vec2 | `{x: 0, y: 0}` | 相对实体中心的偏移,以物理单位计 |+| `radius` | number | `0.0` | 圆角半径。大于 0 时创建圆角矩形 |++加上所有[通用属性](#通用属性)。++## CircleCollider++圆形碰撞体。++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `radius` | number | `0.5` | 圆半径,以物理单位计 |+| `offset` | Vec2 | `{x: 0, y: 0}` | 相对实体中心的偏移,以物理单位计 |++加上所有[通用属性](#通用属性)。++## CapsuleCollider++胶囊形碰撞体(矩形上下两端为半圆)。++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `radius` | number | `0.5` | 胶囊半径,以物理单位计 |+| `halfHeight` | number | `0.5` | 矩形中段的半高,以物理单位计 |+| `offset` | Vec2 | `{x: 0, y: 0}` | 相对实体中心的偏移,以物理单位计 |++加上所有[通用属性](#通用属性)。++## 参见++- [线段碰撞器](./segment-collider/) — 线段碰撞体+- [多边形碰撞器](./polygon-collider/) — 自定义凸多边形碰撞体+- [链条碰撞器](./chain-collider/) — 地形线段链+- [碰撞事件](./events/) — 碰撞与传感器事件diff --git a/docs/astro/src/content/docs/zh/guides/physics/debug-draw.mdx b/docs/astro/src/content/docs/zh/guides/physics/debug-draw.mdxnew file mode 100644index 000000000..c43368fd3--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/debug-draw.mdx@@ -0,0 +1,75 @@+---+title: 调试绘制+description: 碰撞体、速度和接触点的物理调试可视化+---++import { Aside } from '@astrojs/starlight/components';++物理调试绘制叠加层渲染所有碰撞体的线框轮廓、速度箭头和接触点。使用引擎的 `Draw` API,在编辑器和运行时均可使用。++## 启用调试绘制++```typescript+import { Physics } from 'esengine/physics';++// 开启/关闭调试绘制+Physics.setDebugDraw(app, true);+```++## 配置++控制显示哪些元素:++```typescript+import { Physics } from 'esengine/physics';++Physics.setDebugDrawConfig(app, {+ enabled: true,+ showColliders: true, // 碰撞体线框轮廓+ showVelocity: true, // 动态刚体的速度箭头+ showContacts: false, // 接触点标记+});+```++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `enabled` | boolean | `false` | 调试绘制主开关 |+| `showColliders` | boolean | `true` | 绘制碰撞体线框 |+| `showVelocity` | boolean | `false` | 绘制动态刚体的速度箭头 |+| `showContacts` | boolean | `false` | 绘制碰撞进入时的接触点 |++## 颜色编码++碰撞体轮廓按刚体类型着色:++| 刚体类型 | 颜色 |+|----------|------|+| Static | 蓝色 |+| Dynamic | 绿色 |+| Kinematic | 青色 |+| Sensor | 黄色(半透明) |++速度箭头为红色。接触点显示为红色圆点。++<Aside type="tip">+ 调试绘制注册为名为 `'physics-debug-draw'` 的自定义绘制回调。物理插件初始化时自动设置——你只需启用它。+</Aside>++## PhysicsDebugDraw 资源++如需高级控制,可直接访问 `PhysicsDebugDraw` 资源:++```typescript+import { PhysicsDebugDraw } from 'esengine/physics';++const config = app.getResource(PhysicsDebugDraw);+config.enabled = true;+config.showVelocity = true;+app.insertResource(PhysicsDebugDraw, config);+```++## 参见++- [物理概述](./index.mdx) — 设置与配置+- [碰撞体](./colliders/) — 碰撞体形状+- [自定义绘制](/microes/zh/guides/custom-draw/) — 引擎绘制 APIdiff --git a/docs/astro/src/content/docs/zh/guides/physics/events.mdx b/docs/astro/src/content/docs/zh/guides/physics/events.mdxnew file mode 100644index 000000000..b3bedbae2--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/events.mdx@@ -0,0 +1,85 @@+---+title: 碰撞事件+description: ESEngine 物理中碰撞与传感器事件的处理+---++import { Aside } from '@astrojs/starlight/components';++每帧从 `PhysicsEvents` 资源中读取碰撞和传感器事件。++## PhysicsEvents 资源++```typescript+import { defineSystem, addSystem, Res } from 'esengine';+import { PhysicsEvents } from 'esengine/physics';++addSystem(defineSystem(+ [Res(PhysicsEvents)],+ (events) => {+ for (const e of events.collisionEnters) {+ // e.entityA, e.entityB, e.normalX, e.normalY, e.contactX, e.contactY+ }+ for (const e of events.collisionExits) {+ // e.entityA, e.entityB+ }+ for (const e of events.sensorEnters) {+ // e.sensorEntity, e.visitorEntity+ }+ for (const e of events.sensorExits) {+ // e.sensorEntity, e.visitorEntity+ }+ }+));+```++## 事件类型++### 碰撞进入++两个非传感器碰撞体开始接触的第一帧触发。++| 字段 | 类型 | 说明 |+|------|------|------|+| `entityA` | Entity | 碰撞对中的第一个实体 |+| `entityB` | Entity | 碰撞对中的第二个实体 |+| `normalX` | number | 碰撞法线 X 分量 |+| `normalY` | number | 碰撞法线 Y 分量 |+| `contactX` | number | 世界空间中的接触点 X |+| `contactY` | number | 世界空间中的接触点 Y |++### 碰撞退出++两个非传感器碰撞体停止接触的第一帧触发。++| 字段 | 类型 | 说明 |+|------|------|------|+| `entityA` | Entity | 碰撞对中的第一个实体 |+| `entityB` | Entity | 碰撞对中的第二个实体 |++### 传感器进入++非传感器碰撞体开始与传感器碰撞体重叠时触发。++| 字段 | 类型 | 说明 |+|------|------|------|+| `sensorEntity` | Entity | `isSensor = true` 的实体 |+| `visitorEntity` | Entity | 进入传感器区域的实体 |++### 传感器退出++非传感器碰撞体停止与传感器碰撞体重叠时触发。++| 字段 | 类型 | 说明 |+|------|------|------|+| `sensorEntity` | Entity | `isSensor = true` 的实体 |+| `visitorEntity` | Entity | 离开传感器区域的实体 |++<Aside type="tip">+ 将碰撞体的 `isSensor` 设为 `true` 可创建触发区域,检测重叠但不产生物理响应。详见[碰撞体](./colliders/)。+</Aside>++## 参见++- [物理概述](./index.mdx) — 设置与配置+- [碰撞体](./colliders/) — 碰撞体形状与传感器属性+- [物理 API](./api/) — 运行时物理控制diff --git a/docs/astro/src/content/docs/zh/guides/physics/index.mdx b/docs/astro/src/content/docs/zh/guides/physics/index.mdxnew file mode 100644index 000000000..1bf482cf0--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/index.mdx@@ -0,0 +1,96 @@+---+title: 物理+description: ESEngine 中使用 Box2D 的 2D 物理模拟+---++import { Aside } from '@astrojs/starlight/components';++物理系统提供基于独立 Box2D WASM 模块的 2D 刚体模拟。编辑器和构建流程会自动处理模块加载——你只需在设置中启用物理并为实体添加组件。++## 设置++在编辑器中启用物理:**Settings → Physics → Enable Physics**。++在同一面板中配置模拟参数:++| 设置项 | 默认值 | 说明 |+|--------|--------|------|+| Gravity X | `0` | 水平重力 |+| Gravity Y | `-9.81` | 垂直重力(负数 = 向下) |+| Fixed Timestep | `1/60` | 物理步进间隔(秒) |+| Sub-Step Count | `4` | 每次物理步进的子步数,用于提高精度 |+| Contact Hertz | `120` | 接触刚度(周期/秒)。越高穿透越少但抖动越明显 |+| Contact Damping Ratio | `10` | 接触弹性阻尼。越低重叠恢复越快但弹性越强 |+| Contact Speed | `10` | 最大重叠修正速度(米/秒) |++<Aside type="note">+ 物理 WASM 模块由编辑器预览和构建流程自动加载,无需在游戏脚本中手动初始化插件。+</Aside>++### 坐标转换 (PPU)++碰撞体尺寸(`halfExtents`、`radius`、`halfHeight`)以**物理单位(米)**设定。Canvas 组件的 `pixelsPerUnit`(默认 `100`)决定像素坐标与物理坐标之间的换算比例。++位置转换自动完成——实体位置(像素)在发送到 Box2D 时除以 PPU,读回时乘以 PPU。Physics API 的值(`force`、`velocity`、`impulse`、`gravity`)同样使用物理单位,无需手动换算。++## 刚体类型++### Static(0)++不移动。用于墙壁、地面和平台。++```typescript+rigidBody.bodyType = 0;+```++### Kinematic(1)++通过代码(变换)移动,不受物理力影响。其他刚体会与之碰撞但不会推动它。用于移动平台和电梯。++```typescript+rigidBody.bodyType = 1;+```++### Dynamic(2)++完全模拟。响应重力、力和碰撞。用于玩家、投射物和物理对象。++```typescript+rigidBody.bodyType = 2;+```++## 组件++在场景编辑器中将物理组件与 `Transform` 一起添加到实体上。每个物理实体需要一个 [RigidBody](./rigidbody/) 和至少一个[碰撞体](./colliders/)。++## 示例:简单平台跳跃++在编辑器中设置地面、玩家和金币传感器,然后用代码处理事件:++```typescript+import { defineSystem, addSystem, Res, Input, Query, Mut, Transform } from 'esengine';+import { RigidBody, PhysicsEvents } from 'esengine/physics';+import { Player, Coin } from './components';++addSystem(defineSystem(+ [Res(PhysicsEvents)],+ (events) => {+ for (const e of events.sensorEnters) {+ // 金币收集+ }+ }+));+```++**编辑器设置:**+- **地面**:`Transform` + `RigidBody`(bodyType=0 Static)+ `BoxCollider`(halfExtents=`{x:10, y:0.5}`)+ `Sprite`+- **玩家**:`Transform` + `RigidBody`(bodyType=2 Dynamic,fixedRotation=true)+ `BoxCollider` + `Sprite` + `Player` 标签+- **金币**:`Transform` + `RigidBody`(bodyType=0 Static)+ `CircleCollider`(isSensor=true)+ `Sprite` + `Coin` 标签++## 下一步++- [刚体](./rigidbody/) — 刚体属性+- [碰撞体](./colliders/) — 碰撞体形状概览+- [碰撞事件](./events/) — 碰撞与传感器事件+- [物理 API](./api/) — 运行时力与速度控制+- [调试绘制](./debug-draw/) — 调试可视化diff --git a/docs/astro/src/content/docs/zh/guides/physics/polygon-collider.mdx b/docs/astro/src/content/docs/zh/guides/physics/polygon-collider.mdxnew file mode 100644index 000000000..3d93acca2--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/polygon-collider.mdx@@ -0,0 +1,65 @@+---+title: 多边形碰撞器+description: 支持顶点编辑的凸多边形碰撞体+---++import { Aside } from '@astrojs/starlight/components';++`PolygonCollider` 定义最多 8 个顶点的凸多边形形状。适用于无法用盒形、圆形或胶囊形表示的自定义碰撞形状。++## 属性++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `vertices` | Vec2[] | `[]` | 多边形顶点,以物理单位计(局部空间)。最多 8 个顶点 |+| `radius` | number | `0.0` | 多边形外围的蒙皮半径。大于 0 时创建圆角多边形 |+| `density` | number | `1.0` | 质量密度 |+| `friction` | number | `0.6` | 表面摩擦力 |+| `restitution` | number | `0.0` | 弹性 |+| `isSensor` | boolean | `false` | 触发区域,无物理响应 |+| `categoryBits` | number | `1` | 碰撞过滤类别位 |++<Aside type="caution">+ Box2D 限制每个多边形最多 **8 个顶点**。超过此数量的多边形将被拒绝。如需更复杂的形状,请将其分解为多个凸多边形或使用 [ChainCollider](./chain-collider/) 处理静态边界。+</Aside>++## 场景视图中的顶点编辑++在编辑器中选中带有 `PolygonCollider` 的实体时,场景视图中会显示顶点控制点:++- **拖拽控制点**移动顶点+- **双击边**添加新顶点(在 8 顶点限制以内时)+- **右键点击控制点**删除顶点++<Aside type="note">+ 顶点必须构成**凸多边形**。编辑器会强制保持凸性——如果拖拽会产生凹形状,顶点位置会被约束。+</Aside>++## 用法++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 2 }),+ PolygonCollider.with({+ vertices: [+ { x: -0.5, y: -0.5 },+ { x: 0.5, y: -0.5 },+ { x: 0.3, y: 0.5 },+ { x: -0.3, y: 0.5 },+ ],+ }),+);+```++## 提示++- 保持多边形简单。顶点越少性能越好。+- `radius` 属性在多边形外围添加蒙皮,可减少堆叠场景中的碰撞抖动。+- 对于凹形状,将其拆分为多个凸 `PolygonCollider` 实体,挂载到同一父实体下。++## 参见++- [碰撞体概览](./colliders/) — 所有碰撞体类型+- [线段碰撞器](./segment-collider/) — 线段形状+- [链条碰撞器](./chain-collider/) — 连接线段链diff --git a/docs/astro/src/content/docs/zh/guides/physics/rigidbody.mdx b/docs/astro/src/content/docs/zh/guides/physics/rigidbody.mdxnew file mode 100644index 000000000..b1fe8773d--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/rigidbody.mdx@@ -0,0 +1,57 @@+---+title: 刚体+description: 物理实体的 RigidBody 组件属性+---++每个物理实体都需要 `RigidBody` 组件,定义刚体类型和物理属性。++## 属性++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `bodyType` | number | `2`(Dynamic) | 0=静态,1=运动学,2=动态 |+| `gravityScale` | number | `1.0` | 重力倍率 |+| `linearDamping` | number | `0.0` | 线速度阻尼 |+| `angularDamping` | number | `0.0` | 角速度阻尼 |+| `fixedRotation` | boolean | `false` | 锁定旋转 |+| `bullet` | boolean | `false` | 高速物体连续碰撞检测 |+| `enabled` | boolean | `true` | 启用物理刚体 |++## 刚体类型++### Static(0)++不移动。用于墙壁、地面和平台。静态刚体具有无限质量,不响应力。++```typescript+rigidBody.bodyType = 0;+```++### Kinematic(1)++通过代码(变换)移动,不受物理力影响。其他刚体会与之碰撞但不会推动它。用于移动平台和电梯。++```typescript+rigidBody.bodyType = 1;+```++### Dynamic(2)++完全模拟。响应重力、力和碰撞。用于玩家、投射物和物理对象。++```typescript+rigidBody.bodyType = 2;+```++## 使用注意++- `gravityScale` 可为每个刚体单独调整重力。设为 `0` 可实现零重力物体,负值可实现反向重力。+- `fixedRotation` 适用于碰撞时不应旋转的角色控制器。+- `bullet` 启用连续碰撞检测(CCD),防止高速物体穿过薄碰撞体。由于有性能开销,应谨慎使用。+- `linearDamping` 和 `angularDamping` 模拟空气阻力。值越高刚体减速越快。++## 参见++- [物理概述](./index.mdx) — 设置与坐标转换+- [碰撞体](./colliders/) — 为刚体附加碰撞体形状+- [物理 API](./api/) — 运行时力与速度控制diff --git a/docs/astro/src/content/docs/zh/guides/physics/segment-collider.mdx b/docs/astro/src/content/docs/zh/guides/physics/segment-collider.mdxnew file mode 100644index 000000000..56231ec37--- /dev/null+++ b/docs/astro/src/content/docs/zh/guides/physics/segment-collider.mdx@@ -0,0 +1,51 @@+---+title: 线段碰撞器+description: 用于薄墙和屏障的线段碰撞体+---++import { Aside } from '@astrojs/starlight/components';++`SegmentCollider` 定义两点之间的线段。适用于薄墙、单向平台和不需要体积形状的隐形屏障。++## 属性++| 属性 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `point1` | Vec2 | `{x: -0.5, y: 0}` | 起点,以物理单位计(局部空间) |+| `point2` | Vec2 | `{x: 0.5, y: 0}` | 终点,以物理单位计(局部空间) |+| `density` | number | `1.0` | 质量密度 |+| `friction` | number | `0.6` | 表面摩擦力 |+| `restitution` | number | `0.0` | 弹性 |+| `isSensor` | boolean | `false` | 触发区域,无物理响应 |+| `categoryBits` | number | `1` | 碰撞过滤类别位 |++## 用法++将 `SegmentCollider` 组件添加到同时具有 `RigidBody` 和 `Transform` 的实体上。++**薄墙:**创建无需完整盒形的隐形碰撞边界。++```typescript+commands.spawn(+ Transform.default(),+ RigidBody.with({ bodyType: 0 }),+ SegmentCollider.with({+ point1: { x: 0, y: 0 },+ point2: { x: 0, y: 5 },+ }),+);+```++**单向平台:**搭配静态刚体创建物体可以落在上面的边缘。++**隐形屏障:**定义游戏区域边界,无需可见碰撞体几何形状。++<Aside type="note">+ 线段碰撞体是单面的。如需双面碰撞边界,请考虑使用薄 [BoxCollider](./colliders/#boxcollider) 或 [ChainCollider](./chain-collider/)。+</Aside>++## 参见++- [碰撞体概览](./colliders/) — 所有碰撞体类型+- [链条碰撞器](./chain-collider/) — 用于地形的连接线段链+- [多边形碰撞器](./polygon-collider/) — 凸多边形形状