proton 1.0.8

A lightweight and powerful flutter particle framework based on Proton.

Proton

A lightweight and flexible particle system for Flutter, inspired by the Proton library for JavaScript.

Features

• Flexible Architecture: Based on Emitters, Particles, Initializers, and Behaviours.
• Rich Behaviours: Includes Alpha, Color, Scale, Rotate, Gravity, Attraction, Collision, Repulsion, CrossZone, etc.
• Various Initializers: Customize Mass, Radius, Life, Velocity, Position, Body, etc.
• Multiple Emitters: Support for multiple emitters in a single system.
• Customizable Rendering: Built-in support for Zerker rendering, but extensible for other rendering engines.
• Zone Support: Define zones like Point, Line, Circle, Rect, Image for emission or interaction.

Installation

Add proton to your pubspec.yaml dependencies:

dependencies:
  proton: ^0.5.1
  zerker: ^2.2.6 # Required for default rendering

Then install packages from the command line:

flutter packages get

Usage

Proton works by creating a Proton system, adding Emitters to it, and then updating the system in an animation loop.

The following example shows how to use Proton with Zerker for rendering.

1. Import Packages

import 'package:flutter/material.dart';
import 'package:proton/proton.dart';
import 'package:zerker/zerker.dart';

2. Create a Particle System

class MyGame extends StatefulWidget {
  @override
  _MyGameState createState() => _MyGameState();
}

class _MyGameState extends State<MyGame> {
  @override
  Widget build(BuildContext context) {
    return Zerker(
      app: ZKApp(),
      onReady: (app) {
        // 1. Create the Proton instance
        Proton proton = Proton();

        // 2. Create an Emitter
        Emitter emitter = Emitter();
        
        // Set Emission Rate: 1-2 particles every 0.01-0.02 seconds
        emitter.rate = Rate(Proton.getSpan(1, 2), Proton.getSpan(0.01, 0.02));
        
        // 3. Add Initializers (Set initial properties)
        emitter.addInitialize(Mass(1));
        emitter.addInitialize(Radius(10));
        emitter.addInitialize(Life(2, 4));
        emitter.addInitialize(Velocity(3, Proton.getSpan(0, 360), 'polar'));
        
        // 4. Add Behaviours (Define how particles act over time)
        emitter.addBehaviour(Color('random')); // Random color
        emitter.addBehaviour(Alpha(1, 0));     // Fade out
        emitter.addBehaviour(Scale(1, 0.1));   // Shrink
        emitter.addBehaviour(Rotate());        // Rotate
        
        // 5. Add Emitter to Proton
        proton.addEmitter(emitter);
        
        // 6. Add Renderer (Bind Proton to Zerker App)
        proton.addRenderer(ZerkerRenderer(app));
        
        // Start emitting
        emitter.emit();

        // 7. Update Loop
        app.onUpdate = (dt) {
          proton.update();
        };
      },
    );
  }
}

Core Concepts

• Proton: The main system that manages the particle pool, emitters, and renderers.
• Emitter: Responsible for creating and managing particles.
• Particle: The visual element that moves and changes.
• Initializer: Sets the initial state of a particle (e.g., start position, velocity, color).
• Behaviour: Modifies the state of a particle over time (e.g., gravity, fading, scaling).
• Renderer: Draws the particles on the screen. ZerkerRenderer is provided out-of-the-box.

License

This project is licensed under the MIT License - see the LICENSE file for details.