< GeeXLab Reference Guide />

gh_box2d library

Description

gh_box2d is the module that manages the Box2D Physics engine. This module is in WIP state (work in progress) and can change in future versions of GeeXLab.

Number of functions: 47

gh_box2d.init ()
gh_box2d.terminate ()
gh_box2d.get_version ()
gh_box2d.world_init ()
gh_box2d.world_terminate ()
gh_box2d.world_set_gravity ()
gh_box2d.world_step_simulation ()
gh_box2d.world_clear_forces ()
gh_box2d.world_set_auto_clear_forces ()
gh_box2d.world_create_actor_box ()
gh_box2d.world_create_actor_circle ()
gh_box2d.world_kill_actor ()
gh_box2d.world_create_actor ()
gh_box2d.actor_add_vertices ()
gh_box2d.actor_chain_build ()
gh_box2d.actor_polygon_build ()
gh_box2d.actor_box_set_size ()
gh_box2d.actor_box_build ()
gh_box2d.actor_circle_set_radius ()
gh_box2d.actor_circle_build ()
gh_box2d.actor_apply_transform ()
gh_box2d.actor_set_transform ()
gh_box2d.actor_get_transform ()
gh_box2d.actor_set_damping ()
gh_box2d.actor_set_ccd ()
gh_box2d.actor_set_enabled ()
gh_box2d.actor_set_awake ()
gh_box2d.actor_is_awake ()
gh_box2d.actor_set_sleeping_allowed ()
gh_box2d.actor_set_linear_velocity ()
gh_box2d.actor_set_linear_angular ()
gh_box2d.actor_set_density ()
gh_box2d.actor_set_friction ()
gh_box2d.actor_set_restitution ()
gh_box2d.actor_apply_force ()
gh_box2d.actor_apply_force_to_center ()
gh_box2d.actor_apply_torque ()
gh_box2d.actor_apply_linear_impulse ()
gh_box2d.actor_apply_linear_impulse_to_center ()
gh_box2d.actor_raycast ()
gh_box2d.actor_read_contacts ()
gh_box2d.actor_get_contact_actor ()
gh_box2d.world_kill_joint ()
gh_box2d.world_create_joint_distance ()
gh_box2d.joint_distance_set_stiffness ()
gh_box2d.joint_distance_set_damping ()
gh_box2d.joint_distance_compute_linear_stiffness ()

init

Description

Initializes the Box2D plugin. This the first function to call.

Syntax

ret = gh_box2d.init()

Languages

Parameters

This function has no input parameter(s).

Return Values

ret [BOOLEAN]: return code: 1 (success) or 0 (error)

Code sample


ret = gh_box2d.init()

terminate

Description

Terminates the Box2D plugin. This function should be call in the TERMINATE script.

Syntax

ret = gh_box2d.terminate()

Languages

Parameters

This function has no input parameter(s).

Return Values

ret [BOOLEAN]: return code: 1 (success) or 0 (error)

Code sample


ret = gh_box2d.terminate()

get_version

Description

Returns the version of the Box2D engine.

Syntax

major, minor, revision = gh_box2d.get_version()

Languages

Parameters

This function has no input parameter(s).

Return Values

major, minor, revision [INTEGER]: version

Code sample


major, minor, revision = gh_box2d.get_version()

world_init

Description

Creates and initializes a physics world. Every Box2D demo begins with the creation of a world. A world is the physics hub that manages all Box2D objects.

Syntax

wid = gh_box2d.world_init()

Languages

Parameters

This function has no input parameter(s).

Return Values

wid [ID]: world identifier

Code sample


wid = gh_box2d.world_init()

world_terminate

Description

Terminates and destroys a physics world.

Syntax

gh_box2d.world_terminate( wid )

Languages

Parameters

wid [ID]: world identifier

Return Values

This function has no return value(s).

Code sample


gh_box2d.world_terminate(wid)

world_set_gravity

Description

Sets the world gravity vector.

Syntax

gh_box2d.world_set_gravity( wid, x, y )

Languages

Parameters

wid [ID]: world identifier
x, y [REAL]: gravity vector

Return Values

This function has no return value(s).

Code sample


gh_box2d.world_set_gravity(wid, 0, -10)

world_step_simulation

Description

Performs a world simulation step.

Syntax

gh_box2d.world_step_simulation( wid, time_step, velocity_iterations, position_iterations )

Languages

Parameters

