nape.constraint.UserConstraint

UserConstraint providing a low-level API for user-defined Constraints.

This API is intended to be powerful enough to model any constraint that Nape can handle, but not so low level as to be completely prohibitive.
For instance, things like soft-constraints are automatically provided by this API.

Working with this API will require mathematical skills. A full manual for this API is provided at: http://napephys.com/help/Constraints.pdf

You may also be interested in the nape-symbolic module that is available on github/haxelib/nape downloads. Which provides a run-time compiled DSL using this API to make prototyping (or creating non-performance critical) user-defined constraints simple without the need for great mathematical skills as well as being much quicker to work with.

Constructor

`@:value({ velocityOnly : false })new(dimensions:Int, velocityOnly:Bool = false)`

Base constructor for user constraints.

You should never call this function directly, only though use of super(..) in sub-typed UserConstraint.

Parameters:

`dimensions`	The number of constraint space dimensions.
`velocityOnly`	If true, then this constraint will be implemented as a velocity-only constraint like the MotorJoint.

Throws:

`#`	If dimensions < 1

Variables

`@:value(null)zpp_inner_zn:ZPP_UserConstraint = null`

@private

Methods

`__bindVec2():Vec2`

Create a Vec2 property for user-constraint.

This method is used in creating a custom constraint, to create a Vec2 property which will be tied to this constraint so that modifications to the Vec2 will have the appropriate side effects on constraint.

//Haxe (Cleanest way without using macros, clearly you must ensure this
//      is set at least once, likely in constructor)
public var property(default, set_property):Vec2;
inline function set_property(property:Vec2) {
if (this.property == null) this.property = __bindVec2();
return this.property.set(property);

}
//AS3
private var _property:Vec2 = __bindVec2();
public function get property():Vec2 { return _property; }
public function set property(property:Vec2):void {
_property.set(property);

}

This bound Vec2 will behave like standard Nape anchor/direction Vec2's.

You should hide this method in your sub-type.

`__copy():UserConstraint`

Internal copying of user defined constraint.

This method must be overriden, and defines how your customised constraint is to be copied. Likely by simply calling your constructor with constraint properties as argument.

You should hide this method in your sub-type.

Returns:

A copy of your constraint.

Throws:

`#`	If not overriden by sub-type.

`__broken():Void`

Internal extra steps in breaking constraint

This method may be optionally overriden, and defines extra steps to be taken when your constraint is broken. This will be called before the constraint is removed or made inactive.

You should hide this method in your sub-type.

`__validate():Void`

Internal validation of constraint.

This method may be optionally overriden, and defines extra validation steps to be made in validating your constraint integrity in terms of property values. (Think things like standard nape errors if a body is not in the same space as constraint).

This method will be called in all build types, not just debug and can also be used to pre-compute values that will remain constant over an entire time step and do not depend on the state of the Body's.

You should hide this method in your sub-type.

`__draw(debug:Debug):Void`

Internal debug drawing of constraint.

This method will be called by Nape debug draws when enabled to draw your constraint. You do not need to override this method.

You should hide this method in your sub-type.

Parameters:

`debug`	Nape Debug draw to draw constraint to.

`__prepare():Void`

Internal position dependant calculations for constraint.

This method may be overriden to define extra computations that will remain constant as long as a Body's position/rotation is not changed.

You should hide this method in your sub-type.

`__position(err:TArray<Float>):Void`

Internal positional error function for constraint.

You should hide this method in your sub-type.

Parameters:

`err`	The output array to store constraint space positional error.

Throws:

`#`	If this is not a velocity-only constraint, and is not overriden.

`__velocity(err:TArray<Float>):Void`

Internal velocity error function for constraint.

You should hide this method in your sub-type.

Parameters:

`err`	The output array to store constraint space velocity error.

Throws:

`#`	If not overriden by sub-type.

`__eff_mass(eff:TArray<Float>):Void`

Internal effective mass matrix function for constraint.

This array will be of size dimension * (dimension - 1) as a compressed, symmetric matrix:

// Assuming dimension of 3 for constraint:
[ eff[0] eff[1] eff[2] ]
[ eff[1] eff[3] eff[4] ]
[ eff[2] eff[4] eff[5] ]

You should hide this method in your sub-type.

Parameters:

