Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

PhysicsServer2D

继承: Object

派生: PhysicsServer2DExtension

用于访问低阶 2D 物理的服务器接口。

描述

PhysicsServer2D 是负责所有 2D 物理的服务器。它可以直接创建和操作所有物理对象:

  • Space(空间)是用于物理仿真的自包含世界。它包含实体、区域和关节。可以对其状态进行查询,获取碰撞和相交信息,并且可以修改部分仿真参数。

  • Shape(形状)是圆形、矩形、胶囊形、多边形等几何形状。加入到实体/区域中就可以用来进行碰撞检测,还可以带有相对于实体/区域原点的额外变换。实体/区域中可以添加多个(变换后的)形状,并且可以使用不同的局部变换将单个形状多次添加到实体/区域中。

  • Body(实体)是物理对象,可以处于静态、运动学或刚性模式。可以对其状态进行查询和更新(例如位置、速度等)。可以设置力的集成回调,自定义实体的物理特性。

  • Area(区域)是空间中的区块,可用于检测进入和离开它的实体和区域。可以设置实体的监视回调,报告进入/离开的实体形状,同样可以设置区域的监视回调。通过设置区域参数,可以在区域内覆盖重力和阻尼。

  • Joint(关节)是两个实体之间或一个实体相对于某个点的约束。可以调整关节偏置和弹簧关节的放松长度等参数。

PhysicsServer2D 中的物理对象可以独立创建和操作;不必将它们绑定到场景树中的节点。

注意:所有 2D 物理节点都在内部使用这个物理服务器。将物理节点添加到场景树,就会导致在物理服务器中创建相应的物理对象。刚体节点会注册回调,该回调会(在每次物理更新时)使用物理服务器中相应实体对象的变换更新该节点的变换。区域节点会注册回调,用来通知区域节点与物理服务器中相应区域对象的重叠。射线投射节点会查询物理服务器中相关空间的直接状态。

方法

void

area_add_shape ( RID area, RID shape, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), bool disabled=false )

void

area_attach_canvas_instance_id ( RID area, int id )

void

area_attach_object_instance_id ( RID area, int id )

void

area_clear_shapes ( RID area )

RID

area_create ( )

int

area_get_canvas_instance_id ( RID area ) const

int

area_get_collision_layer ( RID area ) const

int

area_get_collision_mask ( RID area ) const

int

area_get_object_instance_id ( RID area ) const

Variant

area_get_param ( RID area, AreaParameter param ) const

RID

area_get_shape ( RID area, int shape_idx ) const

int

area_get_shape_count ( RID area ) const

Transform2D

area_get_shape_transform ( RID area, int shape_idx ) const

RID

area_get_space ( RID area ) const

Transform2D

area_get_transform ( RID area ) const

void

area_remove_shape ( RID area, int shape_idx )

void

area_set_area_monitor_callback ( RID area, Callable callback )

void

area_set_collision_layer ( RID area, int layer )

void

area_set_collision_mask ( RID area, int mask )

void

area_set_monitor_callback ( RID area, Callable callback )

void

area_set_monitorable ( RID area, bool monitorable )

void

area_set_param ( RID area, AreaParameter param, Variant value )

void

area_set_shape ( RID area, int shape_idx, RID shape )

void

area_set_shape_disabled ( RID area, int shape_idx, bool disabled )

void

area_set_shape_transform ( RID area, int shape_idx, Transform2D transform )

void

area_set_space ( RID area, RID space )

void

area_set_transform ( RID area, Transform2D transform )

void

body_add_collision_exception ( RID body, RID excepted_body )

void

body_add_constant_central_force ( RID body, Vector2 force )

void

body_add_constant_force ( RID body, Vector2 force, Vector2 position=Vector2(0, 0) )

void

body_add_constant_torque ( RID body, float torque )

void

body_add_shape ( RID body, RID shape, Transform2D transform=Transform2D(1, 0, 0, 1, 0, 0), bool disabled=false )

void

body_apply_central_force ( RID body, Vector2 force )

void

body_apply_central_impulse ( RID body, Vector2 impulse )

void

body_apply_force ( RID body, Vector2 force, Vector2 position=Vector2(0, 0) )

void

body_apply_impulse ( RID body, Vector2 impulse, Vector2 position=Vector2(0, 0) )

void

body_apply_torque ( RID body, float torque )

void

body_apply_torque_impulse ( RID body, float impulse )

void

body_attach_canvas_instance_id ( RID body, int id )

void