wid [ID]: world identifier
time_step [REAL]: time step between two frames
velocity_iterations [INTEGER]: number of solver iterations for velocity
position_iterations [INTEGER]: number of solver iterations for position

Return Values

This function has no return value(s).

Code sample


dt = 1.0/60.0			
velocity_iterations = 8
position_iterations = 4
gh_box2d.world_step_simulation(wid, dt, velocity_iterations, position_iterations)

world_clear_forces

Description

Clears all forces of all objects. Automatically done after each world_step_simulation() unless you disable this feature with world_set_auto_clear_forces().

Syntax

gh_box2d.world_clear_forces( wid )

Languages

Parameters

wid [ID]: world identifier

Return Values

This function has no return value(s).

Code sample


gh_box2d.world_clear_forces(wid)

world_set_auto_clear_forces

Description

Set the auto clear forces state.

Syntax

gh_box2d.world_set_auto_clear_forces( wid, state )

Languages

Parameters

wid [ID]: world identifier
state [BOOLEAN]: disables (0) or enabled (1)

Return Values

This function has no return value(s).

Code sample


state = 0
gh_box2d.world_set_auto_clear_forces(wid, state)

world_create_actor_box

Description

Creates a box actor and adds it to the world.

Syntax

aid = gh_box2d.world_create_actor_box( wid, posx, posy, width, height, body_type, density, friction, restitution )

Languages

Parameters

wid [ID]: world identifier
posx, posy [REAL]: initial position
width, height [REAL]: box size
body_type [STRING]: body type: static, kinematic or dynamic
density [REAL]: density - mass will be computed later based on the volume and density.
friction [REAL]: friction
restitution [REAL]: restitution

Return Values

aid [ID]: actor identifier

Code sample


body_type = "dynamic"			
density = 10.0
friction = 0.1
restitution = 0.4
aid = gh_box2d.world_create_actor_box(wid, posx, posy, width, height, body_type, density, friction, restitution)

world_create_actor_circle

Description

Creates a circle (disc?) actor and adds it to the world.

Syntax

aid = gh_box2d.world_create_actor_circle( wid, posx, posy, radius, body_type, density, friction, restitution )

Languages

Parameters

wid [ID]: world identifier
posx, posy [REAL]: initial position
radius [REAL]: disc radius
body_type [STRING]: body type: static, kinematic or dynamic
density [REAL]: density - mass will be computed later based on the volume and density.
friction [REAL]: friction
restitution [REAL]: restitution

Return Values

aid [ID]: actor identifier

Code sample


body_type = "dynamic"			
density = 10.0
friction = 0.1
restitution = 0.4
aid = gh_box2d.world_create_actor_circle(wid, posx, posy, radius, body_type, density, friction, restitution)

world_kill_actor

Description

Destroys and remove an actor from the world.

Syntax

gh_box2d.world_kill_actor( wid, aid )

Languages

Parameters

wid [ID]: world identifier
aid [ID]: actor identifier

Return Values

This function has no return value(s).

Code sample


gh_box2d.world_kill_actor(wid, aid)

world_create_actor

Description

Creates a generic actor and adds it to the world. Its shape (circle, box, polygon, chain) must be defined before calling world_step_simulation().

Syntax

aid = gh_box2d.world_create_actor( wid, posx, posy, body_type )

Languages

Parameters

wid [ID]: world identifier
posx, posy [REAL]: initial position
body_type [STRING]: body type: static, kinematic or dynamic

Return Values

aid [ID]: actor identifier

Code sample


body_type = "dynamic"			
aid = gh_box2d.world_create_actor(wid, posx, posy, body_type)
gh_box2d.actor_circle_set_radius(aid, 2.0)
gh_box2d.actor_circle_build(aid)

actor_add_vertices

Description

Adds a vertex to the vertices list of an actor. This vertices list will be used to build the shape later.

Syntax

gh_box2d.actor_add_vertices( aid, x, y )

Languages

Parameters

aid [ID]: actor identifier
x, y [REAL]: vertex 2D position

Return Values

This function has no return value(s).

Code sample


b2_triangle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_triangle, -1,-1)
gh_box2d.actor_add_vertices(b2_triangle,  0, 1)
gh_box2d.actor_add_vertices(b2_triangle,  1,-1)
gh_box2d.actor_polygon_build(b2_triangle)

actor_chain_build

Description

Builds a chain shaped actor from the vertices list initialized with calls to actor_add_vertices().

