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 by the player and CLI to instantiate effects, and is fully open for extension with your own custom effects.

See Discover effects, presets, and settings for the typed effects.snow catalog, preset inspection, CLI commands, and settings validation. presets(name) returns independent settings copies. resolve_settings validates selections without constructing effects. Explicit settings override a known preset; unknown presets always fail.

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, validating and copying its preset configurations.

Custom settings classes need not inherit EffectSettings. Their instances are type-checked; built-in EffectSettings also validate field values.

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 independent settings copies keyed by preset name.

For example, presets(‘snow’)[‘light’] is SnowSettings(intensity=0.005, wind=0.0, show_info=False, collision=False). Editing it is safe.

resolve_settings(name: str, *, settings: object | None = None, preset: str | None = None, seed: int | None = None) → object | None

Validate a selection without constructing an effect or opening resources.

Explicit settings override a known preset. Unknown presets always raise KeyError with available names. Preset values are copied before use. None leaves the effect constructor responsible for its defaults. A supplied seed overrides the selected EffectSettings on an independent copy. None preserves the seed in the selected settings or preset.

create(name: str, buffer: Buffer, background: str, *, settings: object | None = None, preset: str | None = None, seed: int | 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.