Dynamic Physics Box

Box2D dynamic rigid body affected by gravity, physical impulses, forces, friction, and bounce.

Type: DynamicBodyNode · Category: Physics & Collision · Also found as: dynamicbody, dynamic_body

Properties

Property	Type	Default	Description
linearVelocity	vec2	(0, 0)	Velocity (px/s). Range -1000 to 1000.
angularVelocity	number	0	Spin (degrees/s). Range -360 to 360.
linearDamping	number	0.05	Slows movement over time (air drag). Range 0 to 20.
angularDamping	number	0.05	Slows spin over time. Range 0 to 20.
gravityScale	number	1	Multiplies the world’s gravity for this body (0 floats, negative rises). Range -5 to 5.
sleepThreshold	number	1.5	Below this speed the body may sleep (px/s). Range 0 to 100.
enableSleep	boolean	true	Let the body sleep when at rest (saves time; contacts wake it).
isAwake	boolean	true	Awake (simulated) now.
fixedRotation	boolean	false	Never rotate (characters, upright crates).
isBullet	boolean	false	Continuous collision against other moving bodies (fast projectiles).
allowFastRotation	boolean	false	Allow very fast spin (wheels); can be less stable.
debugColor	color	#60a5faff	Colour of the collider outline drawn with Show Bounds & Colliders (and the game’s debug draw).

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

DynamicBodyNode:connect(event, handler)

Connects a handler to one of this node’s events: collision_started (Contact with another body began), collision_ended (Contact with another body ended); the tree events; custom ones.

self.node:connect("collision_started", function(value, source) Log.info("collision_started") end)

• event DynamicBodyNodeEvent|string
• handler fun(value: any, source: DynamicBodyNode)

Returns integer id Connection id for disconnect

DynamicBodyNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("linearVelocity")

• path DynamicBodyNodeProperty|string

Returns any

DynamicBodyNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("linearVelocity", 100, 50)

• path DynamicBodyNodeProperty|string
• value any
• y? number

DynamicBodyNode:apply_force(fx, fy)

Applies a continuous force to this node (requires DynamicBodyNode).

self.node:apply_force(0, -500)

• fx number Force X in Newtons
• fy number Force Y in Newtons

DynamicBodyNode:apply_impulse(ix, iy)

Applies an instantaneous impulse to this node (requires DynamicBodyNode).

self.node:apply_impulse(0, -300)

• ix number Impulse X
• iy number Impulse Y

DynamicBodyNode:get_linear_velocity()

Gets the linear velocity of the physics body or character mover in world units per second.

local vx, vy = self.node:get_linear_velocity(); if vy > 400 then self.falling = true end

Returns number vx Linear velocity X, number vy Linear velocity Y

DynamicBodyNode:set_linear_velocity(vx, vy)

Sets the linear velocity of the physics body or character mover directly.

self.node:set_linear_velocity(200, 0)

• vx number Linear velocity X
• vy number Linear velocity Y

DynamicBodyNode:get_angular_velocity()

Gets the angular velocity of the physics body in degrees per second.

local omega = self.node:get_angular_velocity(); if math.abs(omega) > 720 then Log.info("spinning") end

Returns number omega Angular velocity in degrees/sec

DynamicBodyNode:set_angular_velocity(omega)

Sets the angular velocity of the physics body in degrees per second.

self.node:set_angular_velocity(180)

• omega number Angular velocity in degrees/sec

DynamicBodyNode:get_gravity_scale()

Gets the gravity scale multiplier for this physics body.

local g = self.node:get_gravity_scale(); self.node:set_gravity_scale(g * 0.5)

Returns number

DynamicBodyNode:set_gravity_scale(scale)

Sets the gravity scale multiplier for this physics body.

self.node:set_gravity_scale(0)

• scale number

DynamicBodyNode:is_fixed_rotation()

Checks whether rotation is locked on this body.

if not self.node:is_fixed_rotation() then self.node:set_fixed_rotation(true) end

Returns boolean

DynamicBodyNode:set_fixed_rotation(fixed)

Locks or unlocks rotation on this physics body.

self.node:set_fixed_rotation(true)

• fixed boolean

DynamicBodyNode:set_linear_damping(damping)

Sets the linear drag/damping coefficient.

self.node:set_linear_damping(2.0)

• damping number

DynamicBodyNode:set_angular_damping(damping)

Sets the angular drag/damping coefficient.

self.node:set_angular_damping(1.5)

• damping number

DynamicBodyNode:is_awake()

Checks if the physics body is awake and participating in simulation.

if not self.node:is_awake() then self.node:set_awake(true) end

Returns boolean

DynamicBodyNode:set_awake(awake)

Wakes up or puts the body to sleep.

self.node:set_awake(true)

• awake boolean

In a scene file

{
  "type": "DynamicBodyNode",
  "name": "DynamicPhysicsBox",
  "position": [
    0,
    0
  ],
  "properties": {
    "linearVelocity": [
      0,
      0
    ],
    "angularVelocity": 0,
    "linearDamping": 0.05
  }
}