Settings¶

Most built-in effects are configured through a settings dataclass. Construct a settings object, populate only the fields you care about (all have defaults), and pass it to the effect constructor. Settings can also be omitted entirely — each effect falls back to its own defaults.

from bruhanimate import SnowSettings, effects

effects.snow.play(settings=SnowSettings(wind=0.6), duration=10)

Settings validate types and finite values on construction and again when passed to an effect. Ranges and choices are available through bruhanimate info EFFECT. Invalid types raise TypeError; invalid values raise ValueError with the field name. Zero probability disables new particles where supported, and palette index 0 means black. See Discover effects, presets, and settings for presets, editor hints, and CLI usage.

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.settings.EffectSettings(*, seed: int | None = None)[source]¶

Bases: object

Validated built-in configuration, with typed fields and explicit ranges.

Construction rejects wrong types (TypeError) and invalid values (ValueError). Effects revalidate supplied settings before use, including edited instances. Settings remain mutable; editing one does not reconfigure an existing effect. Probabilities and halt ranges use simulation ticks, not display frames. seed selects independent Python/NumPy streams; None uses fresh entropy. Equal seeds reproduce a fresh effect with equal settings, size and updates in the same dependency versions. External inputs (such as audio) must match.

seed: int | None = None¶

validate() → None[source]¶: Validate every field without clamping or changing the configuration.

