Class: MSPhysics::Body

Inherits:
Entity
  • Object
show all
Defined in:
RubyExtension/MSPhysics/body.rb

Overview

The Body class represents a physics body in simulation. Every body in simulation is designed to have its own Body object.

Since:

  • 1.0.0

Force Control Functions collapse

Contact Related Functions collapse

Joint Associated Functions collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Entity

#inspect, #to_s

Constructor Details

#initialize(world, entity, shape_id, offset_tra, type_id) ⇒ Body #initialize(body, transformation, reapply_forces, type_id) ⇒ Body

Returns a new instance of Body

Overloads:

  • #initialize(world, entity, shape_id, offset_tra, type_id) ⇒ Body
    Note:

    The specified entity must have all axis perpendicular to each other; otherwise, it is considered invalid. The entity will also be considered invalid if its collision shape turns out flat (not considering “null” or “static_mesh” collision shapes).

    Create a new body.

    Parameters:

    • world (World)
    • entity (Sketchup::Group, Sketchup::ComponentInstance)
    • shape_id (Fixnum) —

      Shape ID. See SHAPE_NAMES

    • offset_tra (Geom::Transformation, nil) —

      A local transform to apply to the collision.

    • type_id (Fixnum) —

      Body type: 0 -> dynamic; 1 -> kinematic.

    Raises:

    • (TypeError) —

      if the specified world is invalid.

    • (TypeError) —

      if the specified entity is invalid.

    • (TypeError) —

      if the specified collision shape is invalid.

  • #initialize(body, transformation, reapply_forces, type_id) ⇒ Body

    Create a clone of an existing body.

    Parameters:

    • body (Body) —

      A body Object.

    • transformation (Geom::Transformation, Array<Numeric>, nil) —

      New transformation matrix or nil to create new body at the current location.

    • reapply_forces (Boolean) —

      Whether to reapply force and torque.

    • type_id (Fixnum) —

      Body type: 0 -> dynamic; 1 -> kinematic.

    Raises:

    • (TypeError) —

      if the specified body is invalid.

    • (TypeError) —

      if the specified transformation matrix is not acceptable.

Since:

  • 1.0.0

Class Method Details

.all_bodies ⇒ Array<Body>

Note:

Bodies that do not have a MSPhysics::Body instance are not included in the array.

Get all bodies.

Returns:

Since:

  • 1.0.0

.bodies_aabb_overlap?(body1, body2) ⇒ Boolean

Determine if the bounding boxes of two bodies overlap.

Parameters:

Returns:

  • (Boolean)

Since:

  • 1.0.0

.bodies_collidable?(body1, body2) ⇒ Boolean

Determine if two bodies can collide with each other.

Parameters:

Returns:

  • (Boolean)

Since:

  • 1.0.0

.bodies_touching?(body1, body2) ⇒ Boolean

Determine if two bodies are in contact.

Parameters:

Returns:

  • (Boolean)

Since:

  • 1.0.0

.body_by_address(address) ⇒ Body?

Get body by body address.

Parameters:

  • address (Fixnum)

Returns:

Since:

  • 1.0.0

.closest_points(body1, body2) ⇒ Array<Geom::Point3d>?

Note:

This works with convex and compound bodies only. Nil will be returned if one the passed bodies have a static mesh or a null collision.

Get closest collision points between two bodies.

Parameters:

Returns:

  • (Array<Geom::Point3d>, nil) —

    [contact_pt1, contact_pt2]

Since:

  • 1.0.0

.force_between_bodies(body1, body2) ⇒ Geom::Vector3d

Get contact force between two bodies.

Parameters:

Returns:

  • (Geom::Vector3d) —

    force in newtons (kg*m/s/s).

Since:

  • 1.0.0

