Firework Effect

Copyright 2023 Ethan Christensen

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class bruhanimate.bruheffect.firework_effect.Particle(x: int, y: int, dx: float, dy: float, width: int, height: int, symbol: chr = '*', life: int = None, trail_length: int = 0)

Bases: object

Class representing a particle in a firework with optional trail effects.

__init__(x: int, y: int, dx: float, dy: float, width: int, height: int, symbol: chr = '*', life: int = None, trail_length: int = 0)

Initialize a particle with the given parameters.

Parameters:

• x (int) – The x position of the particle.

• y (int) – The y position of the particle.

• dx (float) – The horizontal velocity of the particle.

• dy (float) – The vertical velocity of the particle.

• width (int) – The width of the canvas or screen.

• height (int) – The height of the canvas or screen.

• symbol (chr, optional) – The character that will be displayed to the screen. Defaults to “*”.

• life (int, optional) – How long this particle can live for (frames). Defaults to None.

• trail_length (int, optional) – Length of the particle’s trail. 0 means no trail. Defaults to 0.

update()

Function to update a particle and its parameters each frame.

get_display_points()

Returns all points that should be displayed, including trails if enabled.

Returns:

List of tuples (x, y, symbol) for all points to display

Return type:

list

is_alive()

Whether or not the particle is still alive. A Particle is alive if it has life left and is within bounds.

class bruhanimate.bruheffect.firework_effect.Firework(firework_type: Literal['circular', 'ring', 'starburst', 'cone', 'spiral', 'cross', 'burst', 'wave', 'flower', 'doublering', 'heart', 'start', 'fireball', 'diamond', 'shockwave', 'snowflake', 'cluster', 'comet', 'willow', 'dna', 'infinity', 'galaxy', 'phoenix', 'fountain', 'butterfly', 'dragon', 'tornado', 'matrix', 'portal', 'fractal', 'tessellation', 'quantum', 'mandelbrot', 'hypercube', 'chaos', 'timewarp', 'interdimensional', 'blackhole', 'mtheory', 'realitywarp', 'noneuclidean', 'cosmicstring', 'fancytrailburst', 'random'], height: int, width: int, firework_color_type: str = None, color_enabled: bool = False, allowed_firework_types: List[str] = None)

Bases: object

The Firework class. Responsible for creating and updating fireworks.

__init__(firework_type: Literal['circular', 'ring', 'starburst', 'cone', 'spiral', 'cross', 'burst', 'wave', 'flower', 'doublering', 'heart', 'start', 'fireball', 'diamond', 'shockwave', 'snowflake', 'cluster', 'comet', 'willow', 'dna', 'infinity', 'galaxy', 'phoenix', 'fountain', 'butterfly', 'dragon', 'tornado', 'matrix', 'portal', 'fractal', 'tessellation', 'quantum', 'mandelbrot', 'hypercube', 'chaos', 'timewarp', 'interdimensional', 'blackhole', 'mtheory', 'realitywarp', 'noneuclidean', 'cosmicstring', 'fancytrailburst', 'random'], height: int, width: int, firework_color_type: str = None, color_enabled: bool = False, allowed_firework_types: List[str] = None)

Initialize a Firework object.

Parameters:

• firework_type (FireworkType) – The type of firework this object should be. (eg. ‘random’, ‘ring’, ‘snowflake’).

• height (int) – The height of the display area (generally the terminal window).

• width (int) – The width of the display area (generally the terminal window).

• firework_color_type (str, optional) – The type of color to be applied to the Firework. Defaults to None.

• color_enabled (bool, optional) – Whether of not the Firework should have color. Defaults to False.

• allowed_firework_types (List[str], optional) – List of allowed firework types in the instance firework_type is ‘random’. Defaults to None.

update()

Function to update the firework’s state. If the firework hasn’t exploded yet, then it’s trail needs to be advanced. If the firework has exploded, then we need to update the particles that make up the firework.

move_straight()

Function to move the firework trail straight up and down.

move_arc()

Function to move the firework trail in an arcing trajectory.

move_zigzag()

Function to move the firework trail in a zigzag pattern.

create_particles()

Function to create the particles for the firework after it has reached it’s peak. It is determined by the firework_type parameter.

circular_explosion()

Creates a circular explosion effect.

ring_explosion()

Creates a ring explosion effect.

starburst_explosion()

Creates a starburst explosion effect.