__init__(*, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.WaterSettings(color: bool = True, wave_speed: float = 0.45, damping: float = 0.985, drop_chance: float = 0.12, strength: float = 1.0, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Reflecting water surface. Speed is cells/tick; damping retains wave motion.

drop_chance is the probability of a random impulse per tick. The maximum wave_speed keeps the two-dimensional finite-difference scheme stable.

color: bool = True¶

wave_speed: float = 0.45¶

damping: float = 0.985¶

drop_chance: float = 0.12¶

strength: float = 1.0¶

__init__(color: bool = True, wave_speed: float = 0.45, damping: float = 0.985, drop_chance: float = 0.12, strength: float = 1.0, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.SmokeSettings(color: bool = True, style: Literal['smoke', 'ink'] = 'smoke', rise: float = 0.65, turbulence: float = 0.6, decay: float = 0.985, diffusion: float = 0.1, intensity: float = 0.8, source_width: float = 0.15, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Advected density in an artistic curl field, with an optional obstacle mask.

rise is cells/tick; turbulence scales horizontal drift. decay retains density per tick. source_width is a fraction of viewport width. Ink sinks.

color: bool = True¶

style: Literal['smoke', 'ink'] = 'smoke'¶

rise: float = 0.65¶

turbulence: float = 0.6¶

decay: float = 0.985¶

diffusion: float = 0.1¶

intensity: float = 0.8¶

source_width: float = 0.15¶

__init__(color: bool = True, style: Literal['smoke', 'ink'] = 'smoke', rise: float = 0.65, turbulence: float = 0.6, decay: float = 0.985, diffusion: float = 0.1, intensity: float = 0.8, source_width: float = 0.15, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.MetaballsSettings(color: bool = True, count: int = 5, radius: float = 0.28, speed: float = 0.035, threshold: float = 1.0, filled: bool = True, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Merging implicit surfaces. Radius is a fraction of the shorter visual axis.

speed is radians/tick; threshold selects the field’s visible isosurface. Terminal cells are treated as twice as tall as they are wide.

color: bool = True¶

count: int = 5¶

radius: float = 0.28¶

speed: float = 0.035¶

threshold: float = 1.0¶

filled: bool = True¶

__init__(color: bool = True, count: int = 5, radius: float = 0.28, speed: float = 0.035, threshold: float = 1.0, filled: bool = True, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.ClothSettings(color: bool = True, pattern: Literal['flag', 'checker', 'text'] = 'flag', text: str = 'BRUH', amplitude: float = 0.12, speed: float = 0.12, wavelength: float = 1.5, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Pinned waving cloth; a kinematic animation, not a spring simulation.

amplitude is a fraction of viewport height; wavelength counts wave cycles across the cloth; speed is radians/tick. Text contains single-cell glyphs. Supply custom ASCII rows to ClothEffect(image=…) to carry your own art.

color: bool = True¶

pattern: Literal['flag', 'checker', 'text'] = 'flag'¶

text: str = 'BRUH'¶

amplitude: float = 0.12¶

speed: float = 0.12¶

wavelength: float = 1.5¶

validate() → None[source]¶: Validate every field without clamping or changing the configuration.

__init__(color: bool = True, pattern: Literal['flag', 'checker', 'text'] = 'flag', text: str = 'BRUH', amplitude: float = 0.12, speed: float = 0.12, wavelength: float = 1.5, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.TerrainSettings(color: bool = True, style: Literal['shaded', 'contours'] = 'shaded', speed: float = 0.12, scale: float = 0.12, roughness: float = 0.8, horizon: float = 0.3, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Perspective flyover of seeded coherent terrain, with a fixed camera height.

speed is world units/tick; scale is noise frequency per world unit; roughness scales elevation; horizon is a fraction of viewport height.

color: bool = True¶

style: Literal['shaded', 'contours'] = 'shaded'¶

speed: float = 0.12¶

scale: float = 0.12¶

roughness: float = 0.8¶

horizon: float = 0.3¶

__init__(color: bool = True, style: Literal['shaded', 'contours'] = 'shaded', speed: float = 0.12, scale: float = 0.12, roughness: float = 0.8, horizon: float = 0.3, *, seed: int | None = None) → None¶

bruhanimate.bruheffect.settings.validated_settings(value: S | None, expected: type[S]) → S[source]¶: Get defaults or validate a supplied configuration before effect allocation.

class bruhanimate.bruheffect.settings.AudioSettings(mode: Literal['objects', 'tiles', 'glow', 'bars', 'mirror', 'waveform', 'spectrum'] = 'bars', bar_char: str = '|', smoothing: float = 0.7, num_bars: int = 0, color: bool = True, sensitivity: float = 1.0, compact: bool = False, noise_floor: float = -65.0, bar_gain: float = 2.0, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Seven audio modes with fixed-scale levels and a configurable dB noise floor.

num_bars=0 follows viewport width. smoothing retains the previous level on release (0..1); attack retention is capped at 0.25 for a responsive rise. noise_floor defaults to -65 dB to retain quieter mid/treble detail. Frequency levels sum band energy on a sine-peak-equivalent scale; overall volume uses RMS. Neither is a calibrated SPL reading. sensitivity scales both amplitudes. bar_gain scales only Bars/Mirror height and peak caps (default 2, 1 restores the analyzed height, 0 hides bars). It does not normalize individual frames.

mode: Literal['objects', 'tiles', 'glow', 'bars', 'mirror', 'waveform', 'spectrum'] = 'bars'¶

bar_char: str = '|'¶

smoothing: float = 0.7¶

num_bars: int = 0¶

color: bool = True¶

sensitivity: float = 1.0¶

compact: bool = False¶

noise_floor: float = -65.0¶

bar_gain: float = 2.0¶

__init__(mode: Literal['objects', 'tiles', 'glow', 'bars', 'mirror', 'waveform', 'spectrum'] = 'bars', bar_char: str = '|', smoothing: float = 0.7, num_bars: int = 0, color: bool = True, sensitivity: float = 1.0, compact: bool = False, noise_floor: float = -65.0, bar_gain: float = 2.0, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.DrawLinesSettings(char: str | None = None, thin: bool = False, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Single-cell line glyph; None chooses the built-in line characters.

char: str | None = None¶

thin: bool = False¶

__init__(char: str | None = None, thin: bool = False, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.FireSettings(intensity: float = 0.2, wind_direction: float = 0.0, wind_strength: float = 0.0, use_char_color: bool = False, background_color: bool = False, swell: bool = False, swell_halt: int = 1, turbulence: float = 0.0, heat_spot_intensity: float = 0.1, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Fire probabilities/strengths in [0, 1]; wind_direction is degrees.

intensity: float = 0.2¶

wind_direction: float = 0.0¶

wind_strength: float = 0.0¶

use_char_color: bool = False¶

background_color: bool = False¶

swell: bool = False¶

swell_halt: int = 1¶

turbulence: float = 0.0¶

heat_spot_intensity: float = 0.1¶

__init__(intensity: float = 0.2, wind_direction: float = 0.0, wind_strength: float = 0.0, use_char_color: bool = False, background_color: bool = False, swell: bool = False, swell_halt: int = 1, turbulence: float = 0.0, heat_spot_intensity: float = 0.1, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.FireworkSettings(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'] = 'circular', color_enabled: bool = False, color_type: Literal['solid', 'twotone', 'rainbow', 'random'] = 'solid', rate: float = 0.05, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Burst style and per-tick launch probability; rate=0 disables launches.

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'] = 'circular'¶

color_enabled: bool = False¶

color_type: Literal['solid', 'twotone', 'rainbow', 'random'] = 'solid'¶

rate: float = 0.05¶

__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'] = 'circular', color_enabled: bool = False, color_type: Literal['solid', 'twotone', 'rainbow', 'random'] = 'solid', rate: float = 0.05, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.GameOfLifeSettings(decay: bool = False, color: bool = False, color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE', scale: Literal['random', 'default', '.', 'o', '0'] = 'random', *, seed: int | None = None)[source]¶

Bases: EffectSettings

Life display palette and optional decay glyph scale.

decay: bool = False¶

color: bool = False¶

color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE'¶

scale: Literal['random', 'default', '.', 'o', '0'] = 'random'¶

__init__(decay: bool = False, color: bool = False, color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE', scale: Literal['random', 'default', '.', 'o', '0'] = 'random', *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.MatrixSettings(character_halt_range: tuple[int, int] = (1, 2), color_halt_range: tuple[int, int] = (1, 2), character_randomness_one: float = 0.7, character_randomness_two: float = 0.6, color_randomness: float = 0.5, gradient_length: int = 1, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Positive ordered tick ranges and probabilities in [0, 1].

character_halt_range: tuple[int, int] = (1, 2)¶

color_halt_range: tuple[int, int] = (1, 2)¶

character_randomness_one: float = 0.7¶

character_randomness_two: float = 0.6¶

color_randomness: float = 0.5¶

gradient_length: int = 1¶

__init__(character_halt_range: tuple[int, int] = (1, 2), color_halt_range: tuple[int, int] = (1, 2), character_randomness_one: float = 0.7, character_randomness_two: float = 0.6, color_randomness: float = 0.5, gradient_length: int = 1, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.NoiseSettings(intensity: int = 200, color: bool = False, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Noise density on a 0-999 scale; zero disables new noise.

intensity: int = 200¶

color: bool = False¶

__init__(intensity: int = 200, color: bool = False, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.OffsetSettings(direction: Literal['left', 'right'] = 'right', *, seed: int | None = None)[source]¶

Bases: EffectSettings

Supported horizontal offset pattern directions.

direction: Literal['left', 'right'] = 'right'¶

__init__(direction: Literal['left', 'right'] = 'right', *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.PlasmaSettings(color: bool = False, characters: bool = True, random_colors: bool = False, show_info: bool = False, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Plasma glyph and palette rendering switches.

color: bool = False¶

characters: bool = True¶

random_colors: bool = False¶

show_info: bool = False¶

__init__(color: bool = False, characters: bool = True, random_colors: bool = False, show_info: bool = False, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.RainSettings(intensity: int = 200, wind_direction: Literal['none', 'east', 'west'] = 'none', swells: bool = False, collision: bool = False, lightning: bool = False, lightning_chance: float = 0.02, lightning_threshold: int = 500, lightning_color: bool = False, lightning_color_type: int = 226, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Density in [0, 999], lightning probability in [0, 1], color in [0, 255].

intensity: int = 200¶

wind_direction: Literal['none', 'east', 'west'] = 'none'¶

swells: bool = False¶

collision: bool = False¶

lightning: bool = False¶

lightning_chance: float = 0.02¶

lightning_threshold: int = 500¶

lightning_color: bool = False¶

lightning_color_type: int = 226¶

__init__(intensity: int = 200, wind_direction: Literal['none', 'east', 'west'] = 'none', swells: bool = False, collision: bool = False, lightning: bool = False, lightning_chance: float = 0.02, lightning_threshold: int = 500, lightning_color: bool = False, lightning_color_type: int = 226, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.SnowSettings(intensity: float = 0.01, wind: float = 0.0, show_info: bool = False, collision: bool = False, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Per-tick flake probability in [0, 1]; wind in [-1, 1] (left to right).

intensity: float = 0.01¶

wind: float = 0.0¶

show_info: bool = False¶

collision: bool = False¶

__init__(intensity: float = 0.01, wind: float = 0.0, show_info: bool = False, collision: bool = False, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.StarSettings(color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE', *, seed: int | None = None)[source]¶

Bases: EffectSettings

Palette for the blinking star field.

color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE'¶

__init__(color_type: Literal['GREYSCALE', 'GREYSCALE_r', 'GREYSCALE_MUTED', 'RAINBOW', 'RAINBOW_r'] = 'GREYSCALE', *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.TwinkleSettings(twinkle_chars: list[str] = <factory>, density: float = 0.05, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Nonempty single-cell glyph list and fraction of twinkling cells in [0, 1].

twinkle_chars: list[str]¶

density: float = 0.05¶

__init__(twinkle_chars: list[str] = <factory>, density: float = 0.05, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.BoidsSettings(num_boids: int = 60, color: bool = True, char: str = '*', max_speed: float = 1.5, perception: float = 12.0, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Flock count, single-cell glyph, speed per tick and perception radius.

num_boids: int = 60¶

color: bool = True¶

char: str = '*'¶

max_speed: float = 1.5¶

perception: float = 12.0¶

__init__(num_boids: int = 60, color: bool = True, char: str = '*', max_speed: float = 1.5, perception: float = 12.0, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.SandSettings(color: bool = True, char: str = '#', spawn_rate: float = 0.2, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Single-cell sand glyph and per-tick spawn probability in [0, 1].

color: bool = True¶

char: str = '#'¶

spawn_rate: float = 0.2¶

__init__(color: bool = True, char: str = '#', spawn_rate: float = 0.2, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.DiffusionSettings(color: bool = True, char: str = '.', f: float = 0.055, k: float = 0.062, steps_per_frame: int = 8, *, seed: int | None = None, shading: bool = False, seed_pattern: Literal['center', 'scattered'] = 'center')[source]¶

Bases: EffectSettings

Feed/kill rates in [0, 1]; steps_per_frame counts substeps per update tick.

color: bool = True¶

shading: bool = False¶

seed_pattern: Literal['center', 'scattered'] = 'center'¶

char: str = '.'¶

f: float = 0.055¶

k: float = 0.062¶

steps_per_frame: int = 8¶

__init__(color: bool = True, char: str = '.', f: float = 0.055, k: float = 0.062, steps_per_frame: int = 8, *, seed: int | None = None, shading: bool = False, seed_pattern: Literal['center', 'scattered'] = 'center') → None¶

class bruhanimate.bruheffect.settings.AutomatonSettings(color: bool = True, char: str = '#', rule: int = 30, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Elementary cellular automaton rule number in [0, 255].

color: bool = True¶

char: str = '#'¶

rule: int = 30¶

__init__(color: bool = True, char: str = '#', rule: int = 30, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.VoronoiSettings(color: bool = True, char: str = '#', num_seeds: int = 12, seed_speed: float = 0.3, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Positive seed count and non-negative seed speed per tick.

color: bool = True¶

char: str = '#'¶

num_seeds: int = 12¶

seed_speed: float = 0.3¶

__init__(color: bool = True, char: str = '#', num_seeds: int = 12, seed_speed: float = 0.3, *, seed: int | None = None) → None¶

class bruhanimate.bruheffect.settings.PerlinSettings(color: bool = True, char: str = '.', octaves: int = 4, speed: float = 0.015, threshold: float = 0.35, *, seed: int | None = None)[source]¶

Bases: EffectSettings

Positive octave count, non-negative speed per tick, threshold in [0, 1].

color: bool = True¶

char: str = '.'¶

octaves: int = 4¶

speed: float = 0.015¶

threshold: float = 0.35¶

__init__(color: bool = True, char: str = '.', octaves: int = 4, speed: float = 0.015, threshold: float = 0.35, *, seed: int | None = None) → None¶