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