Neutrinoparticles.pixi NPM

neutrinoparticles.pixi

The package allows you to render NeutrinoParticles effects in PIXI graphical framework.

PIXI versions

This package (5.x.x) works for PIXI v7

Version 4.x.x of this package is obsolete, as effects loading interface is changed and it is no longer supported.

For other versions:

Versions 2.x.x of this package are for PIXI v5 and PIXI v6. go to branch
Versions 1.x.x of this package are for PIXI v4. go to branch

API documentation

For more info about latest API you can check API documentation pages.

For specific library version refer to Releases page.

Installation

You can install the package with npm:

> npm install neutrinoparticles.pixi

Or download pre-built package at Releases page. There are UMD packages which you can use in any environment.

Quick usage

ES6 + Static effects import

In the NeutrinoParticles Editor in the project settings you have to specify ES6 export: ES6 export in the project settings

And if you exported effect with name test_effect:

import * as PIXI from 'pixi.js'
import * as PIXINeutrino from 'neutrinoparticles.pixi'

// Import simulation model. This effect has to be exported as (!) ES6 file.
import { NeutrinoEffect as TestEffect } from './export_js/test_effect.js'

// Register library plugins before creating PIXI.Application
PIXINeutrino.registerPlugins(PIXI.extensions);

// Create PIXI.Application
const app = new PIXI.Application({
  width: 800,
  height: 600,
  neutrino: {
    texturesBasePath: 'textures/' // Prefix for loading textures. Slash in the end!
  }
});

document.body.appendChild(app.view);

// Generate turbulence if necessary. Otherwise it won't work.
// app.neutrino.generateNoise();

// Create an effect model. One model can be used to instantiate many effects on the scene.
const effectModel = new PIXINeutrino.EffectModel(

  // PIXINeutrino.Context. Added to the PIXI.Application by the plugin.
  app.neutrino, 

  // Creating simulation model from exported effect file.
  new TestEffect(app.neutrino.neutrino), 

  // Adapter for textures loader. This is default one that uses PIXI.Assets.loader.
  // Textures loading will be started right away inside EffectModel constructor.
  PIXINeutrino.defaultAssetsTexturesLoader 
);

// Once all textures are loaded and the effect model is ready to use
effectModel.once('ready', () => {

  // Create instance of the effect and add it to the scene.
  const effect = new PIXINeutrino.Effect(effectModel, {
    position: [400, 300, 0], // Optional. There are also rotation, scale, paused etc.
  });
  app.stage.addChild(effect);

  // Call update for the effect on every frame.
  app.ticker.add((delta) => {
    const msec = delta / PIXI.settings.TARGET_FPMS;
    const sec = msec / 1000.0;

    effect.update(sec > 1.0 ? 1.0 : sec);
  });
});

HTML + Dynamic effects loading

Please note that in case of dynamic effects loading eval() is used!

In the NeutrinoParticles Editor in the project settings you have to specify For XHR Request export:

ES6 export in the project settings

And if you exported effect with name test_effect:

...
<body>
<script src="/path/to/pixi.js/dist/pixi.js"></script>

<!-- Load both neutrinoparticles libraries -->
<script src="/path/to/neutrinoparticles.js/dist/neutrinoparticles.umd.js"></script>
<script src="/path/to/neutrinoparticles.pixi.umd.js"></script>

<script>

// Register library plugins before creating PIXI.Application
PIXINeutrino.registerPlugins(PIXI.extensions);

// Create PIXI.Application
const app = new PIXI.Application({
  width: 800,
  height: 600,
  neutrino: {
    texturesBasePath: 'textures/' // Prefix for loading textures. Slash in the end!
  }
});

document.body.appendChild(app.view);

// Generate turbulence if necessary. Otherwise it won't work.
// app.neutrino.generateNoise();

// Create bundle for loading resources
PIXI.Assets.addBundle('resources', [
  { 
    name: 'testEffect', // Resource name for further access
    srcs: 'export_js/test_effect.js', // Path to an effect exported (!) for XHR Request
    data: app.neutrino.loadData // Mandatory. Indicates NeutrinoParticles effect.
  }
]);

PIXI.Assets.loadBundle('resources').then((resources) => {
	// Create instance of the effect and add it to the scene.
  const effect = new PIXINeutrino.Effect(resources.testEffect, {
    position: [400, 300, 0], // Optional. There are also rotation, scale, paused etc.
  });
  app.stage.addChild(effect);

  // Call update for the effect on every frame.
  app.ticker.add((delta) => {
    const msec = delta / PIXI.settings.TARGET_FPMS;
    const sec = msec / 1000.0;

    effect.update(sec > 1.0 ? 1.0 : sec);
  });
});

</script>
</body>

Tutorials

Samples

There are several samples in folder /samples which you can refer to.

Running samples

To run the samples you will need web server running on localhost:80 with a web root on the root repository folder. If you have Python3 installed you can use /start_http_server.sh script to start it.

After server is running you can access the samples by http://localhost/samples/<sample_name>.html

For different web server configuration, please adjust the path above accordingly.

Debug Samples with VSCode

You can use following launch configuration to start debuging of samples:

{
    "name": "Samples in Chrome",
    "type": "chrome",
    "runtimeExecutable": "/path/to/chrome",
    "runtimeArgs": [
        "--incognito",
        "--new-window",
        "--remote-debugging-port=9222",
        "--user-data-dir=remote-profile"
    ],
    "request": "launch",
    "url": "http://localhost/samples/simplest.html",
    "webRoot": "${workspaceFolder}",
    "breakOnLoad": true,
    "sourceMaps": true,
    "port": 9222,
}

To be able to set breakpoint in .html files you will need to enable Allow Breakpoints Everywhere flag in VSCode Settings.

Tests

Running tests

To run tests you can use npm run test command as usual. It will start IBCT (image based comparison tests) in WebGL and Canvas modes. You will need to provide GPU environment to run the tests. It can be hardware video card or software renderer.

Debug with VSCode

You can use following launch configuration to start debugging of main thread of electron-mocha application which perform the tests:

{
	"name": "Debug Tests",
	"type": "node",
	"request": "launch",
	"cwd": "${workspaceRoot}",
	"runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-mocha",
	"windows": {
	  "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-mocha.cmd"
	},
	"program": "${workspaceRoot}/test/test.js",
	"args": [
		"--require", "@babel/register",
		"--timeout", "999999",
		"--colors",
		"--ibct-expect-dir", "__my_expect__",
		"test/test.js"
	],
	"console": "integratedTerminal",
	"protocol": "inspector",
}

To be able to set breakpoint in .html files you will need to enable Allow Breakpoints Everywhere flag in VSCode Settings.

Please note, that ibct-expect-dir argument overrides default expectation files directory __expect__ for IBCT. The directory is placed in /test/ibct. Such behaviour is useful when running tests locally, because different hardware gives different results and default expectations will most probably fail for you.