Syntax

gh_box2d.actor_chain_build( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

This function has no return value(s).

Code sample


b2_chain = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_chain, 1, 1)
gh_box2d.actor_add_vertices(b2_chain,  0, -1)
gh_box2d.actor_add_vertices(b2_chain,  -1, -1)
gh_box2d.actor_add_vertices(b2_chain,  -2, 1)
gh_box2d.actor_chain_build(b2_chain)

actor_polygon_build

Description

Builds a polygon shaped actor from the vertices list initialized with calls to actor_add_vertices().

Syntax

gh_box2d.actor_polygon_build( aid, x, y )

Languages

Parameters

aid [ID]: actor identifier
x, y [REAL]: vertex 2D position

Return Values

This function has no return value(s).

Code sample


b2_triangle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_add_vertices(b2_triangle, -1,-1)
gh_box2d.actor_add_vertices(b2_triangle,  0, 1)
gh_box2d.actor_add_vertices(b2_triangle,  1,-1)
gh_box2d.actor_polygon_build(b2_triangle)

actor_box_set_size

Description

Sets the size of a box shaped actor.

Syntax

gh_box2d.actor_box_set_size( aid, w, h )

Languages

Parameters

aid [ID]: actor identifier
w, h [REAL]: width and height

Return Values

This function has no return value(s).

Code sample


b2_box = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_box_set_size(b2_box, 2.0, 2.0)
gh_box2d.actor_box_build(b2_box)

actor_box_build

Description

Builds a box shaped actor.

Syntax

