Boxed Physics

Boxed Physics is an implementation of the Box2D physics engine that allows for the use of joints, springs, sliders, and other complex physics interactions within your projects.

This documentation will guide you through the process of using Boxed Physics.

Working with Worlds

When using the Boxed Physics extension, you must initialize the physics environment before starting your project. To do this, use the Make world, Scale 1m: [SCALE] Gravity: [GRAVITY] Wind: [WIND] Scene: [SCENE] block.

Note: the environment is initialised to the default every time the project starts, but it's good practice to use this block every flag click anyways

Scene Types

The scene type determines the containment type for your physics world:

Semi-closed stage: Prevents objects from leaving the bottom and sides of the stage but allows infinite upward movement.
Boxed stage: Fully contains objects within the stage, preventing them from leaving the top, bottom, or sides.
Opened stage: Only prevents objects from falling off the bottom.
Nothing: Removes all walls, allowing objects to move freely.

when gf clicked Make world, Scale 1m: [50] Gravity: [-10] Wind: [0] Scene: [semi-closed stage v] :: #2cb0c0

Changing World Options

Once the world is created, you can modify gravity and wind dynamically without creating a new world.

when gf clicked forever Set world options, Gravity: (-10) Wind: ((5) * ([sin v] of ((timer) * (70)))) :: #2cb0c0 end

Additionally, you can enable slow motion using the Set slow motion to [VALUE] block.

Creating Your First Object

Objects in Boxed Physics are invisible physics-based hitboxes. To add an object, define its shape and attributes, and then create it in the world.

Basic Box Example

when gf clicked Dеfine Box, Width: [100] Height: [100] :: #2cb0c0 Make object [Object1] at X: [0] y: [0] Dir: [90] :: #2cb0c0 forever Step Simulation :: #2cb0c0 //Remember to run this block every tick end

You can create multiple objects efficiently:

when gf clicked Dеfine Box, Width: [100] Height: [100] :: #2cb0c0 set [index v] to (0) repeat (4) change [index v] by (1) Make object (join [Object] (index)) at X: (pick random (-100) to (100)) y: (pick random (-100) to (100)) Dir: [90] :: #2cb0c0 end

Other Shapes

Circles

Dеfine Circle, Size: [100] :: #2cb0c0 Make object [Object1] at X: [0] y: [0] Dir: [90] :: #2cb0c0

Polygons

Costume-based: Directly convert the current costume into a polygon (no holes).
Point-based: Define polygons with a list of coordinates.

Dеfine polygon as this costume :: #2cb0c0 Make object [Object2] at X: [50] y: [50] Dir: [0] :: #2cb0c0 Dеfine polygon, Points: [0 50 40 -50 -40 -50] :: #2cb0c0 // Triangle Make object [Object3] at X: [0] y: [0] Dir: [90] :: #2cb0c0

Point-based objects simply take an array of "x y" values seperated by 3 spaces. You can visualise any point-based polygon in this demo.

Defining Base Attributes

Customize objects with the Define base block:

Type Determines if the object is static or dynamic.
Density, Friction, Bounce Control physical properties like weight, surface interaction, and bounciness.

when gf clicked //Super bouncy imovable triangle Dеfine polygon, Points: [0 50 40 -50 -40 -50] :: #2cb0c0 Dеfine base, Type: [static v] Density: [0.1] Friction: [0.5] Bounce: [2] :: #2cb0c0 Make object [Object1] at X: [0] y: [0] Dir: [90] :: #2cb0c0

Modifying Objects

Damping (air resistance)

The damping of each object can also be changed with the Set [BODYATTR] of object [NAME] to [VALUE] block.

when gf clicked Set [damping v] of object [Object1] to [0.1] :: #2cb0c0

Destroying Objects

You can delete individual objects or clear all objects at once.

when I receive [Destroy Object1 v] Destroy object [Object1] :: #2cb0c0 when I receive [Nuke everything! v] Destroy every object :: #2cb0c0 //This will also remove all joints

