物理组件

下面每个字段都由引擎自身的组件注册表推导而来——就是编辑器 Details 面板读的那一份—— 所以这里的类型和默认值就是你添加组件时真正拿到的值，且不可能与代码脱节。讲怎么用的正文在每条目所链接的指南里。字段说明取自 C++ ES_PROPERTY 处的原文，因此为英文。

`BoxCollider`

A rectangular collision shape. Sizes are in **metres**, not pixels.

Explained in gameplay/physics.

Field	Type	Default	Notes
`halfExtents`	`Vec2`	`(0.5, 0.5)`
`offset`	`Vec2`	`(0, 0)`
`radius`	`number`	`0.05`
`density`	`number`	`1`
`friction`	`number`	`0.3`
`restitution`	`number`	`0`
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`

`BoxCollider3D`

A box collision shape in 3D. Half-extents are in world units.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`halfExtents`	`Vec3`	`(0.5, 0.5, 0.5)`
`friction`	`number`	`0.3`	Range ≥ 0.
`restitution`	`number`	`0`	Range 0–1.
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`

`CapsuleCollider`

A capsule collision shape — the usual choice for a character body.

Explained in gameplay/physics.

Field	Type	Default	Notes
`radius`	`number`	`0.25`
`halfHeight`	`number`	`0.5`
`offset`	`Vec2`	`(0, 0)`
`density`	`number`	`1`
`friction`	`number`	`0.3`
`restitution`	`number`	`0`
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`

`CapsuleCollider3D`

An upright capsule — what a 3D character is. Total height is 2*(halfHeight + radius).

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`radius`	`number`	`0.3`	Range ≥ 0.
`halfHeight`	`number`	`0.5`	Range ≥ 0.
`friction`	`number`	`0.3`	Range ≥ 0.
`restitution`	`number`	`0`	Range 0–1.
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`

`ChainCollider`

A polyline of edges — open or looped — for static terrain.

Explained in gameplay/physics.

Field	Type	Default	Notes
`points`	`Vec2[]`	`[{"x":-1,"y":0},{"x":0,"y":0.5},{"x":1,"y":0},{"x":0,"y":-0.5}]`
`isLoop`	`boolean`	`true`
`friction`	`number`	`0.6`
`restitution`	`number`	`0`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`
`enabled`	`boolean`	`true`

`CharacterController`

Kinematic character movement that slides along walls, climbs slopes and reports ground contact.

Explained in gameplay/physics.

Field	Type	Default	Notes
`velocity`	`Vec2`	`(0, 0)`
`up`	`Vec2`	`(0, 1)`
`floorMaxAngle`	`number`	`0.7854`	Max walkable slope from up (radians) Range 0–1.5708, step 0.01.
`maxSlides`	`number`	`4`	Range 1–8, step 1.
`skinWidth`	`number`	`1`	Range ≥ 0, step 0.25.
`snapLength`	`number`	`0`	Floor-snap probe length; 0 disables stair/slope stick Range ≥ 0, step 0.5.
`slideOnCeiling`	`boolean`	`true`
`maskBits`	`number`	`65535`
`isOnFloor`	`boolean`	`false`
`isOnWall`	`boolean`	`false`
`isOnCeiling`	`boolean`	`false`
`floorNormal`	`Vec2`	`(0, 0)`
`realVelocity`	`Vec2`	`(0, 0)`

`CharacterController3D`

A kinematic 3D mover: swept against the world, climbs steps, stays glued to slopes, and reports the ground it is on.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`velocity`	`Vec3`	`(0, 0, 0)`
`radius`	`number`	`0.3`	Range ≥ 0.
`halfHeight`	`number`	`0.5`	Range ≥ 0.
`maxSlope`	`number`	`0.87`	Steepest ground it can stand on Range 0–1.5708, step 0.01.
`layer`	`number`	`0`	Range 0–15, step 1.
`stepHeight`	`number`	`0.4`	Range ≥ 0, step 0.05.
`snapDown`	`number`	`0.5`	Range ≥ 0, step 0.05.
`mass`	`number`	`70`	Range ≥ 0.
`pushForce`	`number`	`5000`	How hard it can shove what it walks into Range ≥ 0.
`enabled`	`boolean`	`true`
`isOnFloor`	`boolean`	`false`
`floorNormal`	`Vec3`	`(0, 0, 0)`
`realVelocity`	`Vec3`	`(0, 0, 0)`

`CircleCollider`

A circular collision shape. Radius is in **metres**.

Explained in gameplay/physics.

Field	Type	Default	Notes
`radius`	`number`	`0.5`
`offset`	`Vec2`	`(0, 0)`
`density`	`number`	`1`
`friction`	`number`	`0.3`
`restitution`	`number`	`0`
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`

