diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f5b70848..df2f51ba 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,6 @@ # How to contribute -It is essential to the development of React Pixi that the community is empowered +It is essential to the development of PixiJS React that the community is empowered to make changes and get them into the library. Here are some guidelines to make that process silky smooth for all involved. @@ -13,7 +13,7 @@ version so that our users learn about the upcoming changes and migrate their cod ## Reporting issues To report a bug, request a feature, or even ask a question, make use of the GitHub Issues -section for [React Pixi][issues]. When submitting an issue please take the following steps: +section for [PixiJS React][issues]. When submitting an issue please take the following steps: 1. **Search for existing issues.** Your question or bug may have already been answered or fixed, be sure to search the issues first before putting in a duplicate issue. @@ -44,7 +44,7 @@ To setup for making changes you will need to take a few steps, we've outlined th for the [command line][fork-cli] and for the [GitHub Client][fork-gui]. 3. Next, run `npm install` from within your clone of your fork. That will install dependencies - necessary to build React Pixi. + necessary to build PixiJS React. 4. Pixi React is set up as a monorepo, with separate packages for: - The main library - `packages/react` @@ -67,7 +67,7 @@ Your change should be made directly to the branch in your fork, or to a branch i ### Testing Your Change -You can test your change by using the automated tests packaged with React Pixi. You can run these tests by running `npm test` +You can test your change by using the automated tests packaged with PixiJS React. You can run these tests by running `npm test` from the command line, either from the project root to test all packages or from within an individual package to test only that package. If you fix a bug please add a test that will catch that bug if it ever happens again. This prevents regressions from sneaking in. @@ -89,7 +89,7 @@ You can use the `docs` package as a way to test Pixi React features are working ### Submitting Your Change After you have made and tested your change, commit and push it to your fork. Then, open a Pull Request -from your fork to the main **React Pixi** repository on the branch you used in the `Making a Change` section of this document. +from your fork to the main **PixiJS React** repository on the branch you used in the `Making a Change` section of this document. ## Quickie Code Style Guide diff --git a/packages/docs/docs/about.mdx b/packages/docs/docs/about.mdx index 02e307a1..651302a7 100644 --- a/packages/docs/docs/about.mdx +++ b/packages/docs/docs/about.mdx @@ -5,147 +5,200 @@ sidebar_position: 1 # About -

+

+

Pixi React

pixi-react -

+
-

- Simply the best way to write PIXI applications in React +

+ Simply the best way to write PixiJS applications in React
- Write PIXI applications using React + Write PixiJS applications using React declarative style 👌 -