`eff`	The output array to store constraint space effective mass matrix.

Throws:

`#`	If this method is not overriden.

`__clamp(jAcc:TArray<Float>):Void`

Internal, optional clamping of impulse for constraint.

You should hide this method in your sub-type.

Parameters:

`jAcc`	The constraint space impulse to be clamped.

`__impulse(imp:TArray<Float>, body:Body, out:Vec3):Void`

Internal application of impulse to body.

You should hide this method in your sub-type.

Parameters:

`imp`	The constraint space impulse to be applied to bodies.
`body`	The body to apply impulse to.
`out`	The Vec3 to store impulse on body to be applied. This should be in world space.

`impulse():MatMN`

@inheritDoc

For user-defined constraints, this will be a dimensions * 1 MatMN.

`bodyImpulse(body:Body):Vec3`

@inheritDoc

`visitBodies(lambda:Body ‑> Void):Void`

@inheritDoc

`__invalidate():Void`

Internal method to invalidate constraint on property changes

This method should be hidden in your sub-type, and called by your constraint's API when a property of the constraint has been changed.
This does not need to be called for Vec2 properties created via the bindVec2 method.

Throws:

`#`	If you call this method in the middle of a space step.

`__registerBody(oldBody:Null<Body>, newBody:Null<Body>):Null<Body>`

Internal method to register Body's with constraint.

This method should be hidden in your sub-type, and used to deal with adding/removing objects from the constraint so that a functionally equivalent constraint can be created (Dealing with all necessary side-effects etc).

//Haxe
public var body1(default, set_body1):Null<Body>;
inline function set_body1(body1:Null<Body>) {
return this.body1 = __registerBody(this.body1, body1);

}
//AS3
private var _body1:Body;
public function get body1():Body {
return _body1;

}
public function set body1(body1:Body):void {
_body1 = __registerBody(_body1, body1);

}

Parameters:

`oldBody`	The present value of body parameter.
`newBody`	The new value for body parameter.

Returns:

Returns newBody parameter.

Throws:

`#`	If oldBody is not registered with constraint.
`#`	If you call this method in the middle of a space step.

Inherited Variables

Defined by Constraint

`zpp_inner:ZPP_Constraint`

@private

`read onlyuserData:Dynamic<Dynamic>`

Dynamic object for user to store additional data.

This object cannot be set, only its dynamically created properties may be set. In AS3 the type of this property is &#42

This object will be lazily constructed so that until accessed for the first time, will be null internally.

`@:value(true)debugDraw:Bool = true`

Set to disable debug drawing/

When true, this Constraint will not be drawn during debug draw operations unless specifically given as argument to Debug draw() method.

`compound:Null<Compound>`

Compound this Constraints belong to.

If this constraint is in a Space or another Compound and you change its compound, then it will be removed from that Space or Compound.

`space:Null<Space>`

Space this constraint is inside of.

Whether this constraint is directly in a Space, or part of a Compound which is inside of a space, this value will be equal to that Space.

If this constraint is inside of a Compound, then you cannot modify its Space as the constraint belongs to that Compound.

`read onlyisSleeping:Bool`

Whether this constraint is sleeping or not.

This property is only defined if the constraint is inside of a Space and is active, otherwise an error will be thrown should you access this property.

This value is immutable, In Nape you do not ever need to manually wake up a Constraint. It will always be done automatically without error.

To manually put a Constraint to sleep is against the very nature of Nape API and so is excluded from the core of Nape. If you really want to do this you should make use of the nape-hacks module.

`active:Bool`

Whether this constraint is active or not.

Setting a constraint to be no longer active is a useful way of temporarigly disabling a constraint without having to remove it from a Space.

`ignore:Bool`

Whether interactions between related Bodys will be ignored.

If true, then the Bodys related to this constraint will not be permitted to interact in anyway, including callbacks.

`stiff:Bool`

Whether constraint is stiff, or elastic.

A stiff constraint has its positional error resolved directly as with contact penetrations. This is generally a more stable way of solving positional errors but has a side-effect that for example changing the pivot point on a constraint used for mouse control will not cause the objects to swing as the positional error is solved without effecting the velocity of the object which may not be wanted.

If false, then the positional error of the constraint will be resolved in an elastic way using changes in velocity.

`frequency:Float`

Frequency of elastic properties of constraint.