cone_explosion()

Creates a cone explosion effect.

spiral_explosion()

Creates a spiral explosion effect.

wave_explosion()

Creates a wave explosion effect.

burst_explosion()

Creates a burst explosion effect.

cross_explosion()

Creates a cross explosion effect.

flower_explosion()

Creates a flower explosion effect.

double_ring_explosion()

Creates a double ring explosion effect.

heart_explosion()

Creates a heart explosion effect.

star_explosion()

Creates a star explosion effect.

fireball_explosion()

Creates a fireball explosion effect.

diamond_explosion()

Creates a diamond explosion effect.

burst_with_shockwave_explosion()

Creates a burst with shockwave explosion effect.

snowflake_explosion()

Creates a snowflake explosion effect.

cluster_explosion()

Creates a cluster explosion effect with particles moving in different directions

comet_tail_explosion()

Creates a comet tail explosion effect with particles following a comet-like path

willow_explosion()

Creates a willow explosion effect with multiple branches extending from the center

dna_explosion()

Creates a double helix pattern resembling DNA structure

infinity_explosion()

Creates an infinity symbol (∞) pattern

galaxy_explosion()

Creates a spiral galaxy pattern with arms and central bulge

phoenix_explosion()

Creates a rising phoenix pattern with wings and tail

fountain_explosion()

Creates an upward-shooting fountain pattern with cascading particles

butterfly_explosion()

Creates a butterfly pattern with wings that flutter

dragon_explosion()

Creates a dragon shape with body, wings, and fire breath

tornado_explosion()

Creates a spinning tornado effect that grows wider at the top

matrix_explosion()

Creates a Matrix-style digital rain effect

portal_explosion()

Creates two connected portals with particles flowing between them

fractal_tree_explosion()

Creates a fractal tree pattern that branches out recursively

tessellation_explosion()

Creates an Islamic geometric pattern-inspired explosion

quantum_explosion()

Creates a quantum probability cloud-like pattern with orbital shells

mandelbrot_explosion()

Creates an explosion pattern inspired by the Mandelbrot set

hypercube_explosion()

Creates a 4D hypercube projection explosion pattern

chaos_theory_explosion()

A completely chaotic explosion that uses strange attractors and randomness

time_warp_explosion()

Creates particles that appear to move through time differently

interdimensional_portal_explosion()

Creates a swirling portal effect that seems to connect different dimensions

black_hole_singularity()

Creates a black hole effect that warps space around it and emits Hawking radiation

m_theory_explosion()

Creates patterns inspired by 11-dimensional M-theory with membrane interactions

reality_warping_tessellation()

Creates a pattern that seems to fold and unfold reality itself

non_euclidean_explosion()

Creates patterns that follow non-Euclidean geometry rules

cosmic_string_explosion()

Creates patterns based on theoretical cosmic strings and topological defects

fancy_trail_burst_explosion()

Creates a more complex explosion with varying trail lengths and spiral motion

is_active()

Returns True if the portal is active (emitting particles), False otherwise.

Returns:

Whether or not the firework is still alive

Return type:

bool

get_colors()

Get the colors for the firework based on its color type.

Returns:

List of colors that should be used to color the firework.

Return type:

list[int]

render(buffer: Buffer)

Render the firework to a Buffer object.

Parameters:

buffer (Buffer) – Buffer used to house the image effect.

class bruhanimate.bruheffect.firework_effect.FireworkEffect(buffer: Buffer, background: str)

Bases: BaseEffect

A spectacular fireworks display effect that can create various types of firework patterns.

This class provides a highly customizable fireworks display with support for different explosion patterns, colors, and special effects. It can render traditional circular bursts, as well as exotic patterns like fractals, quantum effects, and interdimensional portals.

Example Usage:

from bruhanimate import Buffer
from bruhanimate.bruheffect import FireworkEffect

# Create a basic fireworks display
buffer = Buffer(width=80, height=24)
fireworks = FireworkEffect(buffer=buffer, background=" ")

# Configure the fireworks
fireworks.set_firework_type("circular")
fireworks.set_firework_rate(0.1)
fireworks.set_firework_color_enabled(True)
fireworks.set_firework_color_type("rainbow")

# Render frames in your animation loop
for frame in range(100):
    fireworks.render_frame(frame)
    buffer.display()

Advanced Example:

