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: split physics guide into per-topic pages

esengined3836e7aab25
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 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.mdx
deleted file mode 100644
index 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 generation
diff --git a/docs/astro/src/content/docs/guides/physics/api.mdx b/docs/astro/src/content/docs/guides/physics/api.mdx
new file mode 100644
index 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 events
diff --git a/docs/astro/src/content/docs/guides/physics/chain-collider.mdx b/docs/astro/src/content/docs/guides/physics/chain-collider.mdx
new file mode 100644
index 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 shapes
diff --git a/docs/astro/src/content/docs/guides/physics/colliders.mdx b/docs/astro/src/content/docs/guides/physics/colliders.mdx
new file mode 100644
index 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 events
diff --git a/docs/astro/src/content/docs/guides/physics/debug-draw.mdx b/docs/astro/src/content/docs/guides/physics/debug-draw.mdx
new file mode 100644
index 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 API
diff --git a/docs/astro/src/content/docs/guides/physics/events.mdx b/docs/astro/src/content/docs/guides/physics/events.mdx
new file mode 100644
index 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 control
diff --git a/docs/astro/src/content/docs/guides/physics/index.mdx b/docs/astro/src/content/docs/guides/physics/index.mdx
new file mode 100644
index 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 visualization
diff --git a/docs/astro/src/content/docs/guides/physics/polygon-collider.mdx b/docs/astro/src/content/docs/guides/physics/polygon-collider.mdx
new file mode 100644
index 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 segments
diff --git a/docs/astro/src/content/docs/guides/physics/rigidbody.mdx b/docs/astro/src/content/docs/guides/physics/rigidbody.mdx
new file mode 100644
index 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 control
diff --git a/docs/astro/src/content/docs/guides/physics/segment-collider.mdx b/docs/astro/src/content/docs/guides/physics/segment-collider.mdx
new file mode 100644
index 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 shapes
diff --git a/docs/astro/src/content/docs/zh/guides/physics.mdx b/docs/astro/src/content/docs/zh/guides/physics.mdx
deleted file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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/) — 引擎绘制 API
diff --git a/docs/astro/src/content/docs/zh/guides/physics/events.mdx b/docs/astro/src/content/docs/zh/guides/physics/events.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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/) — 凸多边形形状