`ConvexCollider3D`

Collides against the convex hull of an imported mesh — the shape a solver can push, unlike a mesh collider.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`mesh`	`Asset<mesh>`	`none`	Geometry (.esmesh) whose convex hull collides.
`friction`	`number`	`0.3`	Range ≥ 0.
`restitution`	`number`	`0`	Range 0–1.
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`

`DistanceJoint`

Holds two bodies a fixed (or spring-limited) distance apart.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchorA`	`Vec2`	`(0, 0)`
`anchorB`	`Vec2`	`(0, 0)`
`length`	`number`	`1`
`enableSpring`	`boolean`	`false`
`hertz`	`number`	`1`
`dampingRatio`	`number`	`0.5`
`enableLimit`	`boolean`	`false`
`minLength`	`number`	`0.5`
`maxLength`	`number`	`2`
`enableMotor`	`boolean`	`false`
`maxMotorForce`	`number`	`0`
`motorSpeed`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`DistanceJoint3D`

Keeps two 3D bodies a distance apart: a rope, a rod, or a spring when a frequency is given.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchor`	`Vec3`	`(0, 0, 0)`
`connectedAnchor`	`Vec3`	`(0, 0, 0)`
`minLength`	`number`	`0`
`maxLength`	`number`	`100`
`frequency`	`number`	`0`
`damping`	`number`	`0.5`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`FixedJoint3D`

Locks two 3D bodies together in the pose they were placed in — no freedom at all.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`HingeJoint3D`

One axis of rotation between two 3D bodies — a door or a driven wheel, with optional limits and a motor.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchor`	`Vec3`	`(0, 0, 0)`
`axis`	`Vec3`	`(0, 1, 0)`
`enableLimit`	`boolean`	`false`
`lowerAngle`	`number`	`-1.5708`
`upperAngle`	`number`	`1.5708`
`enableMotor`	`boolean`	`false`
`motorSpeed`	`number`	`0`
`maxMotorTorque`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`
`angle`	`number`	`0`

`MeshCollider3D`

Collides against an imported mesh’s own triangles — terrain, stairs, a room. Always static, and one-sided.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`mesh`	`Asset<mesh>`	`none`	Geometry (.esmesh) to collide against.
`layer`	`number`	`0`	Range 0–15.
`friction`	`number`	`0.3`	Range ≥ 0.
`restitution`	`number`	`0`	Range 0–1.
`enabled`	`boolean`	`true`

`MotorJoint`

Drives one body toward a target offset and angle — moving platforms and conveyors.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`linearVelocity`	`Vec2`	`(0, 0)`
`maxVelocityForce`	`number`	`0`
`angularVelocity`	`number`	`0`
`maxVelocityTorque`	`number`	`0`
`linearHertz`	`number`	`0`
`linearDampingRatio`	`number`	`0`
`maxSpringForce`	`number`	`0`
`angularHertz`	`number`	`0`
`angularDampingRatio`	`number`	`0`
`maxSpringTorque`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`OneWayPlatform`

Makes a collider solid from one side only, so a body passes up through it and lands on top.

Explained in gameplay/physics.

Field	Type	Default	Notes
`normal`	`Vec2`	`(0, 1)`
`enabled`	`boolean`	`true`

`PointJoint3D`

Holds two 3D bodies at a shared point, free to turn on all three axes — a chain link, a ragdoll limb.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchor`	`Vec3`	`(0, 0, 0)`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`PolygonCollider`

A convex polygon collision shape from your own points.

Explained in gameplay/physics.

Field	Type	Default	Notes
`vertices`	`Vec2[]`	`[{"x":-0.5,"y":-0.5},{"x":0.5,"y":-0.5},{"x":0.5,"y":0.5},{"x":-0.5,"y":0.5}]`
`radius`	`number`	`0`
`density`	`number`	`1`
`friction`	`number`	`0.3`
`restitution`	`number`	`0`
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`

`PrismaticJoint`

Constrains two bodies to slide along one axis — a piston or lift.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchorA`	`Vec2`	`(0, 0)`
`anchorB`	`Vec2`	`(0, 0)`
`axis`	`Vec2`	`(1, 0)`
`enableSpring`	`boolean`	`false`
`hertz`	`number`	`1`
`dampingRatio`	`number`	`0.5`
`enableLimit`	`boolean`	`false`
`lowerTranslation`	`number`	`0`
`upperTranslation`	`number`	`0`
`enableMotor`	`boolean`	`false`
`maxMotorForce`	`number`	`0`
`motorSpeed`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`RevoluteJoint`

