Physics

[This feature is still in Open Beta and may have some bugs. Please direct any feedback to the Planetary Processing Team on Discord]

Physics is an optional server-side setting that can be enabled for entities. When physics is applied to an entity, it is assigned a mass, a body (defining its shape), and a velocity. Forces can be applied to modify an entity’s velocity, and collisions between entities are simulated server-side.

Using Physics

Physics must be enabled on an entity for it to have a velocity and interact in collisions. An entity with physics enabled will not collide with another entity that does not have Physics enabled.

1. Enable Physics:

self.Physics = true

1. Assign a Body & Mass:

The body can be either a sphere or a box.

local box = api.physics.NewBoxShape(1, 1, 1) -- width=1, length=1, depth=1
self.Body = api.physics.NewBody(box, 10) --shape=box, mass=10

1. Set Velocity or apply Forces:

--1: Set velocity
self.Body.Velocity = api.physics.NewVector(0, -20, 0)
--2: Apply a one-time force 
local vector = api.physics.NewVector(0, .2, 0)
self.Body:ApplyForce(vector)

Force

The function ApplyForce() applies a force to an entity once during a physics update and is then reset immediately afterward. To apply a continuous force, you must reapply it each update.

Multiple forces can be applied within a single update cycle. These forces are combined and applied together in the next physics update.

self.Body:ApplyForce(vector)

Physics Objects

Shape

The Planetary Processing physics engine currently supports two kinds of 3D shapes: a box or a sphere. Shapes are used to define the collision boundaries for an entity's Body.

Body

The Body represents an entity for the game's server-side physics. It defines the entity’s shape and mass. These attributes determine how the entity interacts with forces, collisions, and other physics-based calculations.

Vector

For physics interactions in 3D space, motion occurs across the X, Y, and Z axes. So it helps to group XYZ values into vectors to represent a single direction, for fields like velocities and forces.

Collisions

When two entities with Physics enabled and a Body intersect, they collide. The physics engine calculates a 3D elastic collision, determining the resulting motion vectors.

• Collisions are Elastic: No energy is lost during collisions.

• Collision Detection: Collisions are only detected if entities are overlapping during an update.

Elastic Collision

Fixed Body Collisions

To simulate a fixed body, such as a wall, assign it a very high mass (e.g., 999999). The mass should be several orders of magnitude larger than other entities that might collide with it. This ensures the body’s velocity remains effectively unchanged during collisions, with all energy transferred to the colliding object.

For absolute certainty that it won’t move, manually set its velocity to 0 every update.

Collision between two box-shaped bodies of the same size/shape. One depicted with a very high mass.

Inelastic Collisions

To create an inelastic collision (in which rebound momentum is not conserved), try applying an additional force to an object when its velocity changes.

Inelastic collision

Inelastic collision between a faster and slower cube.

Troubleshooting Collisions

If the game's ticks per second (TPS) is low and an entity's speed is high, collisions may be missed. To prevent this, ensure:

$$\frac{Entity Max Speed }{Entity Min Diameter} > TPS$$

A higher TPS reduces the risk of undetected collisions and unintended behaviour.

Collision fails because of a very low TPS.

Physics API

A number of API calls are available for certain physics-related actions, such as creating a physics Body. They are accessed using the api.physics object available to all server-side scripts.

Methods

Method	Parameters	Returns	Description
NewBody	shape: Shape mass: float	Body	Create a physics body with a shape and mass capable of collisions.
NewBoxShape	width: float length: float depth: float	Box	An axis-aligned bounding box.
NewSphereShape	radius: float	Sphere	It's just a sphere.

---

Shape

api.physics.NewBoxShape(1, 1, 1)
api.physics.NewSphereShape(1)

Shape	Parameters	Description
Box	width: float length: float depth: float	An axis-aligned bounding box.
Sphere	radius: float	It's just a sphere.

---

Body

api.physics.NewBody(shape, mass)

Fields

Field	Type	Description
Shape	Shape	The size and shape of the Body's collision boundaries.
Mass	float	The mass of the physics body, which dictates how effective forces are upon it.
Force	Vector	The XYZ vector of force being applied to the physics body on the current update.
Velocity	Vector	The current velocity of the physics body, for how fast it is moving in an XYZ direction.

Methods

Each of these methods takes the Body object self.Body as its first parameter. Hence you may use self.Body:ApplyForce(force) instead of self.Body.ApplyForce(self.Body, force).

Method	Parameters	Returns	Description
ApplyForce	force: vector	None	Apply a one time XYZ force to a physics body. It is applied on the next update.
GetBoxDimensions	None	width: float length: float depth: float	Get the dimensions of a box shaped Body. Errors if the Body is not a Box.
GetRadius	None	radius: float	Get the radius of a Body. Errors if the Body is not a Sphere.

---

Vector

api.physics.NewVector(1,1,0)

Fields

Field	Type
X	float
Y	float
Z	float

Methods

Each of these methods takes the Vector object as its first parameter. Hence you may use vector_a:Add(vector_b) instead of vector_a.Add(vector_a,vector_b).

v1 = api.physics.NewVector(1,1,0)
v2 = api.physics.NewVector(0,2,2)

sum_v1_v2 = v1:Add(v2)
-- sum_v1_2 is now &{1 3 2}

Method	Parameters	Returns	Description
Add	b: Vector	Vector	Add the corresponding vector value: a.X + b.X a.Y + b.Y a.Z + b.Z
Sub	b: Vector	Vector	Subtract the corresponding vector value: a.X - b.X a.Y - b.Y a.Z - b.Z
Dot	b: Vector	float	Measure the degree of directional similarity between the parameters: a.X*b.X + a.Y*b.Y + a.Z*b.Z
Mul	b: float	Vector	Multiply each vector value by a number: a.X * b a.Y * b a.Z * b
Cross	b: Vector	Vector	Create a third vector, perpendicular to the parameters: a.Y*b.Z - a.Z*b.Y a.Z*b.X - a.X*b.Z a.X*b.Y - a.Y*b.X
Normalize	None	Vector	Make a vector unit length: mag = Sqrt(v.X^2 ​ +v.Y^2 ​ +v.Z^2) norm = Mul(v, 1/mag)
Magnitude	None	Vector	Calculate the scale of the vector. mag = Sqrt(v.X^2 ​ +v.Y^2 ​ +v.Z^2)

Notes

• Currently rotation is not supported.

• Planetary Processing Physics is in continuous development. Please contact us on our Discord if you would like to request specific functionality.
• Due to synchronization between multiplayer elements, physics is not deterministic. This means that you may experience different physics interactions each time you run a simulation.