Thank you very much for your support and for using the Force2D Physics Engine
This guideline explains how to use the physics engine, and is roughly divided into several sections: how to create objects, how to create joints between objects, how to access attributes of objects, and how to adjust settings.

Getting Started
Download or remix the package to start using the library
Force2D v3.1.3 package: https://scratch.mit.edu/projects/1320076341/

Example demotration of the physics engine:
Force2D v3.1.1 demo: https://scratch.mit.edu/projects/1311913398/

Things You Need to Know

1. The angle coordinate system of this physics engine is based on the polar coordinate system, and the unit is degrees. Therefore, counterclockwise rotation is considered positive, which is opposite to the angle system used in Scratch.
   
2. Naming convention of Force2D variables:
   _ represents a constant/static variable.
   # represents an index.
   Variables or lists starting with an uppercase letter are shared “for all sprites”
   Variables or lists starting with a lowercase letter are “for this sprite only”.
   
3. World Space vs Local Space
   In Force2D, coordinates and vectors can exist in either world space or local space:
   local space: The position/vector that is relative to the origin (0, 0). All vertices or anchor points of the object are defined relative to this internal coordinate system.
   world space: The position/vector represents the absolute coordinates within the entire game world. These coordinates are subject to global transformations, such as camera movement and zoom scales
   

Launcher
To start using the physics engine, we need to locate the Launcher, which will also serve as your primary development environment.
The Launcher is in the sprite “Your Sprite”, divided into an initialize section and an update section. If you wish to add objects, please do so only after Force2D has finished initializing (as the initialization process includes deleting all existing objects).

when green flag clicked
initilaize
broadcast [initialize force2d v] and wait
forever
erase all
broadcast [update force2d v]
broadcast [render force2d v]
end

 initilaize 

initilaize the camera position and the zoom scale

 broadcast [initialize force2d v] and wait 

initialize the force2d (including delete all objects)

 broadcast [update force2d v] 

update the physics simulation steps

 broadcast [render force2d v] 

Update the built-in renderer (if you intend to use Sprites instead of the Pen tool, you can remove this block).

Objects

new circle at x:() y:() radius() direction() density()

create a circle rigid-body
x, y - the world cooridinate (x, y) of the center of circle, unit is pixel
radius - the radius of the circle, unit is pixel
direction - the direction of the circle, unit is degree (0.0 ~ 360.0)
density - the mass density of the circle, if you want to fix the circle, just set it to 0

new rectangle at x:() y:() width() height() direction() density()

create a rectangle rigid-body
x, y - the world cooridinate (x, y) of the center of rectangle, unit is pixel.
width, height - the width and height of the rectangle, unit is pixel
direction - the direction of the rectangle, unit is degree (0.0 ~ 360.0)
density - the mass density of the rectangle, if you want to fix the rectangle, just set it to 0

new regular polygon at x:() y:() sides() size() direction() density()

create a regular polygon rigid-body
x, y - the world cooridinate (x, y) of the center of regular polygon, unit is pixel
size - the size of the regular polygon
sides - the number of sides of the regular polygon
direction - the direction of the regular polygon, unit is degree (0.0 ~ 360.0)
density - the mass density of the regular polygon, if you want to fix the regular polygon, just set it to 0

create a customize polygon
For any convex polygon, please follow these rules for creation:
This physics engine only supports convex polygons, and the vertices must be defined in counter-clockwise (CCW) order. Below is the example code for creating a trapezoid:

define new trapezoid at x:(x) y:(y) direction:(direction) density:(density)
new vertex at x:(20) y:(20)
new vertex at x:(-20) y:(20)
new vertex at x:(-40) y:(-20)
new vertex at x:(40) y:(-20)
new customize polygon at x:(x) y:(y) direction(direction) density:(density)

 new vertex at x:() y:() 

create vertex of the abstract convex polygon
x, y - the local cooridinate (x, y) of the vertex relative to polygon position, unit is pixel

 new customized polygon at x:() y:() direction:() density:() 

create a abstract convex polygon
x, y - the world cooridinate (x, y) of the position of abstract polygon, unit is pixel
direction - the direction of the abstract polygon, unit is degree (0.0 ~ 360.0)
density - the mass density of the abstract polygon, if you want to fix the abstract polygon, just set it to 0

 set material of rigid:()friction:()restitution:()

set the friction and restitution to the given rigid-body
rigid - the index of the rigid-body
friction - friction coefficient (must greater than 0)
restitution - restitution/bounciness ceofficient (0.0 ~ 1.0)

 destroy rigid:() 

remove the rigid-body by its given index (after removal, the indices of all subsequent rigid bodies will shift down by one, as the list is re-indexed)
rigid - the index of the rigid-body that to be removed

 drag rigids with force:() 

apply a mouse joint force to the clicked rigid body.
force: the force apply on the rigid-body

