Stardust-engine

author:
matyasf
Description:
Particle System with Editor. Compatible with Starling 1.x and 2.0
Tag:
particles, particle system
compatible:
1.5.x, 1.6.x, 1.7.x, 1.8.x, v2.0
Effect Editor:
https://s3-eu-west-1.amazonaws.com/s3.funkypandagame.com/startdust-particle-editor/stardust-editor.html
Library Github:
https://github.com/matyasf/stardust-library-plumbee
Loader Github:
https://github.com/matyasf/stardust-sim-loader
Examples:
https://github.com/matyasf/stardust-examples

Overview

Stardust is a particle engine originally developed for AS3. We have extended its functionality and made an effect editor for it.

Features:

  • Effect editor with live preview.
  • Loader/playback library, that makes simulation integration easy.
  • Super fast Starling renderer: 1300+ particles on an iPhone 4S/iPad 2 @60FPS, 15000+ particles @60FPS on a good PC.
  • 15+ different forces/actions that can affect the particles during their lifetime.
  • Particle images can be an animation(sprite sheet).
  • Emitters are batched: A single simulation will take 1 draw call (provided you don't cause a state change - see below)
  • Simulations can be started from a saved state.
  • Blend modes, bursting emitters, multiple emitters, arbitrary emitter area, moving emitters, spawning particles on conditions…
  • Very easy to extend: Just extend a class to define new behaviors for particles.
  • Particles can be modified via code dynamically when the simulation is running.
  • Open source and free (Apache license).

Starling integration should be quite future proof since it uses one class to interact with Starling (the renderer)

Examples

The editor has some example simulations built in, just press the “Examples” button on the top right to load one.

Code examples

(click the image to see it in action)

Source for this simulation is at is at https://github.com/matyasf/stardust-examples .

A mobile example is at https://github.com/matyasf/stardust-examples/tree/master/mobileApp

Starling 2.x

This project is Starling 2 compatible! The only thing you need to do is to use the library .swc from the Starling 2 branch in Github. The files made with the editor are compatible both with Starling 1.x and 2, the loader .swc is compatible with both Starling versions.

How to use

  1. Include the Stardust library from https://github.com/matyasf/stardust-library-plumbee/tree/own-develop/build in your project
  2. Include the loader library from https://github.com/matyasf/stardust-sim-loader/tree/own_develop/build in your project
  3. (include Starling obviously)
  4. Load and play the simulation, for example:
[Embed(source = "exampleSim.sde", mimeType = 'application/octet-stream')]
private static var Asset:Class;
 
private const loader : SimLoader = new SimLoader();
private const player : SimPlayer = new SimPlayer();
 
public function loadSim()
{
    loader.addEventListener(Event.COMPLETE, onSimLoaded);
    var assetInstance:ByteArray = new Asset();
    loader.loadSim(assetInstance);
}
 
private function onSimLoaded(event : flash.events.Event) : void
{
    var project : ProjectValueObject = loader.createProjectInstance();
    const simCanvas: Sprite = new Sprite(); // Staring Sprite
    addChild(simCanvas);
    player.setProject(project);
    player.setRenderTarget(simCanvas);
    addEventListener(EnterFrameEvent.ENTER_FRAME, onEnterFrame);
}
 
private function onEnterFrame(event : EnterFrameEvent) : void
{
    player.stepSimulation(event.passedTime);
}

Note: I recommend that you use the editor in Firefox, sadly the Chrome and IE flash plugins are completely broken. I cant believe that I have to recommend a browser in 2015 :( .

Note2: The editor packs all textures in the same simulation into a single texture atlas. The size of this atlas can not exceed 2048×2048 pixels, if you try to include bigger images you will not be able to render the simulation.

Of course you can use just the Stardust library and make effects manually.

Performance tips

  • The two main bottlenecks are rendering and calculating the simulation.
  • Rendering is done in the StardustStarlingRenderer class. This class takes the data of all particles (position, rotation, texture to display,..) and uploads it to the GPU on every frame for rendering. Thus the more particles the more data to upload, and more load on the CPU.
  • The simulation is calculated in Actions. These run on every particle on every frame to determine what happens to them. Obviously more actions or more particles put more load on the CPU.
  • Initializers don’t add any significant extra load, since they just set a value on particle creation.
  • If your particles are huge they can use up all the fill rate of your GPU (especially on mobile devices), so don't try to render hundreds of particles which have 100s of pixels width and height.
  • Call StardustStarlingRenderer.init(numberOfBuffers : uint, maxParticlesPerBuffer : uint) before loading any simulation (but only after creating a Stage3D context). This call lets you fine tune your app for the best memory usage and performance. The first parameter should be the maximum number of draw calls used by simulations +1 you want to run at the same time. The second parameter is how much particles will an emitter render maximum. (The maximum number that can be rendered is 16383, this is a Stage3D limitation.) if your emitters use more draw calls than its specified in numberOfBuffers, then the GPU will stall resulting in reduced performance. On the other hand a single buffer with the maximum amount of particles (16383) takes up 2MB of GPU memory. So for example for a mobile app 10 buffers and 1000 particles per buffer is reasonable. This way you can display up to 10 emitters without the GPU stalling and the buffers use just around 1.2MB of GPU memory. The default values are 2 buffers with 16383 particles per buffer.

Batching

The editor makes a texture atlas from the images you use at a single simulation, allowing to render a simulation in one draw call. However this is only possible if all emitters have the same premultiply alpha, blend mode, smoothing settings. You can check the number of draw calls in the stats window on the top left.

Also simulation instances created from the same .sde file are batched if they share the same displayObject parent and are siblings (they have the same RenderTarget set in the player and this object has no other children)

Batching of multiple different simulations

Note: I recommend that first just try your app without batching multiple simulations. This extra effort will only lead to minor improvements unless you are rendering lots of simulations (5+).

Batching multiple simulations is only possible manually, since each simulation loads its own textures. But its quite straightforward to do it manually: First make sure that all simulations have the same premultiply alpha, blend mode, smoothing settings. Plus they must have the same rendertarget and the render target should not contain other children. If these are met, load the simulation as in the “how to use” example. Then you need to manually set the emitter images from the same atlas:

// myProjects is an array of ProjectValueObjects.
// They are created by SimLoaders by calling SimLoader.createProjectInstance()
// (they can be loaded with different loaders)
for each (var project : ProjectValueObject in myProjects)
{
    for each (var emitterVO : EmitterValueObject in project.emitters)
    {
        var particleHandler : StarlingHandler = StarlingHandler(emitterVO.emitter.particleHandler);
        // the getTexturesForEmitter() function should return the subTextures for this emitter. You will get
        // SubTextures if you getTextures() on a TextureAtlas instance.
        // You can keep track of emitters based on their ID, it does not change if you save a simulation.
        var textures : Vector.<SubTexture> = getTexturesForEmitter(emitterVO.id);
        particleHandler.setTextures(textures);
        // set all of them to render on the same object
        particleHandler.container = myRenderTarget;
    }
}
// finally add any of the simulations to a player - the renderer will find the sibling simulations
// automatically and batch them:
myPlayer = new SimPlayer();
myPlayer.setProject(project);
myPlayer.setRenderTarget(myRenderTarget); // set the same render target again.
 
// finally call step() on every step of your game to run the simulations as in the first example:
...
myPlayer.stepSimulation();

Desktop app

You can download a thin wrapper for the editor from GitHub. This is a small desktop app that loads the editors from the web and adds some desktop functions like associating the editor with .sde files and caching it for offline use.

Technical stuff

The project consists of 3 libraries:

Stardust library: An extended version of the original library with added functionality and Starling support. Stardust has a very flexible structure that makes it easy to extend and its possible to alter the simulation while its running via code. A simulation has the following components:

Emitters: The main part of the simulation. This class is responsible for stepping the simulation, creating and destroying particles, calling the initializers and actions.

Initializers: Classes that are executed if a particle is created, they set initial properties of particles. For example position, speed, alpha, mass…

Actions: Classes that are executed on every step on every living particle. For example changing speed, destroying particles on conditions, bouncing back from objects,…

The simulation is rendered with a custom Starling renderer, it is a heavily optimized Starling DisplayObject with its custom render method. It is loosely based on FFParticleSystem’s renderer.

Stardust-sim-loader: A library that loads the .sde files made with the and parses them. Furthermore it contians a player class to play back the parsed simulations.

Stardust-editor: An editor made with Flex that can be used to make simulations. It uses the sim-loader library under the hood to load and play back simulations. You can see most changes dynamically while you are changing them. Plus it can display the zones of different intializers/actions, and show performance metrics of your simulation.

.sde files: These files are .zip files created by the editor that contain the simulation descriptor xml(s), the particle images and saved simulation states (if any). Since these are human readable you can make modifications easily by hand (but the editor might not be able to cope with your changes).

Thanks

FunkyPanda where I had the opportunity to work on this project.

Plumbee where I could work on this project.

Allen Chou For the original Stardust code

FFParticleSystem and Starling contributors for the code.

User Comments

For bug reports and feature requests please use the Github page of the appropriate library.

For discussion or other stuff use the forum here http://forum.starling-framework.org/topic/release-stardust-particle-engine-extension-and-gui-for-making-particle-effects

  extensions/stardust-engine.txt · Last modified: 2016/09/20 21:13 by 86.101.85.21
 
Powered by DokuWiki