Effect Registry

The effect_registry is a module-level singleton that maps every built-in effect name to its implementation class, settings class, description, and named presets. It is the single source of truth used internally by all renderers to instantiate effects, and is fully open for extension with your own custom effects.

from bruhanimate import effect_registry

# Discover all registered effects
for name, entry in effect_registry.entries().items():
    print(name, "—", entry.description)

# List presets for an effect
print(effect_registry.presets("snow"))
# {'light': SnowSettings(...), 'blizzard': SnowSettings(...), ...}

# Create an effect instance by name using a preset
effect = effect_registry.create("snow", buffer, " ", preset="blizzard")

# Create with a custom settings object (takes priority over preset)
from bruhanimate import SnowSettings
effect = effect_registry.create("snow", buffer, " ", settings=SnowSettings(wind=0.9))

# Register your own effect
effect_registry.register(
    "myeffect",
    MyEffect,
    settings_cls=MySettings,
    description="Does something cool",
    presets={"fast": MySettings(speed=10)},
)

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.registry.EffectEntry(name: str, effect_cls: ~typing.Type, settings_cls: ~typing.Type | None, description: str, presets: dict[str, ~typing.Any] = <factory>)

Bases: object

Metadata for a single registered effect.

name: str

effect_cls: Type

settings_cls: Type | None

description: str

presets: dict[str, Any]

__init__(name: str, effect_cls: ~typing.Type, settings_cls: ~typing.Type | None, description: str, presets: dict[str, ~typing.Any] = <factory>) → None

class bruhanimate.bruheffect.registry.EffectRegistry

Bases: object

Central registry that maps effect names to their implementation class, settings class, description, and named presets.

Usage:

from bruhanimate import effect_registry

# list all registered effects
for name, entry in effect_registry.entries().items():
    print(name, "—", entry.description)

# create an effect by name (returns a BaseEffect instance)
effect = effect_registry.create("snow", buffer, " ")

# create with a named preset
effect = effect_registry.create("snow", buffer, " ", preset="blizzard")

# create with a custom settings object
from bruhanimate import SnowSettings
effect = effect_registry.create("snow", buffer, " ", settings=SnowSettings(wind=0.8))

# register your own effect
effect_registry.register(
    "myeffect",
    MyEffect,
    settings_cls=MySettings,
    description="Does something cool",
    presets={"fast": MySettings(speed=10)},
)

__init__()

register(name: str, effect_cls: Type, settings_cls: Type | None = None, description: str = '', presets: dict[str, Any] | None = None) → None

Register an effect under name.

get(name: str) → EffectEntry

Return the EffectEntry for name, or raise KeyError.

names() → list[str]

Return a sorted list of all registered effect names.

entries() → dict[str, EffectEntry]

Return a copy of the full registry dict.

presets(name: str) → dict[str, Any]

Return the preset dict for the named effect.

create(name: str, buffer: Buffer, background: str, *, settings: Any = None, preset: str | None = None) → BaseEffect

Instantiate the named effect.

Priority: settings > preset > effect defaults.

Parameters:

• name – Registered effect name (e.g. "snow").

• buffer – The Buffer the effect will draw into.

• background – Background fill character.

• settings – A settings dataclass instance to pass directly.

• preset – Name of a registered preset to use when settings is not provided.

Returns:

A ready-to-use BaseEffect instance.