Joints
There are few joint types: distance joint, revolute joint, mouse joint, prismatic joint, weld joint.
All the joint function was shown in demotrations: https://scratch.mit.edu/projects/1311913398/

new distance joint between rigid A:() rigid B:() anchor local pos A:()() B:()()stiffness:() damping:()

create a distance joint between objects, fixes two objects at a specific distance apart, and can also adjust stiffness to behave like a spring. Applications like hanging lamps, bridges, signboards, etc.

rigid A, rigid B - the objects index that you want to connect with
anchor local pos A - the anchor local position relative to the object A position
anchor local pos B - the anchor local position relative to the object B position
stiffness - the stiffness of the joint, if you want to keep it completely rigid, set it to 0. Higher value resulting the higher stiffness.
damping - how quickly the oscillation of the distance joint slows down

new revolute joint between rigid A:() B:() anchor local pos A:()() B:()()stiffness:() motor speed:() max torque()

create a revolute joint between objects, make objects can rotate with the specific point. Application like windmills, hinges, etc.

rigid A, rigid B - the objects index that you want to connect with
anchor local pos A - the anchor local position relative to the object A position
anchor local pos B - the anchor local position relative to the object B position
stiffness - the stiffness of the joint (0.0 ~ 1.0)
motor speed - the rotational target speed of the motor
max torque - the maximum torque the motor can apply to achieve its target speed

new prismatic joint between rigid A:() B:() anchor local pos A:()()B:()()axis:()lower limit:() upper limit:()fix in direction?<>motor speed:()max force:()

create prismatic joint between objects, make objects can slide in the specific axis. Application like pistons, elevators, etc.

rigid A, rigid B - the objects index that you want to connect with
anchor local pos A - the anchor local position relative to the object A position
anchor local pos B - the anchor local position relative to the object B position
axis - the direction axis that the objects slide, unit is degree (0.0 ~ 360.0)
lower limit - the minimum slide position in the direction axis the object can reach
upper limit - the maximum slide position in the direction axis the object can reach
Motor speed - the target speed of the motor along the axis.
Max force - the maximum force he motor can apply to achieve the target speed

new mouse joint with target rigid:()point position:()()anchor local pos:()()max force:()stiffness()damping:()

create a spring like joint to the target object, to hang or drag objects. Application like dragging objects, elastic suspended objects, etc…

target rigid – The rigid body connected to the mouse joint
point position – The target position in world coordinates
anchor local pos – The local anchor position on the rigid body
max force – The maximum force the joint can apply
stiffness – how strongly the object follows the target position
damping – how quickly oscillation and movement are reduced

new weld joint between rigid A:()rigid B:()anchor local pos A:()()B:()()stiffness:()

create a weld joint to attaches two objects together so they behave as a single body. Their relative position and rotation remain fixed. Application like creating compound bodies or vehicles

rigid A, rigid B - the objects index that you want to connect with
anchor local pos A - the anchor local position relative to the object A position
anchor local pos B - the anchor local position relative to the object B position
stiffness - the stiffness of the joint (0.0 ~ 1.0)

 destroy joint:() 

remove a joint by its given index. (after removal, the indices of all subsequent joints will shift down by one, as the list is re-indexed)
joint - the index of the joint that to be removed

Disabling Collisions
To disable collision between objects, the following two methods are provided:

disable collision between rigid A:() B:()

to directly disable collision between objects
rigid A, rigid B - the indices of the objects whose collisions will be disabled

set collision layer of rigid:()layer:()can acess layers:()()()()()()

sets the collision layer of an object and specifies which layers it can interact with.

rigid: the index of the object
layer - the collision layer assigned to the object (default is 1)
can access layers - the layers that this object is allowed to collide with (make sure that the layers an object can access also include its own layer)

Object Coloring

fill rigid:() with hexadecimal color code:()

fill the object with color that the format is hexadecimal code

