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: correct the physics guide against real SDK API
yhhde6385170bc7
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/guides/physics.mdxindex 44cef6191..6a2224366 100644--- a/docs/astro/src/content/docs/guides/physics.mdx+++ b/docs/astro/src/content/docs/guides/physics.mdx@@ -1,15 +1,19 @@---title: Physics-description: Rigid bodies, colliders, forces, queries, and collision events.+description: Rigid bodies, colliders, forces, and collision events.---import { Aside } from '@astrojs/starlight/components';-Estella's physics runs in the C++/WebAssembly core. You add the physics plugin,-attach a `RigidBody` and a collider to an entity, and drive or query it through-the `Physics` API.+Estella's physics runs in the C++/WebAssembly core (Box2D). You attach a+`RigidBody` and a collider to an entity, and drive or read it through the+physics resources.-## Enable physics+## Enabling physics++Physics is a loadable module. In the editor and the web runtime it loads+automatically when a scene uses physics components — you don't wire anything up.+In a custom app you can add it yourself:```typescriptimport { PhysicsPlugin } from 'esengine/physics';@@ -19,37 +23,42 @@ app.addPlugin(new PhysicsPlugin('physics.js', {}));```-The module loads asynchronously; physics is ready once its init settles.-## Bodies and colliders-Attach a `RigidBody` plus one collider shape. **Collider dimensions are in-meters, not pixels** — divide pixel sizes by your pixels-per-unit (PPU):+Attach a `RigidBody` plus one collider. **Collider dimensions are in meters, not+pixels** — divide pixel sizes by your pixels-per-unit (PPU). Spawn entities from+a system that takes `Commands()`:```typescript-import { RigidBody, BodyType, CircleCollider, BoxCollider } from 'esengine';+import {+ defineSystem, Commands, Transform,+ RigidBody, BodyType, CircleCollider,+} from 'esengine';const PPU = 100;-cmds.spawn()- .insert(Transform, { position: { x, y, z: 0 } })- .insert(RigidBody, { bodyType: BodyType.Dynamic })- .insert(CircleCollider, { radius: 24 / PPU, restitution: 0.4 });+const spawnBall = defineSystem([Commands()], (cmds) => {+ cmds.spawn()+ .insert(Transform, { position: { x: 0, y: 250, z: 0 } })+ .insert(RigidBody, { bodyType: BodyType.Dynamic })+ .insert(CircleCollider, { radius: 24 / PPU, restitution: 0.4 });+});```- **`BodyType`** — `Static` (immovable), `Kinematic` (moved by you), `Dynamic`(moved by the simulation).-- **Collider shapes** — `BoxCollider`, `CircleCollider`, `CapsuleCollider`,- `SegmentCollider`, `PolygonCollider`, `ChainCollider`. All share `density`,- `friction`, `restitution`, `isSensor`, `categoryBits`, `maskBits`.+- **Collider shapes** (from `esengine`) — `BoxCollider`, `CircleCollider`,+ `CapsuleCollider`, `SegmentCollider`, `PolygonCollider`, `ChainCollider`. They+ share `density`, `friction`, `restitution`, `isSensor`, `categoryBits`,+ `maskBits`.- **Joints** — `RevoluteJoint`, `DistanceJoint`, `PrismaticJoint`, `WeldJoint`,`WheelJoint`.## Collision layers-`categoryBits` (what layer this 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:+`categoryBits` (what layer a body is on) and `maskBits` (what it collides with)+are bit filters. Two bodies collide only if each one's category is in the+other's mask:```typescriptconst LAYER_PLAYER = 0x0001;@@ -62,38 +71,45 @@ const LAYER_GROUND = 0x0008;});```-## Forces, velocity, and queries+## Forces and velocity-Read the `Physics` resource in a system to push bodies and query the world:+Read the `PhysicsAPI` resource in a system to push bodies around:```typescript-import { defineSystem, Res, Physics } from 'esengine';+import { defineSystem, Res } from 'esengine';+import { PhysicsAPI } from 'esengine/physics';-defineSystem([Res(Physics)], (physics) => {- physics.applyImpulse(player, { x: 0, y: 5 }); // jump- physics.setLinearVelocity(player, { x: 3, y: 0 });-- // Queries take pixel-space and auto-scale by PPU.- const hits = physics.raycast(origin, direction, 200);- const inRange = physics.overlapCircle(center, 64);+const push = defineSystem([Res(PhysicsAPI)], (physics) => {+ physics.applyImpulse(entity, { x: 0, y: 5 }); // jump+ physics.setLinearVelocity(entity, { x: 3, y: 0 });+ physics.applyTorque(entity, 2);});```+`PhysicsAPI` also exposes `applyForce`, `getLinearVelocity`, `setGravity` /+`getGravity`, angular variants, and spatial queries (raycast / overlap) that take+pixel-space arguments and scale by the live PPU.+## Collision eventsThe `PhysicsEvents` resource carries this frame's contacts:```typescript-import { PhysicsEvents } from 'esengine';--defineSystem([Res(PhysicsEvents)], (events) => {- for (const c of events.collisionEnters) { /* c.entityA, c.entityB */ }- for (const s of events.sensorEnters) { /* trigger volumes */ }+import { 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, c.normalY, c.contactX, c.contactY+ }+ for (const s of events.sensorEnters) {+ // s.sensorEntity, s.visitorEntity+ }});```<Aside type="caution">- Set `isSensor: true` on a collider to get enter/exit events **without** a- physical response (trigger zones). Physics steps at a fixed timestep, not the+ Set `isSensor: true` on a collider to get sensor enter/exit events **without**+ a physical response (trigger zones). Physics steps at a fixed timestep, not theframe delta, so read `PhysicsEvents` every frame.</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/guides/physics.mdxindex 9f072385f..86826adf9 100644--- a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/physics.mdx@@ -1,15 +1,18 @@---title: 物理-description: 刚体、碰撞体、力、查询与碰撞事件。+description: 刚体、碰撞体、力与碰撞事件。---import { Aside } from '@astrojs/starlight/components';-Estella 的物理运行在 C++/WebAssembly 内核中。你添加物理插件,给实体挂上 `RigidBody`-和一个碰撞体,再通过 `Physics` API 驱动或查询它。+Estella 的物理运行在 C++/WebAssembly 内核中(Box2D)。你给实体挂上 `RigidBody` 和一个+碰撞体,再通过物理资源来驱动或读取它。## 启用物理+物理是一个可加载模块。在编辑器和 Web 运行时中,当场景用到物理组件时它会**自动加载**+——你无需接线。在自定义 App 里你也可以自己添加:+```typescriptimport { PhysicsPlugin } from 'esengine/physics';@@ -18,36 +21,39 @@ app.addPlugin(new PhysicsPlugin('physics.js', {}));```-模块异步加载;初始化完成后物理即就绪。-## 刚体与碰撞体-挂上一个 `RigidBody` 加一个碰撞体形状。**碰撞体尺寸的单位是米,不是像素**——把像素-尺寸除以你的「每单位像素数」(PPU):+挂上一个 `RigidBody` 加一个碰撞体。**碰撞体尺寸的单位是米,不是像素**——把像素尺寸+除以你的「每单位像素数」(PPU)。在带 `Commands()` 参数的系统里生成实体:```typescript-import { RigidBody, BodyType, CircleCollider, BoxCollider } from 'esengine';+import {+ defineSystem, Commands, Transform,+ RigidBody, BodyType, CircleCollider,+} from 'esengine';const PPU = 100;-cmds.spawn()- .insert(Transform, { position: { x, y, z: 0 } })- .insert(RigidBody, { bodyType: BodyType.Dynamic })- .insert(CircleCollider, { radius: 24 / PPU, restitution: 0.4 });+const spawnBall = defineSystem([Commands()], (cmds) => {+ cmds.spawn()+ .insert(Transform, { position: { x: 0, y: 250, z: 0 } })+ .insert(RigidBody, { bodyType: BodyType.Dynamic })+ .insert(CircleCollider, { radius: 24 / PPU, restitution: 0.4 });+});```-- **`BodyType`** —— `Static`(不可移动)、`Kinematic`(由你移动)、`Dynamic`(由模拟- 驱动)。-- **碰撞体形状** —— `BoxCollider`、`CircleCollider`、`CapsuleCollider`、- `SegmentCollider`、`PolygonCollider`、`ChainCollider`。都带 `density`、`friction`、- `restitution`、`isSensor`、`categoryBits`、`maskBits`。+- **`BodyType`** —— `Static`(不可移动)、`Kinematic`(由你移动)、`Dynamic`(由模拟+ 驱动)。+- **碰撞体形状**(来自 `esengine`)—— `BoxCollider`、`CircleCollider`、+ `CapsuleCollider`、`SegmentCollider`、`PolygonCollider`、`ChainCollider`。它们共享+ `density`、`friction`、`restitution`、`isSensor`、`categoryBits`、`maskBits`。- **关节** —— `RevoluteJoint`、`DistanceJoint`、`PrismaticJoint`、`WeldJoint`、`WheelJoint`。## 碰撞层-`categoryBits`(该刚体所在的层)与 `maskBits`(它会与哪些层碰撞)是 16 位过滤器。-两个刚体只有在各自的 category 都落在对方的 mask 里时才会碰撞:+`categoryBits`(刚体所在的层)与 `maskBits`(它会与哪些层碰撞)是位过滤器。两个刚体+只有在各自的 category 都落在对方的 mask 里时才会碰撞:```typescriptconst LAYER_PLAYER = 0x0001;@@ -60,37 +66,44 @@ const LAYER_GROUND = 0x0008;});```-## 力、速度与查询+## 力与速度-在系统里读取 `Physics` 资源,推动刚体并查询世界:+在系统里读取 `PhysicsAPI` 资源来推动刚体:```typescript-import { defineSystem, Res, Physics } from 'esengine';+import { defineSystem, Res } from 'esengine';+import { PhysicsAPI } from 'esengine/physics';-defineSystem([Res(Physics)], (physics) => {- physics.applyImpulse(player, { x: 0, y: 5 }); // 跳跃- physics.setLinearVelocity(player, { x: 3, y: 0 });-- // 查询以像素为单位,自动按 PPU 缩放。- const hits = physics.raycast(origin, direction, 200);- const inRange = physics.overlapCircle(center, 64);+const push = defineSystem([Res(PhysicsAPI)], (physics) => {+ physics.applyImpulse(entity, { x: 0, y: 5 }); // 跳跃+ physics.setLinearVelocity(entity, { x: 3, y: 0 });+ physics.applyTorque(entity, 2);});```+`PhysicsAPI` 还提供 `applyForce`、`getLinearVelocity`、`setGravity` / `getGravity`、+角速度相关方法,以及空间查询(raycast / overlap)——查询接受像素单位参数,并按实时 PPU+缩放。+## 碰撞事件-`PhysicsEvents` 资源携带当前帧的接触信息:+`PhysicsEvents` 资源携带当前帧的接触信息:```typescript-import { PhysicsEvents } from 'esengine';--defineSystem([Res(PhysicsEvents)], (events) => {- for (const c of events.collisionEnters) { /* c.entityA, c.entityB */ }- for (const s of events.sensorEnters) { /* 触发体 */ }+import { 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、c.normalY、c.contactX、c.contactY+ }+ for (const s of events.sensorEnters) {+ // s.sensorEntity、s.visitorEntity+ }});```<Aside type="caution">- 给碰撞体设 `isSensor: true`,可以在**没有物理响应**的情况下获得进入/离开事件- (触发区)。物理按固定时间步进,而不是帧间隔,所以每帧都要读 `PhysicsEvents`。+ 给碰撞体设 `isSensor: true`,可以在**没有物理响应**的情况下获得传感器进入/离开事件+ (触发区)。物理按固定时间步进,而不是帧间隔,所以每帧都要读 `PhysicsEvents`。</Aside>