ReactPixiFiber – React Fiber renderer for PixiJS

ReactPixiFiber is a JavaScript library for writing PixiJS applications using React declarative style in React 16 and React 17.

For React <16.0.0 see react-pixi.

Demo

See Rotating Bunny demo.

Usage

With ReactDOM

import { render } from "react-dom";
import { Sprite, Stage } from "react-pixi-fiber";
import bunny from "./bunny.png";

function Bunny(props) {
  return <Sprite texture={PIXI.Texture.from(bunny)} {...props} />;
}

render(
  <Stage options={{ backgroundColor: 0x10bb99, height: 600, width: 800 }}>
    <Bunny x={200} y={200} />
  </Stage>,
  document.getElementById("container")
);

This example will render PIXI.Sprite object into a Root Container of PIXI.Application on the page.

The HTML-like syntax; called JSX is not required to use with this renderer, but it makes code more readable. You can use Babel with a React preset to convert JSX into native JavaScript.

Without ReactDOM

import { render, Text } from "react-pixi-fiber";
import * as PIXI from "pixi.js";

// Setup PixiJS Application
const canvasElement = document.getElementById("container")
const app = new PIXI.Application({
  backgroundColor: 0x10bb99,
  view: canvasElement,
  width: 800,
  height: 600,
});

render(
  <Text text="Hello World!" x={200} y={200} />, 
  app.stage
);

This example will render PIXI.Text object into a Root Container of PIXI Application (created as app) inside the <canvas id="container"></canvas> element on the page.

Running Examples

1. Run yarn install (or npm install) in the repository root.
2. Run yarn install (or npm install) in the examples directory.
3. Run yarn start (or npm run start) in the examples directory.
4. Wait few seconds and browse examples that will open in new browser window.

Installing

The current version assumes React >16.0.0 and PixiJS >4.4.0

yarn add react-pixi-fiber

or

npm install react-pixi-fiber --save

This package works flawlessly with Create React App – see examples above, they already use it.

Migrating from react-pixi

It is possible to use React Pixi Fiber as a drop-in replacement for react-pixi.

There are two options:

Changing import / require statements

Change:

import ReactPIXI from "react-pixi";
// or
const ReactPIXI = require("react-pixi");

to:

import ReactPIXI from "react-pixi-fiber/react-pixi-alias";
// or
const ReactPIXI = require("react-pixi-fiber/react-pixi-alias");

Using webpack resolve alias

resolve: {
  alias: {
    'react-pixi$': 'react-pixi-fiber/react-pixi-alias'
  }
}

API

Components

React Pixi Fiber currently supports following components:

<Stage />

Renders Root Container of any PIXI.Application.

Expects one the following props:

• app - pass your own PIXI.Application instance,
• options - pass only the PIXI.Application options.

<Container />

Renders PIXI.Container.

<Graphics />

Renders PIXI.Graphics.

<ParticleContainer />

Renders PIXI.particles.ParticleContainer.

<Sprite />

Renders PIXI.Sprite.

<TilingSprite />

Renders PIXI.extras.TilingSprite.

<Text />

Renders PIXI.Text.

<BitmapText />

Renders PIXI.extras.BitmapText.

<NineSlicePlane />

Renders PIXI.NineSlicePlane.

Props

Similarly to ReactDOM in React 16, ReactPixiFiber is not ignoring unknown PIXI.DisplayObject members – they are all passed through. You can read more about Unknown Prop Warning in ReactDOM, however ReactPixiFiber will not warn you about unknown members.

Setting values for Point and ObservablePoint types

For setting properties on PixiJS types that are either PIXI.Points or PIXI.ObservablePoints you can use either and array of integers or a comma-separated string of integers in the following forms: [x,y], "x,y", [i], "i".

In the case where two integers are provided, the first will be applied to the x coordinate and the second will be applied to the y coordinate. In the case where a single integer if provided, it will be applied to both coordinates.

You can still create your own PIXI Point or ObservablePoint objects and assign them directly to the property. These won't actually replace the property but they will be applied using the original object's .copy() method.

Context – Accessing PIXI.Application instance created by <Stage />

PIXI.Application is automatically provided using the following definition (either as a prop or in context):

