Configuration & API Guide

Methods & Properties

Use these public members on your initialised fireworks instance.

After const fireworks = new GrandFireworks(config), these methods control the instance. A return type of this means the same instance, so calls can be chained. Await Promise-returning methods to wait for completion. Examples below are code samples; they do not launch effects on this page.

await fireworks.stop();
// Stops new launches, finishes active fireworks,
// plays the finale when configured, fades out, then resolves.

fireworks.stop({ immediate: true }); // Emergency stop
fireworks.stop({ finale: false });   // Skip one configured finale
fireworks.finalize();                // Graceful stop with finale

Show lifecycle

fireworks.start({ duration: 10000 });

await fireworks.stop({ finale: true });

fireworks.pause();

fireworks.resume();

fireworks.clear();

fireworks.destroy();

await fireworks.finalize();

Launch effects

fireworks.launch({ type: 'grand_peony', x: 0.5, burstHeight: 0.3 });

fireworks.placeburst({ element: '#celebrate', radius: 120 });

fireworks.launchTo({ x: 40, y: 300, targetX: 200, targetY: 80, duration: 600, radius: 100 });

const lines = await fireworks.launchText('HELLO', { tilt: [-15, 15] });

const result = await fireworks.launchTextSequence(['READY', 'GO'], { interval: 3000 });

const cancelled = fireworks.cancelTextSequence({ clear: true });

fireworks.launchFinale({ stopAfter: false });

fireworks.launchWorldEnder({ firstSplitCount: 6, stopAfter: false });

Live settings and audio

fireworks.setOptions({ show: { intensity: 1.2 } });

fireworks.setOpacity(0.7);

fireworks.setZoom(0.5);

fireworks.setStyle('cinematic');

fireworks.setColorTheme('iceBlue');

button.addEventListener('click', () => fireworks.enableSound());

fireworks.disableSound();

fireworks.setMuted(true);
fireworks.setMuted(false); // restore previous volume

const generated = fireworks.feelingLucky();

Read settings and state

const settings = fireworks.getOptions();

const stats = fireworks.getStats();
console.log(stats.state, stats.fps);

Host rendering

fireworks.setRenderPass(frame => {
  // Draw your scene with frame.ctx or frame.gl; do not clear the frame.
});

fireworks.renderFrame(16.67); // milliseconds since the last frame

Arguments and per-call options

Omitted option objects default to an empty object and inherit the instance settings where applicable. pause() and resume() default to a manual pause reason; ordinary callers should omit their internal argument. setMuted() defaults to true; renderFrame() defaults to 0; setRenderPass() defaults to null. Text overrides use the text configuration options; World Ender overrides use the World Ender options.

RunOptions

StopOptions

LaunchOptions

BurstOptions

LaunchToOptions (also accepts BurstOptions fields)

TextSequenceOptions

FinaleLaunchOptions

launchTextSequence() accepts a string, an item object, or an array. Item objects use { text, overrides?, duration? }; duration is the interval until the next item in ms. It resolves to { status: "completed" | "cancelled", completed, total }. cancelTextSequence({ clear: true }) also clears active text; clear defaults to true. The runtime additionally accepts gap (extra ms in automatic sequencing), which is currently absent from the TypeScript declarations.

Accessible properties and snapshots

The declarations expose methods and static catalogues. Runtime instance properties exist, but are not declared as a stable public property contract. Use snapshots and setters rather than assigning internal arrays, timers, renderer state or fireworks.options directly.

getStats() fields

renderer

Active renderer: webgl2 or canvas2d.

fallbackActive

Whether Canvas 2D is active despite a non-Canvas preference.

contextLossCount

Number of WebGL context losses.

state

idle, running, paused, finishing, finale, manual, fading, stopped or destroyed.

particles

Active particle count.

rockets

Active rocket count.

fps

Rounded measured frames per second.

durationRemaining

Remaining show milliseconds, or null for an indefinite show.

quality

Current adaptive quality multiplier.

getOptions() returns a deep-cloned resolved configuration. Editing it does not apply settings: call setOptions() to apply changes. getStats() returns a snapshot, not a live object.

Static properties on GrandFireworks

GrandFireworks.VERSION

Engine version string.

GrandFireworks.DEFAULTS

Base constructor options before styles and resolution.

GrandFireworks.PRESETS

Performance preset catalogue.

GrandFireworks.TYPES

Regular shell name array.

GrandFireworks.STYLES

Visual style catalogue; mixed is a selection mode rather than an entry.

GrandFireworks.COLOR_THEMES

Named colour-theme palette catalogue.

Static catalogues are shared runtime objects; treat them as read-only. To customize an instance, pass your own options.

Events

Lifecycle events use ordinary Event objects without a detail payload: start fires when the show starts; pause when a manual pause changes the pause state; resume when a manual resume changes it; stop when shutdown finishes. Custom events below carry detail.

The instance extends EventTarget. Use addEventListener(), removeEventListener() and dispatchEvent() with normal browser EventTarget semantics. Read engine event payloads through event.detail.

rendererchange

detail: { from, to, reason }; fires when renderer selection changes.

finalestage

detail identifies stages such as carrier, trails and secondary-burst; optional count, x/y, type and source depend on the stage.

textlaunch

detail: { text, lines, particles }; text rockets have been scheduled.

textsequencestart

detail: { total }; the sequence starts.

textsequenceitem

detail: { index, total, text }; identifies the current sequence item.

textsequenceend

detail: { status, completed, total }; normal sequence completion.

textsequencecancel

detail: { status, completed, total }; cancellation.

function onRendererChange(event) {
  console.log(event.detail.from, event.detail.to);
}
fireworks.addEventListener('rendererchange', onRendererChange);
// Before discarding your host component:
fireworks.removeEventListener('rendererchange', onRendererChange);

Driving a host render loop

A render pass receives { gl, ctx, canvas, width, height, dpr }. Exactly one context is non-null. Width and height are CSS pixels; dpr describes the drawing buffer. Draw your scene after the engine clears the frame and before its fireworks. Attaching a pass stops the engine’s own loop; continue calling renderFrame during a stop wind-down so its Promise can resolve. Frame deltas are capped at 50 ms. Detach with setRenderPass(null).

let last = performance.now();
let frameId;
function frame(now) {
  fireworks.renderFrame(now - last);
  last = now;
  frameId = requestAnimationFrame(frame);
}
frameId = requestAnimationFrame(frame);
// When the host is disposed: cancelAnimationFrame(frameId); fireworks.destroy();