PubSub

PhysicsJS uses the concept of Publishing and Subscribing to events to encourage loose coupling and modularity.

v0.6.x pubsub

Callback subscribed to an event will receive a data object with all information about the event, including:

topic - the event name
handler - the callback function reference
scope - the scope of the event (usually the world)
any other data specific to the event

These events are generally mediated through the world object. The world itself emits the following events:

add:body (data.body contains the body added)
add:behavior (data.behavior contains the behavior added)
add:integrator (data.integrator contains the integrator added)
add:renderer (data.renderer contains the renderer added)
remove:body (data.body contains the body removed)
remove:behavior (data.behavior contains the behavior removed)
remove:integrator (data.integrator contains the integrator removed)
remove:renderer (data.renderer contains the renderer removed)
render (data.bodies is the array of bodies in the world, data.renderer is the renderer)
step

NB: Behaviors may publish and subscribe to other events.

To subscribe to an event:

world.on( EVENT_NAME, function( data, e ){
    // ...
}, thisRef, PRIORITY);

The EVENT_NAME is a string. thisRef is an optional scope to bind the callback to. PRIORITY is similar to unix priorities. A callback subscribed with a higher priority will be executed sooner than one with a lower priority.

To unsubscribe:

world.off( EVENT_NAME, callbackFn );

To publish an event:

world.emit( EVENT_NAME, data );

More ...

// event data having the "handler" and "type" reference so that one can do things like this:
ps.on( 'my-event', function( data, e ){
    if ( something ) {
        ps.off( e.type, e.handler );
    }
});

// if you only want to listen once...
ps.one( 'my-event', function( data, e ){
    // only triggered once...
});


// multiple events in one shot (works with .off() too)
ps.on({
    'my-event1': function( data, e ) {
        // handle
    },
    'my-event2': function( data, e ) {
        // ...
    }
    // ...
});

// bind to different "this"
ps.on( 'my-event', function( data, e ){
    this === scope; // true
}, scope);

// remove all events bound to "type"
ps.off( 'my-event', true );

// remove all events
ps.off( true );


// priority management
ps.on( 'my-event', function( data, e ){
    // runs last
}, 1 );
ps.on( 'my-event', function( data, e ){
   // runs first, no matter where/when this .on() is called
}, 100);

v0.5.x pubsub