class nape.constraint.UserConstraint extends Constraint

Available on all platforms

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.

Instance Fields

function new(dimensions:Int, ?velocityOnly:Bool = false):Void

Base constructor for user constraints. *

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

dimensions

The number of constraint space dimensions. *

velocityOnly

If true, then this constraint will be implemented * as a velocity-only constraint like the MotorJoint. *

function __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, setproperty):Vec2;
     * inline function setproperty(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.

function __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.

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

Internal, optional clamping of impulse for constraint. *

* You should hide this method in your sub-type. * *

jAcc

The constraint space impulse to be clamped.

function __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. *

function __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. * *

debug

Nape Debug draw to draw constraint to.

function __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. * *

eff

The output array to store constraint space effective mass matrix. *

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

Internal application of impulse to body. *

* You should hide this method in your sub-type. * *

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.

function __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. * *

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

Internal positional error function for constraint. *

* You should hide this method in your sub-type. * *

err

The output array to store constraint space positional error. *

function __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.

function __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, setbody1):Null<Body>;
     * inline function setbody1(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);
     * }
     * 
*

oldBody

The present value of body parameter. *

newBody

The new value for body parameter. *

returns

Returns newBody parameter. *

function __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.

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

Internal velocity error function for constraint. *

* You should hide this method in your sub-type. * *

err

The output array to store constraint space velocity error. *

function bodyImpulse(body:Body):Vec3

@inheritDoc

function impulse():MatMN

@inheritDoc *

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

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

@inheritDoc