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: rewrite the Physics guide to the complete-reference template
yhhd054c375403d
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdxindex 435e97e58..bd449f45e 100644--- a/docs/astro/src/content/docs/guides/physics.mdx+++ b/docs/astro/src/content/docs/guides/physics.mdx@@ -1,19 +1,20 @@---title: Physics-description: Bodies, colliders, forces, queries, events, and joints — the full 2D physics API.+description: The complete 2D physics reference — rigid bodies, colliders, collision filtering, forces, spatial queries, collision/sensor events, joints, and the character controller.---import { Aside } from '@astrojs/starlight/components';-Estella's physics runs in the C++/WebAssembly core (Box2D). You attach a-`RigidBody` and a collider to an entity; then move it with forces, query the-world with raycasts, react to collisions, and connect bodies with joints.+Estella's physics runs in the C++/WebAssembly core, powered by Box2D v3. You attach+a `RigidBody` and a collider to an entity, then move it with forces, query the world+with raycasts, react to collisions, and connect bodies with joints. Physics steps at+a **fixed timestep**, decoupled from the frame rate, for stable simulation.-## Enabling physics+## SetupPhysics is an optional side-module. In the editor and web runtime it loads-automatically when a scene uses physics components. In a custom app you add it-yourself:+automatically when a scene uses physics components. In a custom app, add the plugin+yourself (gravity defaults to `{ x: 0, y: -9.81 }`):```typescriptimport { PhysicsPlugin } from 'esengine/physics';@@ -21,11 +22,17 @@ import { PhysicsPlugin } from 'esengine/physics';app.addPlugin(new PhysicsPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));```+<Aside type="note">+ Physics types are imported from **`esengine/physics`** (the API, plugin, events),+ while the components (`RigidBody`, colliders, `CharacterController`) come from the+ main `esengine` barrel.+</Aside>+## Bodies & colliders-Attach a `RigidBody` plus one collider shape. **Collider dimensions are in-meters, not pixels** — divide pixel sizes by your pixels-per-unit (PPU). Spawn-from a system that takes `Commands()`:+Attach a `RigidBody` plus one collider shape. **Collider dimensions are in meters,+not pixels** — divide pixel sizes by your pixels-per-unit (PPU). Spawn from a system+that takes `Commands()`:```typescriptimport {@@ -38,25 +45,52 @@ const PPU = 100;const spawnBall = defineSystem([Commands()], (cmds) => {cmds.spawn().insert(Transform, { position: { x: 0, y: 250, z: 0 } })- .insert(RigidBody, { bodyType: BodyType.Dynamic, gravityScale: 1, linearDamping: 0 })+ .insert(RigidBody, { bodyType: BodyType.Dynamic, gravityScale: 1 }).insert(CircleCollider, { radius: 24 / PPU, density: 1, friction: 0.3, restitution: 0.4 });});```-- **`RigidBody`** — `bodyType` (`Static` / `Kinematic` / `Dynamic`),- `gravityScale`, `linearDamping`, `angularDamping`, `fixedRotation`, `bullet`- (continuous collision for fast bodies).-- **Collider shapes** (from `esengine`) — `BoxCollider` (`halfExtents`),- `CircleCollider` (`radius`), `CapsuleCollider` (`radius`, `halfHeight`),- `SegmentCollider` (`point1`, `point2`), `PolygonCollider` (`vertices`),- `ChainCollider` (`points`, `isLoop`). All share `density`, `friction`,- `restitution`, `isSensor`, `categoryBits`, `maskBits`.--## Collision layers--`categoryBits` (what layer a body is on) and `maskBits` (what it collides with)-are 16-bit filters. Two bodies collide only if each one's category is in the-other's mask:+### `RigidBody`++| Property | Type | Default | Description |+|---|---|---|---|+| `bodyType` | `BodyType` | `Dynamic` | `Static` (immovable), `Kinematic` (moved by code), `Dynamic` (simulated). |+| `gravityScale` | number | `1` | Multiplier on world gravity (`0` = float). |+| `linearDamping` | number | `0` | Linear velocity drag. |+| `angularDamping` | number | `0` | Angular velocity drag. |+| `fixedRotation` | boolean | `false` | Lock rotation (typical for characters). |+| `bullet` | boolean | `false` | Continuous collision for fast, thin bodies (anti-tunneling). |+| `enabled` | boolean | `true` | Disable to remove from the simulation. |++### Colliders++All colliders share these fields; each adds its own shape parameters. Dimensions+are in meters.++| Shared property | Type | Default | Description |+|---|---|---|---|+| `offset` | Vec2 | `{0, 0}` | Local offset from the entity origin. |+| `density` | number | `1` | Mass per area (drives the body's mass). |+| `friction` | number | `0.3` | Surface friction, 0..1+. |+| `restitution` | number | `0` | Bounciness, 0..1. |+| `isSensor` | boolean | `false` | Detect overlaps without a physical response (triggers). |+| `categoryBits` | number | `0x0001` | Which collision layer this collider is on. |+| `maskBits` | number | `0xFFFF` | Which layers it collides with. |+| `enabled` | boolean | `true` | Disable the shape. |++| Component | Shape parameters |+|---|---|+| `BoxCollider` | `halfExtents` (`{0.5, 0.5}`), `radius` (rounded corner, `0.05`). |+| `CircleCollider` | `radius` (`0.5`). |+| `CapsuleCollider` | `radius`, `halfHeight`. |+| `SegmentCollider` | `point1`, `point2` (a one-sided edge). |+| `PolygonCollider` | `vertices: Vec2[]`, `radius` (rounded). |+| `ChainCollider` | `points: Vec2[]`, `isLoop` (static edge chain; no `density`/`isSensor`). |++## Collision filtering++`categoryBits` (what layer a body is on) and `maskBits` (what it collides with) are+16-bit filters. Two bodies collide only if each one's category is in the other's mask:```typescriptconst LAYER_PLAYER = 0x0001;@@ -70,10 +104,9 @@ const LAYER_GROUND = 0x0008;});```-## Move bodies: forces & velocity+## Moving bodies — forces & velocity-Read the `PhysicsAPI` resource to push bodies around. All of these take a world-entity:+Read the `PhysicsAPI` resource to drive bodies. Every method takes the world entity:```typescriptimport { defineSystem, Query, Res, RigidBody } from 'esengine';@@ -84,69 +117,76 @@ const move = defineSystem([Query(RigidBody), Res(PhysicsAPI)], (q, physics) => {physics.applyForce(entity, { x: 0, y: 20 }); // continuous forcephysics.applyImpulse(entity, { x: 0, y: 5 }); // instant kick (jump)physics.setLinearVelocity(entity, { x: 3, y: 0 });- physics.applyTorque(entity, 2);- physics.applyAngularImpulse(entity, 0.5);}});```-Also: `getLinearVelocity`, `getAngularVelocity`, `setAngularVelocity`,-`setGravity` / `getGravity` (world gravity), `getMass`, `getInertia`,-`getCenterOfMass`, `getMassData`, and `setAwake` / `isAwake` (sleeping bodies).+| Method | Description |+|---|---|+| `applyForce(e, v)` / `applyImpulse(e, v)` | Continuous force / instantaneous impulse. |+| `applyTorque(e, t)` / `applyAngularImpulse(e, i)` | Rotational force / impulse. |+| `setLinearVelocity(e, v)` / `getLinearVelocity(e)` | Set / read linear velocity. |+| `setAngularVelocity(e, w)` / `getAngularVelocity(e)` | Set / read angular velocity. |+| `setGravity(v)` / `getGravity()` | World gravity. |+| `getMass(e)` / `getInertia(e)` / `getCenterOfMass(e)` / `getMassData(e)` | Mass properties. |+| `setAwake(e, awake)` / `isAwake(e)` | Sleeping-body control. |## Spatial queries-Queries take **pixel-space** arguments and auto-scale by the live PPU:+Queries take **pixel-space** arguments and auto-scale by the live PPU. Each accepts+an optional `maskBits` to filter by layer:```typescript-// Raycast — returns every hit along the ray, nearest first.+// Raycast — every hit along the ray, nearest first.const hits = physics.raycast(origin, direction, 200);for (const hit of hits) {// hit.entity, hit.point, hit.normal}-// Overlap — entities whose colliders intersect a shape.-const nearby = physics.overlapCircle(center, 64); // Entity[]-const inBox = physics.overlapAABB(min, max); // Entity[]--// Shape cast — sweep a shape and get what it would hit.-const swept = physics.shapeCastCircle(/* … */);+const nearby = physics.overlapCircle(center, 64); // Entity[]+const inBox = physics.overlapAABB(min, max); // Entity[]+const swept = physics.shapeCastCircle(/* … */); // sweep a shape```-Each takes an optional `maskBits` to filter by layer. `overlapCircle` /-`overlapAABB` / `shapeCastBox` / `shapeCastCapsule` round out the set.+| Method | Returns | Description |+|---|---|---|+| `raycast(origin, dir, dist, maskBits?)` | hit list | All hits along a ray, nearest first. |+| `overlapCircle(center, radius, maskBits?)` | `Entity[]` | Colliders overlapping a circle. |+| `overlapAABB(min, max, maskBits?)` | `Entity[]` | Colliders overlapping a box. |+| `shapeCastCircle` / `shapeCastBox` / `shapeCastCapsule` | hit | Sweep a shape and get what it would hit. |## Collision & sensor events-The `PhysicsEvents` resource carries this frame's contacts. Set `isSensor: true`-on a collider to get enter/exit events **without** a physical response (trigger-zones):+The `PhysicsEvents` resource carries this frame's contacts. Set `isSensor: true` on a+collider to get enter/exit events **without** a physical response (trigger zones):```typescriptimport { defineSystem, Res } from 'esengine';import { PhysicsEvents } from 'esengine/physics';const onHit = defineSystem([Res(PhysicsEvents)], (events) => {- for (const c of events.collisionEnters) {- // c.entityA, c.entityB, c.normalX/Y, c.contactX/Y- }- for (const x of events.collisionExits) { /* x.entityA, x.entityB */ }- for (const h of events.collisionHits) {- // high-speed impact: h.approachSpeed, h.pointX/Y, h.normalX/Y- }- for (const s of events.sensorEnters) { /* s.sensorEntity, s.visitorEntity */ }- for (const s of events.sensorExits) { /* … */ }+ for (const c of events.collisionEnters) { /* c.entityA, c.entityB, c.normalX/Y, c.contactX/Y */ }+ for (const x of events.collisionExits) { /* x.entityA, x.entityB */ }+ for (const h of events.collisionHits) { /* h.approachSpeed, h.pointX/Y, h.normalX/Y */ }+ for (const s of events.sensorEnters) { /* s.sensorEntity, s.visitorEntity */ }+ for (const s of events.sensorExits) { /* … */ }});```+| Event list | Fired when |+|---|---|+| `collisionEnters` / `collisionExits` | Two solid colliders begin / stop touching. |+| `collisionHits` | A high-speed impact (carries `approachSpeed`). |+| `sensorEnters` / `sensorExits` | A body enters / leaves a sensor collider. |+## JointsConnect two bodies. Add a joint **component** (`RevoluteJoint`, `DistanceJoint`,-`PrismaticJoint`, `WeldJoint`, `WheelJoint`), or create one imperatively and-drive its motor / limits:+`PrismaticJoint`, `WeldJoint`, `WheelJoint`), or create one imperatively and drive+its motor / limits:```typescript-// A hinge with a motor (e.g. a powered wheel or a swinging door).+// A hinge with a motor (a powered wheel or swinging door).physics.createRevoluteJoint(bodyA, bodyB, anchorA, anchorB, {enableMotor: true, motorSpeed: 6, maxMotorTorque: 200,enableLimit: true, lowerAngle: -1.0, upperAngle: 1.0,@@ -158,18 +198,62 @@ const angle = physics.getRevoluteAngle(bodyA);physics.destroyJoint(bodyA);```-Distance, prismatic, and wheel joints have the parallel set —-`setDistanceJointLength`, `enablePrismaticJointMotor`, `setWheelJointMotorSpeed`,-and so on.+Each joint type has a parallel set of control methods:++| Joint | Control methods |+|---|---|+| Revolute (hinge) | `setRevoluteMotorSpeed`, `setRevoluteMaxMotorTorque`, `enableRevoluteMotor`, `enableRevoluteLimit`, `setRevoluteLimits`, `getRevoluteAngle`, `getRevoluteMotorTorque`. |+| Distance (spring) | `setDistanceJointLength`, `getDistanceJoint*Length`, `enableDistanceJointSpring`/`Limit`/`Motor`, `setDistanceJointLimits`, `setDistanceJointMotorSpeed`, … |+| Prismatic (slider) | `getPrismaticJointTranslation`/`Speed`, `enablePrismaticJointSpring`/`Limit`/`Motor`, `setPrismaticJointLimits`/`MotorSpeed`/`MaxMotorForce`, … |+| Wheel | `enableWheelJointSpring`/`Limit`/`Motor`, `setWheelJointLimits`/`MotorSpeed`/`MaxMotorTorque`, `getWheelJointMotorTorque`. |++Destroy any joint with `destroyJoint(bodyA)`.## Character controller-For a player that doesn't tumble like a dynamic body, add a `CharacterController`-and resolve movement with `moveAndSlide` — a kinematic move-and-slide that walks-along surfaces instead of bouncing.+For a player that walks along surfaces instead of tumbling like a dynamic body, add+a `CharacterController`. Set its `velocity` from gameplay each step; the system+resolves a kinematic move-and-slide, writes the result back, and reports what it+touched:-<Aside type="caution">- Physics steps at a **fixed timestep**, not the frame delta, so read- `PhysicsEvents` every frame and apply continuous forces every frame. Set- `bullet: true` on fast, thin bodies to avoid tunneling.-</Aside>+```typescript+import { defineSystem, Query, Mut, CharacterController } from 'esengine';++const drive = defineSystem([Query(Mut(CharacterController))], (q) => {+ for (const [entity, cc] of q) {+ cc.velocity = { x: input.moveX * 240, y: cc.velocity.y - 900 * dt }; // gravity+ if (cc.isOnFloor && jumpPressed) cc.velocity.y = 480;+ }+});+```++| Property | Type | Default | Description |+|---|---|---|---|+| `velocity` | Vec2 | `{0, 0}` | Desired velocity in world pixels/second (set each step). |+| `up` | Vec2 | `{0, 1}` | Up direction for floor/ceiling classification. |+| `floorMaxAngle` | number | `0.785` | Max walkable slope from `up`, radians (45°). |+| `maxSlides` | number | `4` | Slide iterations per move (corners need more). |+| `skinWidth` | number | `1` | Gap kept from surfaces (px) to avoid sticking. |+| `snapLength` | number | `0` | Down-probe (px) to stay glued to slopes/stairs; `0` = off. |+| `slideOnCeiling` | boolean | `true` | Slide along a ceiling vs. stop the move. |+| `maskBits` | number | `0xFFFF` | Layers that block the character. |+| `isOnFloor` / `isOnWall` / `isOnCeiling` | boolean | — | **Output**: what was touched this move. |+| `floorNormal` | Vec2 | — | **Output**: normal of the last floor touched. |+| `realVelocity` | Vec2 | — | **Output**: actual displacement / dt after collisions. |++## Best practices++- **Fixed timestep**: apply continuous forces and read `PhysicsEvents` *every frame*,+ since physics substeps independently of the frame delta.+- **`bullet: true`** on fast, thin bodies (bullets, thin platforms) to avoid tunneling.+- **`fixedRotation: true`** for characters so they don't topple.+- **Colliders in meters** (÷ PPU), but **queries and the character controller in+ pixels** — mixing the two is the most common bug.+- **Sensors for triggers**: `isSensor: true` gives enter/exit events with no physical push.+- **Filter with layers** (`categoryBits` / `maskBits`) instead of checking entity types+ in event handlers.++## See also++- [Scenes](/docs/guides/scene/) — physics components serialize with the scene.+- [Math Helpers](/docs/guides/math/) — vector math for velocities and directions.diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/guides/physics.mdxindex a753b732b..537534876 100644--- a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx@@ -1,17 +1,18 @@---title: 物理-description: 刚体、碰撞体、力、查询、事件与关节 —— 完整的 2D 物理 API。+description: 完整的 2D 物理参考——刚体、碰撞体、碰撞过滤、力、空间查询、碰撞/传感事件、关节,以及角色控制器。---import { Aside } from '@astrojs/starlight/components';-Estella 的物理运行在 C++/WebAssembly 内核中(Box2D)。你给实体挂上 `RigidBody` 和一个-碰撞体;然后用力移动它、用射线查询世界、响应碰撞、用关节连接刚体。+Estella 的物理跑在 C++/WebAssembly 内核里,由 Box2D v3 驱动。你给实体加一个 `RigidBody`+和一个碰撞体,然后用力移动它、用射线查询世界、响应碰撞、用关节连接刚体。物理以**固定时间步**+推进,与帧率解耦,得到稳定的模拟。-## 启用物理+## 安装-物理是可选 side-module。在编辑器和 Web 运行时中,场景用到物理组件时它会自动加载。在-自定义 App 里你也可以自己添加:+物理是一个可选的侧模块。在编辑器和 Web 运行时里,当场景使用物理组件时会自动加载。在自定义+应用里,自己加插件(重力默认 `{ x: 0, y: -9.81 }`):```typescriptimport { PhysicsPlugin } from 'esengine/physics';@@ -19,10 +20,15 @@ import { PhysicsPlugin } from 'esengine/physics';app.addPlugin(new PhysicsPlugin('physics.js', { gravity: { x: 0, y: -9.81 } }));```+<Aside type="note">+ 物理的类型从 **`esengine/physics`** 导入(API、插件、事件),而组件(`RigidBody`、各碰撞体、+ `CharacterController`)来自主 `esengine` barrel。+</Aside>+## 刚体与碰撞体-挂一个 `RigidBody` 加一个碰撞体形状。**碰撞体尺寸单位是米,不是像素**——把像素尺寸-除以你的 PPU(每单位像素数)。在带 `Commands()` 的系统里生成:+加一个 `RigidBody` 再加一个碰撞体形状。**碰撞体尺寸以米计,不是像素**——把像素尺寸除以你的+每单位像素数(PPU)。从一个取 `Commands()` 的系统里生成:```typescriptimport {@@ -35,24 +41,51 @@ const PPU = 100;const spawnBall = defineSystem([Commands()], (cmds) => {cmds.spawn().insert(Transform, { position: { x: 0, y: 250, z: 0 } })- .insert(RigidBody, { bodyType: BodyType.Dynamic, gravityScale: 1, linearDamping: 0 })+ .insert(RigidBody, { bodyType: BodyType.Dynamic, gravityScale: 1 }).insert(CircleCollider, { radius: 24 / PPU, density: 1, friction: 0.3, restitution: 0.4 });});```-- **`RigidBody`** —— `bodyType`(`Static` / `Kinematic` / `Dynamic`)、- `gravityScale`、`linearDamping`、`angularDamping`、`fixedRotation`、`bullet`- (快速物体的连续碰撞检测)。-- **碰撞体形状**(来自 `esengine`)—— `BoxCollider`(`halfExtents`)、- `CircleCollider`(`radius`)、`CapsuleCollider`(`radius`、`halfHeight`)、- `SegmentCollider`(`point1`、`point2`)、`PolygonCollider`(`vertices`)、- `ChainCollider`(`points`、`isLoop`)。都共享 `density`、`friction`、- `restitution`、`isSensor`、`categoryBits`、`maskBits`。--## 碰撞层--`categoryBits`(刚体所在的层)与 `maskBits`(它会与哪些层碰撞)是 16 位过滤器。两个-刚体只有在各自的 category 都落在对方的 mask 里时才碰撞:+### `RigidBody`++| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `bodyType` | `BodyType` | `Dynamic` | `Static`(不动)、`Kinematic`(由代码移动)、`Dynamic`(被模拟)。 |+| `gravityScale` | number | `1` | 世界重力的倍率(`0` = 漂浮)。 |+| `linearDamping` | number | `0` | 线速度阻尼。 |+| `angularDamping` | number | `0` | 角速度阻尼。 |+| `fixedRotation` | boolean | `false` | 锁定旋转(角色常用)。 |+| `bullet` | boolean | `false` | 对快速细小刚体做连续碰撞(防穿透)。 |+| `enabled` | boolean | `true` | 关掉即从模拟中移除。 |++### 碰撞体++所有碰撞体共享这些字段,各自再加自己的形状参数。尺寸以米计。++| 共享属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `offset` | Vec2 | `{0, 0}` | 相对实体原点的局部偏移。 |+| `density` | number | `1` | 单位面积质量(决定刚体质量)。 |+| `friction` | number | `0.3` | 表面摩擦,0..1+。 |+| `restitution` | number | `0` | 弹性,0..1。 |+| `isSensor` | boolean | `false` | 检测重叠但无物理响应(触发器)。 |+| `categoryBits` | number | `0x0001` | 该碰撞体所在的碰撞层。 |+| `maskBits` | number | `0xFFFF` | 它与哪些层碰撞。 |+| `enabled` | boolean | `true` | 关掉该形状。 |++| 组件 | 形状参数 |+|---|---|+| `BoxCollider` | `halfExtents`(`{0.5, 0.5}`)、`radius`(圆角,`0.05`)。 |+| `CircleCollider` | `radius`(`0.5`)。 |+| `CapsuleCollider` | `radius`、`halfHeight`。 |+| `SegmentCollider` | `point1`、`point2`(单边)。 |+| `PolygonCollider` | `vertices: Vec2[]`、`radius`(圆角)。 |+| `ChainCollider` | `points: Vec2[]`、`isLoop`(静态边链;无 `density`/`isSensor`)。 |++## 碰撞过滤++`categoryBits`(刚体在哪一层)和 `maskBits`(它与什么碰撞)是 16 位过滤器。仅当彼此的 category+都在对方的 mask 里,两个刚体才碰撞:```typescriptconst LAYER_PLAYER = 0x0001;@@ -62,13 +95,13 @@ const LAYER_GROUND = 0x0008;.insert(CircleCollider, {radius: 16 / PPU,categoryBits: LAYER_PLAYER,- maskBits: LAYER_ENEMY | LAYER_GROUND, // 忽略其他玩家+ maskBits: LAYER_ENEMY | LAYER_GROUND, // ignores other players});```-## 移动刚体:力与速度+## 移动刚体 —— 力与速度-读 `PhysicsAPI` 资源来推动刚体。它们都作用于一个世界实体:+读 `PhysicsAPI` 资源来驱动刚体。每个方法都取世界实体:```typescriptimport { defineSystem, Query, Res, RigidBody } from 'esengine';@@ -76,70 +109,77 @@ import { PhysicsAPI } from 'esengine/physics';const move = defineSystem([Query(RigidBody), Res(PhysicsAPI)], (q, physics) => {for (const [entity] of q) {- physics.applyForce(entity, { x: 0, y: 20 }); // 持续力- physics.applyImpulse(entity, { x: 0, y: 5 }); // 瞬时冲量(跳跃)+ physics.applyForce(entity, { x: 0, y: 20 }); // continuous force+ physics.applyImpulse(entity, { x: 0, y: 5 }); // instant kick (jump)physics.setLinearVelocity(entity, { x: 3, y: 0 });- physics.applyTorque(entity, 2);- physics.applyAngularImpulse(entity, 0.5);}});```-还有:`getLinearVelocity`、`getAngularVelocity`、`setAngularVelocity`、-`setGravity` / `getGravity`(世界重力)、`getMass`、`getInertia`、-`getCenterOfMass`、`getMassData`,以及 `setAwake` / `isAwake`(休眠刚体)。+| 方法 | 说明 |+|---|---|+| `applyForce(e, v)` / `applyImpulse(e, v)` | 持续力 / 瞬时冲量。 |+| `applyTorque(e, t)` / `applyAngularImpulse(e, i)` | 旋转力 / 冲量。 |+| `setLinearVelocity(e, v)` / `getLinearVelocity(e)` | 设置 / 读取线速度。 |+| `setAngularVelocity(e, w)` / `getAngularVelocity(e)` | 设置 / 读取角速度。 |+| `setGravity(v)` / `getGravity()` | 世界重力。 |+| `getMass(e)` / `getInertia(e)` / `getCenterOfMass(e)` / `getMassData(e)` | 质量属性。 |+| `setAwake(e, awake)` / `isAwake(e)` | 睡眠刚体控制。 |## 空间查询-查询接受**像素单位**参数,并按实时 PPU 自动缩放:+查询取**像素空间**参数,并按当前 PPU 自动缩放。每个都接受一个可选的 `maskBits` 按层过滤:```typescript-// 射线检测 —— 返回射线上的每个命中,由近到远。+// Raycast — every hit along the ray, nearest first.const hits = physics.raycast(origin, direction, 200);for (const hit of hits) {- // hit.entity、hit.point、hit.normal+ // hit.entity, hit.point, hit.normal}-// 重叠 —— 碰撞体与某形状相交的实体。-const nearby = physics.overlapCircle(center, 64); // Entity[]-const inBox = physics.overlapAABB(min, max); // Entity[]--// 形状扫掠 —— 扫一个形状,得到它会撞到什么。-const swept = physics.shapeCastCircle(/* … */);+const nearby = physics.overlapCircle(center, 64); // Entity[]+const inBox = physics.overlapAABB(min, max); // Entity[]+const swept = physics.shapeCastCircle(/* … */); // sweep a shape```-每个都可传可选的 `maskBits` 按层过滤。`overlapCircle` / `overlapAABB` /-`shapeCastBox` / `shapeCastCapsule` 补齐整套。+| 方法 | 返回 | 说明 |+|---|---|---|+| `raycast(origin, dir, dist, maskBits?)` | 命中列表 | 射线上所有命中,最近优先。 |+| `overlapCircle(center, radius, maskBits?)` | `Entity[]` | 与圆重叠的碰撞体。 |+| `overlapAABB(min, max, maskBits?)` | `Entity[]` | 与盒重叠的碰撞体。 |+| `shapeCastCircle` / `shapeCastBox` / `shapeCastCapsule` | 命中 | 扫掠一个形状并得到它会撞到什么。 |-## 碰撞与传感器事件+## 碰撞与传感事件-`PhysicsEvents` 资源携带当前帧的接触。给碰撞体设 `isSensor: true`,可在**没有物理-响应**的情况下获得进入/离开事件(触发区):+`PhysicsEvents` 资源携带这一帧的接触。给碰撞体设 `isSensor: true` 即可得到 enter/exit 事件+而**没有**物理响应(触发区):```typescriptimport { defineSystem, Res } from 'esengine';import { PhysicsEvents } from 'esengine/physics';const onHit = defineSystem([Res(PhysicsEvents)], (events) => {- for (const c of events.collisionEnters) {- // c.entityA、c.entityB、c.normalX/Y、c.contactX/Y- }- for (const x of events.collisionExits) { /* x.entityA、x.entityB */ }- for (const h of events.collisionHits) {- // 高速撞击:h.approachSpeed、h.pointX/Y、h.normalX/Y- }- for (const s of events.sensorEnters) { /* s.sensorEntity、s.visitorEntity */ }- for (const s of events.sensorExits) { /* … */ }+ for (const c of events.collisionEnters) { /* c.entityA, c.entityB, c.normalX/Y, c.contactX/Y */ }+ for (const x of events.collisionExits) { /* x.entityA, x.entityB */ }+ for (const h of events.collisionHits) { /* h.approachSpeed, h.pointX/Y, h.normalX/Y */ }+ for (const s of events.sensorEnters) { /* s.sensorEntity, s.visitorEntity */ }+ for (const s of events.sensorExits) { /* … */ }});```+| 事件列表 | 触发时机 |+|---|---|+| `collisionEnters` / `collisionExits` | 两个实心碰撞体开始 / 停止接触。 |+| `collisionHits` | 高速冲击(携带 `approachSpeed`)。 |+| `sensorEnters` / `sensorExits` | 刚体进入 / 离开一个传感碰撞体。 |+## 关节-连接两个刚体。加一个关节**组件**(`RevoluteJoint`、`DistanceJoint`、-`PrismaticJoint`、`WeldJoint`、`WheelJoint`),或用命令式创建并驱动它的马达/限位:+连接两个刚体。加一个关节**组件**(`RevoluteJoint`、`DistanceJoint`、`PrismaticJoint`、+`WeldJoint`、`WheelJoint`),或命令式创建一个并驱动它的马达 / 限位:```typescript-// 带马达的铰链(例如带动力的轮子或摆动的门)。+// A hinge with a motor (a powered wheel or swinging door).physics.createRevoluteJoint(bodyA, bodyB, anchorA, anchorB, {enableMotor: true, motorSpeed: 6, maxMotorTorque: 200,enableLimit: true, lowerAngle: -1.0, upperAngle: 1.0,@@ -151,15 +191,57 @@ const angle = physics.getRevoluteAngle(bodyA);physics.destroyJoint(bodyA);```-距离、棱柱、轮子关节有对应的整套——`setDistanceJointLength`、-`enablePrismaticJointMotor`、`setWheelJointMotorSpeed` 等等。+每种关节都有一套平行的控制方法:++| 关节 | 控制方法 |+|---|---|+| Revolute(铰链) | `setRevoluteMotorSpeed`、`setRevoluteMaxMotorTorque`、`enableRevoluteMotor`、`enableRevoluteLimit`、`setRevoluteLimits`、`getRevoluteAngle`、`getRevoluteMotorTorque`。 |+| Distance(弹簧) | `setDistanceJointLength`、`getDistanceJoint*Length`、`enableDistanceJointSpring`/`Limit`/`Motor`、`setDistanceJointLimits`、`setDistanceJointMotorSpeed`…… |+| Prismatic(滑轨) | `getPrismaticJointTranslation`/`Speed`、`enablePrismaticJointSpring`/`Limit`/`Motor`、`setPrismaticJointLimits`/`MotorSpeed`/`MaxMotorForce`…… |+| Wheel(车轮) | `enableWheelJointSpring`/`Limit`/`Motor`、`setWheelJointLimits`/`MotorSpeed`/`MaxMotorTorque`、`getWheelJointMotorTorque`。 |++用 `destroyJoint(bodyA)` 销毁任何关节。## 角色控制器-想要一个不像动态刚体那样翻滚的玩家,加一个 `CharacterController`,用 `moveAndSlide`-解算移动——这是一种运动学的"移动并滑动",沿着表面行走而不是弹开。+想让玩家沿着表面行走、而不是像动态刚体那样翻滚,加一个 `CharacterController`。每步从玩法设它+的 `velocity`;系统会解析一次运动学 move-and-slide,把结果写回,并报告它碰到了什么:-<Aside type="caution">- 物理按**固定时间步**步进,而不是帧间隔,所以每帧都要读 `PhysicsEvents`、每帧都要施加- 持续力。给又快又薄的物体设 `bullet: true` 以避免穿透。-</Aside>+```typescript+import { defineSystem, Query, Mut, CharacterController } from 'esengine';++const drive = defineSystem([Query(Mut(CharacterController))], (q) => {+ for (const [entity, cc] of q) {+ cc.velocity = { x: input.moveX * 240, y: cc.velocity.y - 900 * dt }; // gravity+ if (cc.isOnFloor && jumpPressed) cc.velocity.y = 480;+ }+});+```++| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `velocity` | Vec2 | `{0, 0}` | 期望速度(世界像素/秒,每步设置)。 |+| `up` | Vec2 | `{0, 1}` | 用于地面/天花板分类的上方向。 |+| `floorMaxAngle` | number | `0.785` | 相对 `up` 的最大可行走坡度,弧度(45°)。 |+| `maxSlides` | number | `4` | 每次移动的滑动迭代次数(拐角需要更多)。 |+| `skinWidth` | number | `1` | 与表面保持的间隙(px),避免粘住。 |+| `snapLength` | number | `0` | 向下探测(px)以贴住斜坡/台阶;`0` = 关。 |+| `slideOnCeiling` | boolean | `true` | 沿天花板滑动 vs 停止移动。 |+| `maskBits` | number | `0xFFFF` | 阻挡角色的层。 |+| `isOnFloor` / `isOnWall` / `isOnCeiling` | boolean | — | **输出**:这次移动碰到了什么。 |+| `floorNormal` | Vec2 | — | **输出**:最后接触地面的法线。 |+| `realVelocity` | Vec2 | — | **输出**:碰撞后的实际位移 / dt。 |++## 最佳实践++- **固定时间步**:*每帧*施加持续力、读 `PhysicsEvents`,因为物理独立于帧 delta 做子步。+- 快速细小刚体(子弹、薄平台)用 **`bullet: true`** 防穿透。+- 角色用 **`fixedRotation: true`** 免得翻倒。+- **碰撞体用米**(÷ PPU),但**查询和角色控制器用像素**——混用是最常见的 bug。+- **触发器用传感器**:`isSensor: true` 给出 enter/exit 事件而无物理推挤。+- **用层过滤**(`categoryBits` / `maskBits`),而不是在事件处理里判断实体类型。++## 参见++- [场景](/docs/zh-cn/guides/scene/) —— 物理组件随场景序列化。+- [数学辅助](/docs/zh-cn/guides/math/) —— 速度与方向的向量运算。