flutter_infinite_universe 1.0.1

A premium collection of futuristic, space-inspired, visually stunning loading animations for Flutter.

flutter_infinite_universe 🌌

A premium, production-grade, open-source library of futuristic, space-inspired, and visually stunning loading animations for Flutter. Designed to completely replace traditional loading spinners, flutter_infinite_universe delivers cinematic, physics-based simulations including stars twinkling, black holes consuming matter, galaxies orbiting, and quantum networks flowing.

Optimized to run at a consistent 60/120 FPS on both mobile and desktop platforms using isolated RepaintBoundary widgets, manual canvas drawing, and high-performance object pooling to prevent garbage collection hiccups.

---

Features 🚀

• 13 Physics-Based Loaders: Fluid flow fields, gravity voids, orbital revolution simulations, subatomic network grids, and cosmic synapses.
• Interactive Gestures: Tap, drag, double-tap, and long-press actions deform particles in real time via gravitational and repulsion forces.
• 10 Premium Themes: Built-in color palettes right out of the box (Deep Space, Milky Way, Cyber Galaxy, Quantum Void, Nebula Storm, Aurora Cosmos, Solar Flare, Dark Matter, Stellar Core, AI Singularity).
• Custom Shaders: Includes GPU-accelerated effects (Bloom, Glow, Chromatic aberration, and space warp) for supported platforms.
• Universe Studio: An interactive, desktop-class developer suite built into the example app. Preview, tweak, generate code, and export custom scene presets visually.
• Cross-Platform: Fully compatible with Android, iOS, Web, Windows, macOS, and Linux.

---

Supported Platforms 📱💻🌐

• iOS: iOS 12.0+ (Impeller & Metal supported)
• Android: API Level 21+ (Vulkan & OpenGL supported)
• Web: HTML5 Canvas & CanvasKit (WebAssembly)
• Windows: Windows 10+
• macOS: OS X 10.11+
• Linux: Ubuntu 18.04+ (GTK desktop wrapper)

---

Installation 📦

Add the package to your pubspec.yaml dependencies:

dependencies:
  flutter_infinite_universe: ^1.0.0

Or run:

flutter pub add flutter_infinite_universe

---

Quick Start 🌠

Exposing a signature flagship loader with a single line of code:

import 'package:flutter_infinite_universe/flutter_infinite_universe.dart';

// Minimalistic Signature Loader
const InfiniteUniverseLoader(
  width: 300,
  height: 300,
  themePreset: UniverseThemePreset.cyberGalaxy,
)

---

Core Loaders List 💫

The package provides 13 core loading animations:

Loader Widget	Description	Key Customization Variables
InfiniteUniverseLoader	Flagship Loader: Parallax starfield, meteors, constellations, gas clouds, and touch gravity.	starDensity, starSpeed, meteorFrequency, particleCount
GalaxyOrbitLoader	Concentric Keplerian planetary orbital loops revolving around a pulsing solar center.	orbitCount, orbitSpeed, showOrbitPaths
BlackHoleLoader	Gravity void with a dark event horizon, glowing accretion disk, and speed-warping particles.	gravityStrength, eventHorizonRadius, particleCount
SupernovaLoader	Dynamic looping cycle: particles converge to center, core charges up, and bursts in a shockwave.	cycleDuration, glowIntensity, particleCount
ConstellationLoader	Floating procedural stars drawing connection lines when in range, building a moving crystal mesh.	nodeCount, maxDistance, movementSpeed
CosmicDustLoader	Organic flow-field fluid simulations where gas particles drift along trigonometric wind waves.	flowSpeed, flowFrequency, particleSize
QuantumSpaceLoader	Subatomic network nodes showing attraction, repulsion, Brownian jitter, and energy pulses.	nodeCount, speedMultiplier, enablePulses
NeuralGalaxyLoader	Glowing synapse nodes transmitting electric impulses and electrical currents.	nodeCount, glowIntensity, impulseFrequency
WormholeLoader	Three-dimensional tunnel progression with speed-warped stars flowing out of a core.	tunnelRadius, velocity, starCount
AsteroidFieldLoader	Procedural asteroid shapes rotating in a parallax debris field with physical collisions.	asteroidCount, driftSpeed, collisionResponse
DarkMatterLoader	Gravitational lensing effect distorting background stars as dark matter fields drift.	fieldIntensity, lensingStrength, particleCount
TimeWarpLoader	Chronographic time dilation visual lines showing speed-warps and dilation effects.	timeDilation, distortionIntensity, warpLinesCount
MultiverseLoader	Overlapping dimensional bubble spheres with cross-gravitational influence.	universeCount, overlapIntensity, bubbleSpeed

---

Usage Examples 💡

Basic Usage

