pixijs / floss

Unit-testing for those hard to reach places

PixiJS — The HTML5 Creation Engine

This project aims to provide a fast, lightweight 2D library that works across all devices. The PixiJS renderer allows everyone to enjoy the power of hardware acceleration without prior knowledge of WebGL. Also, it's fast. Really fast.

If you want to keep up to date with the latest PixiJS news then feel free to follow us on Twitter @PixiJS and we will keep you posted! You can also check back on our site as any breakthroughs will be posted up there too!

We are now a part of the Open Collective and with your support you can help us make PixiJS even better. To make a donation, simply click the button below and we'll love you forever!

What to Use PixiJS for and When to Use It

PixiJS is a rendering library that will allow you to create rich, interactive graphics and cross-platform applications and games without having to dive into the WebGL API or deal with browser and device compatibility.

PixiJS supports WebGPU with fallback support for WebGL. As a library, PixiJS is a fantastic tool for authoring interactive content. Use it for your graphics-rich, interactive websites, applications, and HTML5 games. Out-of-the-box, cross-platform compatibility and graceful degradation mean you have less work to do and more fun doing it! If you want to create polished and refined experiences relatively quickly without delving into dense, low-level code, all while avoiding the headaches of browser inconsistencies, then sprinkle your next project with some PixiJS magic!

Boost your development and feel free to use your imagination!

Current features

• WebGL renderer (with automatic smart batching, allowing for REALLY fast performance)
• WebGPU renderer (new to the latest browsers!)
• Canvas renderer (Fastest in town!)
• Full scene graph
• Super easy to use API (similar to the flash display list API)
• Support for texture atlases
• Asset loader / sprite sheet loader
• Auto-detect which renderer should be used
• Full Mouse and Multi-touch Interaction
• Text
• BitmapFont text
• Multiline Text
• Render Texture
• Primitive Drawing
• Masking
• Filters
• Community-Supported Plugins
  • React
  • Spine
  • Filters
  • Animate
  • Lights
  • UI
  • Layout
  • GIF
  • And more!

Setup

It's easy to get started with PixiJS! Simply download a prebuilt build!

Alternatively, PixiJS can be installed with npm or simply using a content delivery network (CDN) URL to embed PixiJS directly on your HTML page.

NPM Install

npm install pixi.js

There is no default export. The correct way to import PixiJS is:

import * as PIXI from 'pixi.js';

CDN Install

Via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pixi.min.js"></script>

Or via unpkg:

<script src="https://unpkg.com/[email protected]/dist/pixi.min.js"></script>

Basic Usage Example

import { Application, Sprite, Assets } from 'pixi.js';

// The application will create a renderer using WebGL, if possible,
// with a fallback to a canvas render. It will also setup the ticker
// and the root stage PIXI.Container
const app = new Application();

// Wait for the Renderer to be available
await app.init();

// The application will create a canvas element for you that you
// can then insert into the DOM
document.body.appendChild(app.canvas);

// load the texture we need
const texture = await Assets.load('bunny.png');

// This creates a texture from a 'bunny.png' image
const bunny = new Sprite(texture);

// Setup the position of the bunny
bunny.x = app.renderer.width / 2;
bunny.y = app.renderer.height / 2;

// Rotate around the center
bunny.anchor.x = 0.5;
bunny.anchor.y = 0.5;

// Add the bunny to the scene we are building
app.stage.addChild(bunny);

// Listen for frame updates
app.ticker.add(() => {
    // each frame we spin the bunny around a bit
    bunny.rotation += 0.01;
});

Learn

• Website: Find out more about PixiJS on the official website.
• Getting Started:
  • Check out the getting started guide.
  • Also, check out @miltoncandelero's PixiJS tutorials aimed toward videogames with recipes and best practices here
• Examples: Get stuck right in and play around with PixiJS code and features right here!
• API Documentation: Get to know the PixiJS API by checking out the docs.
• Guide: Supplementary usage guides to the API Documentation here.

Demos

• Filters Demo
• Bunny Demo
• Masking Demo
• Interaction Demo
• More examples

Community

