@pixi/runner

What is @pixi/runner?

@pixi/runner is a utility package for the PixiJS library that provides a mechanism to manage and execute a series of functions (runners) in a specific order. It is particularly useful for managing events and callbacks in a structured and efficient manner.

What are @pixi/runner's main functionalities?

Creating a Runner

This feature allows you to create a new Runner instance. The 'onEvent' string is the name of the event that the runner will manage.

const { Runner } = require('@pixi/runner');
const myRunner = new Runner('onEvent');

Adding Functions to a Runner

You can add multiple functions (callbacks) to a runner. These functions will be executed in the order they were added when the runner is triggered.

function callback1() { console.log('Callback 1 executed'); }
function callback2() { console.log('Callback 2 executed'); }
myRunner.add(callback1);
myRunner.add(callback2);

Executing a Runner

This feature allows you to execute all the functions added to the runner in the order they were added. In this example, 'Callback 1 executed' and 'Callback 2 executed' will be logged to the console.

myRunner.emit();

Removing Functions from a Runner

You can remove specific functions from the runner. After removal, the function will no longer be executed when the runner is triggered.

myRunner.remove(callback1);

Other packages similar to @pixi/runner

eventemitter3

EventEmitter3 is a high-performance event emitter for Node.js and the browser. It provides a similar mechanism for managing and emitting events but is more general-purpose compared to @pixi/runner, which is tailored for use with PixiJS.

mitt

Mitt is a tiny functional event emitter. It offers a simple and minimalistic API for managing events and callbacks, similar to @pixi/runner, but without the specific integration with PixiJS.

node-event-emitter

Node-Event-Emitter is another event management library that provides a straightforward API for creating and managing events. It is similar to @pixi/runner in functionality but is designed to be used in a broader range of applications.

README

@pixi/runner

A simple alternative to events and signals with an emphasis on performance.

Can be used as an alternative to events / signals.

Installation

npm install @pixi/runner

Usage

import { Runner } from '@pixi/runner';

const onComplete = new Runner('onComplete');

// listenerObject needs to have a 'onComplete' function
onComplete.add(listenerObject);

// emit() and all listeners will have their 'onComplete' functions called
onComplete.emit(data);

Can be used to execute a function on many objects. Handy for games. If you need to update you game elements each frame:

import { Runner } from '@pixi/runner';

const updateRunner = new Runner('update');

// gameItems should all have a 'update' function
updateRunner.add(gameItem1);
updateRunner.add(gameItem2);
updateRunner.add(gameItem3);

// Update game elements...
updateRunner.emit();

Features

• Easy to use familiar API.
• Under the hood it dynamically creates a looping function that is highly optimised.
• Avoids using 'call' and runs the function directly (which is faster!).
• You can pass parameters when emitting.

Pros:

• Doesn't rely on strings.
• Code-completion works properly.
• Trying to dispatch or listen to an event type that doesn't exist throws errors (helps you find errors early).
• No need to create constants to store string values.
• Easy to identify which signals the object dispatch.
• Favor composition over inheritance.
• Doesn't mess with the prototype chain.
• Its fast, a lot faster than events and signals.
• Great for when performance matters.
• Its light weight, with a tiny memory footprint (smaller than events and signals)

Cons:

• Not quite as flexible. All listeners / items in the runner must have the correct function name specified within the runners constructor.

When to Use

In practice I have found the Runner incredibly useful and so thought it would be nice to share with the world. It currently forms the backbone of the messaging system in our game engine. Its working out great for things like update events, collision events etc.

Great to use if you are say looping through and array and calling the same function on each object. The resulting code is cleaner than a loop whilst still keeping the performance as fast as possible.

So yeah, if you are dispatching signals/events to a lot of listeners often (like everyframe often), then I would consider using this alternative. For most cases, this performance boost is not really important enough to switch from your current fave.

Think of this as a nice alternative for when speed really counts!

to run the tests, move to the runner-benchmark folder then run the following:

npm run benchmark

Next open you browser (http://localhost:9966). The test is run in the console. The test result above comes from macbook pro chrome 58.

Any thoughts or comments hit me up on twitter @doormat23, I'd love to hear them!