react-pixi-fiber

by michalochman

michalochman /react-pixi-fiber

Write PixiJS applications using React declarative style.

498 Stars 69 Forks Last release: almost 2 years ago (v0.5.0) MIT License 289 Commits 43 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

ReactPixiFiber – React Fiber renderer for PixiJS

npm License CircleCI codecov styled with prettier gitter

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

For React <16.0.0 see

react-pixi
.

Demo

See Rotating Bunny demo.

Usage

With ReactDOM

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

function Bunny(props) { return ; }

render( , 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

```jsx harmony 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( , app.stage ); ```

This example will render

PIXI.Text
object into a Root Container of PIXI Application (created as

app
) inside the
 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:

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.

Renders

PIXI.Container
.

Renders

PIXI.Graphics
.

Renders

PIXI.particles.ParticleContainer
.

Renders

PIXI.Sprite
.

Renders

PIXI.extras.TilingSprite
.

Renders

PIXI.Text
.

Renders

PIXI.extras.BitmapText
.

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.Point
s or
PIXI.ObservablePoint
s 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

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.
Using withApp Higher-Order Component (with all React versions)

To get app prop in your component you may wrap it with withApp higher-order component:

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 =&gt; {
    this.setState(state =&gt; ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

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

const RotatingBunnyWithApp = withApp(RotatingBunny);

render(
  <stage options="{{" backgroundcolor: height: width:>
    <rotatingbunnywithapp x="{200}" y="{200}"></rotatingbunnywithapp>
  </stage>,
  document.getElementById("container")
);
Using New Context API directly (with React 16.3.0 and newer)
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 =&gt; {
    this.setState(state =&gt; ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

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

render(
  <stage options="{{" backgroundcolor: height: width:>
    <appcontext.consumer>
      {app =&gt; (
        <rotatingbunny app="{app}" x="{200}" y="{200}"></rotatingbunny>
      )}
    </appcontext.consumer>
  </stage>,
  document.getElementById("container")
);
Using Legacy Context API directly (with React older than 16.3.0)

This approach is not recommended as it is easier to just use withApp HoC mentioned above.

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 =&gt; {
    this.setState(state =&gt; ({
      rotation: state.rotation + 0.1 * delta,
    }));
  };

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

render(
  <stage options="{{" backgroundcolor: height: width:>
    <rotatingbunny x="{200}" y="{200}"></rotatingbunny>
  </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: ```javascript // 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); ```

```jsx harmony // 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( , app.stage ); ```

Testing

Caveats

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.
.

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.