Pins two bodies at a point and lets them rotate — a hinge, with optional limits and a motor.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchorA`	`Vec2`	`(0, 0)`
`anchorB`	`Vec2`	`(0, 0)`
`enableMotor`	`boolean`	`false`
`motorSpeed`	`number`	`0`
`maxMotorTorque`	`number`	`0`
`enableLimit`	`boolean`	`false`
`lowerAngle`	`number`	`0`
`upperAngle`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`RigidBody`

Puts the entity under the solver: static, kinematic or dynamic, with damping, gravity scale and sleep.

Explained in gameplay/physics.

Field	Type	Default	Notes
`bodyType`	`enum`	`Dynamic`	One of `Static`, `Kinematic`, `Dynamic`.
`gravityScale`	`number`	`1`
`linearDamping`	`number`	`0`	Range ≥ 0.
`angularDamping`	`number`	`0`	Range ≥ 0.
`fixedRotation`	`boolean`	`false`
`bullet`	`boolean`	`false`
`enabled`	`boolean`	`true`

`RigidBody3D`

Puts the entity under the 3D solver — its own component set, so a 2D scene keeps the world it already has.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`bodyType`	`enum`	`Dynamic`	One of `Static`, `Kinematic`, `Dynamic`.
`layer`	`number`	`0`	Range 0–15.
`gravityScale`	`number`	`1`	Range ≥ 0.
`linearDamping`	`number`	`0.05`	Range ≥ 0.
`angularDamping`	`number`	`0.05`	Range ≥ 0.
`fixedRotation`	`boolean`	`false`
`continuousCollision`	`boolean`	`false`	Check the whole path a step covers — what a bullet needs
`enabled`	`boolean`	`true`

`SegmentCollider`

A single line segment — a one-sided wall or edge.

Explained in gameplay/physics.

Field	Type	Default	Notes
`point1`	`Vec2`	`(-0.5, 0)`
`point2`	`Vec2`	`(0.5, 0)`
`density`	`number`	`1`
`friction`	`number`	`0.3`
`restitution`	`number`	`0`
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`
`categoryBits`	`number`	`1`
`maskBits`	`number`	`65535`

`SliderJoint3D`

One axis of travel between two 3D bodies — a lift or a piston, with optional limits and a motor.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchor`	`Vec3`	`(0, 0, 0)`
`axis`	`Vec3`	`(0, 1, 0)`
`enableLimit`	`boolean`	`false`
`lowerTranslation`	`number`	`-100`
`upperTranslation`	`number`	`100`
`enableMotor`	`boolean`	`false`
`motorSpeed`	`number`	`0`
`maxMotorForce`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`
`translation`	`number`	`0`

`SphereCollider3D`

A sphere collision shape in 3D.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
`radius`	`number`	`0.5`	Range ≥ 0.
`friction`	`number`	`0.3`	Range ≥ 0.
`restitution`	`number`	`0`	Range 0–1.
`isSensor`	`boolean`	`false`
`enabled`	`boolean`	`true`

`WeldJoint`

Locks two bodies rigidly together, with optional spring give.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchorA`	`Vec2`	`(0, 0)`
`anchorB`	`Vec2`	`(0, 0)`
`linearHertz`	`number`	`0`
`angularHertz`	`number`	`0`
`linearDampingRatio`	`number`	`1`
`angularDampingRatio`	`number`	`1`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`

`WheelJoint`

A suspension axis plus a spinning axle — the wheel half of a vehicle.

Explained in gameplay/physics.

Field	Type	Default	Notes
`connectedEntity`	`Entity`	`-1`
`anchorA`	`Vec2`	`(0, 0)`
`anchorB`	`Vec2`	`(0, 0)`
`axis`	`Vec2`	`(0, 1)`
`enableSpring`	`boolean`	`true`
`hertz`	`number`	`5`
`dampingRatio`	`number`	`0.7`
`enableLimit`	`boolean`	`false`
`lowerTranslation`	`number`	`0`
`upperTranslation`	`number`	`0`
`enableMotor`	`boolean`	`false`
`maxMotorTorque`	`number`	`0`
`motorSpeed`	`number`	`0`
`collideConnected`	`boolean`	`false`
`enabled`	`boolean`	`true`