body_attach_object_instance_id ( RID body, int id )

void

body_clear_shapes ( RID body )

RID

body_create ( )

int

body_get_canvas_instance_id ( RID body ) const

int

body_get_collision_layer ( RID body ) const

int

body_get_collision_mask ( RID body ) const

float

body_get_collision_priority ( RID body ) const

Vector2

body_get_constant_force ( RID body ) const

float

body_get_constant_torque ( RID body ) const

CCDMode

body_get_continuous_collision_detection_mode ( RID body ) const

PhysicsDirectBodyState2D

body_get_direct_state ( RID body )

int

body_get_max_contacts_reported ( RID body ) const

BodyMode

body_get_mode ( RID body ) const

int

body_get_object_instance_id ( RID body ) const

Variant

body_get_param ( RID body, BodyParameter param ) const

RID

body_get_shape ( RID body, int shape_idx ) const

int

body_get_shape_count ( RID body ) const

Transform2D

body_get_shape_transform ( RID body, int shape_idx ) const

RID

body_get_space ( RID body ) const

Variant

body_get_state ( RID body, BodyState state ) const

bool

body_is_omitting_force_integration ( RID body ) const

void

body_remove_collision_exception ( RID body, RID excepted_body )

void

body_remove_shape ( RID body, int shape_idx )

void

body_reset_mass_properties ( RID body )

void

body_set_axis_velocity ( RID body, Vector2 axis_velocity )

void

body_set_collision_layer ( RID body, int layer )

void

body_set_collision_mask ( RID body, int mask )

void

body_set_collision_priority ( RID body, float priority )

void

body_set_constant_force ( RID body, Vector2 force )

void

body_set_constant_torque ( RID body, float torque )

void

body_set_continuous_collision_detection_mode ( RID body, CCDMode mode )

void

body_set_force_integration_callback ( RID body, Callable callable, Variant userdata=null )

void

body_set_max_contacts_reported ( RID body, int amount )

void

body_set_mode ( RID body, BodyMode mode )

void

body_set_omit_force_integration ( RID body, bool enable )

void

body_set_param ( RID body, BodyParameter param, Variant value )

void

body_set_shape ( RID body, int shape_idx, RID shape )

void

body_set_shape_as_one_way_collision ( RID body, int shape_idx, bool enable, float margin )

void

body_set_shape_disabled ( RID body, int shape_idx, bool disabled )

void

body_set_shape_transform ( RID body, int shape_idx, Transform2D transform )

void

body_set_space ( RID body, RID space )

void

body_set_state ( RID body, BodyState state, Variant value )

bool

body_test_motion ( RID body, PhysicsTestMotionParameters2D parameters, PhysicsTestMotionResult2D result=null )

RID

capsule_shape_create ( )

RID

circle_shape_create ( )

RID

concave_polygon_shape_create ( )

RID

convex_polygon_shape_create ( )

float

damped_spring_joint_get_param ( RID joint, DampedSpringParam param ) const

void

damped_spring_joint_set_param ( RID joint, DampedSpringParam param, float value )

void

free_rid ( RID rid )

int

get_process_info ( ProcessInfo process_info )

void

joint_clear ( RID joint )

RID

joint_create ( )

void

joint_disable_collisions_between_bodies ( RID joint, bool disable )

float

joint_get_param ( RID joint, JointParam param ) const

JointType

joint_get_type ( RID joint ) const

bool

joint_is_disabled_collisions_between_bodies ( RID joint ) const

void

joint_make_damped_spring ( RID joint, Vector2 anchor_a, Vector2 anchor_b, RID body_a, RID body_b=RID() )

void

joint_make_groove ( RID joint, Vector2 groove1_a, Vector2 groove2_a, Vector2 anchor_b, RID body_a=RID(), RID body_b=RID() )

void

joint_make_pin ( RID joint, Vector2 anchor, RID body_a, RID body_b=RID() )

void

joint_set_param ( RID joint, JointParam param, float value )

bool

pin_joint_get_flag ( RID joint, PinJointFlag flag ) const

float

pin_joint_get_param ( RID joint, PinJointParam param ) const

void

pin_joint_set_flag ( RID joint, PinJointFlag flag, bool enabled )

void

pin_joint_set_param ( RID joint, PinJointParam param, float value )

RID

rectangle_shape_create ( )

RID

segment_shape_create ( )

RID

separation_ray_shape_create ( )

void

set_active ( bool active )

Variant

shape_get_data ( RID shape ) const

ShapeType

shape_get_type ( RID shape ) const

