https://github.com/ms19101996/meridian-halo/releases

Meridian Halo: Lightweight Animated Web Particle Halo with Three.js and ESM/CJS

Meridian Halo is an animated particle halo for the web. It is a drop-in Three.js visual with ESM/CJS and browser builds, polished demos, and a tiny API. The project aims to be small in footprint while big in visual impact. It targets modern browsers with WebGL support and offers a straightforward path from zero to a shimmering halo around your scene.

This README explains what Meridian Halo gives you, how to use it, and how to extend it. It walks you through installation, usage patterns, and advanced topics like shader customization and performance tuning. It also covers build options, types, and how to contribute. It is designed to help you integrate a beautiful particle halo quickly and confidently.

Table of contents

• Quick overview
• Why Meridian Halo
• Core features
• Architecture and build targets
• Demos and visuals
• Getting started
• Installation
• Basic usage
• API overview
• Options and customization
• Particle system internals
• Shaders and rendering
• Performance and best practices
• TypeScript support
• Build and distribution
• Assets and assets pipeline
• Demos and examples gallery
• Theming and styling
• Advanced usage and shader customization
• Debugging and troubleshooting
• API reference (detailed)
• Roadmap
• Contributors and ecosystem
• License

Quick overview Meridian Halo creates a dynamic, glowing ring of particles that orbits and reacts to the scene around it. It leverages Three.js for scene management and WebGL for fast, GPU-powered visuals. The library is designed to be dropped into an existing Three.js project with minimal configuration. It supports both ESM and CommonJS (CJS) module formats, and it ships browser builds for quick experimentation without a bundler.

Why Meridian Halo

• A polished, opinionated particle halo that looks great out of the box.
• Lightweight and efficient. The goal is to avoid heavy baggage while delivering rich visuals.
• Flexible integration. Works with most Three.js scenes and rendering setups.
• Tiny API surface. Small surface area makes it easy to learn and extend.
• Shader-driven visuals. The halo uses GPU shaders to achieve smooth glow and subtle luminescence.
• Cross-format compatibility. Use ESM in modern tooling or CJS where you need it, plus browser builds for quick testing.

Core features

• Drop-in halo: Integrates with existing Three.js scenes with minimal setup.
• GPU-powered glow: A shader-based glow that remains crisp across screen sizes.
• Customizable color and gradient: Fine-tune the halo’s look with colors, gradients, and intensity.
• Particle system: Thousands of particles with efficient rendering, culling, and drift.
• Two rendering paths: ESM and CJS for flexible project setups.
• IIFE build: Immediate use in the browser without module bundling.
• Demo gallery: Polished demos that illustrate typical uses and creative ideas.
• TypeScript ready: Types that help you integrate Meridian Halo in TS projects.
• Accessible API: Clear, concise methods to start, stop, or reconfigure the halo.

Architecture and build targets

• Core module: The main halo logic is encapsulated in a tiny, well-documented module. It exposes a clean API to create, configure, and control the halo.
• Shader-driven visuals: The rendering relies on a pair of vertex/fragment shaders tailored to particle halos. The shaders implement smooth noise, additive blending, and glow without sacrificing performance.
• Particle system: A GPU-accelerated particle buffer stores positions, colors, and life, with a simple drift model to keep motion natural.
• Build targets:
  • ESM: Modern import syntax for tree-shaken usage in bundlers.
  • CJS: CommonJS compatibility for Node environments and older tooling.
  • IIFE: Browser-ready bundle for quick testing without a build step.
• Asset structure: The distribution includes core JavaScript, TypeScript typings, and prebuilt bundles for quick adoption. Demos and examples are included to showcase usage.

Demos and visuals

• The repository ships polished demos to illustrate typical use cases:
  • Basic halo in a clean scene with adjustable radius and intensity.
  • Interactive halo that responds to mouse or pointer position.
  • Multi-halo scenes with layered halos for a richer effect.
  • A time-based color shift, blending between hues for a living look.
  • A shader-friendly demo that you can customize by tweaking uniforms.
• Each demo provides a minimal starting point and a guided path to extend for your project.
• Preview assets show the halo rendering under different lighting conditions and camera angles.

Getting started

• The simplest path starts with a direct installation and a tiny snippet of code. If you already have a Three.js project, you can drop Meridian Halo in with minimal changes and then tune the visuals to your taste.
• The library is designed to be friendly to both newcomers and experienced developers. The API is intentionally small and well-documented, so you can get a halo on screen quickly and then refine it as needed.

Installation

• With a package manager:
  • npm
  • yarn
• The recommended approach for new projects is to install Meridian Halo as a dependency and import it in your module graph.
• If you prefer to experiment without a bundler, use the IIFE browser build included in the distribution, and reference it directly in your HTML.

Usage quick-start

