#Rigid bodies and joints

Physics covers bodies, colliders, the character controller and queries. This page is about bodies that the simulation moves, and tying them together.

#A body that falls

Give an entity a collider and a Rigidbody with type Dynamic. It then falls, lands, rolls and is pushed.

The body exists from the first fixed update after the component was added.

#Pushing it from a script

function Ball:OnStart()
	self.Body = self.Entity.Rigidbody
end

-- A kick: changes its momentum at once.
function Ball:Kick(direction)
	self.Body:AddImpulse(direction * 8)
end

-- A steady push: call it every fixed step.
function Rocket:OnFixedUpdate()
	self.Body:AddForce(self.Entity.Up * 50)
end

-- A jump keeps the sideways speed and sets the upward one.
function Hopper:Jump()
	local velocity = self.Body:GetVelocity()
	velocity.y = 6
	self.Body:SetVelocity(velocity)
end

export = DefineScript({
	Body: {} as Rigidbody,

	OnStart() {
		this.Body = this.Entity.Rigidbody!;
	},

	// A kick: changes its momentum at once.
	Kick(direction: Vec3) {
		this.Body.AddImpulse(direction.mul(8));
	},

	// A steady push: call it every fixed step.
	OnFixedUpdate() {
		this.Body.AddForce(this.Entity.Up.mul(50));
	},

	// A jump keeps the sideways speed and sets the upward one.
	Jump() {
		const velocity = this.Body.GetVelocity();
		velocity.y = 6;
		this.Body.SetVelocity(velocity);
	},
});

Forces and impulses work on dynamic bodies only.

#Moving a body yourself

Do not set the Position of a dynamic body every frame: that teleports it, and it passes through things. Push it, or set its velocity.

A Kinematic body is the kind you move yourself. Set its entity's position, or tween it, and it pushes dynamic bodies out of the way without being pushed back. Use it for lifts, doors and moving platforms:

Tween.To(self.Entity, "Position", self.Top, 3, "EaseInOut")

declare const entity: Entity;
declare const top: Vec3;

Tween.To(entity, "Position", top, 3, "EaseInOut");

#Joints

A Joint ties its entity's body to another entity's body, or to the world when no entity is given. The entity needs a Rigidbody and a collider.

Anchor and Axis are relative to the joint's own entity. ConnectedAnchor is relative to the connected entity, or a point of the world when tied to the world. A negative distance means the distance the two points start at.

A lamp hanging from the ceiling is a dynamic body with a Distance joint tied to the world:

{"command": "entity.update", "entity": "Lantern", "data": {"Rigidbody": {"Type": "Dynamic"}, "SphereCollider": {}, "Joint": {"Type": "Distance", "ConnectedAnchor": [0, 5, 0]}}}

From a script, joint:SetConnectedEntity(entity) ties it to another body, and nil ties it to the world.

Turn on Colliders in the viewport to see joints drawn in magenta.

#Sleeping

A body that has come to rest falls asleep and costs nothing until something touches it. Contact callbacks keep arriving as Stay while it sleeps.