stingray.PhysicsWorld object reference

Description

Represents a physics world: a collection of interacting physics objects where Actors live.

In the Stingray engine, exactly one PhysicsWorld is associated with each game World.

Constructors and accessors

stingray.World.physics_world()

Related sample code

Character template: /player.lua

Other related reference items

	stingray.Raycast
	stingray.Raycast.cast()
	Physics

Related help topics

	Release Notes > Stingray 1.2 Release Notes
	Creating Gameplay > Scripting with Lua > Using the Lua API > Object lifetimes and userdata binding
	Creating Gameplay > Physics > Set up vector field (wind) effects

Functions

apply_wind ( self, vf, id ) Applies the wind from the VectorField to the actors in the world that collide with the specified collision filter.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
vf :	stingray.VectorField	A vector field from which a wind is applied.
id :	string	The id of the collision filter with which the actors collide.

Returns

This function does not return any values.

Call this function every frame if you want to continously apply a vector field wind to a physics world.

Note that the wind is only applied to actors that are awake. The reason is that otherwise the wind would keep every actor in the level awake, which would have severe effects on the physics performance.

If you play a strong short-lived wind effect (such an explosion), you should make sure to wake all actors that can be affected by the explosion. Otherwise, the explosion would not move the sleeping actors. Use the function wake_actors() to wake sleeping actors.

Other related reference items

stingray.VectorField

break_joints ( self, u1, ac1, u2, ac2 ) Breaks the joints between two connected actors that are not in the scene, typically because they are currently disabled.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
u1 :	stingray.Unit	The Unit to which the first actor belongs.
ac1 :	string	The name of the first actor.
u2 :	stingray.Unit	The Unit to which the second actor belongs.
ac2 :	string	The name of the second actor.

Returns

This function does not return any values.

break_joints ( self, ac1, ac2 ) Breaks the joints between the two specified actors.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
ac1 :	stingray.Actor	The first joined actor.
ac2 :	stingray.Actor	The second joined actor.

Returns

This function does not return any values.

For example, this can be used to dismember ragdolls.

create_joint ( self, type, actor_1, pose_1, actor_2, pose_2 ) : stingray.Joint Creates a physics joint between two actors in the world.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
type :	stingray.Joint.Type	The type of joint. Must be one of the Joint.Type enum values: SPHERICAL, REVOLUTE, PRISMATIC, FIXED, DISTANCE or D6.
actor_1 :	any(stingray.Actor, nil)	The first actor to participate in the joint. Can be nil to join objects to the world. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
pose_1 :	stingray.Matrix4x4	Joint orientation in actor_1 local frame.
actor_2 :	any(stingray.Actor, nil)	The second actor to participate in the joint. Can be nil to join objects to the world. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
pose_2 :	stingray.Matrix4x4	Joint orientation in actor_2 local frame.

Returns

stingray.Joint

The newly spawned joint.

Use destroy_joint() to destroy it

Other related reference items

stingray.PhysicsWorld.destroy_joint()

destroy_actor ( self, actor ) Destroys a dynamic actor that was created with spawn_sphere(), spawn_box() or spawn_plane().

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
actor :	stingray.Actor	The dynamic actor to destroy.

Returns

This function does not return any values.

Do not use this function to destroy Actors that belong to Units.

destroy_joint ( self, joint ) Destroys a dynamic joint that was created with create_joint().

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
joint :	stingray.Joint	The dynamic joint to destroy.

Returns

This function does not return any values.

Do not use this function to destroy joints that belong to Units.

Other related reference items

stingray.PhysicsWorld.create_joint()