gh_box2d.actor_box_build( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

This function has no return value(s).

Code sample


b2_box = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_box_set_size(b2_box, 2.0, 2.0)
gh_box2d.actor_box_build(b2_box)

actor_circle_set_radius

Description

Sets the radius of a circle shaped actor.

Syntax

gh_box2d.actor_circle_set_radius( aid, r )

Languages

Parameters

aid [ID]: actor identifier
r [REAL]: radius

Return Values

This function has no return value(s).

Code sample


b2_circle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_circle_set_radius(b2_circle, 2.0, 2.0)
gh_box2d.actor_box_actor_circle_buildbuild(b2_circle)

actor_circle_build

Description

Builds a circle shaped actor.

Syntax

gh_box2d.actor_circle_build( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

This function has no return value(s).

Code sample


b2_circle = gh_box2d.world_create_actor(b2_world, -3, 10,  "dynamic")
gh_box2d.actor_circle_set_radius(b2_circle, 2.0, 2.0)
gh_box2d.actor_box_actor_circle_buildbuild(b2_circle)

actor_apply_transform

Description

Applies the transformation of a Box2D actor to a 3D object.

Syntax

gh_box2d.actor_apply_transform( aid, object_id )

Languages

Parameters

aid [ID]: actor identifier
object_id [ID]: object identifier

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_transform(aid, mesh_id)

actor_set_transform

Description

Sets the transformation of a Box2D actor.

Syntax

gh_box2d.actor_set_transform( aid, x, y, angle )

Languages

Parameters

aid [ID]: actor identifier
x, y [REAL]: actor position
angle [REAL]: actor orientation in radians

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_transform(aid, x, y, angle)

actor_get_transform

Description

Gets the transformation of a Box2D actor.

Syntax

x, y, angle = gh_box2d.actor_get_transform( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

x, y [REAL]: actor position
angle [REAL]: actor orientation in radians

Code sample


x, y, angle = gh_box2d.actor_get_transform(aid)

actor_set_damping

Description

Sets the damping coefficients of a Box2D actor.

Syntax

gh_box2d.actor_set_damping( aid, linear, angular )

Languages

Parameters

aid [ID]: actor identifier
linear [REAL]: linear damping
angular [REAL]: angular damping

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_damping(aid, linear, angular)

actor_set_ccd

Description

Sets the CCD (continuous collision detection) state of a Box2D actor. Useful for fast moving actors like bullets. Disabled by default.

Syntax

gh_box2d.actor_set_ccd( aid, state )

Languages

Parameters

aid [ID]: actor identifier
state [BOOLEAN]: disabled (0) or enabled (1)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_ccd(aid, state)

actor_set_enabled

Description

Sets the enabled state of a Box2D actor.

Syntax

gh_box2d.actor_set_enabled( aid, state )

Languages

Parameters

aid [ID]: actor identifier
state [BOOLEAN]: disabled (0) or enabled (1)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_enabled(aid, state)

actor_set_awake

Description

Sets the awake state of a Box2D actor.

Syntax

gh_box2d.actor_set_awake( aid, state )

Languages

Parameters

aid [ID]: actor identifier
state [BOOLEAN]: disabled (0) or enabled (1)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_awake(aid, state)

actor_is_awake

Description

Gets the awake state of a Box2D actor.

Syntax

state = gh_box2d.actor_is_awake( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

state [BOOLEAN]: disabled (0) or enabled (1)

Code sample


state = gh_box2d.actor_is_awake(aid)

actor_set_sleeping_allowed

Description

Sets the sleeping allowed state of a Box2D actor.

Syntax

gh_box2d.actor_set_sleeping_allowed( aid, state )

Languages

Parameters

aid [ID]: actor identifier
state [BOOLEAN]: disabled (0) or enabled (1)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_sleeping_allowed(aid, state)

actor_set_linear_velocity

Description

Sets the linear velocity of a Box2D actor.

Syntax

gh_box2d.actor_set_linear_velocity( aid, x, y )

Languages

Parameters

aid [ID]: actor identifier
x, y [REAL]: linear velocity along X and Y axis

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_linear_velocity(aid, x, y)

actor_set_linear_angular

Description

Sets the angular velocity of a Box2D actor.

Syntax

gh_box2d.actor_set_linear_angular( aid, x )

Languages

Parameters

aid [ID]: actor identifier
x [REAL]: angular velocity

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_linear_angular(aid, x)

actor_set_density

Description

Sets the density of an actor. The mass will be updated.

Syntax

gh_box2d.actor_set_density( aid, x )

Languages

Parameters

aid [ID]: actor identifier
x [REAL]: density

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_density(aid, x)

actor_set_friction

Description

Sets the friction of an actor.

Syntax

gh_box2d.actor_set_friction( aid, x )

Languages

Parameters

aid [ID]: actor identifier
x [REAL]: friction

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_friction(aid, x)

actor_set_restitution

Description

Sets the restitution of an actor.

Syntax

gh_box2d.actor_set_restitution( aid, x )

Languages

Parameters

aid [ID]: actor identifier
x [REAL]: restitution

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_set_restitution(aid, x)

actor_apply_force

Description

Apply a force on an actor at a world point.

Syntax

gh_box2d.actor_apply_force( aid, force_x, force_y, point_x, point_y, wake )

Languages

Parameters

aid [ID]: actor identifier
force_x, force_y [REAL]: force in Newtons (N)
point_x, point_y [REAL]: world point
wake [INTEGER]: wake up the actor (1 or 0)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_force(aid, force_x, force_y, point_x, point_y, wake)

actor_apply_force_to_center

Description

Apply a force on the center of mass of an actor.

Syntax

gh_box2d.actor_apply_force_to_center( aid, force_x, force_y, wake )

Languages

Parameters

aid [ID]: actor identifier
force_x, force_y [REAL]: force in Newtons (N)
wake [INTEGER]: wake up the actor (1 or 0)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_force_to_center(aid, force_x, force_y, wake)

actor_apply_torque

Description

Apply a torque on an actor.

Syntax

gh_box2d.actor_apply_torque( aid, torque, wake )

Languages

Parameters

aid [ID]: actor identifier
torque [REAL]: torque in N-m
wake [INTEGER]: wake up the actor (1 or 0)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_torque(aid, torque, wake)

actor_apply_linear_impulse

Description

Apply an impulse on an actor at a world point.

Syntax

gh_box2d.actor_apply_linear_impulse( aid, impulse_x, impulse_y, point_x, point_y, wake )

Languages

Parameters

aid [ID]: actor identifier
impulse_x, impulse_y [REAL]: impulse in N-seconds or kg-m/s
point_x, point_y [REAL]: world point
wake [INTEGER]: wake up the actor (1 or 0)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_linear_impulse(aid, impulse_x, impulse_y, point_x, point_y, wake)

actor_apply_linear_impulse_to_center

Description

Apply an impulse on the center of mass of an actor.

Syntax

gh_box2d.actor_apply_linear_impulse_to_center( aid, impulse_x, impulse_y, wake )

Languages

Parameters

aid [ID]: actor identifier
impulse_x, impulse_y [REAL]: impulse in N-seconds or kg-m/s
wake [INTEGER]: wake up the actor (1 or 0)

Return Values

This function has no return value(s).

Code sample


gh_box2d.actor_apply_linear_impulse_to_center(aid, impulse_x, impulse_y, wake)

actor_raycast

Description

Casts a ray on an actor and gets the hit point.

Syntax

ret, hit_point_x, hit_point_y = gh_box2d.actor_raycast( aid, x0, y0, x1, y1 )

Languages

Parameters

aid [ID]: actor identifier
x0, y0 [REAL]: ray start
x1, y1 [REAL]: ray end

Return Values

ret [INTEGER]: 1 if intersection found, 0 otherwise.
hit_point_x, hit_point_y [REAL]: coordinates of the hit point.

Code sample


ret, hit_point_x, hit_point_y = gh_box2d.actor_raycast(aid, x0, y0, x1, y1)

actor_read_contacts

Description

Sets the angular velocity of a Box2D actor.

Syntax

num_contacts, x, y = gh_box2d.actor_read_contacts( aid )

Languages

Parameters

aid [ID]: actor identifier

Return Values

num_contacts [INTEGER]: number of contacts
x, y [REAL]: position of the first contact

Code sample


num_contacts, x, y = gh_box2d.actor_read_contacts(aid)

actor_get_contact_actor

Description

Gets the actor ID of a particular contact.

Syntax

contact_actor_id, cx, cy = gh_box2d.actor_get_contact_actor( actor_id, contact_index )

Languages

Parameters

actor_id [ID]: actor identifier
contact_index [INTEGER]: contact index from [0; num_contacts] - call actor_read_contacts() for num_contacts.

Return Values

contact_actor_id [ID]: ID of the actor in contact
cx, cy [REAL]: position of the contact

Code sample


num_contacts, x, y = gh_box2d.actor_read_contacts(actor_id)
for i=0, num_contacts-1 do
  contact_actor_id, cx, cy = gh_box2d.actor_get_contact_actor(actor_id, i)
	...
end

world_kill_joint

Description

Kills an existing joint.

Syntax

gh_box2d.world_kill_joint( wid, jid )

Languages

Parameters

wid [ID]: world identifier
jid [ID]: joint identifier

Return Values

This function has no return value(s).

Code sample


gh_box2d.world_kill_joint(wid, jid)

world_create_joint_distance

Description

Creates a distance joint between two actors (A and B).

Syntax

jid = gh_box2d.world_create_joint_distance( wid, a, b, anchor_a_x, anchor_a_y, anchor_b_x, anchor_b_y )

Languages

Parameters

wid [ID]: world identifier
a [ID]: actor A
b [ID]: actor B
anchor_a_x, anchor_a_y [REAL]: anchor point in actor A
anchor_b_x, anchor_b_y [REAL]: anchor point in actor B

Return Values

jid [ID]: joint identifier

Code sample


jid = gh_box2d.world_create_joint_distance(wid, a, b, anchor_a_x, anchor_a_y, anchor_b_x, anchor_b_y)

joint_distance_set_stiffness

Description

Sets the stiffness of a joint.

Syntax

gh_box2d.joint_distance_set_stiffness( wid, stiffness )

Languages

Parameters

wid [ID]: world identifier
stiffness [REAL]: stiffness value

Return Values

This function has no return value(s).

Code sample


gh_box2d.joint_distance_set_stiffness(jid, stiffness)

joint_distance_set_damping

Description

Sets the damping of a joint.

Syntax

gh_box2d.joint_distance_set_damping( wid, damping )

Languages

Parameters

wid [ID]: world identifier
damping [REAL]: damping value

Return Values

This function has no return value(s).

Code sample


gh_box2d.joint_distance_set_damping(jid, damping)

joint_distance_compute_linear_stiffness

Description

Utility function that computes the stiffness and damping of a joint.

Syntax

stiffness, damping = gh_box2d.joint_distance_compute_linear_stiffness( wid, frequency_hz, damping_ratio )

Languages

Parameters

wid [ID]: world identifier
frequency_hz [REAL]: frequency in Hertz
damping_ratio [REAL]: non-dimensional value, typically between 0 and 1

Return Values

stiffness, damping [REAL]: stiffness and damping

Code sample


frequency_hz = 4.0			
damping_ratio = 0.5
stiffness, damping = gh_box2d.joint_distance_compute_linear_stiffness(jid, frequency_hz, damping_ratio)

GeeXLab Rootard Guide | Downloads | Contact