Robert Herhold edited this page Feb 14, 2016 · 10 revisions

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

See also: API Reference on PubSub

NOTE: there were major changes to the pubsub system in v0.6.0 (beta). See v0.5.x for the old documentation.

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

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)
  • 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.subscribe(EVENT_NAME, function( data ){
    // ...
}, 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.unsubscribe( EVENT_NAME, callbackFn );

To publish an event:

world.publish({
    topic: EVENT_NAME,
    // ...
});
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.