linear_capsule_sweep ( self, from, to, rotation, radius, half_height, max_hits, sweep_params ) : collision_hit[] Performs a linear sweep through space with an oriented capsule.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
from :	stingray.Vector3	The starting point of the swept capsule.
to :	stingray.Vector3	The ending point of the swept capsule.
rotation :	stingray.Quaternion	The rotation of the capsule. By default, the capsule is oriented with its length along the X axis.
radius :	number	The radius of the capsule.
half_height :	number	The distance from the mid-point to the outer top or bottom of the capsule.
max_hits :	integer	The maximum number of hits to report. Must be greater than zero.
sweep_params :	string+	A list of parameters for the sweep. The possible parameters are: "types": Determines the types of objects that should be considered for the sweep. If you specify this parameter, you must follow it with an additional string parameter that specifies the types. "statics" specifies that the sweep should only test against static objects. "dynamics" specifies that the sweep should only test against dynamic objects. "both" specifies that the sweep should test against both static and dynamic objects; this is the default value. "collision_filter": This parameter allows you to specify a collision filter that the sweep test should use to determine which objects it considers. If you specify this parameter, you must follow it with an additional string parameter that specifies the name of the collision filter, as defined in your global.physics_properties data file. By default, the sweep considers all objects in the scene. "report_initial_overlap": Specifies that the sweep should test for overlaps at the from position and report them in the returned table. If the sweep is initially overlapped it will report zero distance in the hits. The + notation indicates that there may be one or more instances of the specified type.

Returns

collision_hit[]

A table that contains an array of collision_hit tables, each of which records one collision point along the sweep. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

linear_obb_sweep ( self, from, to, extents, rotation, max_hits, sweep_params ) : collision_hit[] Performs a linear sweep through space with an oriented bounding box.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
from :	stingray.Vector3	The starting point of the center of the box.
to :	stingray.Vector3	The ending point of the center of the box.
extents :	stingray.Vector3	The extents of the box in the three dimensions.
rotation :	stingray.Quaternion	The rotation of the box in world space.
max_hits :	integer	The maximum number of hits to report.
sweep_params :	string+	A list of parameters for the sweep. The possible parameters are: "types": Determines the types of objects that should be considered for the sweep. If you specify this parameter, you must follow it with an additional string parameter that specifies the types. "statics" specifies that the sweep should only test against static objects. "dynamics" specifies that the sweep should only test against dynamic objects. "both" specifies that the sweep should test against both static and dynamic objects; this is the default value. "collision_filter": This parameter allows you to specify a collision filter that the sweep test should use to determine which objects it considers. If you specify this parameter, you must follow it with an additional string parameter that specifies the name of the collision filter, as defined in your global.physics_properties data file. By default, the sweep considers all objects in the scene. "report_initial_overlap": Specifies that the sweep should test for overlaps at the from position and report them in the returned table. If the sweep is initially overlapped it will report zero distance in the hits. The + notation indicates that there may be one or more instances of the specified type.

Returns

collision_hit[]

A table that contains an array of collision_hit tables, each of which records one collision point along the sweep. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

linear_sphere_sweep ( self, from, to, radius, max_hits, sweep_params ) : collision_hit[] Performs a linear sweep through space with a sphere.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
from :	stingray.Vector3	The starting point of the sphere.
to :	stingray.Vector3	The ending point of the sphere.
radius :	number	The radius of the sphere.
max_hits :	integer	The maximum number of hits to report.
sweep_params :	string+	A list of parameters for the sweep. The possible parameters are: "types": Determines the types of objects that should be considered for the sweep. If you specify this parameter, you must follow it with an additional string parameter that specifies the types. "statics" specifies that the sweep should only test against static objects. "dynamics" specifies that the sweep should only test against dynamic objects. "both" specifies that the sweep should test against both static and dynamic objects; this is the default value. "collision_filter": This parameter allows you to specify a collision filter that the sweep test should use to determine which objects it considers. If you specify this parameter, you must follow it with an additional string parameter that specifies the name of the collision filter, as defined in your global.physics_properties data file. By default, the sweep considers all objects in the scene. "report_initial_overlap": Specifies that the sweep should test for overlaps at the from position and report them in the returned table. If the sweep is initially overlapped it will report zero distance in the hits. The + notation indicates that there may be one or more instances of the specified type.

Returns

collision_hit[]

A table that contains an array of collision_hit tables, each of which records one collision point along the sweep. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

make_raycast ( self, callback, params ) : stingray.Raycast Creates a Raycast object that can be used to make collision tests against physics objects.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
callback :	fun(any(boolean, collision_hit[]), stingray.Vector3?, number?, stingray.Vector3?, stingray.Actor?:nil)?	A function that will be called when each collision test made by the returned Raycast object is completed. If this value is omitted, the raycasts you carry out using the returned Raycast object will be performed synchronously. See the description of the Raycast object for full details. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The fun(...) notation indicates that this is a function that accepts parameters of the types shown to the left of the colon :, and that returns the types shown to the right of the colon.. The ? notation indicates that this type is optional: there may be zero or one instances of it.
params :	string*	A list of parameters that control the collision tests carried out by the Raycast object. See the description of the Raycast object for full details. The * notation indicates that there may be zero or more instances of the specified type.

