< GeeXLab Reference Guide />

> Back to Reference Guide Index


gh_bullet3 Library

Description

gh_bullet3 is the module that manages the Bullet Physics engine.


Number of functions: 47

  1. gh_bullet3.init (Lua - Python)
  2. gh_bullet3.terminate (Lua - Python)
  3. gh_bullet3.get_api_version (Lua - Python)
  4. gh_bullet3.scene_init (Lua - Python)
  5. gh_bullet3.scene_init_sap (Lua - Python)
  6. gh_bullet3.scene_terminate (Lua - Python)
  7. gh_bullet3.scene_set_gravity (Lua - Python)
  8. gh_bullet3.scene_set_solver_num_iterations (Lua - Python)
  9. gh_bullet3.scene_step_simulation (Lua - Python)
  10. gh_bullet3.actor_set_3d_object (Lua - Python)
  11. gh_bullet3.scene_sync_3d_objects (Lua - Python)
  12. gh_bullet3.scene_add_actor (Lua - Python)
  13. gh_bullet3.scene_remove_actor (Lua - Python)
  14. gh_bullet3.actor_create_box (Lua - Python)
  15. gh_bullet3.actor_create_sphere (Lua - Python)
  16. gh_bullet3.actor_create_cylinder (Lua - Python)
  17. gh_bullet3.actor_create_static_plane (Lua - Python)
  18. gh_bullet3.actor_create_mesh (Lua - Python)
  19. gh_bullet3.actor_kill (Lua - Python)
  20. gh_bullet3.actor_apply_transform (Lua - Python)
  21. gh_bullet3.actor_set_position (Lua - Python)
  22. gh_bullet3.actor_set_orientation (Lua - Python)
  23. gh_bullet3.actor_get_position (Lua - Python)
  24. gh_bullet3.actor_get_orientation (Lua - Python)
  25. gh_bullet3.actor_set_linear_velocity (Lua - Python)
  26. gh_bullet3.actor_get_linear_velocity (Lua - Python)
  27. gh_bullet3.actor_get_linear_speed2 (Lua - Python)
  28. gh_bullet3.actor_set_angular_velocity (Lua - Python)
  29. gh_bullet3.actor_get_angular_velocity (Lua - Python)
  30. gh_bullet3.actor_get_angular_speed2 (Lua - Python)
  31. gh_bullet3.actor_set_gravity (Lua - Python)
  32. gh_bullet3.actor_set_linear_factor (Lua - Python)
  33. gh_bullet3.actor_set_angular_factor (Lua - Python)
  34. gh_bullet3.actor_apply_central_force (Lua - Python)
  35. gh_bullet3.actor_apply_central_impulse (Lua - Python)
  36. gh_bullet3.actor_apply_torque (Lua - Python)
  37. gh_bullet3.actor_clear_forces (Lua - Python)
  38. gh_bullet3.actor_set_damping (Lua - Python)
  39. gh_bullet3.actor_set_collision_margin (Lua - Python)
  40. gh_bullet3.material_create (Lua - Python)
  41. gh_bullet3.material_kill (Lua - Python)
  42. gh_bullet3.material_update (Lua - Python)
  43. gh_bullet3.actor_set_material (Lua - Python)
  44. gh_bullet3.actor_update_mass (Lua - Python)
  45. gh_bullet3.scene_check_contacts (Lua - Python)
  46. gh_bullet3.actor_get_contact_info (Lua - Python)
  47. gh_bullet3.scene_reset_all_contacts (Lua - Python)



gh_bullet3.init

Description

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

Languages

Lua - Python

Parameters

This function has no input parameter(s).

