Donate Donating to nape helps push me to keep on making it better!
Index | Donators | Forums | Project Page
Loading
nape.space.Space class
Top | Properties | Constructor | Methods

Package nape.space
Class Space

responsible for simulations in nape.


Public Properties
Property Defined By
id : Int
Unique space id		 Space
userData : Dynamic
User defined data		 Space
 
broadphase : Broadphase
[read-only] Broadphase typed used by this space		 Space
sortContacts : Bool = true
Control whether contacts are sorted		 Space
gravity : Vec2
Global gravity		 Space
worldLinearDrag : Float = 0.015
Linear drag applied to all objects		 Space
worldAngularDrag : Float = 0.015
Angular drag applied to all objects		 Space
 
elapsedTime : Float
[read-only] Amount of simulated time passed		 Space
timeStamp : Int
[read-only] Internal discrete clock		 Space
 
compounds : CompoundList
[read-only] List of all compounds added to the space		 Space
bodies : BodyList
[read-only] List of all bodies added to the space		 Space
constraints : ConstraintList
[read-only] List of all constraints added to the space		 Space
 
liveBodies : BodyList
[read-only] Immutable list of all live bodies		 Space
liveConstraints : ConstraintList
[read-only] Immutable list of all live, active constraints in space		 Space
 
world : Body
[read-only] Static reference body for constraints		 Space
 
arbiters : ArbiterList
[read-only] Immutable list of live arbiters		 Space
listeners : ListenerList
[read-only] Mutable listeners list		 Space

Constructor
Constructor
new(?gravity:Vec2, ?broadphase:Broadphase)
Construct new Space

Public Methods
Method Defined By
step(deltaTime:Float, ?velocityIterations:Int=10, ?positionIterations:Int=10)
Perform simulation step		 Space
interactionType(shape1:Shape, shape2:Shape)
Determine InteractionType if any between two shapes		 Space

 
visitBodies(lambda:Body->Void)
Visitor for all bodies		 Space
visitConstraints(lambda:Constraint->Void)
Visitor for all constraints		 Space
visitCompounds(lambda:Compound->Void)
Visitor for all inner compounds		 Space

 
const shapesUnderPoint(point:const Vec2, ?filter:const InteractionFilter) : ShapeList
Find all shapes beneath a point		 Space
const bodiesUnderPoint(point:const Vec2, ?filter:const InteractionFilter) : BodyList
Find all bodies beneath a point		 Space

 
const shapesInAABB(aabb:const AABB, ?containment:Bool=false, ?strict:Bool=true, ?filter:const InteractionFilter) : ShapeList
Find all shapes within an AABB		 Space
const bodiesInAABB(aabb:const AABB, ?containment:Bool=false, ?strict:Bool=true, ?filter:const InteractionFilter) : BodyList
Find all bodies within an AABB		 Space

 
const shapesInCircle(position:const Vec2, radius:Float, ?containment:Bool=false, ?filter:const InteractionFilter) : ShapeList
Find all shapes within a circle		 Space
const bodiesInCircle(position:const Vec2, radius:Float, ?containment:Bool=false, ?filter:const InteractionFilter) : BodyList
Find all bodies within an circle		 Space

 
const shapesInShape(shape:const Shape, ?containment:Bool=false, ?filter:const InteractionFilter) : ShapeList
Find all shapes within another Shape		 Space
const bodiesInShape(shape:const Shape, ?containment:Bool=false, ?filter:const InteractionFilter) : BodyList
Find all bodies within a shape		 Space
const shapesInBody(body:const Body, ?filter:const InteractionFilter) : ShapeList
Find all shapes within a Body		 Space
const bodiesInBody(body:const Body, ?filter:const InteractionFilter) : BodyList
Find all bodies within a Body		 Space

 
const rayCast(ray:const Ray, ?inner:Bool=false, ?filter:InteractionFilter=null) : Maybe<RayResult>
Perform a ray cast, terminating at first intersection		 Space
const rayMultiCast(ray:const Ray, ?inner:Bool=false, ?filter:InteractionFilter=null) : RayResultList
Perform a ray cast, finding all intersections		 Space

Property Detail
id property
property id : Int

Unique id for each Space instantiated. Perhaps a bit strange to do so, but you never know!


userData property
property userData : Dynamic

User defined data


broadphase property
readonly property broadphase : Broadphase

The type of broadphase being used by this space, this cannot be changed once the Space has been constructed!


sortContacts property
property sortContacts : Bool