+
-![release](https://img.shields.io/github/v/release/pixijs/pixi-react)    ![downloads](https://img.shields.io/npm/dm/@pixi/react)    [![CircleCI](https://img.shields.io/circleci/project/github/pixijs/pixi-react/master.svg)](https://circleci.com/gh/pixijs/pixi-react)    ![license](https://img.shields.io/badge/license-MIT-green.svg)    ![react](https://img.shields.io/badge/react-latest-ff69b4.svg)    ![pixi](https://img.shields.io/badge/pixi-v6+-ff69b4.svg) +![release](https://img.shields.io/github/v/release/pixijs/pixi-react)    ![downloads](https://img.shields.io/npm/dm/@pixi/react)    ![pixi](https://img.shields.io/badge/pixi-v6/v7-E72264.svg) -## News! +
-**We're delighted to announce Pixi React v7.0.0, the first major release since making it an official Pixi package!** +## Features -While all the core components remain the same, there have been some significant changes under the hood: - -* Full React 18 support including a new `createRoot` API, matching the signature of [React 18's `ReactDOM/client`](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis) -* Full Pixi V7 support -* New up-to-date [docs site](https://pixijs.io/pixi-react/) -* Repository converted to a monorepo with separate [`@pixi/react`](https://www.npmjs.com/package/@pixi/react) and [`@pixi/animated`](https://www.npmjs.com/package/@pixi/react-animated) packages -* Internally all `pixi.js` library imports were replaced with `@pixi/` scoped package versions, providing bundlesize improvements for users who use modular builds -* Scoped imports allowed us to remove `@pixi/react-legacy` and `@pixi/react-animated-legacy` packages, with rendering deferred to a user's installed `pixi.js` package -* `sideEffects: false` added to `package.json` to support tree-shaking - -We're excited to see what the community builds with the library and as ever please let us know on [GitHub](https://github.com/pixijs/pixi-react/issues) if you run into any issues, or reach out to us on the [Discord](https://discord.gg/zqbXQAADuM) to chat. - -Thanks! -PixiJS Team +- React 17 and 18 support +- PixiJS v6 and v7 support +- `react-spring` compatible animated components ## Quick start -If you want to start a new React project from scratch, we recommend [Create React App](https://github.com/facebook/create-react-app). -To add to an existing React application, just install the dependencies: +If you want to start a new React project from scratch, we recommend [Vite](https://vitejs.dev/guide/). +To add to an existing React application, just install the dependencies. + +### 1. Create a new React project with Vite: -### Start New React Project "my-app" with Create React App: ```bash -# for typescript add "--template typescript" -npx create-react-app my-app +# for typescript use "--template react-ts" +npx create-vite@latest --template react my-app cd my-app +npm install ``` -### Install Pixi React Dependencies: +### 2. Install Pixi-React dependencies: + ```bash npm install pixi.js @pixi/react ``` -## Usage: +### 3. Replace App.jsx with the following: + ```jsx -import { BlurFilter } from 'pixi.js'; -import { Stage, Container, Sprite, Text } from '@pixi/react'; +import './App.css'; import { useMemo } from 'react'; -export const MyComponent = () => -{ - const blurFilter = useMemo(() => new BlurFilter(4), []); +import { BlurFilter, TextStyle } from 'pixi.js'; +import { Stage, Container, Sprite, Text } from '@pixi/react'; +export const App = () => { + const blurFilter = useMemo(() => new BlurFilter(2), []); + const bunnyUrl = 'https://pixijs.io/pixi-react/img/bunny.png'; return ( - - - - - + + + + + + + ); }; ``` -[Codepen examples](https://codepen.io/collection/XPpGdb/) +### 4. Run the app: + +```bash +npm run dev +``` + +The final result should look like this: + +
+ Screenshot of the quick start 'my-app' project +
+ +
+ +See the [Codepen examples](https://codepen.io/collection/XPpGdb/) ## Example ```jsx live noInline -const reducer = (_, { data }) => data; - -const Bunny = () => { - const [motion, update] = useReducer(reducer); - const iter = useRef(0); - - useTick((delta) => { - const i = (iter.current += 0.05 * delta); - - update({ - type: 'update', - data: { - x: Math.sin(i) * 100, - y: Math.sin(i / 1.5) * 100, - rotation: Math.sin(i) * Math.PI, - anchor: Math.sin(i / 2), - }, - }); - }); - - return ; +// import { Stage, Sprite, Container, Text } from '@pixi/react'; +// import { TextStyle, BlurFilter } from 'pixi.js'; +// import { useMemo } from 'react'; +// import { render } from 'react-dom'; + +const App = () => { + const blurFilter = useMemo(() => new BlurFilter(2), []); + const bunnyUrl = 'https://pixijs.io/pixi-react/img/bunny.png'; + return ( + + + + + + + + + + ); }; - -render( - - - - - , -); +render(); ``` ## Components -Pass PIXI properties directly as component props, example: +Pass PixiJS properties directly as component props, example: ```jsx -import { Sprite } from '@pixi/react' +import { Sprite } from '@pixi/react'; +import { BLEND_MODES, BlurFilter } from 'pixi.js'; +import { useMemo } from 'react'; const MyComponent = () => ( + const blurFilter = useMemo(() => new BlurFilter(4), []); + ; ); ``` +## FAQ + +
+ Interaction does not work +
+ + If you are using PixiJS without the `pixi.js` package and are instead using scoped packages like `@pixi/app`, `@pixi/sprite` etc, you will need to import the `@pixi/events` package to enable interaction. + + ```js + import '@pixi/events'; + ``` +
+
+ ## Join us You're missing an amazing feature? Or just want to get in touch with fellow developers diff --git a/packages/docs/docs/components/AnimatedSprite.mdx b/packages/docs/docs/components/AnimatedSprite.mdx index 90b811be..40b0f733 100644 --- a/packages/docs/docs/components/AnimatedSprite.mdx +++ b/packages/docs/docs/components/AnimatedSprite.mdx @@ -2,7 +2,7 @@ ## Props -https://pixijs.download/dev/docs/PIXI.AnimatedSprite.html +https://pixijs.download/v7.x/docs/PIXI.AnimatedSprite.html ### Additional Props @@ -16,6 +16,9 @@ https://pixijs.download/dev/docs/PIXI.AnimatedSprite.html ## Usage ```jsx live noInline +// import { render } from 'react-dom'; +// import { Stage, Container, AnimatedSprite } from '@pixi/react'; + const textures = makeAnimatedSpriteTextures(); render( diff --git a/packages/docs/docs/components/BitmapText.mdx b/packages/docs/docs/components/BitmapText.mdx index fea0af88..647fb887 100644 --- a/packages/docs/docs/components/BitmapText.mdx +++ b/packages/docs/docs/components/BitmapText.mdx @@ -2,11 +2,14 @@ ## Props -https://pixijs.download/dev/docs/PIXI.BitmapText.html +https://pixijs.download/v7.x/docs/PIXI.BitmapText.html ## Usage ```jsx live noInline +// import { render } from 'react-dom'; +// import { Stage, BitmapText, Text } from '@pixi/react'; + const position = { anchor: 0.5, x: 250, @@ -45,11 +48,19 @@ See https://pixijs.io/examples/#/demos/text-demo.js ```js import { render } from 'react-dom' import { Stage, BitmapText } from '@pixi/react' +import { Loader } from 'pixi.js' -PIXI.Loader.shared +Loader.shared .add('desyrel', './assets/desyrel.xml') .load(onAssetsLoaded) +// If using v7 or later, use the following code: +// import { Assets } from 'pixi.js' +// +// Assets +// .load('./assets/desyrel.xml') +// .then(onAssetsLoaded) + const App = () => ( diff --git a/packages/docs/docs/components/Container.mdx b/packages/docs/docs/components/Container.mdx index a348a457..6b72af74 100644 --- a/packages/docs/docs/components/Container.mdx +++ b/packages/docs/docs/components/Container.mdx @@ -2,11 +2,14 @@ ## Props -https://pixijs.download/dev/docs/PIXI.Container.html +https://pixijs.download/v7.x/docs/PIXI.Container.html ## Usage ```jsx live +// import React from 'react' +// import { Stage, Container, Sprite } from '@pixi/react'; + diff --git a/packages/docs/docs/components/Graphics.mdx b/packages/docs/docs/components/Graphics.mdx index 65560d91..535fe8b4 100644 --- a/packages/docs/docs/components/Graphics.mdx +++ b/packages/docs/docs/components/Graphics.mdx @@ -1,6 +1,6 @@ # Graphics -https://pixijs.download/dev/docs/PIXI.Graphics.html +https://pixijs.download/v7.x/docs/PIXI.Graphics.html ## Props @@ -12,6 +12,9 @@ https://pixijs.download/dev/docs/PIXI.Graphics.html ## Usage ```jsx live +// import React, { useCallback } from 'react'; +// import { Stage, Graphics } from '@pixi/react'; + function GraphicsExample() { const draw = useCallback((g) => { g.clear(); diff --git a/packages/docs/docs/components/NineSlicePlane.mdx b/packages/docs/docs/components/NineSlicePlane.mdx index aec55696..8ca8d71f 100644 --- a/packages/docs/docs/components/NineSlicePlane.mdx +++ b/packages/docs/docs/components/NineSlicePlane.mdx @@ -2,11 +2,13 @@ ## Props -https://pixijs.download/dev/docs/PIXI.NineSlicePlane.html +https://pixijs.download/v7.x/docs/PIXI.NineSlicePlane.html ## Usage ```jsx live +// import { Stage, NineSlicePlane } from '@pixi/react'; + Most of the time you won't notice any difference though (rendering 1000 sprites in a particle container is still fast). ## Props -https://pixijs.download/dev/docs/PIXI.ParticleContainer.html +https://pixijs.download/v7.x/docs/PIXI.ParticleContainer.html ### maxSize The maximum number of particles that can be rendered by the container. Affects size of allocated buffers. This will only affect the component once and will be applied during creation. -### [properties](https://pixijs.download/dev/docs/PIXI.ParticleContainer.html#ParticleContainer) +### [properties](https://pixijs.download/v7.x/docs/PIXI.ParticleContainer.html#ParticleContainer) The properties of children that should be uploaded to the gpu and applied. @@ -36,7 +36,9 @@ If true, container allocates more batches in case there are more than `maxSize` ## Usage -```jsx live +``` +// import { ParticleContainer, Sprite, Stage } from '@pixi/react' + diff --git a/packages/docs/docs/components/SimpleMesh.mdx b/packages/docs/docs/components/SimpleMesh.mdx index 7a41b9c4..f859a1b1 100644 --- a/packages/docs/docs/components/SimpleMesh.mdx +++ b/packages/docs/docs/components/SimpleMesh.mdx @@ -2,11 +2,16 @@ ## Props -https://pixijs.download/dev/docs/PIXI.SimpleMesh.html +https://pixijs.download/v7.x/docs/PIXI.SimpleMesh.html ## Usage ```jsx live noInline +// import React from 'react'; +// import { render } from 'react-dom'; +// import { Stage, SimpleMesh } from '@pixi/react'; +// import { DRAW_MODES } from 'pixi.js'; + const { uvs, vertices, indices } = makeSimpleMeshData(); render( @@ -16,7 +21,7 @@ render( uvs={uvs} vertices={vertices} indices={indices} - drawMode={PIXI.DRAW_MODES.TRIANGLES} + drawMode={DRAW_MODES.TRIANGLES} /> , ); diff --git a/packages/docs/docs/components/SimpleRope.mdx b/packages/docs/docs/components/SimpleRope.mdx index e3bb8687..53c67067 100644 --- a/packages/docs/docs/components/SimpleRope.mdx +++ b/packages/docs/docs/components/SimpleRope.mdx @@ -2,19 +2,22 @@ ## Props -https://pixijs.download/dev/docs/PIXI.SimpleRope.html +https://pixijs.download/v7.x/docs/PIXI.SimpleRope.html ## Usage ```jsx live +// import { Stage, SimpleRope } from '@pixi/react' +// import { Point } from 'pixi.js' + diff --git a/packages/docs/docs/components/Sprite.mdx b/packages/docs/docs/components/Sprite.mdx index 25420f7e..fbaf964b 100644 --- a/packages/docs/docs/components/Sprite.mdx +++ b/packages/docs/docs/components/Sprite.mdx @@ -2,11 +2,13 @@ ## Props -https://pixijs.download/dev/docs/PIXI.Sprite.html +https://pixijs.download/v7.x/docs/PIXI.Sprite.html ## Usage ```jsx live +// import { Stage, Sprite } from '@pixi/react' + `, ``, `` and many more), but in some use cases you'd like to add new "reconciler primitive" components. +ReactPixi already covers a large set of PixiJS components (like ``, ``, `` and many more), but in some use cases you'd like to add new "reconciler primitive" components. To tap into the React reconciliation you can create custom components with `PixiComponent`. @@ -37,8 +37,8 @@ export default PixiComponent('ComponentName', { ## Props helper -ReactPixi comes with a handy utility method `applyDefaultProps` that can help you applying props directly to a PIXI -primitive instance handling events, PIXI props and point-like values. +ReactPixi comes with a handy utility method `applyDefaultProps` that can help you applying props directly to a PixiJS +primitive instance handling events, PixiJS props and point-like values. Here's an example to pass through every other DisplayObject props and handle prop `count` separately: @@ -70,8 +70,10 @@ In most cases you can use simple React compositions. A rule of thumb is to use c Example, don't do: ```jsx +import { Sprite } from 'pixi.js'; + PixiComponent('Rectangle', { - create: () => new PIXI.Sprite(), + create: () => new Sprite(), applyProps: () => {...} }); ``` diff --git a/packages/docs/docs/fallback-to-canvas.mdx b/packages/docs/docs/fallback-to-canvas.mdx index f5d9a050..32b4c0b3 100644 --- a/packages/docs/docs/fallback-to-canvas.mdx +++ b/packages/docs/docs/fallback-to-canvas.mdx @@ -42,7 +42,7 @@ replace these with different legacy builds. ## Verify -Check the PIXI welcome message in your console to make sure your application is actually running in Canvas, you should see +Check the PixiJS welcome message in your console to make sure your application is actually running in Canvas, you should see something like: ( Click anywhere to animate ```jsx live noInline +// import React, { useState } from 'react'; +// import { render } from 'react-dom'; +// import { Spring } from 'react-spring'; +// import { Texture } from 'pixi.js'; +// import * as ReactPixiAnimated from '@pixi/react-animated'; + const config = { - size: { width: 926, height: 500 }, + size: { width: 800, height: 500 }, spring: { mass: 10, tension: 1000, friction: 100 }, - stage: { antialias: true, backgroundColor: 0xff0ff0 }, + stage: { antialias: true, backgroundColor: 0x1099bb }, }; const set = () => ({ @@ -41,7 +47,7 @@ const Box = (props) => ( {(props) => ( ); ## Animating `tint` values -