Return Values

  • ret [INTEGER]: error code: 1 if ok or 0 if error.

    Code sample

        
    rc = gh_bullet3.init()
                


    gh_bullet3.terminate

    Description

    Stops the Bullet engine and frees resources.

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • ret [INTEGER]: error code: 1 if ok or 0 if error.

    Code sample

        
    rc = gh_bullet3.terminate()
                


    gh_bullet3.get_api_version

    Description

    Gets the Bullet API version as a single integer (ex: 288).

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • v [INTEGER]: API version.

    Code sample

        
    v = gh_bullet3.get_api_version()
                


    gh_bullet3.scene_init

    Description

    Initializes a physics scene (Bullet Dbvt broadphase)

    Languages

    Lua - Python

    Parameters

    This function has no input parameter(s).

    Return Values

  • sid [INTEGER]: scene id.

    Code sample

        
    sid = gh_bullet3.scene_init()
                


    gh_bullet3.scene_init_sap

    Description

    Initializes a physics scene (Bullet AxisSweep3 broadphase). For this scene, you have to specify the expected scene dimensions.

    Languages

    Lua - Python

    Parameters

  • min_x, min_y, min_z [REAL]: world dimensions (minimal AABB values).
  • max_x, max_y, max_z [REAL]: world dimensions (max AABBvalues).

    Return Values

  • sid [INTEGER]: scene id.

    Code sample

        
    sid = gh_bullet3.scene_init_sap(x0, y0, z0,  x1, x1, z1)
                


    gh_bullet3.scene_terminate

    Description

    Terminates a physics scene.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_terminate(sid)
                


    gh_bullet3.scene_set_gravity

    Description

    Sets the global gravity of the scene (ex: [0.0, -10; 0.0]).

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.
  • x, y, z [REAL]: gravity vector.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_set_gravity(sid, x, y, z)
                


    gh_bullet3.scene_set_solver_num_iterations

    Description

    Sets the number of iterations of the solver. The simulation stability increases with the number of iterations but the simulation is slower.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.
  • iterations [INTEGER]: number of iterations - default value is 10.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_set_solver_num_iterations(sid, iterations)
                


    gh_bullet3.scene_step_simulation

    Description

    Performs a scene simulation step. The relation between the parameters should follow this rule: timeStep < maxSubSteps * fixedTimeStep.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.
  • time_step [REAL]: time step between two frames.
  • max_sub_steps [INTEGER]: number of sub steps.
  • fixed_time_step [REAL]: fixed time step - default value: 1.0/60.0

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_step_simulation(sid, dt, max_sub_steps, 1.0/60.0)
                


    gh_bullet3.actor_set_3d_object

    Description

    Allows to associate a physics actor and a 3D object. Useful for the scene_sync_3d_objects() function.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • oid [INTEGER]: 3d object id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_3d_object(aid, oid)
                


    gh_bullet3.scene_sync_3d_objects

    Description

    Synchronizes physics and graphics objects. A physcis actor is associated to a 3D object using the actor_set_3d_object() function

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_sync_3d_objects(sid)
                


    gh_bullet3.scene_add_actor

    Description

    Adds a physics actor to a physics scene.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.
  • aid [INTEGER]: actor id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_add_actor(sid, aid)
                


    gh_bullet3.scene_remove_actor

    Description

    Removes a physics actor from a physics scene.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.
  • aid [INTEGER]: actor id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_remove_actor(sid, aid)
                


    gh_bullet3.actor_create_box

    Description

    Creates a box actor.

    Languages

    Lua - Python

    Parameters

  • w, h, d [REAL]: dimensions of the box.
  • x, y, z [REAL]: initial position of the actor.
  • mass [REAL]: mass (set the mass = 0 for a kinematic actor).
  • mid [INTEGER]: material id.

    Return Values

  • aid [INTEGER]: actor id.

    Code sample

        
    aid = gh_bullet3.actor_create_box(w, h, d, x, y, z, mass, mid)
                


    gh_bullet3.actor_create_sphere

    Description

    Creates a sphere actor.

    Languages

    Lua - Python

    Parameters

  • radius [REAL]: sphere radius.
  • x, y, z [REAL]: initial position of the actor.
  • mass [REAL]: mass (set the mass = 0 for a kinematic actor).
  • mid [INTEGER]: material id.

    Return Values

  • aid [INTEGER]: actor id.

    Code sample

        
    aid = gh_bullet3.actor_create_sphere(radius, x, y, z, mass, mid)
                


    gh_bullet3.actor_create_cylinder

    Description

    Creates a cylinder actor.

    Languages

    Lua - Python

    Parameters

  • central_axis [INTEGER]: direction of the main axis: 0 (along X axis), 1 (along Y axis) or 2 (along Z axis)
  • height [REAL]: cylinder height.
  • radius [REAL]: cylinder radius.
  • x, y, z [REAL]: initial position of the actor.
  • mass [REAL]: mass (set the mass = 0 for a kinematic actor).
  • mid [INTEGER]: material id.

    Return Values

  • aid [INTEGER]: actor id.

    Code sample

        
    aid = gh_bullet3.actor_create_cylinder(central_axis, height, radius, x, y, z, mass, mid)
                


    gh_bullet3.actor_create_static_plane

    Description

    Creates a static plane actor. This is an infinite plane defined by a plane eqution.

    Languages

    Lua - Python

    Parameters

  • nx, ny, nz, d [REAL]: plane equation
  • mid [INTEGER]: material id.

    Return Values

  • aid [INTEGER]: actor id.

    Code sample

        
    nx = 0
    ny = 1
    nz = 0
    d = 0            
    aid = gh_bullet3.actor_create_static_plane(nx, ny, nz, d, mid)
                


    gh_bullet3.actor_create_mesh

    Description

    Creates an actor from a mesh.

    Languages

    Lua - Python

    Parameters

  • mesh_id [INTEGER]: mesh id.
  • convex [INTEGER]: convex mesh (1) or not (0).
  • x, y, z [REAL]: initial position of the actor.
  • mass [REAL]: mass (set the mass = 0 for a kinematic actor).
  • mid [INTEGER]: material id.

    Return Values

  • aid [INTEGER]: actor id.

    Code sample

        
    aid = gh_bullet3.actor_create_mesh(meshid, convex, x, y, z, mass, mid)
                


    gh_bullet3.actor_kill

    Description

    Destroys an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_kill(aid)
                


    gh_bullet3.actor_apply_transform

    Description

    Apply the transformation matrix of a physics actor to a 3D object. It's a manual physcis/graphics synchronization. Use this function if you don't use scene_sync_3d_objects().

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • oid [INTEGER]: 3d object id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_apply_transform(aid, oid)
                


    gh_bullet3.actor_set_position

    Description

    Sets the position of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: 3d position.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_position(aid, x, y, z)
                


    gh_bullet3.actor_set_orientation

    Description

    Sets the orientation of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • qx, qy, qz, qw [REAL]: orientation quaternion.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_orientation(aid, qx, qy, qz, qw)
                


    gh_bullet3.actor_get_position

    Description

    Gets the position of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • x, y, z [REAL]: 3d position.

    Code sample

        
    x, y, z = gh_bullet3.actor_get_position(aid)
                


    gh_bullet3.actor_get_orientation

    Description

    Gets the orientation of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • qx, qy, qz, qw [REAL]: orientation quaternion.

    Code sample

        
    qx, qy, qz, qw = gh_bullet3.actor_get_orientation(aid)
                


    gh_bullet3.actor_set_linear_velocity

    Description

    Sets the linear velocity of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: velocity vector.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_linear_velocity(aid, x, y, z)
                


    gh_bullet3.actor_get_linear_velocity

    Description

    Gets the linear velocity of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • x, y, z [REAL]: velocity vector.

    Code sample

        
    x, y, z= gh_bullet3.actor_get_linear_velocity(aid)
                


    gh_bullet3.actor_get_linear_speed2

    Description

    Gets the squared linear speed of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • s [REAL]: squared speed.

    Code sample

        
    s = gh_bullet3.actor_get_linear_speed2(aid)
                


    gh_bullet3.actor_set_angular_velocity

    Description

    Sets the angular velocity of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: velocity vector.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_angular_velocity(aid, x, y, z)
                


    gh_bullet3.actor_get_angular_velocity

    Description

    Gets the angular velocity of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • x, y, z [REAL]: velocity vector.

    Code sample

        
    x, y, z= gh_bullet3.actor_get_angular_velocity(aid)
                


    gh_bullet3.actor_get_angular_speed2

    Description

    Gets the squared angular speed of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

  • s [REAL]: squared speed.

    Code sample

        
    s = gh_bullet3.actor_get_angular_speed2(aid)
                


    gh_bullet3.actor_set_gravity

    Description

    Sets a gravity vector for an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: gravity vector.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_gravity(aid, x, y, z)
                


    gh_bullet3.actor_set_linear_factor

    Description

    Allows to limit (or amplify) the linear velocity along some axis.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: factor.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_linear_factor(aid, x, y, z)
                


    gh_bullet3.actor_set_angular_factor

    Description

    Allows to limit (or amplify) the angular velocity along some axis.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: factor.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_angular_factor(aid, x, y, z)
                


    gh_bullet3.actor_apply_central_force

    Description

    Applies a force to an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: force.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_apply_central_force(aid, x, y, z)
                


    gh_bullet3.actor_apply_central_impulse

    Description

    Applies an impulse force to an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: force.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_apply_central_impulse(aid, x, y, z)
                


    gh_bullet3.actor_apply_torque

    Description

    Applies a torque to an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • x, y, z [REAL]: torque.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_apply_torque(aid, x, y, z)
                


    gh_bullet3.actor_clear_forces

    Description

    Clears (resets) all forces that act on an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_clear_forces(aid)
                


    gh_bullet3.actor_set_damping

    Description

    Sets damping factors.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • linear [REAL]: linear damping.
  • angular [REAL]: angular damping.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_damping(aid, linear, angular)
                


    gh_bullet3.actor_set_collision_margin

    Description

    Sets the collision margin of an actor. Useful to improve simulation stability.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • margin [REAL]: collision margin.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_collision_margin(aid, margin)
                


    gh_bullet3.material_create

    Description

    Creates a new material.

    Languages

    Lua - Python

    Parameters

  • restitution [REAL]: restitution factor.
  • friction [REAL]: friction factor.

    Return Values

  • mid [INTEGER]: material id.

    Code sample

        
    mid = gh_bullet3.material_create(restitution, friction)
                


    gh_bullet3.material_kill

    Description

    Destroys a material.

    Languages

    Lua - Python

    Parameters

  • mid [INTEGER]: material id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.material_kill(mid)
                


    gh_bullet3.material_update

    Description

    updates the properties of a material

    Languages

    Lua - Python

    Parameters

  • mid [INTEGER]: material ID
  • friction [REAL]: friction.
  • restitution [REAL]: resilience / restitution.

    Return Values

    This function has no return value(s).

    Code sample

        
    restitution = 0.9
    friction = 0.5
    gh_bullet3.material_update(mid, restitution, friction)
    -- now update the material for a particular actor.
    gh_bullet3.actor_set_material(aid, mid)
                


    gh_bullet3.actor_set_material

    Description

    updates an actor's material

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor ID
  • mid [INTEGER]: material ID

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_set_material(aid, mid)
                


    gh_bullet3.actor_update_mass

    Description

    updates the mass of an actor

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor ID
  • mass [REAL]: mass

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.actor_update_mass(aid, mass)
                


    gh_bullet3.scene_check_contacts

    Description

    Checks all contacts in a scene.

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.

    Return Values

  • num_contacts [INTEGER]: number of contacts.

    Code sample

        
    num_contacts = gh_bullet3.scene_check_contacts(mid)
                


    gh_bullet3.actor_get_contact_info

    Description

    Gets information about contacts of an actor.

    Languages

    Lua - Python

    Parameters

  • aid [INTEGER]: actor id.
  • px, py, pz [REAL]: position of the first contact.

    Return Values

  • num_contacts [INTEGER]: number of contacts.

    Code sample

        
    num_contacts, px, py, pz = gh_bullet3.actor_get_contact_info(aid)
                


    gh_bullet3.scene_reset_all_contacts

    Description

    Resets all contacts in a scene. Should be called before scene_step_simulation()

    Languages

    Lua - Python

    Parameters

  • sid [INTEGER]: scene id.

    Return Values

    This function has no return value(s).

    Code sample

        
    gh_bullet3.scene_reset_all_contacts(sid)
                






    GeeXLab Rootard Guide | Downloads | Contact | Newsletter