• Typical steps:

  1. Create or reuse a Three.js scene.
  2. Import MeridianHalo (ESM or CJS) and initialize it with your scene and renderer.
  3. Configure options like halo radius, particle count, color, and glow strength.
  4. Start the halo and render your scene as usual.

• Example (ESM):

  • import { MeridianHalo } from 'meridian-halo';
  • const halo = new MeridianHalo({ scene, camera, renderer, radius: 2.5, color: 0x8af, particleCount: 1500 });
  • halo.start();
  • // In your animation loop: halo.update(deltaTime);

• Example (CommonJS):

  • const { MeridianHalo } = require('meridian-halo');
  • const halo = new MeridianHalo({ /* options */ });
  • halo.start();

• Example (IIFE browser build):

  • const halo = MeridianHalo.create({ /* options */ });
  • halo.start();

API overview

• MeridianHalo class (or factory)
  • new MeridianHalo(options)
  • start(): begin animation and particle motion
  • stop(): pause animation and reset timing
  • update(deltaTime): advanced control for custom animation loops
  • setOptions(newOptions): update visuals on the fly
  • dispose(): clean up resources
• Options (typical keys)
  • scene: Three.js Scene instance
  • camera: Three.js Camera instance
  • renderer: Three.js WebGLRenderer or renderer-like object
  • radius: number (halo radius)
  • color: number (HEX color)
  • pulse: boolean (enable color pulsing)
  • speed: number (particle drift speed)
  • particleCount: number
  • blendMode: string (e.g., "additive")
  • glow: number (glow strength, 0-1)
  • texture: string | undefined (optional particle texture)
  • shaderParams: object (custom shader uniforms)
• Events
  • halo:started
  • halo:stopped
  • halo:updated
  • halo:disposed
• Type hints
  • TypeScript types describe the input options, emitted events, and the Halo instance.

Options and customization

• Visual customization
  • Radius: change halo radius to fit your scene scale.
  • Color and gradient: switch base color, add gradient stops, or animate color over time.
  • Glow strength: adjust additive glow to achieve more or less bloom.
  • Particle count: increase for denser halos; decrease for performance-friendly visuals.
  • Texture: swap to a custom particle texture for different shapes and reputations.
• Motion and interactivity
  • Speed: control how fast particles drift around the halo.
  • Interactivity: tie halo behavior to mouse or touch input. For example, tilt the halo toward the pointer or react to pointer velocity.
  • Time-based effects: map color shifts or glow to a time parameter for dynamic scenes.
• Shader-level customization
  • shaderParams: adjust shader uniforms to influence noise, glow falloff, or color ramp.
  • Provide your own vertex/fragment shader code as an advanced option for bespoke looks.
• Performance tuning
  • particleCount: balance quality with frame time.
  • drawCalls: Meridian Halo minimizes draw calls, but a very large halo can still push brightness or fill rate.
  • precision: select floating-point precision if you are targeting legacy hardware, while keeping WebGL features enabled on modern devices.

Particle system internals

• Particles are stored in a GPU buffer with per-particle attributes such as position, color, life, and size.
• A uniform-based time factor drives subtle motion, while a meticulous drift model adds natural variance.
• The halo’s visual is composed by a layered approach: an outer glow, inner core, and subtle specks to simulate depth.
• The system uses additive blending to achieve a luminous look, while color is blended to preserve a sense of glow without washing out details.

Shaders and rendering

• Vertex shader responsibilities
  • Position particles in screen-aligned quads around the halo center.
  • Pass texture coordinates and per-vertex color to the fragment shader.
• Fragment shader responsibilities
  • Compute glow intensity based on distance from the halo center and depth-thickness variation.
  • Apply color ramps, alpha falloff, and bloom-like glow to create a soft halo.
  • Optional texture sampling for per-particle variation.
• Shader customization
  • Expose a shaderParams object to adjust pulse, glow, and noise.
  • Allow the host app to supply a fragment shader override for unique visuals.
  • Ensure the custom shader remains compatible with the engine’s uniforms to keep stability.

Performance and best practices

• Meridian Halo is designed to remain fast on modern hardware, with careful use of WebGL blending, texture lookups, and minimal compute overhead.
• For best results:
  • Keep particleCount within a reasonable range for your target device.
  • Use a single halo per scene to avoid excessive overdraw.
  • Prefer canned textures that are power-of-two to simplify sampling and mipmapping.
  • When possible, reuse the same renderer and scene to minimize setup cost.
  • Use a consistent frame rate target, typically 60fps, and adjust parameters if you see dips.
• Cross-browser considerations
  • Modern browsers with WebGL 1.0/2.0 support deliver the best experience.
  • If you need to support older devices, consider reducing particleCount and glow intensity.
  • Test on both desktop and mobile to ensure consistent visuals and performance.

TypeScript support