If true (default), then dynamic contact arbiters are sorted based on penetration depths. Apart from making behaviour between broadphase types roughly equivalent (full sorting on all arbiter types would be needed for true equivalence), sorting arbiters in this way can help with stability of large piles/stacks at a constant cost equal to the number of arbiters active in the simulation.

This is left configurable as there is no speed penalty in keeping it so. The speed penalty is fairly small (For the StressPyramid demo, disabling contact sorting raises the fps (on my computer) from ~29fps to ~31fps.


gravity property
property gravity : Vec2

Global acceleration due to gravity.
setter is copy by value, not copy by reference and equivalent to gravity.set(v)


worldLinearDrag property
property worldLinearDrag : Float

Every step a force is applied to objects, such that under no outside influence, an object will lose 'worldLinearDrag' amount of its velocity per second. Note that this is purely a force applied as opposed to a fluid's drag which is implemented as a constraint in the physics


worldAngularDrag property
property worldAngularDrag : Float

Every step a torque is applied to objects, such that under no outside influence, an object will lose 'worldAngularDrag' amount of its angular velocity per second. Note that this is purely a torque applied as opposed to a fluid's drag which is implemented as a constraint in the physics


elapsedTime property
readonly property elapsedTime : Float

The amount of simulated time via calls to space.step() that has passed since Space instantiation (measured in seconds)


timeStamp property
readonly property timeStamp : Int

An internal discrete clock corresponding to the number of calls made to space.step()


compounds property
readonly property compounds : CompoundList

List of all compounds add to the space, note that this does 'not' include compounds that are part of some compound tree that was added to the space.


bodies property
readonly property bodies : BodyList

List of all bodies add to the space, note that this does 'not' include bodies that are part of some compound tree that was added to the space.


constraints property
readonly property constraints : ConstraintList

List of all constraints added to the space, note that this does 'not' include constraints that are part of some compound tree that was added to the space.


liveBodies property
readonly property liveBodies : BodyList

An immutable list of all the non-sleeping bodies currently being simulated.


liveConstraints property
readonly property liveConstraints : ConstraintList

An immutable list of all constraints which are currently non-sleeping and activated.


world property
readonly property world : Body

An immutable, static, stationary body which can be used for constraints to do things like pin an object to a static point in space


arbiters property
readonly property arbiters : ArbiterList

Reference to the immutable list of all living, active arbiters belonging to this Space. Sleeping arbiters are not included as this would be rather messy and annoying to deal with internally!


listeners property
readonly property listeners : ListenerList

List of all listeners assigned to this Space for callback generation


Constructor Detail
function new(?gravity:Vec2, ?broadphase:Broadphase)

Construct a new Space with given gravity, default being (0,0) and given broadphase type, the default being a dynamic aabb tree


Method Detail
step method
function step(deltaTime:Float, ?velocityIterations:Int=10, ?positionIterations:Int=10)

Perform simulation step of given time period with given iterations

For best stability, deltaTime should be kept constant for each step though as long as it does not fluctuate too wildly stability should be acceptable
The more velocity iterations there are the more accurate collision responses and constraints will be
Positional iterations are used for contacts, and for stiff constraints to correct positional errors, the more iterations there are the more stable and accurate such calculations will be

Error if:
X    deltaTime<=0
X    velocityIterations<=0
X    positionIterations<=0


interactionType method
function interactionType(shape1:Shape, shape2:Shape)

Given two shapes, which exist within a defined Body this function will determine what sort of interaction 'would' occur between them during a call to space.step() taking into account filters/interaction groups/body types and existance of any active constraints in the space etc so that there is a direct correspondence with what will actually happen. null will be returned if 'no' interaction would occur

Although the Shape's Bodys do not need to be in the Space, it is not acceptable to have the Shape's Body's in 'different' Spaces than the one on which this function is called

Error if:
X    shape1.body==null || shape2.body==null
X    (shape1.body.space!=null && shape1.body.space!=this) || (shape2.body.space!=null && shape2.body.space!=this)


visitBodies method
function visitBodies(lambda:Body->Void)

Apply given function to all bodies contained within the space and down the tree


visitConstraints method
function visitConstraints(lambda:Constraint->Void)

Apply given function to all constraints contained within the space and down the tree


visitCompounds method
function visitCompounds(lambda:Compound->Void)

Apply given function to all compounds contained within the space and down the tree


shapesUnderPoint method
const function shapesUnderPoint(point:const Vec2, ?filter:const InteractionFilter) : ShapeList

Returns a list of all shapes beneath the given point.
If the filter argument is non-null, then only shape who's interactionFilter agrees to "collide" will be considered


bodiesUnderPoint method
const function bodiesUnderPoint(point:const Vec2, ?filter:const InteractionFilter) : BodyList

Returns a list of all objects who's shapes are beneath the given point.
If the filter argument is non-null, then only Bodies with a shape at this point for which the shape's interactionFilter agrees to "collide" will be considered


shapesInAABB method
const function shapesInAABB(aabb:const AABB, ?containment:Bool=false, ?strict:Bool=true, ?filter:const InteractionFilter) : ShapeList

Returns a list of all shapes within the given bounding box.
If the filter argument is non-null, then only shape who's interactionFilter agrees to "collide" will be considered

When strict is false, the shape AABB is considered instead of the shape itself so that a faster query is performed, but erroneous shapes may be considered

If containment is true, then only shapes entirely contained in the given AABB will be included


bodiesInAABB method
const function bodiesInAABB(aabb:const AABB, ?containment:Bool=false, ?strict:Bool=true, ?filter:const InteractionFilter) : BodyList

Returns a list of all bodies with a shape within the given AABB.
If the filter argument is non-null, then only Bodies with a shape within the AABB for which the shape's interactionFilter agrees to "collide" will be considered

When strict is false, the AABB of the shapes is considered instead of the shapes themselves so that a faster query is performed, but erroneous bodies may be considered

If containment is true, then only bodies entirely contained in the given AABB will be included


shapesInCircle method
const function shapesInCircle(position:const Vec2, radius:Float, ?containment:Bool=false, ?filter:const InteractionFilter) : ShapeList

Returns a list of all shapes within the given circle.
If the filter argument is non-null, then only shape who's interactionFilter agrees to "collide" will be considered

If containment is true, then only shapes entirely contained in the given circle will be included


bodiesInCircle method
const function bodiesInCircle(position:const Vec2, radius:Float, ?containment:Bool=false, ?filter:const InteractionFilter) : BodyList

Returns a list of all bodies with a shape within the given circle.
If the filter argument is non-null, then only Bodies with a shape within the circle for which the shape's interactionFilter agrees to "collide" will be considered

If containment is true then only bodies entirely contained in the given circle will be included


shapesInShape method
const function shapesInShape(shape:const Shape, ?containment:Bool=false, ?filter:const InteractionFilter) : ShapeList

Returns a list of all shapes within the given shape. The given shape must belong to a Body to be well defined though this Body need not be inside of any Space.
If the filter is non-null then only shapes that gree to "collide" will be considered, noting that the Shape is treat as purely geometric and it's own filter/interaction group etc are ignored.

If containment is true, then only shapes entirely contained in the given shape will be included

Error if:
X    shape.body==null


bodiesInShape method
const function bodiesInShape(shape:const Shape, ?containment:Bool=false, ?filter:const InteractionFilter) : BodyList

Returns a list of all bodies with a shape within the given shape. The given shape must belong to a Body to be well defined though this Body need not be inside of any Space.
If the filter is non-null then only bodies who's shapes agree to "collide" will be considered, noting that the Shape is treat as purely geometric and it's own filter/interaction group etc are ignored.

If containment is true, then only bodies entirely contained in the given shape will be included

Error if:
X    shape.body==null


shapesInBody method
const function shapesInBody(body:const Body, ?filter:const InteractionFilter) : ShapeList

Returns a list of all shapes intersecting with a shape of the given Body. The input body need not belong to any Space.
If the filter is non-null, then only shapes who agree to "collide" will be considered, noting that the Body is treat as purely geometric and it's own interaction group/shape filters/constraints are ignored.

There is no easy way of performing a containment test in a compound Body.


bodiesInBody method
const function bodiesInBody(body:const Body, ?filter:const InteractionFilter) : BodyList

Returns a list of all bodies with shapes intersecting the shapes of the given Body. The input body need not belong to any Space.
If the filter is non-null, then only shapes who agree to "collide" will be considered, noting that the Body is treat as purely geometric and it's own interaction group/shape filters/constraints are ignored.

There is no easy way of performing a containment test in a compound Body.


rayCast method
const function rayCast(ray:const Ray, ?inner:Bool=false, ?filter:InteractionFilter=null) : Maybe<RayResult>

Perform a ray cast up to the ray's defined maximum distance, terminating at the first intersection.

If inner is true, then the ray will also intersect with the inner surfaces of shapes such that a circle would have 2 intersections.

If filter is non-null, then only shapes which should collide based on interaction filters will be intersected with.


rayMultiCast method
const function rayMultiCast(ray:const Ray, ?inner:Bool=false, ?filter:InteractionFilter=null) : RayResultList

Perform a ray cast up to the ray's defined maximum distance, finding all valid intersections based on arguments. (See normal rayCast)