.validate(body, world = nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Verify that body is valid.

Parameters:

  • body (Body)
  • world (World, nil) (defaults to: nil) —

    A world the body ought to belong to or nil.

Raises:

  • (TypeError) —

    if body is invalid or destroyed.

Since:

  • 1.0.0

.validate2(body1, body2, world = nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Verify that two bodies are valid and unique.

Parameters:

  • body1 (Body)
  • body2 (Body)
  • world (World, nil) (defaults to: nil) —

    A world the body ought to belong to or nil.

Raises:

  • (TypeError) —

    if at least one body is invalid or destroyed.

  • (TypeError) —

    if both bodies link to the same address.

Since:

  • 1.0.0

Instance Method Details

#aabb ⇒ Geom::BoundingBox

Get world axes aligned bounding box (AABB) of the body.

Returns:

  • (Geom::BoundingBox)

Since:

  • 1.0.0

#actual_matrix_scale ⇒ Geom::Vector3d

Get scale of the body matrix that is a product of group scale and collision scale.

Returns:

  • (Geom::Vector3d) —

    A vector representing the local X-axis, Y-axis, and Z-axis scale factors of the actual body matrix.

Since:

  • 1.0.0

#add_force(force) ⇒ Boolean #add_force(fx, fy, fz) ⇒ Boolean

Note:

Unlike the #set_force, this function doesn't overwrite original force, but rather adds force to the force accumulator.

Apply force on the body in Newtons (kg * m/s/s).

Overloads:

  • #add_force(force) ⇒ Boolean

    Parameters:

    • force (Geom::Vector3d, Array<Numeric>)
  • #add_force(fx, fy, fz) ⇒ Boolean

    Parameters:

    • fx (Numeric)
    • fy (Numeric)
    • fz (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#add_impulse(center, delta_vel, timestep) ⇒ Boolean

Add an impulse to a specific point on the body.

Parameters:

  • center (Geom::Point3d, Array<Numeric>) —

    The center of an impulse in global space.

  • delta_vel (Geom::Vector3d, Array<Numeric>) —

    The desired change in velocity. The magnitude of velocity is assumed in meters per second (m/s).

  • timestep (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#add_point_force(point, force) ⇒ Boolean

Add force to a specific point on the body.

Parameters:

  • point (Geom::Point3d, Array<Numeric>) —

    Point on the body in global space.

  • force (Geom::Vector3d, Array<Numeric>) —

    The magnitude of force is assumed in newtons (kg*m/s/s).

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#add_torque(torque) ⇒ Boolean #add_torque(tx, ty, tz) ⇒ Boolean

Note:

Unlike the #set_torque, this function doesn't overwrite original torque, but rather adds torque to the torque accumulator.

Apply torque on the body in Newton-meters (kg * m/s/s * m).

Overloads:

  • #add_torque(torque) ⇒ Boolean

    Parameters:

    • torque (Geom::Vector3d, Array<Numeric>)
  • #add_torque(tx, ty, tz) ⇒ Boolean

    Parameters:

    • tx (Numeric)
    • ty (Numeric)
    • tz (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#address ⇒ Fixnum

Get pointer to the body.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#apply_aerodynamics(drag, wind) ⇒ Boolean

Note:

WIP

Apply fluid resistance to the body. The resistance force and torque is based upon the body's linear and angular velocity, orientation of its collision faces, and the drag coefficient.

Examples:

onUpdate {
  drag = 0.25 # drag coefficient of air
  wind = Geom::Vector3d.new(5,0,0) # 5 m/s along the X-axis
  this.apply_aerodynamics(drag, wind)
}

Parameters:

  • drag (Numeric) —

    Drag coefficient.

  • wind (Geom::Vector3d) —

    Velocity of the wind in meters per second.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#apply_buoyancy(plane_origin, plane_normal, density, linear_viscosity, angular_viscosity, linear_current, angular_current, timestep) ⇒ Boolean

Apply buoyancy to the body.

Examples:

onUpdate {
  plane_origin = Geom::Point3d.new(0,0,100)
  plane_normal = Z_AXIS
  density = 997.04 # density of water
  linear_viscosity = 0.01
  angular_viscosity = 0.01
  linear_current = Geom::Vector3d.new(5,0,0) # 5 m/s along the X-axis
  angular_current = Geom::Vector3d.new(0,0,0)
  timestep = simulation.update_timestep
  this.apply_buoyancy(plane_origin, plane_normal, density, linear_viscosity, angular_viscosity, linear_current, angular_current, timestep)
}

Parameters:

  • plane_origin (Geom::Point3d, Array<Numeric>) —

    Plane origin.

  • plane_normal (Geom::Vector3d, Array<Numeric>) —

    Plane normal.

  • density (Numeric) —

    Fluid density in kilograms per cubic meter (kg/m^3).

  • linear_viscosity (Numeric) —

    Linear viscosity, a value between 0.0 and 1.0.

  • angular_viscosity (Numeric) —

    Angular viscosity, a value between 0.0 and 1.0.

  • linear_current (Geom::Vector3d, Array<Numeric>) —

    Velocity of the fluid global space.

  • angular_current (Geom::Vector3d, Array<Numeric>) —

    Omega of the fluid global space.

  • timestep (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#apply_pick_and_drag(pick_pt, dest_pt, stiffness, damp, timestep) ⇒ Boolean

Apply pick and drag to the body.

Parameters:

  • pick_pt (Geom::Point3d, Array<Numeric>) —

    Pick point, usually on the surface of the body, in global space.

  • dest_pt (Geom::Point3d, Array<Numeric>) —

    Destination point in global space.

  • stiffness (Numeric) —

    Stiffness, a value b/w 0.0 and 1.0.

  • damp (Numeric) —

    Damper, a value b/w 0.0 and 1.0.

  • timestep (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#attach(body) ⇒ MSPhysics::Fixed

Attach a particular body to this body with a Fixed joint.

Parameters:

Returns:

See Also:

Since:

  • 1.0.0

#attached?(body) ⇒ Boolean

Determine whether a particular body is attached to this body.

Parameters:

Returns:

  • (Boolean)

See Also:

Since:

  • 1.0.0

#auto_sleep_enabled=(state) ⇒ Object

Note:

Keeping auto sleep on is a huge performance plus for simulation. Auto sleep enabled is the default state for a created body; however, for player control, AI control or some other special circumstance, the application may want to control the activation/deactivation of the body.

Set auto sleep state of the body. Auto sleep enables body to automatically go to sleep mode when at rest or become active when activated.

Parameters:

  • state (Boolean) —

    true to set body auto-sleep on, or false to set body auto-sleep off.

Since:

  • 1.0.0

#auto_sleep_enabled? ⇒ Boolean

Get the auto-sleep state of the body.

Returns:

  • (Boolean) —

    true if body auto-sleep is on, false if body auto-sleep is off.

Since:

  • 1.0.0

#clear_non_collidable_bodies ⇒ Fixnum

Remove all bodies from the non-collidable list; the bodies that were set non-collidable by the #set_non_collidable_with function.

Returns:

  • (Fixnum) —

    The number of bodies unmarked.

Since:

  • 1.0.0

#collidable=(state) ⇒ Object

Set body collidable.

Parameters:

  • state (Boolean) —

    true to set body collidable, false to set body non-collidable.

Since:

  • 1.0.0

#collidable? ⇒ Boolean

Determine whether body is collidable.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#collision_address ⇒ Fixnum

Get pointer to the collision associated with the body.

Returns:

  • (Fixnum)

Since:

  • 1.0.0

#collision_faces ⇒ Array<Array<Geom::Point3d>>

Get collision faces of the body.

Returns:

  • (Array<Array<Geom::Point3d>>) —

    An array of faces. Each face represents an array of points. Points are coordinated in global space.

Since:

  • 1.0.0

#collision_faces2 ⇒ Array<Array<(Array<Geom::Point3d>, Geom::Point3d, Geom::Vector3d, Numeric)>>

Get collision faces of the body.

Returns:

  • (Array<Array<(Array<Geom::Point3d>, Geom::Point3d, Geom::Vector3d, Numeric)>>) —

    An array of face data. Each face data contains four elements. The first element contains the array of face vertices (sorted counterclockwise) in global space. The second element represents face centroid in global space. The third element represents face normal in global space. And the last element represents face area in inches squared.

Since:

  • 1.0.0

#collision_faces3 ⇒ Array<Array<(Geom::Point3d, Geom::Vector3d, Numeric)>>

Get collision faces of the body.

Returns:

  • (Array<Array<(Geom::Point3d, Geom::Vector3d, Numeric)>>) —

    An array of face data. Each face data contains three elements. The first element represents face centroid in global space. The second element represents face normal in global space. And the last element represents face area in inches squared.

Since:

  • 1.0.0

#connected_bodies ⇒ Array<Body>

Get all bodies connected to this body through joints.

Returns:

Since:

  • 1.0.0

#connected_joints ⇒ Array<Joint, DoubleJoint>

Get joints whose child bodies associate to this body.

Returns:

  • (Array<Joint, DoubleJoint>)

Since:

  • 1.0.0

#contact_points(inc_non_collidable) ⇒ Array<Geom::Point3d>

Get all contact points on the body.

Parameters:

  • inc_non_collidable (Boolean) —

    Whether to included contacts from non-collidable bodies.

Returns:

  • (Array<Geom::Point3d>)

Since:

  • 1.0.0

#contacts(inc_non_collidable) ⇒ Array<Contact>

Get all contacts on the body.

Parameters:

  • inc_non_collidable (Boolean) —

    Whether to include contacts from non-collidable bodies.

Returns:

Since:

  • 1.0.0

#contained_joints ⇒ Array<Joint, DoubleJoint>

Get joints whose parent bodies associate to this body.

Returns:

  • (Array<Joint, DoubleJoint>)

Since:

  • 1.0.0

#context ⇒ BodyContext

Get the associated context.

Returns:

Since:

  • 1.0.0

#continuous_collision_check_enabled=(state) ⇒ Object

Note:

Continuous collision check is known to affect performance. Be cautions when using it. When performing box stacks it's better to reduce simulation update step, to 1/256 for instance, rather than enabling continuous collision check as smaller update step will keep simulation running smoothly while avoiding penetration at the same time.

Enable/disable continuous collision check for this body. Continuous collision check prevents this body from passing through other bodies at high speeds.

Parameters:

  • state (Boolean) —

    Pass true to enable continuous collision check; false to disable continuous collision check.

Since:

  • 1.0.0

#continuous_collision_check_enabled? ⇒ Boolean

Determine whether continuous collision check is enabled for this body. Continuous collision check prevents this body from passing through other bodies at high speeds.

Returns:

  • (Boolean) —

    Returns true if continuous collision check is on; false if continuous collision check is off.

Since:

  • 1.0.0

#copy(reapply_forces, type) ⇒ Body #copy(transformation, reapply_forces, type) ⇒ Body

Create a copy of the body.

Overloads:

  • #copy(reapply_forces, type) ⇒ Body

    Parameters:

    • reapply_forces (Boolean) —

      Whether to reapply force and torque.

    • type (Fixnum) —

      Type: 0 -> dynamic; 1 -> kinematic.

  • #copy(transformation, reapply_forces, type) ⇒ Body

    Parameters:

    • transformation (Geom::Transformation, Array<Numeric>) —

      New transformation matrix.

    • reapply_forces (Boolean) —

      Whether to reapply force and torque.

    • type (Fixnum) —

      Type: 0 -> dynamic; 1 -> kinematic.

    Raises:

    • (TypeError) —

      if the specified transformation matrix is not uniform.

Returns:

  • (Body) —

    A new body object.

Since:

  • 1.0.0

#default_collision_scale ⇒ Geom::Vector3d

Note:

Does not include group scale.

Get default scale of the body collision.

Returns:

  • (Geom::Vector3d) —

    A vector representing the local, default X-axis, Y-axis, and Z-axis scale factors of the collision.

Since:

  • 1.0.0

#density ⇒ Numeric

Get body density in kilograms per cubic meter (kg / m^3).

Returns:

  • (Numeric)

Since:

  • 1.0.0

#density=(value) ⇒ Object

Note:

Density and mass are correlated. If you change density the mass will automatically be recalculated.

Set body density in kilograms per cubic meter (kg / m^3).

Parameters:

  • value (Numeric)

Since:

  • 1.0.0

#destroy(erase_entity = false) ⇒ nil

Destroy the body.

Parameters:

  • erase_entity (Boolean) (defaults to: false) —

    Whether to erase the group/component associated with the body.

Returns:

  • (nil)

Since:

  • 1.0.0

#detach(body) ⇒ Boolean

Detach a particular attached body from this body.

Parameters:

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 1.0.0

#detach_all ⇒ Fixnum

Detach all attached bodies from this body.

Returns:

  • (Fixnum) —

    Number of bodies detached.

See Also:

Since:

  • 1.0.0

#elasticity ⇒ Numeric

Get body coefficient of restitution - bounciness - rebound ratio.

Returns:

  • (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#elasticity=(coefficient) ⇒ Object

Set body coefficient of restitution - bounciness - rebound ratio.

Examples:

A basketball has a rebound ratio of 0.83. This means the new

height of a basketball is 83% of original height within each bounce.

Parameters:

  • coefficient (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#friction_enabled=(state) ⇒ Object

Set friction state of the body.

Parameters:

  • state (Boolean) —

    true to enable body friction, false to disable body friction.

Since:

  • 1.0.0

#friction_enabled? ⇒ Boolean

Get friction state of the body.

Returns:

  • (Boolean) —

    true if body friction is enabled, false if body friction is disabled.

Since:

  • 1.0.0

#frozen=(state) ⇒ Object

Set body collidable.

Parameters:

  • state (Boolean) —

    true to freeze the body, false unfreeze the body.

Since:

  • 1.0.0

#frozen? ⇒ Boolean

Determine whether body is frozen.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#get_angular_damping ⇒ Geom::Vetor3d

Get the viscous damping coefficient applied to the omega of the body.

Returns:

  • (Geom::Vetor3d) —

    A vector representing the local damping coefficients of the axes, each between 0.0 and 1.0.

Since:

  • 1.0.0

#get_centre_of_mass ⇒ Geom::Point3d

Get centre of mass of the body in local coordinates.

Examples:

Getting centre of mass in global space.

centre = body.get_cetre_of_mass.transform( body.get_matrix )

Returns:

  • (Geom::Point3d)

See Also:

Since:

  • 1.0.0

#get_collision_scale ⇒ Geom::Vector3d

Note:

Does not include group scale.

Get body collision scale.

Returns:

  • (Geom::Vector3d) —

    A vector representing the local X-axis, Y-axis, and Z-axis scale factors of the collision.

Since:

  • 1.0.0

#get_euler_angles ⇒ Geom::Vector3d

Get body orientation in form of the three Euler angles.

Returns:

  • (Geom::Vector3d) —

    An vector of three Euler angles expressed in radians: (roll, yaw, pitch).

Since:

  • 1.0.0

#get_force ⇒ Geom::Vector3d

Get the net force, in Newtons, applied on the body after the last world update.

Returns:

  • (Geom::Vector3d)

Since:

  • 1.0.0

#get_linear_damping ⇒ Geom::Vetor3d

Get the viscous damping coefficient applied to the velocity of the body.

Returns:

  • (Geom::Vetor3d) —

    A vector representing the local damping coefficients of the axes, each between 0.0 and 1.0.

Since:

  • 1.0.0

#get_matrix ⇒ Geom::Transformation

Get body transformation matrix.

Returns:

  • (Geom::Transformation)

Since:

  • 1.0.0

#get_non_collidable_bodies ⇒ Array<Body>

Get all bodies that are non-collidable with this body; the bodies that were set non-collidable by the #set_non_collidable_with function.

Returns:

  • (Array<Body>) —

    An array of non-collidable bodies.

Since:

  • 1.0.0

#get_omega ⇒ Geom::Vector3d

Get global angular velocity of the body.

Examples:

Each value of the omega vector represents angular velocity in radians
per second along X-axis, Y-axis, or Z-axis in global space. For example,
if omega of a body is (0,0,PI), it means that the body rotates along
Z-axis in global space at an angular velocity of 360 degrees per second.

Returns:

  • (Geom::Vector3d) —

    The magnitude of the omega vector is represented in radians per second.

Since:

  • 1.0.0

#get_position(mode = 0) ⇒ Geom::Point3d

Get body position.

Parameters:

  • mode (Fixnum) (defaults to: 0) —

    • 0 - get body's origin in global space.

    • 1 - get body's centre of mass in global space.

Returns:

  • (Geom::Point3d)

Since:

  • 1.0.0

#get_torque ⇒ Geom::Vector3d

Get the net torque, in Newton-meters, applied on the body after the last world update.

Returns:

  • (Geom::Vector3d)

Since:

  • 1.0.0

#get_velocity ⇒ Geom::Vector3d

Get global linear velocity of the body.

Returns:

  • (Geom::Vector3d) —

    The magnitude of the velocity vector is represented in meters per second.

Since:

  • 1.0.0

#gravity_enabled=(state) ⇒ Object

Enable/disable gravitational force on this body.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0

#gravity_enabled? ⇒ Boolean

Determine if gravitational force is enabled on this body.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#group ⇒ Sketchup::Group, Sketchup::ComponentInstance

Get the group/component associated with the body.

Returns:

  • (Sketchup::Group, Sketchup::ComponentInstance)

Since:

  • 1.0.0

#inertia ⇒ Geom::Vector3d

Note:

Inertia is the rotational equivalent of mass. It may be used for damping angular velocity through applying dissipative torque.

Note:

If the body is static or has a zero mass, the magnitude of the return inertia will be zero.

Get body local inertia.

Examples:

Applying angular damping

onUpdate {
  # Damping ratio, a value between 0.00 - 1.00
  ratio = 0.1
  # Current angular velocity
  omega = this.get_omega
  # Get the rotational equivalent of mass
  inertia = this.inertia
  # Dissipative torque
  torque = Geom::Vector3d.new(
    -omega.x * inertia.x * ratio,
    -omega.y * inertia.y * ratio,
    -omega.z * inertia.z * ratio)
  # Apply torque
  this.add_torque(torque)
}

Returns:

  • (Geom::Vector3d)

Since:

  • 1.0.0

#integrate_velocity(timestep) ⇒ nil

Note:

For this function to have an effect, the body must be kinematic and have a non-zero mass (non-static).

Integrate linear and angular velocity of the body.

Examples:

# Assuming this body is kinematic
onStart {
  @velocity = Geom::Vector3d.new(2,0,0)
  this.set_velocity(2,0,0)
}
onPreUpdate {
  this.integrate_velocity(simulation.update_timestep)
}

Parameters:

  • timestep (Numeric) —

    Timestep in seconds.

Returns:

  • (nil)

Since:

  • 1.0.0

#kinetic_friction ⇒ Numeric

Get kinetic friction coefficient of the body.

Returns:

  • (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#kinetic_friction=(coefficient) ⇒ Object

Set kinetic friction coefficient of the body.

Parameters:

  • coefficient (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#look_at(pin_dir, accel = 40, damp = 10, strength = 0.9) ⇒ MSPhysics::UpVector?

Make the body's Z-axis to look in a particular direction.

Examples:

onTick {
  if (key(' ') == 1)
    dir = this.group.transformation.origin.vector_to(ORIGIN)
    this.look_at(dir, 40, 10, 0.9)
  else
    this.look_at(nil)
  end
}

Parameters:

  • pin_dir (Geom::Vector3d, nil) —

    Direction in global space. Pass nil to disable the look at constraint.

  • accel (Numeric) (defaults to: 40) —

    Rotational oscillation stiffness.

  • damp (Numeric) (defaults to: 10) —

    Rotational oscillation damping coefficient.

  • strength (Numeric) (defaults to: 0.9) —

    Rotational oscillation strength.

Returns:

Since:

  • 1.0.0

#magnet_force ⇒ Numeric

Note:

This option has an effect if and only if magnet_mode is set to 1.

Get the maximum magnet force in Newton to be applied on the surrounding magnetic bodies.

Returns:

  • (Numeric)

See Also:

Since:

  • 1.0.0

#magnet_force=(force) ⇒ Object

Note:

This option has an effect if and only if magnet_mode is set to 1.

Set the maximum magnet force in Newton to be applied on the surrounding magnetic bodies.

Parameters:

  • force (Numeric)

See Also:

Since:

  • 1.0.0

#magnet_mode ⇒ Fixnum

Get the mode for controlling the way this magnet should work.

  • 1; to have the magnet force be calculated with the following equation: actual_magnet_force = f * (d - r)^2 / r^2; where f is the maximum magnet force (in Newtons), d is the distance between this magnet and a magnetic body (in meters), and r is the maximum magnet range (in meters). In this mode, the magnet_force and magnet_range methods are used for controlling the magnet.

  • 2; to have magnet force be computed with a slightly different equation: actual_magnet_force = s / d^2; where s is the magnet strength and d is the distance between this magnet and a magnetic body (in meters). In this mode, the magnet_strength method must be used for controlling the magnet.

Returns:

  • (Fixnum) —

    Returns one of the following values:

Since:

  • 1.0.0

#magnet_mode=(mode) ⇒ Object

Set the mode for controlling the way this magnet should work.

  • Pass 1 to have the magnet force be calculated with the following equation: actual_magnet_force = f * (d - r)^2 / r^2; where f is the maximum magnet force (in Newtons), d is the distance between this magnet and a magnetic body (in meters), and r is the maximum magnet range (in meters). In this mode, the magnet_force and magnet_range methods are used for controlling the magnet.

  • Pass 2 to have magnet force be computed with a slightly different equation: actual_magnet_force = s / d^2; where s is the magnet strength and d is the distance between this magnet and a magnetic body (in meters). In this mode, the magnet_strength method must be used for controlling the magnet.

Parameters:

  • mode (Fixnum)

Since:

  • 1.0.0

#magnet_range ⇒ Numeric

Note:

This option has an effect if and only if magnet_mode is set to 1.

Get the maximum magnet range in meters. Magnet force is distributed along the magnet range. Magnetic bodies outside the magnet range are not affected.

Returns:

  • (Numeric)

See Also:

Since:

  • 1.0.0

#magnet_range=(range) ⇒ Object

Note:

This option has an effect if and only if magnet_mode is set to 1.

Set the maximum magnet range in meters. Magnet force is distributed along the magnet range. Magnetic bodies outside the magnet range are not affected.

Parameters:

  • range (Numeric)

See Also:

Since:

  • 1.0.0

#magnet_strength ⇒ Numeric

Note:

This option has an effect if and only if magnet_mode is set to 2.

Get the magnet force magnitude to be applied on the surrounding magnetic bodies.

Returns:

  • (Numeric)

See Also:

Since:

  • 1.0.0

#magnet_strength=(magnitude) ⇒ Object

Note:

This option has an effect if and only if magnet_mode is set to 2.

Set the magnet force magnitude to be applied on the surrounding magnetic bodies.

Parameters:

  • magnitude (Numeric)

See Also:

Since:

  • 1.0.0

#magnetic=(state) ⇒ Object

Set body magnetic. Magnetic bodies will be affected by other bodies with magnetism.

Parameters:

  • state (Boolean) —

    true to set body magnetic, false to set body non-magnetic.

Since:

  • 1.0.0

#magnetic? ⇒ Boolean

Determine whether body is magnetic.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#mass ⇒ Numeric

Get body mass in kilograms (kg).

Returns:

  • (Numeric)

Since:

  • 1.0.0

#mass=(value) ⇒ Object

Note:

Mass and density are correlated. If you change mass the density will automatically be recalculated.

Set body mass in kilograms (kg).

Parameters:

  • value (Numeric)

Since:

  • 1.0.0

#net_contact_force ⇒ Geom::Vector3d

Get total force generated from contacts on the body.

Returns:

  • (Geom::Vector3d) —

    Magnitude of the net force is retrieved in newtons (kg*m/s/s).

Since:

  • 1.0.0

#non_collidable_with?(body) ⇒ Boolean

Determine whether this body is non-collidable with a particular body.

Parameters:

  • body (Body) —

    The body to test.

Returns:

  • (Boolean) —

    true if this body is non-collidable with the given body, false if this body is collidable with the given body.

Since:

  • 1.0.0

#normal_matrix ⇒ Geom::transformation

Get body matrix with no scale factors.

Returns:

  • (Geom::transformation)

Since:

  • 1.0.0

#point_velocity(point) ⇒ Geom::Vector3d

Get velocity at a specific point on the body.

Parameters:

  • point (Geom::Point3d, Array<Numeric>) —

    A point in global space.

Returns:

  • (Geom::Vector3d) —

    Velocity at the given point. The magnitude of velocity is retrieved in meters per second (m/s).

Since:

  • 1.0.0

#reset_mass_properties(density) ⇒ Boolean

Reset/recalculate body volume and mass.

Parameters:

  • density (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#rotation ⇒ Array<Numeric>

Get body orientation in form of the unit quaternion.

Returns:

  • (Array<Numeric>) —

    An array of four numeric values: [q0, q1, q2, q3] - [x,y,z,w].

Since:

  • 1.0.0

#set_angular_damping(damp) ⇒ nil #set_angular_damping(dx, dy, dz) ⇒ nil

Set the viscous damping coefficient applied to the omega of the body.

Overloads:

  • #set_angular_damping(damp) ⇒ nil

    Parameters:

    • damp (Geom::Vector3d, Array<Numeric>) —

      Each value of the damp vector is assumed as an angular coefficient, a value b/w 0.0 and 1.0.

  • #set_angular_damping(dx, dy, dz) ⇒ nil

    Parameters:

    • dx (Numeric) —

      Local X-axis damping coefficient, a value b/w 0.0 and 1.0.

    • dy (Numeric) —

      Local Y-axis damping coefficient, a value b/w 0.0 and 1.0.

    • dz (Numeric) —

      Local Z-axis damping coefficient, a value b/w 0.0 and 1.0.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_centre_of_mass(centre) ⇒ nil #set_velocity(px, py, pz) ⇒ nil

Set centre of mass of the body in local coordinates.

Overloads:

  • #set_centre_of_mass(centre) ⇒ nil

    Parameters:

    • centre (Geom::Point3d, Array<Numeric>) —

      A point is assumed in body coordinates.

  • #set_velocity(px, py, pz) ⇒ nil

    Parameters:

    • px (Numeric) —

      X position in local space.

    • py (Numeric) —

      Y position in local space.

    • pz (Numeric) —

      Z position in local space.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_collision_scale(scale) ⇒ nil #set_collision_scale(sx, sy, sz) ⇒ nil

Note:

Does not include group scale.

Set body collision scale.

Overloads:

  • #set_collision_scale(scale) ⇒ nil

    Parameters:

    • scale (Geom::Vector3d, Array<Numeric>) —

      A vector representing the local X-axis, Y-axis, and Z-axis scale factors of the body collision.

  • #set_collision_scale(sx, sy, sz) ⇒ nil

    Parameters:

    • sx (Numeric) —

      Scale along the local X-axis of the body, a value between 0.01 and 100.

    • sy (Numeric) —

      Scale along the local Y-axis of the body, a value between 0.01 and 100.

    • sz (Numeric) —

      Scale along the local Z-axis of the body, a value between 0.01 and 100.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_euler_angles(angles) ⇒ nil #set_euler_angles(roll, yaw, pitch) ⇒ nil

Note:

The angles are assumed in radians.

Set body orientation via the three Euler angles.

Overloads:

  • #set_euler_angles(angles) ⇒ nil

    Parameters:

    • angles (Geom::Vector3d, Array<Numeric>) —

      A vector representing the roll, yaw, and pitch Euler angles in radians.

  • #set_euler_angles(roll, yaw, pitch) ⇒ nil

    Parameters:

    • roll (Numeric)
    • yaw (Numeric)
    • pitch (Numeric)

Returns:

  • (nil)

Since:

  • 1.0.0

#set_force(force) ⇒ Boolean #set_force(fx, fy, fz) ⇒ Boolean

Note:

Unlike the #add_force, this function overwrites original force, thus discarding the previously applied force.

Apply force on the body in Newton (kg * m/s/s).

Overloads:

  • #set_force(force) ⇒ Boolean

    Parameters:

    • force (Geom::Vector3d, Array<Numeric>)
  • #set_force(fx, fy, fz) ⇒ Boolean

    Parameters:

    • fx (Numeric)
    • fy (Numeric)
    • fz (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#set_linear_damping(damp) ⇒ Object #set_linear_damping(dx, dy, dz) ⇒ Object

Set the viscous damping coefficient applied to the velocity of the body.

Overloads:

  • #set_linear_damping(damp) ⇒ Object

    Parameters:

    • damp (Geom::Vector3d, Array<Numeric>) —

      Each value of the damp vector is assumed as a local damping coefficient, a value b/w 0.0 and 1.0.

  • #set_linear_damping(dx, dy, dz) ⇒ Object

    Parameters:

    • dx (Numeric) —

      Local X-axis damping coefficient, a value b/w 0.0 and 1.0.

    • dy (Numeric) —

      Local Y-axis damping coefficient, a value b/w 0.0 and 1.0.

    • dz (Numeric) —

      Local Z-axis damping coefficient, a value b/w 0.0 and 1.0.

Since:

  • 1.0.0

#set_matrix(matrix) ⇒ nil

Set body transformation matrix.

Parameters:

  • matrix (Geom::Transformation, Array<Numeric>)

Returns:

  • (nil)

Raises:

  • (TypeError) —

    if some or all matrix axis are not perpendicular to each other.

  • (TypeError) —

    if some or all matrix axis have a scale of zero.

Since:

  • 1.0.0

#set_non_collidable_with(body, state) ⇒ nil

Set this body non-collidable with a particular body.

Parameters:

  • body (Body)
  • state (Boolean) —

    true to set this body non-collidable with another, false to set this body collidable with another.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_omega(omega) ⇒ nil #set_omega(vx, vy, vz) ⇒ nil

Set global angular velocity of the body.

Overloads:

  • #set_omega(omega) ⇒ nil

    Parameters:

    • omega (Geom::Vector3d, Array<Numeric>) —

      The magnitude of the omega vector is assumed in radians per second.

  • #set_omega(vx, vy, vz) ⇒ nil

    Parameters:

    • vx (Numeric) —

      Omega in radians per second along X-axis.

    • vy (Numeric) —

      Omega in radians per second along Y-axis.

    • vz (Numeric) —

      Omega in radians per second along Z-axis.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_position(position, mode = 0) ⇒ nil #set_position(px, py, pz, mode = 0) ⇒ nil

Set body position.

Overloads:

  • #set_position(position, mode = 0) ⇒ nil

    Parameters:

    • position (Geom::Point3d, Array<Numeric>) —

      A point in global space.

    • mode (Fixnum) (defaults to: 0) —

      • 0 - reposition body origin to a desired location in global space.

      • 1 - reposition body centre of mass to a desired location in global space.

  • #set_position(px, py, pz, mode = 0) ⇒ nil

    Parameters:

    • px (Numeric) —

      X position in global space.

    • py (Numeric) —

      Y position in global space.

    • pz (Numeric) —

      Z position in global space.

    • mode (Fixnum) (defaults to: 0) —

      • 0 - reposition body origin to a desired location in global space.

      • 1 - reposition body centre of mass to a desired location in global space.

Returns:

  • (nil)

Since:

  • 1.0.0

#set_torque(torque) ⇒ Boolean #set_torque(tx, ty, tz) ⇒ Boolean

Note:

Unlike the #add_torque, this function overwrites original torque, thus discarding the previously applied torque.

Apply torque on the body in Newton-meters (kg * m/s/s * m).

Overloads:

  • #set_torque(torque) ⇒ Boolean

    Parameters:

    • torque (Geom::Vector3d, Array<Numeric>)
  • #set_torque(tx, ty, tz) ⇒ Boolean

    Parameters:

    • tx (Numeric)
    • ty (Numeric)
    • tz (Numeric)

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0

#set_velocity(velocity) ⇒ nil #set_velocity(vx, vy, vz) ⇒ nil

Set global linear velocity of the body.

Overloads:

  • #set_velocity(velocity) ⇒ nil

    Parameters:

    • velocity (Geom::Vector3d, Array<Numeric>) —

      The magnitude of the velocity vector is assumed in meters per second.

  • #set_velocity(vx, vy, vz) ⇒ nil

    Parameters:

    • vx (Numeric) —

      Velocity in meters per second along X-axis.

    • vy (Numeric) —

      Velocity in meters per second along Y-axis.

    • vz (Numeric) —

      Velocity in meters per second along Z-axis.

Returns:

  • (nil)

Since:

  • 1.0.0

#sleeping=(state) ⇒ Object

Note:

This function can only set body active, the sleeping is controlled by equilibrium.

Set body sleeping.

Parameters:

  • state (Boolean) —

    true to set body sleeping, false to set body active.

Since:

  • 1.0.0

#sleeping? ⇒ Boolean

Determine whether body is sleeping. Sleeping bodies are bodies at rest.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#softness ⇒ Numeric

Get contact softness coefficient of the body.

Returns:

  • (Numeric) —

    A value between 0.01 and 1.00.

Since:

  • 1.0.0

#softness=(coefficient) ⇒ Object

Set contact softness coefficient of the body.

Parameters:

  • coefficient (Numeric) —

    A value between 0.01 and 1.00.

Since:

  • 1.0.0

#static=(state) ⇒ Object

Set body static.

Parameters:

  • state (Boolean) —

    true to set body static, false to set body dynamic.

Since:

  • 1.0.0

#static? ⇒ Boolean

Determine whether body is static.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#static_friction ⇒ Numeric

Get static friction coefficient of the body.

Returns:

  • (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#static_friction=(coefficient) ⇒ Object

Set static friction coefficient of the body.

Parameters:

  • coefficient (Numeric) —

    A value between 0.01 and 2.00.

Since:

  • 1.0.0

#touching_bodies(inc_non_collidable) ⇒ Array<Body>

Get all bodies that are in contact with this body.

Parameters:

  • inc_non_collidable (Boolean) —

    Whether to include contacts from non-collidable bodies.

Returns:

Since:

  • 1.0.0

#touching_with?(body) ⇒ Boolean

Determine if this body is in contact with another body.

Parameters:

  • body (Body) —

    A body to test.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#type ⇒ Fixnum

Get body type.

Returns:

  • (Fixnum) —

    Type: 0 -> dynamic; 1 -> kinematic

Since:

  • 1.0.0

#valid? ⇒ Boolean

Determine whether this body is valid - not destroyed.

Returns:

  • (Boolean)

Since:

  • 1.0.0

#volume ⇒ Numeric

Get body volume in cubic meters (m^3).

Returns:

  • (Numeric)

Since:

  • 1.0.0

#volume=(value) ⇒ Object

Note:

Volume and mass are correlated. If you change volume the mass will automatically be recalculated.

Set body volume in cubic meters (m^3).

Parameters:

  • value (Numeric)

Since:

  • 1.0.0

#world ⇒ World

Get world in which the body was created.

Returns:

Since:

  • 1.0.0