This property only has an effect when constraint is not stiff.

This value corresponds to in an ideal situation, the number of spring like oscillations the constraint will make per second.

This value must be strictly positive (0 not allowed).

`damping:Float`

Damping ratio of elastic properties of constraint.

This property only has an effect when constraint is not stiff.

This value corresponds to in the ideal situation, the damping ratio of the constraints oscillations with 1 corresponding to a total dampening, and values greater than one being over-dampening.

This value must be zero or positive.

`maxForce:Float`

The maximum amount of force this constraint is allowed to use.

This value, whilst still used in a stiff constraint will not work as you might hope for; since a stiff constraint resolves positional error without using impulses, the maxForce will not have any effect on how positional errors are resolved.

This value must be zero or positive.

`maxError:Float`

The maximum amount of error this constraint is allowed to use.

For stiff constraints, this value only serves to work in conjunction with breakUnderError to permit breaking of the constraint.

For non-stiff constraints, this value will also effect how the constraint behaves when breakUnderError is false by restricting the amount of error that will be resolved; this will not work for stiff constraints.

`read onlycbTypes:CbTypeList`

Set of CbTypes for this constraints for callbacks.

This value cannot at present be set, but can be modified.

class UserConstraint

package nape.constraint

extends Constraint

Constructor

@:value({ velocityOnly : false })new(dimensions:Int, velocityOnly:Bool = false)

Variables

@:value(null)zpp_inner_zn:ZPP_UserConstraint = null

Methods

__bindVec2():Vec2

__copy():UserConstraint

__broken():Void

__validate():Void

__draw(debug:Debug):Void

__prepare():Void

__position(err:TArray<Float>):Void

__velocity(err:TArray<Float>):Void

__eff_mass(eff:TArray<Float>):Void

__clamp(jAcc:TArray<Float>):Void

__impulse(imp:TArray<Float>, body:Body, out:Vec3):Void

impulse():MatMN

bodyImpulse(body:Body):Vec3

visitBodies(lambda:Body ‑> Void):Void

__invalidate():Void

__registerBody(oldBody:Null<Body>, newBody:Null<Body>):Null<Body>

Inherited Variables

Defined by Constraint

zpp_inner:ZPP_Constraint

read onlyuserData:Dynamic<Dynamic>

@:value(true)debugDraw:Bool = true

compound:Null<Compound>

space:Null<Space>

read onlyisSleeping:Bool

active:Bool

ignore:Bool

stiff:Bool

frequency:Float

damping:Float

maxForce:Float

maxError:Float

breakUnderForce:Bool

breakUnderError:Bool

removeOnBreak:Bool

read onlycbTypes:CbTypeList

Inherited Methods

Defined by Constraint

@:keeptoString():String

copy():Constraint

`@:value({ velocityOnly : false })new(dimensions:Int, velocityOnly:Bool = false)`

`@:value(null)zpp_inner_zn:ZPP_UserConstraint = null`

`__bindVec2():Vec2`

`__copy():UserConstraint`

`__broken():Void`

`__validate():Void`

`__draw(debug:Debug):Void`

`__prepare():Void`

`__position(err:TArray<Float>):Void`

`__velocity(err:TArray<Float>):Void`

`__eff_mass(eff:TArray<Float>):Void`

`__clamp(jAcc:TArray<Float>):Void`

`__impulse(imp:TArray<Float>, body:Body, out:Vec3):Void`

`impulse():MatMN`

`bodyImpulse(body:Body):Vec3`

`visitBodies(lambda:Body ‑> Void):Void`

`__invalidate():Void`

`__registerBody(oldBody:Null<Body>, newBody:Null<Body>):Null<Body>`

`zpp_inner:ZPP_Constraint`

`read onlyuserData:Dynamic<Dynamic>`

`@:value(true)debugDraw:Bool = true`

`compound:Null<Compound>`

`space:Null<Space>`

`read onlyisSleeping:Bool`

`active:Bool`

`ignore:Bool`

`stiff:Bool`

`frequency:Float`

`damping:Float`

`maxForce:Float`

`maxError:Float`

`breakUnderForce:Bool`

`breakUnderError:Bool`

`removeOnBreak:Bool`

`read onlycbTypes:CbTypeList`

`@:keeptoString():String`

`copy():Constraint`