Returns

stingray.Raycast

The newly created Raycast object.

See the Raycast description for details on using the returned object to carry out a collision test.

Other related reference items

	stingray.Raycast
	stingray.Raycast.cast()

overlap ( self, callback, params ) : table Performs an overlap test in the physics world: a collision test that finds all the actors in the world that are within a specified shape.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
callback :	fun(stingray.Actor[]:nil)	A callback function that is called when the overlap test is completed. This function is passed a table that contains an array of all Actor objects found by the test. The fun(...) notation indicates that this is a function that accepts parameters of the types shown to the left of the colon :, and that returns the types shown to the right of the colon..
params :	any+	Specifies the shape of the overlap. Possible values are: "shape": Specifies the shape used for the test. If you specify this parameter, you must follow it with another string parameter that specifies the volume to use: "sphere" for a spherical volume (the default), aabb" for an axis-aligned bounding box, "oobb" for an object-oriented bounding box, or "capsule" for a capsule. "position": Specifies the position of the overlap volume. If you specify this parameter, you must follow it with a Vector3 parameter. If omitted, the default is (0,0,0). "rotation": Specifies the rotation of the overlap volume. If you specify this parameter, you must follow it with a Quaternion parameter. If omitted, the default is zero rotation. "pose": Specifies the position and rotation of the overlap volume. If you specify this parameter, you must follow it with a Matrix4x4 parameter. If omitted, the default is zero rotation at position (0,0,0). "size": Specifies the size of the shape. If you specify this parameter, you must follow it with either a Vector3 parameter or a number. The size value is interpreted differently for different shapes. For a sphere, the size value sets the radius. If you pass a Vector3, the largest of its X, Y and Z values is used. For an AABB or an OOBB, the size represents the "half-extents" of the box along each axis. If you pass a single number, it is used for all three axes. For a capsule, the radius of the cylinder and of the ending hemispheres is set by the larger of the X and Z dimensions, and the Y value gives the half-height of the cylinder. If you pass a single number, it is used for all three axes. "types": Determines the types of objects that should be considered for the overlap. If you specify this parameter, you must follow it with an additional string parameter that specifies the types. "statics" specifies that the overlap should only test against static objects. "dynamics" specifies that the overlap should only test against dynamic objects. "both" specifies that the overlap should test against both static and dynamic objects; this is the default value. "collision_filter": This parameter allows you to specify a collision filter that the overlap test should use to determine which objects it considers. If you specify this parameter, you must follow it with an additional string parameter that specifies the name of the collision filter, as defined in your global.physics_properties data file. By default, the overlap considers all objects in the scene. "use_global_table": If this argument is used, a global table will be used to store the actors for the callback. This avoids the memory allocation that would otherwise be needed to allocate space for the table. But be aware that if you use this parameter, the table contents are valid only until the next call to overlap(). The + notation indicates that there may be one or more instances of the specified type.

Returns

table

An internal opaque object that represents the overlap test.

For example, you could find all actors in a 20-meter sphere around the player.

raycast ( self, start, dir, length, params ) : any(boolean, collision_hit[]), stingray.Vector3?, number?, stingray.Vector3?, stingray.Actor? Tests for collisions with the physics objects that live in the same PhysicsWorld.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
start :	stingray.Vector3	Specifies the starting position for the raycast.
dir :	stingray.Vector3	Specifies the direction that the ray will be cast from its starting point.
length :	number?	Optional. Specifies the maximum length of the ray. If not specified, the ray will be infinitely long. The ? notation indicates that this type is optional: there may be zero or one instances of it.
params :	string*	A list of parameters that control the collision tests and determine what return values this function will produce. See the Raycast object description for full details. The * notation indicates that there may be zero or more instances of the specified type.

Returns