• Meridian Halo ships with TypeScript typings to help integrate with TS projects.
• The typings describe the Halo options, events, and the public API.
• Example:
  • import { MeridianHalo, MeridianHaloOptions } from 'meridian-halo';
  • const options: MeridianHaloOptions = { scene, camera, renderer, radius: 3.0, color: 0x66ccff, particleCount: 1200 };
  • const halo = new MeridianHalo(options);
  • halo.start();
• If you extend the library or write custom plugins, your type-safe code will benefit from autocompletion and type checking.
• Type coverage aims to be pragmatic, focusing on the most common usage patterns while leaving advanced usage ergonomic through explicit option shapes.

Build and distribution

• The repository ships multiple build artifacts to cover different usage scenarios:
  • ESM: For modern bundlers and module systems.
  • CJS: For Node.js-style environments or older tooling.
  • IIFE: For quick, no-build browser testing.
• How to use the builds
  • ESM: import { MeridianHalo } from 'meridian-halo';
  • CJS: const { MeridianHalo } = require('meridian-halo');
  • IIFE: Use a script tag to include meridian-halo.iife.js and call MeridianHalo.create or new MeridianHalo depending on the build.
• Packaging notes
  • The distribution includes a small API surface, a handful of demos, and a types package.
  • Tree-shaking friendly: the library is designed so unused parts do not bloat the bundle.
  • Source maps are included to facilitate debugging during development.
• How to build from source
  • Install dependencies
  • Run the build script
  • Validate by loading the IIFE bundle in a simple HTML page
• How to upgrade
  • Upgrade by bumping the version in your package.json
  • Read the changelog for breaking changes and migration steps

Assets and assets pipeline

• The project includes prebuilt assets for immediate use, plus a pipeline to generate new assets during development.
• Asset options
  • Particle textures: swap with your own PNGs or use generated textures.
  • Gradient textures: supply gradient textures to influence color ramps.
• Asset sizing
  • Prefer textures with consistent dimensions and power-of-two sizes for optimal sampling.
  • Use high-dpi assets for retina displays only if you need ultra-crisp visuals; otherwise, keep textures small to save memory.
• Asset licensing
  • Assets included or referenced in demos are licensed for development use in open-source projects.
  • If you replace assets, ensure you hold rights to them or use permissive/openly licensed resources.

Demos and examples gallery

• A curated gallery showcases typical use cases and creative patterns.
• Each demo includes:
  • A short description of the visual goal.
  • The required setup steps.
  • A live code snippet to recreate the effect.
  • A toggle to switch between different color palettes and glow strengths.
• How to run demos locally
  • Install dependencies
  • npm run start:demo (or yarn start:demo)
  • Open the provided local URL in your browser
• Extending demos
  • Copy a demo folder and adapt it to your scene.
  • Replace scene parameters or swap the halo’s color ramps to match your branding.
  • Use the shaderParams hook to tune glow or pulse behavior per demo.

Theming and styling

• Meridian Halo focuses on visuals rather than UI components. The halo itself is themable via color, glow, and gradient, while the surrounding scene remains under your control.
• For branding, use a color palette that aligns with your project. The halo reacts to a chosen base color and can blend with other scene lighting for a cohesive look.
• If you want to drive color changes with scene events, hook into halo.setOptions or halo.update to apply palette shifts in response to environmental cues (time of day, user interactions, etc.).

Advanced usage and shader customization

• Advanced workflows
  • Provide your own vertex/fragment shader pair to create unique particle halos or interaction patterns.
  • Pass custom uniforms to your shader through shaderParams to adjust behavior on the fly.
  • Use a post-processing step to composite the halo into complex scenes.
• Shader routing
  • Meridian Halo exposes a clean interface for injecting custom shader code while preserving the core rendering path.
  • Ensure your custom shader uses the same attribute and uniform names expected by the core module to maintain compatibility.
• Debugging shaders
  • Use WebGL inspector tools to inspect uniforms, textures, and buffers.
  • Validate that your custom shaders compile without errors and that attributes are correctly bound.

How to contribute

• Contribute with confidence. The project welcomes community involvement and collaboration.
• Ways to contribute
  • Report issues with clear steps to reproduce.
  • Propose enhancements with rationale and potential impact.
  • Submit pull requests with focused changes and tests.
• Code style and quality
  • Follow the repository’s existing style guidelines.
  • Add comments where needed to explain non-obvious decisions.
  • Include tests where appropriate to cover new features and edge cases.
• Documentation and examples
  • Update the README with examples of new features.
  • Add new demo files that illustrate your changes.
• Roadmap involvement
  • Share ideas for future improvements or new capabilities.
  • Participate in discussions about design trade-offs and performance goals.

Release notes and releases page