# Create a mixed fireworks display with specific types
fireworks.set_firework_type("random")
fireworks.set_allowed_firework_types([
    "circular", "starburst", "butterfly",
    "quantum", "galaxy"
])

Warning

• High firework rates (>0.3) may impact performance on slower systems

• Some exotic firework types may be CPU intensive

• Color support requires a terminal that supports ANSI color codes

Note

The firework patterns are designed to work best in terminals with aspect ratios close to 1:2 (height:width). Some patterns may appear distorted in terminals with very different aspect ratios.

See also

• BaseEffect: The parent class for all effects

• Buffer: The buffer class used for rendering

__init__(buffer: Buffer, background: str)

Initialize the fireworks effect

Parameters:

• buffer (Buffer) – Image buffer used to push updates to

• background (str) – Character that should be used for the background of the buffer

set_firework_type(firework_type: Literal['circular', 'ring', 'starburst', 'cone', 'spiral', 'cross', 'burst', 'wave', 'flower', 'doublering', 'heart', 'start', 'fireball', 'diamond', 'shockwave', 'snowflake', 'cluster', 'comet', 'willow', 'dna', 'infinity', 'galaxy', 'phoenix', 'fountain', 'butterfly', 'dragon', 'tornado', 'matrix', 'portal', 'fractal', 'tessellation', 'quantum', 'mandelbrot', 'hypercube', 'chaos', 'timewarp', 'interdimensional', 'blackhole', 'mtheory', 'realitywarp', 'noneuclidean', 'cosmicstring', 'fancytrailburst', 'random'])

Set the type of firework explosions to be created.

Parameters:

firework_type (FireworkType) – The type of firework to create. Can be one of: - “circular”: Traditional circular burst - “starburst”: Radiating star pattern - “butterfly”: Elegant butterfly pattern - “quantum”: Quantum probability cloud … and many more

Example:

fireworks.set_firework_type("butterfly")
# Or use random for variety
fireworks.set_firework_type("random")

Warning

Some exotic firework types (like “quantum”, “hypercube”, etc.) may be more CPU intensive than traditional patterns.

Note

When using “random” type, the actual patterns used will be limited to those specified in allowed_firework_types.

set_firework_color_enabled(color_enabled: bool)

Set how frequently new fireworks should be launched.

Parameters:

firework_rate (float) – Probability (0.0 to 1.0) of launching a new firework each frame. Higher values mean more frequent launches.

Example:

# Sparse fireworks
fireworks.set_firework_rate(0.05)  # 5% chance per frame

# Dense show
fireworks.set_firework_rate(0.3)   # 30% chance per frame

Warning

• Values >0.3 may cause performance issues on slower systems

• Values >0.5 may create very dense/cluttered displays

• Values ≤0.0 will prevent any fireworks from launching

Note

The actual visual density will depend on your frame rate. Adjust this value based on how frequently you call render_frame().

set_firework_color_type(firework_color_type: Literal['solid', 'twotone', 'rainbow', 'random'])

Enable or disable colored fireworks.

Parameters:

color_enabled (bool) – Whether fireworks should be rendered in color.

Example:

# Enable colorful display
fireworks.set_firework_color_enabled(True)
fireworks.set_firework_color_type("rainbow")

Warning

• Colors require a terminal that supports ANSI color codes

• Some terminals may display colors differently

• Windows command prompt has limited color support

Note

Even when enabled, colors will only be visible if a color type is set via set_firework_color_type().

set_firework_rate(firework_rate: float)

Function to set the rate at which fireworks should be launched

set_allowed_firework_types(allowed_firework_types)

Specify which firework types can be used when type is set to “random”.

Parameters:

allowed_firework_types (List[str]) – List of firework type names to allow. Must be valid types from valid_firework_types.

Example:

# Create a show with only geometric patterns
fireworks.set_allowed_firework_types([
    "circular", "ring", "diamond", "star"
])

# Create a show with exotic effects
fireworks.set_allowed_firework_types([
    "quantum", "hypercube", "galaxy",
    "interdimensional", "cosmic_string"
])

Warning

• An empty list or list with no valid types will revert to all types

• Invalid type names will be silently ignored

• Some combinations of types may create visually jarring transitions

Note

This setting only affects fireworks when type is set to “random”. For consistent displays, choose types with similar visual characteristics.

set_second_effect(second_effect: any)

render_frame(frame_number)

Renders the background to the screen