rigid - the object index that to be filled
hexadecimal color code - the hexadecimal code of a color (exp: #00FFFF, 0x50FFFFFF)

fill rigid:() with color r:()g:()b:()a:()

fill the object with color that the format is RGBA

rigid - the object index that to be filled
r - red value (0 ~ 255)
g - green value (0 ~ 255)
b - blue value (0 ~ 255)
a - alpha/transparency (0 ~ 255)

fill rigid:() with color h:()s:()v:()

fill the object with color that the format is HSV/HVB

h: hue (0 ~ 359)
s: saturation (0.0 ~ 1.0)
v: value/brightness (0.0 ~ 1.0)

Common Attributes
The following are commonly used attributes, which can be used to retrieve the current state of a rigid body:

(item (5) of [Rigids position x v] :: list)

The position x of the 5th rigid-body

(item (5) of [Rigids position y v] :: list)

The position y of the 5th rigid-body

(item (5) of [Rigids direction v] :: list)

The direction of the 5th rigid-body

(item (5) of [Rigids velocity x v] :: list)

The velocity x of the 5th rigid-body

(item (5) of [Rigids velocity y v] :: list)

The velocity y of the 5th rigid-body

(item (5) of [Rigids shape v] :: list)

The shape of the 5th rigid-body

(item (5) of [Rigids radius v] :: list)

The radius of the 5th rigid-body, only if its shape type is circle

(item (5) of [Rigids width v] :: list)

The width of the 5th rigid-body, only if its shape type is rectangle

(item (5) of [Rigids height v] :: list)

The height of the 5th rigid-body, only if its shape type is rectangle

(item (5) of [Rigids friction v] :: list)

The friction of the 5th rigid-body

(item (5) of [Rigids restitution v] :: list)

The restitution/bounciness of the 5th rigid-body

(item (5) of [Rigids is colliding? v] :: list)

boolean value. Indicates whether the 5th rigid body is colliding with another rigid body. Returns “true” if it is colliding, otherwise “false”

Physics Settings
In the Sprite “Settings”, you can find this custom block definition, which includes several parameters that can be adjusted according to your project.

define initialize physics settings

set [ _iter impulse v] to []

The number of impulse iterations. A higher value makes the physics simulation more stable, but reduces performance efficiency

set [ _time step v] to []

The physics update time step. It is usually set based on the average FPS of the development environment

set [ _gravity x v] to []

The gravitational acceleration in the x direction. If set too high, it may cause instability in stacked objects or result in physics tunneling (objects passing through each other)

set [ _gravity y v] to []

The gravitational acceleration in the y direction. If set too high, it may cause instability in stacked objects or result in physics tunneling (objects passing through each other)

set [ _restitution v] to []

The default restitution/bounciness value when creating a new rigid-body

set [ _friction v] to []

The default friction value when creating a new rigid-body

set [ _air drag rate v] to []

The air drag coefficient. It controls how strongly air resistance slows down objects over time.

set [ _impulse scale v] to []

The warm-starting impulse scale. It controls how much of the previous frame’s impulses are reused to improve solver stability (0.0 ~ 1.0)

Rendering Setting
The rendering settings are located in the sprite “Renderer”, where you can configure the style of the built-in renderer. you can find this custom block definition, which includes several parameters that can be adjusted according to your project:

define reset render option list

define reset render option information list

Where you can set the color and pen size, what to draw or what to not draw based on your preference

Enjoy and good luck on your development!

Thanks !

Ricky-Jan wrote:

…

Download or remix the package to start using the library
Force2D v3.1.3 pakagepackage: https://scratch.mit.edu/projects/1320076341/

Example demotrationdemonstration of the physics engine:
Force2D v3.1.1 demo: https://scratch.mit.edu/projects/1311913398/

…

To start using the physics engine, weyou need to locate the Launcher, which will also serve as your primary development environment.

…

 initialize 

initilaizeinitialize the camera position and the zoom scale

…

Joints
There are few joint types: distance joint, revolute joint, mouse joint, prismatic joint, weld joint.
All the joint function was shown in demotrationsdemonstrations: https://scratch.mit.edu/projects/1311913398/

…

new revolute joint between rigid A:() B:() anchor local pos A:()() B:()()stiffness:() motor speed:() max torque()

create a revolute joint between objects, make objects canable to rotate withabout the specific point. Application like windmills, hinges, etc.

…

new prismatic joint between rigid A:() B:() anchor local pos A:()()B:()()axis:()lower limit:() upper limit:()fix in direction?<>motor speed:()max force:()

create prismatic joint between objects, make objects can able to slide inalong the specific axis. Application like pistons, elevators, etc.

…

new mouse joint with target rigid:()point position:()()anchor local pos:()()max force:()stiffness()damping:()

create a spring like joint to the target object, to hang or drag objects. Application like dragging objects, elastic suspended objects, etc...

…

new weld joint between rigid A:()rigid B:()anchor local pos A:()()B:()()stiffness:()

create a weld joint to attachesattach two objects together so they behave as a single body. Their relative position and rotation remain fixed. Application like creating compound bodies or vehicles

…

Object Coloring

fill rigid:() with hexadecimal color code:()

fillfills the object with color that the format isformatted as a hexadecimal color code

…

fill rigid:() with color r:()g:()b:()a:()

fillfills the object with color that the format is RGBA

…

fill rigid:() with color h:()s:()v:()

fillfills the object with color that the format is HSV/HVB

…

There's a few more, but these are the major typos and/or grammar mistakes I found.

Also, your custom blocks are showing as red because the renderer doesn't see the definitions for them. IIRC you need to force the color with “::custom”. e.g.

this is red

this is the right color::custom

Anyways really cool engine! It's surprisingly fast