void

shape_set_data ( RID shape, Variant data )

RID

space_create ( )

PhysicsDirectSpaceState2D

space_get_direct_state ( RID space )

float

space_get_param ( RID space, SpaceParameter param ) const

bool

space_is_active ( RID space ) const

void

space_set_active ( RID space, bool active )

void

space_set_param ( RID space, SpaceParameter param, float value )

RID

world_boundary_shape_create ( )


枚举

enum SpaceParameter:

SpaceParameter SPACE_PARAM_CONTACT_RECYCLE_RADIUS = 0

常量,用于设置/获取一对物体在其碰撞状态被重新计算之前的最大移动距离。该参数的默认值为 ProjectSettings.physics/2d/solver/contact_recycle_radius

SpaceParameter SPACE_PARAM_CONTACT_MAX_SEPARATION = 1

常量,用于设置/获取两个形状间的最大距离,超过该距离后它们将被视为分离,接触将被弃置。该参数的默认值为 ProjectSettings.physics/2d/solver/contact_max_separation

SpaceParameter SPACE_PARAM_CONTACT_MAX_ALLOWED_PENETRATION = 2

常量,用于设置/获取两个形状互相穿透的最大距离,超过该距离后将视为碰撞。该参数的默认值为 ProjectSettings.physics/2d/solver/contact_max_allowed_penetration

SpaceParameter SPACE_PARAM_CONTACT_DEFAULT_BIAS = 3

常量,用于设置/获取所有物理接触的默认求解器偏差。求解器偏差是控制两个对象在重叠后“反弹”的程度的一个系数,以避免由于数值不精确而使它们处于该状态。该参数的默认值为 ProjectSettings.physics/2d/solver/default_contact_bias

SpaceParameter SPACE_PARAM_BODY_LINEAR_VELOCITY_SLEEP_THRESHOLD = 4

常量,用于设置/获取活跃的阈值线速度。一个线性速度和角速度都被标记为可能处于非活动状态的物体,将在给定时间后进入睡眠状态。该参数的默认值为 ProjectSettings.physics/2d/sleep_threshold_linear

SpaceParameter SPACE_PARAM_BODY_ANGULAR_VELOCITY_SLEEP_THRESHOLD = 5

常量,用于设置/获取活跃的阈值角速度。一个线性速度和角速度都被标记为可能处于非活动状态的物体,将在给定时间后进入睡眠状态。该参数的默认值为 ProjectSettings.physics/2d/sleep_threshold_angular

SpaceParameter SPACE_PARAM_BODY_TIME_TO_SLEEP = 6

常量,用于设置/获得最大的活动时间。一个被标记为线速度和角速度都可能不活动的物体,在这个时间之后将被置入睡眠状态。

SpaceParameter SPACE_PARAM_CONSTRAINT_DEFAULT_BIAS = 7

常量,用于设置/获取所有物理约束的默认求解器偏差。求解器偏差是控制两个对象在违反约束后“反弹”的程度的一个系数,以避免由于数值不精确而使它们处于该状态。该参数的默认值为 ProjectSettings.physics/2d/solver/default_constraint_bias

SpaceParameter SPACE_PARAM_SOLVER_ITERATIONS = 8

常量,用于设置/获取所有接触与约束的求解器迭代数。迭代次数越多,碰撞越准确。但是,大量的迭代会需要更多的 CPU 能力,会降低性能。


enum ShapeType:

ShapeType SHAPE_WORLD_BOUNDARY = 0

常量,用于创建世界边界形状。一个世界边界形状,是具有原点和法线的无限直线。因此,它可以用于前面/背面检查。

ShapeType SHAPE_SEPARATION_RAY = 1

常量,用于创建分离射线形状。一条分离射线由一个长度定义,并将其自身与接触其远端点的物体分开。对角色控制器很有用。

ShapeType SHAPE_SEGMENT = 2

常量,用于创建线段形状。一条线段形状是从点 A 到点 B 的有限线段。可以用于检查交叉点。

ShapeType SHAPE_CIRCLE = 3

这是创建圆形的常量。一个圆的形状只有一个半径。它可以用于交点和内/外侧检查。

ShapeType SHAPE_RECTANGLE = 4

这是用于创建矩形形状的常量。矩形形状是由宽度和高度定义的。它可以用于交点和内/外侧检查。

ShapeType SHAPE_CAPSULE = 5

这是创建胶囊形状的常量。一个胶囊形状由一个半径和一个长度定义。它可以用于交点和内/外侧检查。