Use the default theme parameters or select a predefined theme preset:

import 'package:flutter/material.dart';
import 'package:flutter_infinite_universe/flutter_infinite_universe.dart';

class SimpleLoadingScreen extends StatelessWidget {
  const SimpleLoadingScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      backgroundColor: Color(0xFF02020A),
      body: Center(
        child: BlackHoleLoader(
          themePreset: UniverseThemePreset.quantumVoid,
          width: 250,
          height: 250,
        ),
      ),
    );
  }
}

Advanced Usage with Custom Theme & Parameters

Override individual color parameters, particle limits, and speed vectors:

import 'package:flutter/material.dart';
import 'package:flutter_infinite_universe/flutter_infinite_universe.dart';

class CustomLoaderScreen extends StatelessWidget {
  const CustomLoaderScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final customTheme = UniverseTheme.fromPreset(UniverseThemePreset.deepSpace).copyWith(
      glowColor: const Color(0xFFFF5E3A), // Hot orange glow
      particleColor: const Color(0xFFFFFFFF), // White core stars
      nebulaColor: const Color(0xFF2C0A5E), // Purple gas cloud background
    );

    return Scaffold(
      body: Center(
        child: NeuralGalaxyLoader(
          theme: customTheme,
          nodeCount: 80,
          glowIntensity: 2.0,
          enableShaders: true,
          width: 350,
          height: 350,
        ),
      ),
    );
  }
}

Fullscreen Viewer Integration

Wrap any loader in the InteractiveUniverseWrapper to handle gestural interactions:

import 'package:flutter/material.dart';
import 'package:flutter_infinite_universe/flutter_infinite_universe.dart';

class FullscreenLoaderPage extends StatelessWidget {
  const FullscreenLoaderPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: Colors.black,
      body: InteractiveUniverseWrapper(
        child: SizedBox.expand(
          child: InfiniteUniverseLoader(
            width: double.infinity,
            height: double.infinity,
            themePreset: UniverseThemePreset.nebulaStorm,
            starDensity: 2.5,
            starSpeed: 1.8,
            enableInteraction: true,
          ),
        ),
      ),
    );
  }
}

---

Universe Studio: Visual Theme Designer 🛠️

Inside the package example application lies the Universe Studio—a comprehensive developer playground.

• Live Customization: Tweak physical constants (gravity strength, wind speed, drift frequency) using sidebar sliders.
• Scene Builder: Layer multiple loaders (e.g. place a SupernovaLoader on top of a CosmicDustLoader) to build composite animations.
• Flutter Code Generator: Copy and paste pre-configured code structures matching your visually customized animation.
• Performance Panel: Track paint durations, frame rate stability, and active particle pooling efficiency in real time.

To run Universe Studio locally:

git clone https://github.com/yourusername/flutter_infinite_universe.git
cd flutter_infinite_universe/example
flutter run -d chrome --release

---

Performance Recommendations ⚡

Because these animations render dozens of particles dynamically, follow these guidelines to keep your applications running smoothly:

1. Use Const Constructors: Ensure all loading widgets use the const keyword when applicable.
2. Limit Particle Counts on Lower-End Devices: Check device specifications and limit particle counts (e.g. asteroidCount, nodeCount) or toggle isPerformanceMode: true on older platforms.
3. Isolate with RepaintBoundary: If you place loaders inside dynamic parent layouts, wrap them in a RepaintBoundary to prevent redundant rebuild signals. The loaders automatically include internal RepaintBoundaries.
4. Disable Custom Shaders on Web (HTML Renderer): For Flutter Web, use CanvasKit instead of the HTML renderer when enabling fragment shaders.

---

Frequently Asked Questions ❓

Q: Why does my loader not react to my mouse hover/touch drag?

A: Ensure you have set enableInteraction: true on the loader and wrapped it inside an InteractiveUniverseWrapper to correctly relay gesture events.

Q: Do these custom painters leak memory?

A: No. All loaders utilize a centralized ParticlePool which recycles old particle instances rather than continuously allocating new memory objects.

Q: Can I use this for production apps?

A: Absolutely. The package is heavily tested, warning-clean, and has a high pub.dev scoring potential.

---

Roadmap 🗺️

• Planned: Add 3D WebGL/Three.js inspired canvas shaders.
• Planned: Implement audio-reactive loader modes.
• Planned: Create additional preset configurations (Solar Eclipse, Milky Way Collisions).
• Planned: Develop a desktop-based Universe Studio native app export.

---

Contribution Guidelines 🤝

Contributions are welcome! Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md files before submitting pull requests.

---

Version Compatibility ⚙️

Package Version	Flutter SDK	Dart SDK
v1.0.0	>=3.0.0	>=3.0.0 <4.0.0

---

License 📄

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