any(boolean, collision_hit[])	Whether or not a collision occurred. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
stingray.Vector3?	Position of the collision. The ? notation indicates that this type is optional: there may be zero or one instances of it.
number?	Distance to collision. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector3?	Normal of collision surface. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Actor?	Actor that was hit. The ? notation indicates that this type is optional: there may be zero or one instances of it.

The raycast will be run immediately and the results of the collision test will be returned by this function. See the description of the Raycast object for details about how to interpret the return values.

Related sample code

Picking a unit with the mouse

Other related reference items

stingray.Raycast

set_debug_draw ( self, enable ) Enables or disables debug drawing for this world.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
enable :	boolean	A flag to enable or disable debug drawing.

Returns

This function does not return any values.

set_gravity ( self, gravity ) Sets the gravity in the specified PhysicsWworld, expressed as a Vector3.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
gravity :	stingray.Vector3	The new gravity value to set for the world.

Returns

This function does not return any values.

The default gravity is Vector3(0,0,-9.82).

set_observer ( self, mat ) Sets the observer for the physics world.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
mat :	stingray.Matrix4x4	The matrix to set as the observer.

Returns

This function does not return any values.

This is used to determine the LOD of physics objects. Currently, only a single observer is supported.

spawn_box ( self, pos, radius, actor, shape, material ) : stingray.Actor Spawns an improvised box at the specified position.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
pos :	stingray.Vector3	The location where the new box is produced.
radius :	stingray.Vector3	The half-extent of the box along each axis.
actor :	string?	The name of the actor template to use when constructing the box, if any. If specified, you must also specify the shape and material parameters. The ? notation indicates that this type is optional: there may be zero or one instances of it.
shape :	string?	The name of the shape template to use when constructing the box. The ? notation indicates that this type is optional: there may be zero or one instances of it.
material :	string?	The name of the material template to use when constructing the box. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Actor

The newly spawned box.

Most physics objects in a scene come from the units through the physics settings specified in the .physics file. However, sometimes it can be useful to spawn a completely improvised physics actor. This function spawns an improvised box.

Other related reference items

stingray.PhysicsWorld.destroy_actor()

spawn_plane ( self, pos, normal, actor, shape, material ) : stingray.Actor Spawns a static plane with specified position and normal.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
pos :	stingray.Vector3	The position of the plane.
normal :	stingray.Vector3	The normal of the plane.
actor :	string?	The name of the actor template to use when constructing the plane, if any. If specified, you must also specify the shape and material parameters. The ? notation indicates that this type is optional: there may be zero or one instances of it.
shape :	string?	The name of the shape template to use when constructing the plane. The ? notation indicates that this type is optional: there may be zero or one instances of it.
material :	string?	The name of the material template to use when constructing the plane. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Actor

The newly spawned plane.

Most physics objects in a scene come from the units through the physics settings specified in the .physics file. However, sometimes it can be useful to spawn a completely improvised physics actor. This function spawns an improvised plane.

Other related reference items

stingray.PhysicsWorld.destroy_actor()

spawn_sphere ( self, pos, radius, actor, shape, material ) : stingray.Actor Spawns an improvised sphere at specified position.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
pos :	stingray.Vector3	The location where the new sphere is produced.
radius :	number	The radius of the sphere.
actor :	string?	The name of the actor template to use when constructing the sphere, if any. If specified, you must also specify the shape and material parameters. The ? notation indicates that this type is optional: there may be zero or one instances of it.
shape :	string?	The name of the shape template to use when constructing the sphere. The ? notation indicates that this type is optional: there may be zero or one instances of it.
material :	string?	The name of the material template to use when constructing the sphere. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Actor

The newly spawned sphere.

Most physics objects in a scene come from the units through the physics settings specified in the .physics file. However, sometimes it can be useful to spawn a completely improvised physics actor. This function spawns an improvised sphere.

Other related reference items

stingray.PhysicsWorld.destroy_actor()

wake_actors ( self, filter_id, min, max ) Wakes all physics actors that collide with the specified collision filter and that intersect the axis-oriented bounding box defined by the specified minima and maxima.

Parameters

self :	stingray.PhysicsWorld	Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation.
filter_id :	string	The id of the collision filter.
min :	stingray.Vector3	The minimum value of the vector.
max :	stingray.Vector3	The maximum value of the vector.

Returns

This function does not return any values.

Other related reference items

stingray.PhysicsWorld.apply_wind()