Handles collisions by backing up in time with binary search algorithm. For better performance uses collision time estimates and handles imminent collisions.

When a collision is encountered, advance backs up to just before the time of collision, handles the collision, then continues to advance to the end of the time step. (This process can happen many times during a single call to advance). Uses a binary search algorithm to get to the time just before the collision. The DiffEqSolver is used to move the simulation forward in time.

Debugging with WayPoints

CollisonAdvance can be very tricky to debug because the set of Collisions found drive the process, yet they come and go as we move backward and forward in time. Specifying WayPoints lets you focus on only the relevant aspects of the process, greatly reducing the volume of debug messages to sort thru.

A WayPoint is a step of the AdvanceStrategy process where debug info can be printed. See the methods addWayPoints, setWayPoints. The method setDebugLevel selects a pre-defined group of WayPoints.

Here is an example of how to turn on debugging.

const advance = new CollisionAdvance(sim);

See Observing The Collision Handling Process in 2D Physics Engine Overview, and DebugLevel.

Type Parameters




backupCount_: number = 0

how many times we had to backup

binarySearch_: boolean = false

whether searching for collision using binary search algorithm

binarySteps_: number = 0

during binary search, number of consecutive same-size steps; should never exceed 2

collisionCounter_: number = 0

how many collisions occurred

collisionTotals_: CollisionTotals = ...

long term count of number of collisions, backups, ode steps taken, etc.

collisions_: T[] = []

the current set of collisions; includes joints, contacts, imminent collisions

currentStep_: number = 0

how much time currently trying to advance

debugPaint_: null | (() => void) = null

function to paint canvases, for debugging. If defined, this will be called within do_advance_sim(), so you can see the simulation state after each collision is handled (you will need to arrange your debugger to pause after each invocation of debugPaint_ to see the state).

Type declaration

    • (): void
    • Returns void

detectedTime_: number = NaN

during binary search, remembers time when earliest collision was detected

jointSmallImpacts_: boolean = false

Whether to apply small impacts to joints to keep them aligned.

nextEstimate_: number = NaN

the estimated time when the next collision will happen.

odeSteps_: number = 0

how many ODE (ordinary diff eq) steps were taken

printTime_: number = Number.NEGATIVE_INFINITY

For debugging, when we last printed a debug message.

removedCollisions_: T[] = []

set of collisions that were 'not close enough' to be handled. These are kept to find the estimated time of next collision after handling current collisions.

stats_: CollisionStats = ...

statistics about the current set of collisions

stuckCount_: number = 0

for detecting 'stuck' condition

timeAdvanced_: number = 0

how much time simulation has advanced

timeStep_: number = 0.025

Default amount of time to advance the simulation, in seconds.

totalTimeStep_: number = 0

total length of time requested to advance

wayPoints_: WayPoint[] = ...

Set of waypoints at which to print debug messages


The maximum number of times to go thru the loop in advance() without a successful step that advances the simulation time; when this limit is exceeded then advance() returns false to indicate it was unable to advance the simulation.


  • Adds a group of WayPoints to show debug messages to the existing set of WayPoints.


    • wayPoints: WayPoint[]

      array of WayPoints to add

    Returns void

  • Advances the Simulation state by the specified amount of time.


    • timeStep: number

      the amount of time to advance in seconds

    • Optional opt_memoList: MemoList

      optional MemoList to call whenever the simulation state is advanced

    Returns void


    when unable to advance the simulation

  • Returns the velocities of the collisions.


    • collisions: T[]

    Returns number[]

    minimum velocities

  • Check that there are no unhandled collisions at end of loop. At end of loop there are two cases:

    1. we did a backup to before the collision at which time there should be no unhandled collisions

    2. we handled the collisions

    Returns void

  • Back-up in time to state before last step. Because collision is an illegal state and we want to handle collisions at the moment just before collision so that objects are always in a legal state. *


    • stepSize: number

    Returns void

  • Whether to apply small impacts to joints to keep them aligned.

    Returns boolean

    true means apply small impacts to joints

  • Returns the maximum impulse applied to any of the collisions.


    • collisions: T[]

    Returns number

    maximum impulse applied

  • Returns the smallest (most negative) velocity of the collisions.


    • collisions: T[]

    Returns number

    minimum velocity

  • Parameters

    • message: string
    • Rest ...colors: string[]

      CSS color or background strings

    Returns void

  • Print the debug message corresponding to the given WayPoint.


    • wayPoint: WayPoint

      the way point to print debug information for

    Returns void

  • Prints a collision to console using color to highlight collisions that are colliding or close enough to handle. *


    • time: number

      current simulation time *

    • msg: string

      message to print before the collision *

    • c: T

      the Collision to print

    Returns void

  • Print collisions, possibly leaving out joints and contacts.


    • msg: string

      message to print before each collision

    • printAll: boolean

      whether to print joint and contact collisions

    Returns void

  • Print collisions that had impulse applied above the given minimal impulse size.


    • msg: string

      message to print before each collision

    • impulse: number

      minimum size of impulse

    Returns void

  • Removes from the current set of collisions, those contacts that are not touching, because they cannot participate in the chain of impulses that are passed between objects during serial collision handling. The removed collisions are added to the removed collisions array.


    • _allowTiny: boolean

      regard as close enough collisions that have smaller distance than distance accuracy would normally allow

    Returns boolean

    true if any collisions were removed

  • For debugging, specify a function that will paint canvases, so that you can see the simulation state while stepping thru with debugger.

    Why to use setDebugPaint()

    Using setDebugPaint() allows you to see the sub-steps involved in calculating the next simulation state, such as each collision happening over a time step, or the sub-steps calculated by a DiffEqSolver. Normally you only see the result after the next state is calculated, because the frame is painted after the simulation has advanced by a certain time step. By setting the paintAll function and setting a debugger break point you will be able to see the situation whenever moveObjects() is called. See RigidBodySim for an example and more information.

    Here is example code where simRun.paintAll is the method SimRunner.paintAll which paints all the LabCanvas's.

    advance.setDebugPaint( () => simRun.paintAll() );


    • fn: null | (() => void)

      function that will paint canvases

    Returns void

  • Sets whether to apply small impacts to joints to keep them aligned.


    • value: boolean

      true means apply small impacts to joints

    Returns void

  • Sets the default time step, the small increment of time by which to advance the simulation's state.

    The reason for storing the time step in AdvanceStrategy is so that test/TestViewerApp.TestViewerApp produces the same results as running a test. This is a convenient way for a test to make known the time step to use.


    • timeStep: number

      the default time step, in seconds.

    Returns void

  • Specifies the group of WayPoints to show debug messages at.


    • wayPoints: WayPoint[]

      array of WayPoints to show debug messages for

    Returns void

  • Returns a minimal string representation of this object, usually giving just identity information like the class name and name of the object.

    For an object whose main purpose is to represent another Printable object, it is recommended to include the result of calling toStringShort on that other object. For example, calling toStringShort() on a DisplayShape might return something like this:


    Returns string

    a minimal string representation of this object.

Generated using TypeDoc