物理组件

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

BoxCollider2DBoxCollider3DCapsuleCollider2DCapsuleCollider3DChainCollider2DCharacterController2DCharacterController3DCircleCollider2DConvexCollider3DDistanceJoint2DDistanceJoint3DFixedJoint2DFixedJoint3DHealthHingeJoint2DHingeJoint3DHunterMeleeAttackMeshCollider3DMotorJoint2DOneWayPlatform2DPointJoint3DPolygonCollider2DRigidBody2DRigidBody3DSegmentCollider2DSliderJoint2DSliderJoint3DSphereCollider3DThirdPersonCameraThirdPersonControllerWheelJoint2D

BoxCollider2D

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

CapsuleCollider2D

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

ChainCollider2D

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

CharacterController2D

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)

CircleCollider2D

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

DistanceJoint2D

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)	Where the joint attaches on the connected body, in that body's frame (pixels).
anchorB	Vec2	(0, 0)	Where it attaches on this entity, in its own frame (pixels).
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

FixedJoint2D

Locks two bodies rigidly together, with optional spring give.

Explained in gameplay/physics.

Field	Type	Default	Notes
connectedEntity	Entity	-1
anchorA	Vec2	(0, 0)	Where the joint attaches on the connected body, in that body's frame (pixels).
anchorB	Vec2	(0, 0)	Where it attaches on this entity, in its own frame (pixels).
linearHertz	number	0
angularHertz	number	0
linearDampingRatio	number	1
angularDampingRatio	number	1
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

Health

What something has left, and what makes it damageable at all — written only by the system that answers the Damage bus.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
current	number	100	Range ≥ 0.
max	number	100	Range ≥ 0.

HingeJoint2D

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)	Where the joint attaches on the connected body, in that body's frame (pixels).
anchorB	Vec2	(0, 0)	Where it attaches on this entity, in its own frame (pixels).
enableMotor	boolean	false
motorSpeed	number	0
maxMotorTorque	number	0
enableLimit	boolean	false
lowerAngle	number	0
upperAngle	number	0
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)	Where the joint attaches, in THIS entity's frame (world units).
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

Hunter

A character that hunts what it perceives: it asks navigation for a route, the character controller for the movement, and the animator for a swing — the concrete twin of ThirdPersonController.

Explained in gameplay/ai/overview.

Field	Type	Default	Notes
attackRange	number	110	How close it gets before it swings. Range ≥ 0.
attackInterval	number	1.6	Range ≥ 0.
rotationSpeed	number	540	Range ≥ 0.
idleThreshold	number	8	Range ≥ 0, step 0.05.
enabled	boolean	true
state	string	"idle"	Read-only — the engine computes it.
cooldown	number	0	Read-only — the engine computes it.

MeleeAttack

A swing whose timing is the animation’s and whose reach is the physics world’s: a `hit` beat asks what is around an animated anchor, and gameplay decides who may be hurt.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
radius	number	60	Range ≥ 0.
damage	number	25	Range ≥ 0.
layers	number	0	Range 0–15, step 1.
anchor	Entity	none	The animated socket the swing reaches from.
enabled	boolean	true
attackId	number	0	Read-only — the engine computes it.
hitCount	number	0	Read-only — the engine computes it.

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

MotorJoint2D

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

OneWayPlatform2D

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)	Where the joint attaches, in THIS entity's frame (world units).
collideConnected	boolean	false
enabled	boolean	true

PolygonCollider2D

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

RigidBody2D

Puts the entity under the flat 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

SegmentCollider2D

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

SliderJoint2D

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)	Where the joint attaches on the connected body, in that body's frame (pixels).
anchorB	Vec2	(0, 0)	Where it attaches on this entity, in its own frame (pixels).
axis	Vec2	(1, 0)	Direction of travel, in the connected body's frame.
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

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)	Where the joint attaches, in THIS entity's frame (world units).
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

ThirdPersonCamera

An eye that orbits a target under pointer control and pulls in when something solid stands between.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
target	Entity	none	The transform this camera orbits.
distance	number	420
yaw	number	0
pitch	number	15
minPitch	number	-30
maxPitch	number	70
sensitivity	number	0.2
followDamping	number	12	Range ≥ 0.
targetOffset	Vec3	(0, 90, 0)
obstruction	boolean	true
obstructionRadius	number	15	Range ≥ 0.
obstructionLayers	number	0	Range 0–15, step 1.
enabled	boolean	true

ThirdPersonController

Turns input into a movement request for a CharacterController3D, and reports what the character actually did to its Animator.

Explained in gameplay/physics-3d.

Field	Type	Default	Notes
moveSpeed	number	320
acceleration	number	2400
deceleration	number	3200
rotationSpeed	number	720
jumpSpeed	number	0	Upward speed a jump starts with. 0 = cannot jump. Range ≥ 0.
airControl	number	0.3	Range 0–1, step 0.05.
cameraRelative	boolean	true
camera	Entity	none	Whose forward the stick is read against.
idleThreshold	number	8	Range ≥ 0, step 0.05.
enabled	boolean	true

WheelJoint2D

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)	Where the joint attaches on the connected body, in that body's frame (pixels).
anchorB	Vec2	(0, 0)	Where it attaches on this entity, in its own frame (pixels).
axis	Vec2	(0, 1)	Direction of travel, in the connected body's frame.
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