• The latest release page lists the version, changes, and how to upgrade. It includes compiled assets and source maps for debugging.
• The Releases page hosts the downloadable assets for each version, including ESM, CJS, and IIFE builds. It is the best place to obtain vetted bundles for integration.
• For quick access to the latest assets and notes, visit the Releases area. The page includes download links for the latest version and prebuilt bundles, allowing you to grab the exact artifact you need for your setup.
• See the main Releases page for details, asset types, and compatibility notes.

Releases (where to download)

• The repository hosts a Releases section with downloadable artifacts for all supported builds. The assets include ready-to-use bundles for ESM, CJS, and IIFE, along with source maps and lightweight docs.
• Accessing the releases in a browser lets you pick the right package for your project and platform. You can extract the bundle and integrate it directly into your Three.js scene.
• For teams integrating CI/CD, the releases provide a stable, tested bundle that avoids the risk of pulling directly from the codebase. It enables reproducible builds across environments.
• Quick tip: if you are building a web app with a module bundler, prefer the ESM build for optimized tree-shaking. If you are working in Node or classic scripts, choose the CJS or IIFE builds as appropriate.
• The latest release assets are maintained with clear versioning so you can upgrade with confidence. The release notes describe changes, fixes, and any breaking changes you should be aware of.

Where to look for help

• Documentation pages: The docs describe usage patterns, API details, and examples.
• Demos: The demo gallery provides practical starting points you can copy.
• Community support: If you run into issues, open an issue on GitHub with a clear description and a minimal reproducer.
• Pull requests: If you have a fix or improvement, submit a patch with tests and examples.

FAQ

• Do I need Three.js to use Meridian Halo?
  • Yes. Meridian Halo is designed to work alongside Three.js scenes. It uses Three.js for scene management and WebGL for rendering.
• Can I use Meridian Halo in a vanilla WebGL project?
  • The library is built to integrate with Three.js. If you are not using Three.js, you can adapt the underlying shaders and particle buffers, but it will require more work.
• Is Meridian Halo compatible with TypeScript?
  • Yes. TypeScript typings are included to help you integrate the library into TS projects.
• How do I customize colors?
  • Use the color options and shaderParams to adjust color ramps and cross-fades. You can animate color changes to create living halos.
• Can I replace the particle texture?
  • Yes. The library supports a custom texture option to provide different particle shapes.

Changelog (high level)

• v1.x.x: Initial public release with ESM, CJS, and IIFE builds. Basic halo with polish and a tiny API.
• v1.y.z: Minor improvements to performance, additional color options, and improved documentation.
• v1.y.z+1: Shader customization hooks added for advanced users; improved interop with common Three.js patterns.
• v1.x.y: Bug fixes and minor API refinements based on user feedback. A couple of new demos included.

Contribution guidelines

• Start by forking the repository and creating a feature branch.
• Write tests for any new functionality.
• Keep commits small and focused with informative messages.
• Update documentation and add or amend demos that illustrate the change.
• Ensure builds pass and that the code style remains consistent with the project.

License

• Meridian Halo is released under a permissive open-source license. This makes it easy to use in personal projects, open-source projects, and commercial products.

Appendix: practical quick-start checklist

• Create a Three.js scene if you don’t already have one.
• Install Meridian Halo via your package manager.
• Import and initialize Meridian Halo using ESM or CJS.
• Adjust radius, color, glow, and particleCount to suit your scene.
• Start the halo and render your scene with your main render loop.
• If needed, customize shaders or uniforms to achieve a distinct look.
• Experiment with interactivity by tying halo motion to user input.
• When satisfied, build your project using your preferred toolchain, and optionally upgrade to the latest release from the releases page.

Appendix: quick-start code samples

• ESM quick-start
  • import { MeridianHalo } from 'meridian-halo';
  • const halo = new MeridianHalo({ scene: scene, camera: camera, renderer: renderer, radius: 2.8, color: 0x66ccff, particleCount: 1200, });
  • halo.start();
  • // In your animation loop: halo.update(deltaTime);
• CJS quick-start
  • const { MeridianHalo } = require('meridian-halo');
  • const halo = new MeridianHalo({ scene, camera, renderer, radius: 2.8, color: 0x66ccff, particleCount: 1200 });
  • halo.start();
• IIFE quick-start (browser)
  • const halo = MeridianHalo.create({ scene, camera, renderer, radius: 2.8, color: 0x66ccff, particleCount: 1200 });
  • halo.start();

Releases

• For download and installation, refer to the main Releases page to obtain the latest compiled artifacts and maps.
• The Releases page hosts the files you need to run Meridian Halo across environments and toolchains.
• For quick installation, follow the instructions on the Releases page, then integrate the artifacts with your project’s build and runtime flow.

Note: The Releases page is the gateway to the latest stable assets and accompanying notes. Use it as your primary source for updates, compatibility details, and migration guidance. The link shown at the top provides direct access to the repository’s releases and assets, ensuring you can obtain the exact files you need for your project.