nape.symbolic.SymbolicConstraint

Class provides run-time definition of constraints using a simplified DSL.

These constraints are much easier to write and experiment with than a hand-written UserConstraint as only the constraint itself needs to be defined at a high level using the mathematical DSL.

For a handful of constraints, the performance will be perfectly fine and this class provides a debug() method to print internal information that would be required to more easily translate a given constraint into a hand-written and optimised UserConstraint.

Syntax: The input to this class is a constraint definitino which follows this pseudo-BNF grammar:

# this is a comment
# body parameter declarations
body name [, name]*

# variable decalarations
scalar|vector name [= default-literal]? [-> time-derivative-expression]?

# constraint/variable limits (optional; default 0's)
# The type of min/max expressions must match variable/constraint type
# with limits imposed component-wise for vector values.
# Limits on variables will be checked during constraint verification at runtime.
limit expression|constraint min-expression max-expression

# expressions may be composed of:
# a basic value:
#    literal-scalar # eg: 1.5
#    inf  # infinity
#    eps  # epsilon value (very near 0).

# a vector/matrix/block expression:
#    [ e1 e2 ] # this is a vector, expressions must be scalar typed.
#    [ e1 e2 ; e3 e4 ] # this is a matrix, expressions must be scalar typed.
#    { e1 e2 } # this is a block vector, expressions may be of any type.

# a let expression:
#    let name = e1 in e2

# Composed of operations between expressions:
#    e1 -+/* e2
#    e1 dot e2 # dot product
#    e1 cross e2 # cross product
#    e1 outer e2 # outer product
#    unit expr # unit of expression (sign of scalar, unit vector)
#    | expr | # magnitude of expression (magnitude of scalar, length of vector)
#    [ expr ] # perpendicular to a vector
#    relative name expr # transformation of given vector expression from local
#                       # to relative coordinates given a variable name representing
#                       # an angle.

# A constraint definition:
#    For a 1-dimensional constraint, this expression should be of scalar type.
#    And for 2 and greater dimensional constraints, a block-vector of scalar types.
constraint expr

Each body parameter will automatically define a set of special variables for that body:

body.position   # position of body (vector)
body.velocity   # velocity of body (vector)
body.rotation   # rotation of body (scalar)
body.angularVel # angular velocity of body (scalar)

As an example, we can re-create Nape's DistanceJoint with:

var symbolicDistanceJoint = new SymbolicConstraint("
    body body1, body2
    vector anchor1, anchor2
    scalar jointMin, jointMax

    # declare that jointMin <= jointMax, and jointMin, jointMax >= 0
    limit jointMin 0 jointMax

    # declare constraint as the distance between transformed anchors
    constraint
       let r1 = relative body1.rotation anchor1 in
       let r2 = relative body2.rotation anchor2 in
       | (body2.position + r2) - (body1.position + r1) |

    # limit distance to the joint min/max.
    limit constraint jointMin jointMax
");

And use it like:

symbolicDistanceJoint.space = space;
symbolicDistanceJoint.setBody("body1", somebody);
... etc

For more examples visit the github repo at: https://github.com/deltaluca/nape-symbolic

SymbolicConstraint's make use internally of the UserConstraint API, and so like other UserConstraint's can be made stiff, or soft and elastic with no extra work.