ShapeType SHAPE_CONVEX_POLYGON = 6

常量,用于创建凸多边形形状。一个多边形是由一个点的列表定义的。它可以用于交叉点和内侧/外侧检查。

ShapeType SHAPE_CONCAVE_POLYGON = 7

这是创建凹形多边形的常量。一个多边形是由一个点的列表定义的。它可以用于交叉点检查,但不能用于内/外侧检查。

ShapeType SHAPE_CUSTOM = 8

引擎内部会使用这个常量。任何试图创建这种形状的行为都会导致错误。


enum AreaParameter:

AreaParameter AREA_PARAM_GRAVITY_OVERRIDE_MODE = 0

常量,在一个区域中设置/获取重力覆盖模式。有关可能的值,请参阅 AreaSpaceOverrideMode。这个参数的默认值是 AREA_SPACE_OVERRIDE_DISABLED

AreaParameter AREA_PARAM_GRAVITY = 1

常量,用于设置/获取区域中的重力强度。该参数的默认值为 9.80665

AreaParameter AREA_PARAM_GRAVITY_VECTOR = 2

常量,用于设置/获取区域中的重力向量/中心。该参数的默认值为 Vector2(0, -1)

AreaParameter AREA_PARAM_GRAVITY_IS_POINT = 3

常量,用于设置/获取区域中的重力向量是方向,还是中心点。该参数的默认值为 false

AreaParameter AREA_PARAM_GRAVITY_POINT_UNIT_DISTANCE = 4

常量,用于设置/获取重力强度等于 AREA_PARAM_GRAVITY 控制的重力的距离。例如,在一个半径为 100 像素且表面重力为 4.0 px/s² 的行星上,将重力设置为 4.0,将单位距离设置为 100.0。重力将根据平方反比定律衰减,因此在该示例中,距离中心 200 像素处的重力将为 1.0 px/s²(距离的两倍,重力的 1/4),距离中心 50 像素处重力为 16.0 px/s²(距离的一半,重力的 4 倍),依此类推。

仅当单位距离为正数时,上述情况才成立。当单位距离设置为 0.0 时,重力将与距离无关。该参数的默认值为 0.0

AreaParameter AREA_PARAM_LINEAR_DAMP_OVERRIDE_MODE = 5

常量,用于在一个区域中设置/获取线性阻尼覆盖模式。有关可能的值,请参阅 AreaSpaceOverrideMode。这个参数的默认值是 AREA_SPACE_OVERRIDE_DISABLED

AreaParameter AREA_PARAM_LINEAR_DAMP = 6

常数,用于设置/获取区域的线性阻尼系数。该参数的默认值为 0.1

AreaParameter AREA_PARAM_ANGULAR_DAMP_OVERRIDE_MODE = 7

常量,用于在一个区域中设置/获取角度阻尼覆盖模式。有关可能的值,请参阅 AreaSpaceOverrideMode。这个参数的默认值是 AREA_SPACE_OVERRIDE_DISABLED

AreaParameter AREA_PARAM_ANGULAR_DAMP = 8

常数,用于设置/获取区域的角度阻尼系数。该参数的默认值为 1.0

AreaParameter AREA_PARAM_PRIORITY = 9

常量,用于设置/获取区域的优先级(处理顺序)。该参数的默认值为 0


enum AreaSpaceOverrideMode:

AreaSpaceOverrideMode AREA_SPACE_OVERRIDE_DISABLED = 0

这个区域不影响重力/阻尼。这些一般都是只存在于检测碰撞的区域,以及进入或离开它们的物体。

AreaSpaceOverrideMode AREA_SPACE_OVERRIDE_COMBINE = 1

此区域把它的重力/阻尼加到目前已经计算过的对象上。这样一来,许多重叠的区域可以结合它们的物理运算来产生有趣的效果。

AreaSpaceOverrideMode AREA_SPACE_OVERRIDE_COMBINE_REPLACE = 2

这个区域把它的重力/阻尼加到迄今为止已经计算出来的任何东西上。然后停止考虑其余的区域,甚至默认的区域。

AreaSpaceOverrideMode AREA_SPACE_OVERRIDE_REPLACE = 3

这个区域取代了任何重力/阻尼,甚至是默认的,并停止考虑其余的区域。

AreaSpaceOverrideMode AREA_SPACE_OVERRIDE_REPLACE_COMBINE = 4

这个区域取代了到目前为止计算的任何重力/阻尼,但继续计算其余的区域,直到默认的区域。