• app – an instance of PixiJS Application, with properties like:
  • loader – Loader instance to help with asset loading,
  • renderer – WebGL or CanvasRenderer,
  • ticker – Ticker for doing render updates,
  • view – reference to the renderer's canvas element.

import { render } from "react-dom";
import { Sprite, Stage, withApp } from "react-pixi-fiber";
import bunny from "./bunny.png";

class RotatingBunny extends Component {
  state = {
    rotation: 0,
  };

  componentDidMount() {
    // Note that `app` prop is coming through `withApp` HoC
    this.props.app.ticker.add(this.animate);
  }

  componentWillUnmount() {
    this.props.app.ticker.remove(this.animate);
  }

  animate = delta => {
    this.setState(state => ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

  render() {
    return (
      <Sprite 
        {...this.props}
        texture={PIXI.Texture.from(bunny)}
        rotation={this.state.rotation} 
      />
    );
  }
}
RotatingBunny.propTypes = {
  app: PropTypes.object.isRequired,
};

const RotatingBunnyWithApp = withApp(RotatingBunny);

render(
  <Stage options={{ backgroundColor: 0x10bb99, height: 600, width: 800 }}>
    <RotatingBunnyWithApp x={200} y={200} />
  </Stage>,
  document.getElementById("container")
);

import { render } from "react-dom";
import { AppContext, Sprite, Stage } from "react-pixi-fiber";
import bunny from "./bunny.png";

class RotatingBunny extends Component {
  state = {
    rotation: 0,
  };

  componentDidMount() {
    // Note that `app` prop is coming directly from AppContext.Consumer
    this.props.app.ticker.add(this.animate);
  }

  componentWillUnmount() {
    this.props.app.ticker.remove(this.animate);
  }

  animate = delta => {
    this.setState(state => ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

  render() {
    return (
      <Sprite 
        {...this.props}
        texture={PIXI.Texture.from(bunny)}
        rotation={this.state.rotation} 
      />
    );
  }
}
RotatingBunny.propTypes = {
  app: PropTypes.object.isRequired,
};

render(
  <Stage options={{ backgroundColor: 0x10bb99, height: 600, width: 800 }}>
    <AppContext.Consumer>
      {app => (
        <RotatingBunny app={app} x={200} y={200} />
      )}
    </AppContext.Consumer>
  </Stage>,
  document.getElementById("container")
);

import { render } from "react-dom";
import { Sprite, Stage } from "react-pixi-fiber";
import bunny from "./bunny.png";

class RotatingBunny extends Component {
  state = {
    rotation: 0,
  };

  componentDidMount() {
    // Note that `app` is coming from context, NOT from props
    this.context.app.ticker.add(this.animate);
  }

  componentWillUnmount() {
    this.context.app.ticker.remove(this.animate);
  }

  animate = delta => {
    this.setState(state => ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

  render() {
    return (
      <Sprite 
        {...this.props}
        texture={PIXI.Texture.from(bunny)}
        rotation={this.state.rotation} 
      />
    );
  }
}
// Note that here we tell React to apply `app` via legacy Context API
RotatingBunny.childContextTypes = {
  app: PropTypes.object,
};

render(
  <Stage options={{ backgroundColor: 0x10bb99, height: 600, width: 800 }}>
    <RotatingBunny x={200} y={200} />
  </Stage>,
  document.getElementById("container")
);

Custom Components

ReactPixiFiber can recognize your custom components using API compatible with react-pixi.

CustomPIXIComponent(behavior, type) accepts a behavior object with the following 4 properties and a type string.

customDisplayObject(props)

Use this to create an instance of [PIXI.DisplayObject].

This is your entry point to custom components and the only required method. Can be also passed as behavior of type function to CustomPIXIComponent.

customApplyProps(displayObject, oldProps, newProps) (optional)

Use this to apply newProps to your Component in a custom way.

Note: this replaces the default method of transfering props to the specified displayObject. Call this.applyDisplayObjectProps(oldProps,newProps) inside your customApplyProps method if you want that.

customDidAttach(displayObject) (optional)

Use this to do something after displayObject is attached, which happens after componentDidMount lifecycle method.

customWillDetach(displayObject) (optional)

Use this to do something (usually cleanup) before detaching, which happens before componentWillUnmount lifecycle method.

Simple Graphics example

For example, this is how you could implement Rectangle component:

// components/Rectangle.js
import { CustomPIXIComponent } from "react-pixi-fiber";
import * as PIXI from "pixi.js";

const TYPE = "Rectangle";
export const behavior = {
  customDisplayObject: props => new PIXI.Graphics(),
  customApplyProps: function(instance, oldProps, newProps) {
    const { fill, x, y, width, height } = newProps;
    instance.clear();
    instance.beginFill(fill);
    instance.drawRect(x, y, width, height);
    instance.endFill();
  }
};
export default CustomPIXIComponent(behavior, TYPE);

// App.js
import { render } from "react-pixi-fiber";
import * as PIXI from "pixi.js";
import Rectangle from "./components/Rectangle"

// Setup PixiJS Application
const canvasElement = document.getElementById("container")
const app = new PIXI.Application(800, 600, {
  view: canvasElement
});

render(
  <Rectangle
    x={250}
    y={200}
    width={300}
    height={200}
    fill={0xFFFF00}
  />, 
  app.stage
);

Testing

Caveats

React Context API limitations

Because of a React limitation preventing context to pass through renderers, new React Context API (react >= 16.3.0) cannot be used inside Stage inner components. Even if you're not using this feature directly, some of your dependencies may use it (react-redux, material-ui, ...).

A workaround would be to "make a bridge" between default renderer and react-pixi-fiber one. For example:

// use example
export const App = () => {

  return (
    <GameTitleContext.Provider value={'game title'}>
      <GameTitleContext.Consumer>
        {title => <h1>{title}</h1>}
      <GameTitleContext.Consumer>
      
      <ContextBridge
        contexts={[
          GameTitleContext,
          ReactReduxContext,
          OtherContext,
        ]}
        barrierRender={children => (
          <Stage options={{ height: 600, width: 800 }}>
            {children}
          </Stage>
        )}
      >
        <Container>
          <GameTitleContext.Consumer>
            {title => <Text text={title} />}
          </GameTitleContext.Consumer>
        </Container>
      </ContextBridge>
    </GameTitleContext.Provider>
  );
};

// context-bridge component

/*
 * type ContextBridgeProps = {
 *    contexts: React.Context<any>[];
 *    barrierRender: (children: React.ReactElement | null) => React.ReactElement | null;
 *    children: React.ReactNode;
 * };
 */

export const ContextBridge = ({ barrierRender, contexts, children }) => {

    const providers = values => {

        const getValue = i => values[ values.length - 1 - i ];

        return <>
          {contexts.reduce((innerProviders, Context, i) => (
            <Context.Provider value={getValue(i)}>
                {innerProviders}
            </Context.Provider>
          ), children)}
        </>;
    };

    const consumers = contexts.reduce((getChildren, Context) => (
        values => <Context.Consumer>
            {value => getChildren([ ...values, value ])}
        </Context.Consumer>
    ), values => barrierRender(providers(values)));

    return consumers([]);
};

More infos & workarounds: #93 #84 (comment)

FAQ

Is it production ready?

Yes! Awesome!

What version of PixiJS I can use?

Both PixiJS v4 and v5 are supported.

Can I use already existing PIXI.Application?

Yes, you can pass app property to Stage component, e.g. <Stage app={app} />.

Can I migrate from react-pixi?

Yes, it is easy, read migration guide.

Is server-side rendering supported?

No, unfortunately it is not supported right now.

Contributing

The main purpose of this repository is to be able to render PixiJS objects inside React 16 Fiber architecture.

Development of React Pixi Fiber happens in the open on GitHub, and I would be grateful to the community for any contributions, including bug reports and suggestions.

Read below to learn how you can take part in improving React Pixi Fiber.

Code of Conduct

React Pixi Fiber has adopted a Contributor Covenant Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contributing Guide

Read the contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to React Pixi Fiber.

Contact

You can help others and discuss in our gitter channel.

License

ReactPixiFiber is MIT licensed.

Credits

react-pixi

For making PIXI available in React for the first time.

React Fiber Architecture

For deeply explaining the concepts of Fiber architecture.

Building a custom React renderer

For helping me understand how to build an actual renderer.

React ART

On which this renderer was initially based.

React Contributors

For making an awesome project structure and documentation that is used in similar fashon here.