Moving Objects

Direct Movement

Move object [Object1] to X: [50] Y: [50] :: #2cb0c0 Set rotation of object [Object1] to [45] :: #2cb0c0

Velocity and Impulse

Rotational impulses are simple, just a number for power, but positional impulses are a little more complex.

Positional impulses can be one of two types: World Impulse or Impulse.
They both take a direction, and power, but they behave differently.
The Impulse option is meant for quick movements (like jumping)
while the World Impulse option is meant for movement over time (like pushing a wheel).

Set Velocity of object [Object1] to X: [10] Y: [0] Dir: [0] :: #2cb0c0 Apply Angular Impulse to object [Wheel1] power: [20] :: #2cb0c0

Handling Impacts

Boxed Physics comes with a few blocks that can be used to handle impacts.

On impact

When an object collides with another, this hat block is triggered.
This simple block allows you to run code any time an object is hit.

Note: this block does not restart existing threads

When [Object] has an impact :: #2cb0c0 say [I HAVE BEEN HIT!]

You can also use a boolean version that returns true if an object had an impact during the last tick.

when gf clicked wait until <[Object] had an impact :: #2cb0c0> say [I got hit during the last tick]

What hit me?

You can also check what objects are colliding with the Get all objects touching [NAME] block.
This block simply lists all the names that hit the object.

When [Object1] has an impact :: #2cb0c0 say (join [I was hit by ] (Get all objects touching [Object1] :: #2cb0c0))

Or you can just get if the object is touching anyting if you don't care what was hit.

when gf clicked forever if <[Object] is touching anything :: #2cb0c0> then say [AAAAAAAAAAAAAAAAAHHHHHHHHHHHHHH!!!!!!] else say [] end end

Making Joints

Joints connect objects and enable complex interactions like wheels, sliders and more.

Here is a description of all joints in BoxedPhysics:

Rotating: This joint lets you to join 2 objects togeather while keeping rotations

Weld: This joint locks 2 objects togeather, making them act like one object

Spring: This joint keeps 2 objects at a semi-fixed distance from eachother

Slider: This joint forces an object to only move along the specified axis to the other object

Pin: This joint takes an object and tries to move it to a position with a specified force.
This joint is the only joint to have the input position stay relative to the world instead of the object.

Creating pin joints uses its own block, instead of the create joint block

Dеfine Spring, Length: [100] Damping: [0.7] Freq: [5] :: #2cb0c0 Create Joint [Spring1] of type [Spring v] between [Object1] at [0] [0] and [Object2] at [0] [0] :: #2cb0c0

Experiment with all the joint types in this demo to see what they do.

Joint Properties

Settable: Motor On, Speed, Limits, Torque
Gettable: Angle, Speed, Torque, Tension

Performance Options

You can optimize your simulation by configuring iteration settings to allow for more objets with less lag, or have better physics with fewer objects.

While this doesn't visually change anything (usually) it does change how performant things are, and you will notice that with bigger simulations.

Set physics options, Position iterations: [10] Velocity iterations: [10] Continuous physics: <true :: #5EC15D> Warm starting: <true :: #5EC15D> :: #2cb0c0

Math Utilities

Boxed Physics also includes some math blocks for convenience:

Rotate a point: Rotate a point around the origin (0, 0).
Get rotation from: Find the direction from one point to another.
Magnitude: Calculate the vector length.
Distance: Measure the distance between two points.

(Get [x v] from point x [10] y [-10] rotated by [90] :: #2cb0c0) (Get rotation from x [0] y [0] to x [10] y [15] :: #2cb0c0) (Magnitude of x [5] y [3] :: #2cb0c0) (Distance between x [0] y [0] and x [-20] y [10] :: #2cb0c0)

Examples

Need more help?
Try some example projects here.

GitHub - Submitting an extension - Discord