enum BodyMode:

BodyMode BODY_MODE_STATIC = 0

常量,用于静态物体。在这种模式下,物体只能由用户代码移动,移动时不会与路径上的其他物体发生碰撞。

BodyMode BODY_MODE_KINEMATIC = 1

常量,用于运动学物体。在这种模式下,物体只能由用户代码移动,会与路径上的其他物体发生碰撞。

BodyMode BODY_MODE_RIGID = 2

常量,用于刚体。在这种模式下,物体可以被其他物体推动,能够对其施加力。

BodyMode BODY_MODE_RIGID_LINEAR = 3

常量,用于线性刚体。在这种模式下,物体不能旋转,只有线速度受外力影响。


enum BodyParameter:

BodyParameter BODY_PARAM_BOUNCE = 0

常量,用于设置/获取物体的反弹系数。该参数的默认值为 0.0

BodyParameter BODY_PARAM_FRICTION = 1

常量,用于设置/获取实体摩擦力。该参数的默认值为 1.0

BodyParameter BODY_PARAM_MASS = 2

常量,用于设置/获取一个实体质量。该参数的默认值为1.0。如果该实体的模式被设置为 BODY_MODE_RIGID,那么设置这个参数会有以下附加效果:

  • 如果该参数 BODY_PARAM_CENTER_OF_MASS 从未被明确设置,则该参数的值将根据实体的形状重新计算。

  • 如果该参数 BODY_PARAM_INERTIA 被设置为值 <= 0.0,则该参数的值将根据该实体的形状、质量、和质心重新计算。

BodyParameter BODY_PARAM_INERTIA = 3

常量,用于设置/获取一个实体惯性。该参数的默认值为0.0。如果实体的惯性被设置为一个值 <= 0.0,那么惯性将根据实体的形状、质量、和质心重新计算。

BodyParameter BODY_PARAM_CENTER_OF_MASS = 4

常量,用于在实体局部坐标系中设置/获取一个实体质心位置。该参数的默认值为 Vector2(0,0)。如果该参数从未明确设置,则在设置参数 BODY_PARAM_MASS 或调用 body_set_space 时,会根据实体的形状重新计算。

BodyParameter BODY_PARAM_GRAVITY_SCALE = 5

常量,用于设置/获取物体的重力倍数。该参数的默认值为 1.0

BodyParameter BODY_PARAM_LINEAR_DAMP_MODE = 6

常量,用于设置/获取物体的线性阻尼模式。可能的值见 BodyDampMode。这个参数的默认值为 BODY_DAMP_MODE_COMBINE

BodyParameter BODY_PARAM_ANGULAR_DAMP_MODE = 7

常量,用于设置/获取物体的角度阻尼模式。可能的值见 BodyDampMode。这个参数的默认值为 BODY_DAMP_MODE_COMBINE

BodyParameter BODY_PARAM_LINEAR_DAMP = 8

常量,用于设置/获取物体的线性阻尼系数。该参数的默认值为 0.0

BodyParameter BODY_PARAM_ANGULAR_DAMP = 9

常量,用于设置/获取物体的角度阻尼系数。该参数的默认值为 0.0

BodyParameter BODY_PARAM_MAX = 10

代表 BodyParameter 枚举的大小。


enum BodyDampMode:

BodyDampMode BODY_DAMP_MODE_COMBINE = 0

物体的阻尼值会叠加到替换区域中所设置的值或默认值。

BodyDampMode BODY_DAMP_MODE_REPLACE = 1

物体的阻尼值会替换区域中所设置的值或默认值。


enum BodyState:

BodyState BODY_STATE_TRANSFORM = 0

常量,用于设置/获取物体的当前变换矩阵。

BodyState BODY_STATE_LINEAR_VELOCITY = 1

常量,用于设置/获取物体的当前线速度。

BodyState BODY_STATE_ANGULAR_VELOCITY = 2

常量,用于设置/获取物体的当前角速度。

BodyState BODY_STATE_SLEEPING = 3

常量,用于使物体沉睡/唤醒,或得到它是否在沉睡。

BodyState BODY_STATE_CAN_SLEEP = 4

常量,用于设置/获取物体是否可以休眠。


enum JointType:

JointType JOINT_TYPE_PIN = 0

常量,用于创造钉关节。

JointType JOINT_TYPE_GROOVE = 1

常量,用于创造槽关节。

JointType JOINT_TYPE_DAMPED_SPRING = 2

常量,用于创造有阻尼的弹簧关节