• Forums: Check out the discussions and Stackoverflow -- both friendly places to ask your PixiJS questions.
• Chat: You can join us on Discord to chat about PixiJS.

How to build

Note that for most users you don't need to build this project. If all you want is to use PixiJS, then just download one of our prebuilt releases. The only time you should need to build PixiJS is if you are developing it.

If you don't already have Node.js and NPM, go install them. Then, in the folder where you have cloned the repository, install the build dependencies using npm:

npm install

Then, to build the source, run:

npm run build

How to generate the documentation

The docs can be generated using npm:

npm run docs

Contribute

Want to be part of the PixiJS project? Great! All are welcome! We will get there quicker together :) Whether you find a bug, have a great feature request, or you fancy owning a task from the road map above, feel free to get in touch.

Make sure to read the Contributing Guide before submitting changes.

License

This content is released under the (http://opensource.org/licenses/MIT) MIT License.

floss's Issues

mocha args

Hello! Can we somehow pass args (like --exit or --timeout) to Mocha?

electron 14 removes remote module

Electron 14 has breaking changes for floss. Electron docs here https://github.com/electron/electron/blob/v13.1.4/docs/api/remote.md

Electron 14 is also the first version that allows you to enable webgpu by doing:

const {app, BrowserWindow} = require('electron')
app.commandLine.appendSwitch('enable-unsafe-webgpu')

(being able to test webgpu is really the only reason why it matters to me)

As you may guess, I'd like to have webgpu enabled in floss if possible too! I'm willing to fix and send a pr for both , but would like some guidance on what'd be acceptable to you. Just a fyi, browsing random sites with enable-unsafe-webgpu is supposedly unsafe because cross origin can read gpu data, i seriously dont think that matters though, especially for local testing.

The easiest thing to get floss working with v14 would be to just change the remote import to "@electron/remote" , so like a 1 line change.

enabling webgpu is also just 1 line, but the decision may or may not require some discussion with others.

Question: Are there examples/docs on how to test Pixi.js using floss?

I'm pretty new to Pixi.js and was told that floss is the officially recommended way to test a Pixi.js app. Would love a couple of quick pointers/examples to get started.

"require is not defined" in Electron >12.0.0

See Electron's breaking changes list. This causes the script in index.html to break.

Simply adding contextIsolation: false to the options object used to create an Electron window solved the issue for me, but I haven't looked at the security implications of that.

Typescript example

This project is written in typescript, yet there is no example as to how to run floss (using NPM or otherwise) with ts-node as a require as with regular mocha mocha -r ts-node/register /path/to/code/**.*.ts.

Supporting native ESM

Mocha as partial native support since 7.1.0, and seems to be full support since 8.0.0. Any chance of bumping mocha?

display issue on window

Hi !
Thank for this awesome repository ! =)

I have a display issue on window.

The reporter out this :

←[0m←[0m
←[0m  _forEachDeep :: tag:String => Object => Function => undefined←[0m
  ←[32m  ÔêÜ←[0m←[90m should call func in all children←[0m

←[0m  _mapDeep :: tag:String => Object => Function => Object←[0m
  ←[32m  ÔêÜ←[0m←[90m should call func in all children←[0m
  ←[32m  ÔêÜ←[0m←[90m should return an object with the same structure←[0m
  ←[32m  ÔêÜ←[0m←[90m should return an object with children name equal ok←[0m

←[0m  .createFrom :: Object => Container←[0m
  ←[32m  ÔêÜ←[0m←[90m should expose createFrom←[0m
  ←[31m  1) should return a Container←[0m


←[92m ←[0m←[32m 5 passing←[0m←[90m (59ms)←[0m
←[31m  1 failing←[0m

←[0m  1) .createFrom :: Object => Container should return a Container:
←[0m←[31m     TypeError: Cannot read property 'should' of undefined←[0m←[90m
      at Context.it (C:\Users\florian\Main\modules\pixi-createfrom\test\index.js:90:14)
      at callFn (C:\Users\florian\Main\modules\pixi-createfrom\node_modules\floss\node_modules\mocha\lib\runnable.js:326:21)

Do you know where this issue come from ?

Effort to port to Jest?

Hello, you might remember me from such issues as pixijs/pixijs#7554

Just wanted to get a hot take about the effort it might require to port this to Jest testing / make this work to run Jest tests as well?

Thank you!

Typescript example

Regarding use of typescript with floss (mentioned in #29), I find the example in the wiki to be a bit confusing:

https://github.com/pixijs/floss/wiki/Running-TypeScript-with-Floss

If I am used to run mocha tests with ts-loader, and I have all my .ts tests defined in the "<project_dir>/test" folder, I can run mocha like this:

mocha -r ts-node/register "test/**/*.ts"

What would be the equivalent for floss?

What is the difference between the way FLOSS tests and using JEST alone?

I used Jest alone to test pixi.js project and encountered various problems and reported errors. When I saw pixi.js tested by electron, I thought this way was very special, but I still didn't quite understand the test principle of FLOSS.

Running floss in Docker returns null

We have a test suite that we call like this: ./node_modules/floss/bin/floss.js --path test/index.js
Running it locally on our dev machines outside Docker works like expected, it runs the test suite and returns correct exit code.

However, running it inside Docker fails and returns null.
Here's the log:

0 info it worked if it ends with ok
1 verbose cli [ '/usr/local/bin/node', '/usr/local/bin/npm', 'run', 'test' ]
2 info using [email protected]
3 info using [email protected]
4 verbose run-script [ 'pretest', 'test', 'posttest' ]
5 info lifecycle [email protected]~pretest: [email protected]
6 info lifecycle [email protected]~test: [email protected]
7 verbose lifecycle [email protected]~test: unsafe-perm in lifecycle true
8 verbose lifecycle [email protected]~test: PATH: /usr/local/lib/node_modules/npm/node_modules/npm-lifecycle/node-gyp-bin:/frontend/node_modules/.bin:/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games
9 verbose lifecycle [email protected]~test: CWD: /frontend
10 silly lifecycle [email protected]~test: Args: [ '-c',
10 silly lifecycle   './node_modules/floss/bin/floss.js --path test/index.js' ]
11 silly lifecycle [email protected]~test: Returned: code: 1  signal: null
12 info lifecycle [email protected]~test: Failed to exec test script
13 verbose stack Error: [email protected] test: `./node_modules/floss/bin/floss.js --path test/index.js`
13 verbose stack Exit status 1
13 verbose stack     at EventEmitter.<anonymous> (/usr/local/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:304:16)
13 verbose stack     at EventEmitter.emit (events.js:182:13)
13 verbose stack     at ChildProcess.<anonymous> (/usr/local/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
13 verbose stack     at ChildProcess.emit (events.js:182:13)
13 verbose stack     at maybeClose (internal/child_process.js:961:16)
13 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:248:5)
14 verbose pkgid [email protected]
15 verbose cwd /frontend
16 verbose Linux 4.15.0-42-generic
17 verbose argv "/usr/local/bin/node" "/usr/local/bin/npm" "run" "test"
18 verbose node v10.4.1
19 verbose npm  v6.1.0
20 error code ELIFECYCLE
21 error errno 1
22 error [email protected] test: `./node_modules/floss/bin/floss.js --path test/index.js`
22 error Exit status 1
23 error Failed at the [email protected] test script.
23 error This is probably not a problem with npm. There is likely additional logging output above.
24 verbose exit [ 1, true ]

node_modules/floss/bin/floss.js exists on path in Docker and so does test/index.js.

Is there a special set-up for floss in Docker, or is that a bug in floss?

If you need more info to reproduce this issue, just let me know, I am floss and Docker newbie. :)

Uncaught Exception: TypeError: Cannot use 'in' operator to search for 'detach'

Steps:

• Be on Electron v2.0.0-beta.8
• floss -p test.js -d

Expect:

• Should see window appear with Developer Tools open on the bottom

Actual

• Get an error dialog

The bug:

floss/electron/index.js

Line 73 in a35ee03

mainWindow.webContents.openDevTools('bottom');

The fix:

mainWindow.webContents.openDevTools({ mode: 'bottom' });

The relevant WebContents docs

Maybe the openDevTools API changed slightly between Electron versions?

Will try to do a PR when I have more time to test a binary.