EventHandler

Module: terminaltexteffects.engine.base_character

Register and handle events related to a character.

Events related to character state changes (e.g. scene complete) can be registered with the EventHandler. When an event is triggered, the EventHandler will take the specified action (e.g. activate a Path). The EventHandler is used by the EffectCharacter class to handle events related to the character.

Attributes:

Name	Type	Description
character	EffectCharacter	The character whose events are handled by this EventHandler.
registered_events	dict[tuple[Event, Scene | Waypoint | Path | Mount], list[tuple[Action, Scene | Waypoint | Path | Mount | int | Coord | Callback | str | None]]]	Registered event/action mappings keyed by the triggering event and caller object.

Note

SEGMENT_ENTERED/EXITED events will trigger the first time the character enters or exits a segment. If looping, each loop will trigger the event, but not backwards motion as is possible with the bounce easing functions.

Source code in terminaltexteffects/engine/base_character.py

class EventHandler:
    """Register and handle events related to a character.

    Events related to character state changes (e.g. scene complete) can be registered with the EventHandler.
    When an event is triggered, the EventHandler will take the specified action (e.g. activate a Path).
    The EventHandler is used by the EffectCharacter class to handle events related to the character.

    Attributes:
        character (EffectCharacter): The character whose events are handled by this EventHandler.
        registered_events: Registered event/action mappings keyed by the triggering event and caller object.

    Note:
        SEGMENT_ENTERED/EXITED events will trigger the first time the character enters or exits a segment.
        If looping, each loop will trigger the event, but not backwards motion as is possible with
        the bounce easing functions.

    """

    def __init__(self, character: EffectCharacter) -> None:
        """Initialize the instance with the EffectCharacter object.

        Args:
            character (EffectCharacter): The character for which the EventHandler is handling events.

        """
        self.character = character
        self.registered_events: dict[
            tuple[EventHandler.Event, animation.Scene | motion.Waypoint | motion.Path | space3d.Mount],
            list[
                tuple[
                    EventHandler.Action,
                    animation.Scene
                    | motion.Waypoint
                    | motion.Path
                    | space3d.Mount
                    | int
                    | Coord
                    | EventHandler.Callback
                    | str
                    | None,
                ]
            ],
        ] = {}

    class Event(Enum):
        """An Event that can be registered with the EventHandler.

        Register Events with the EventHandler using the register_event method of the EventHandler class.

        Attributes:
            SEGMENT_ENTERED (Event): A path segment has been entered.
            SEGMENT_EXITED (Event): A path segment has been exited.
            PATH_ACTIVATED (Event): A path has been activated.
            PATH_COMPLETE (Event): A path has been completed.
            PATH_HOLDING (Event): A path has entered the holding state.
            SCENE_ACTIVATED (Event): An animation scene has been activated.
            SCENE_COMPLETE (Event): An animation scene has completed.
            MOUNT_COMPLETE (Event): A 3D mount has finished blending, so the character rides its anchor. The
                caller is the `Mount`.
            MOUNT_RELEASED (Event): The character has been released from a 3D mount. The caller is the `Mount`.

        """

        SEGMENT_ENTERED = auto()
        SEGMENT_EXITED = auto()
        PATH_ACTIVATED = auto()
        PATH_COMPLETE = auto()
        PATH_HOLDING = auto()
        SCENE_ACTIVATED = auto()
        SCENE_COMPLETE = auto()
        MOUNT_COMPLETE = auto()
        MOUNT_RELEASED = auto()

    class Action(Enum):
        """Actions that can be taken when an event is triggered.

        An Action is taken when an Event is triggered. Register Actions with the EventHandler using the
        register_event method of the EventHandler class.

        Attributes:
            ACTIVATE_PATH (Action): Activates a path. The action target is the path itself or its ID.
            ACTIVATE_SCENE (Action): Activates an animation scene. The action target is the scene itself or its ID.
            DEACTIVATE_PATH (Action): Deactivates a path. The action target is the path itself, its ID,
                or None to deactivate the currently active path.
            DEACTIVATE_SCENE (Action): Deactivates an animation scene. The action target is the scene itself,
                its ID, or None to deactivate the currently active scene.
            RESET_APPEARANCE (Action): Resets the appearance of the character to the input symbol and color.
            SET_LAYER (Action): Sets the layer of the character. The action target is the layer number.
            SET_COORDINATE (Action): Sets the coordinate of the character. The action target is the coordinate.
            CALLBACK (Action): Calls a callback function. The action target is an EventHandler.Callback object.
            MOUNT (Action): Mounts the character on a 3D anchor. The action target is a `Mount` made with
                `Space3D.new_mount`.
            UNMOUNT (Action): Releases the character from its 3D mount. The action target is the `Mount`, or None
                to release any active mount.

        """

        ACTIVATE_PATH = auto()
        ACTIVATE_SCENE = auto()
        DEACTIVATE_PATH = auto()
        DEACTIVATE_SCENE = auto()
        RESET_APPEARANCE = auto()
        SET_LAYER = auto()
        SET_COORDINATE = auto()
        CALLBACK = auto()
        MOUNT = auto()
        UNMOUNT = auto()

    @dataclass(init=False)
    class Callback:
        """A callback action target that can be taken when an event is triggered.

        Register callback actions with the EventHandler using the register_event method of the EventHandler class.

        The callback function will be called with the character and any additional arguments when the event
        is triggered. The character will be the first argument passed to the callback function followed by any
        additional arguments in the order they were passed to the Callback object.

        Example:
            Create a callback to set the character's visibility to False. The following code would be
            used within an effect where 'self' is the EffectIterator instance:

                cb = EventHandler.Callback(lambda c: self.terminal.set_character_visibility(c, is_visible=False))

        """

        callback: typing.Callable
        args: tuple[typing.Any, ...]

        def __init__(self, callback: typing.Callable, *args: typing.Any) -> None:
            """Initialize the instance with the callback function and arguments.

            Args:
                callback (typing.Callable): The callback function to call.
                args (tuple[typing.Any,...]): A tuple of arguments to pass to the callback function. The first argument
                    will be the character, followed by any additional arguments.

            """
            self.callback = callback
            self.args = args

    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.ACTIVATE_SCENE],
        target: animation.Scene | str,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.DEACTIVATE_SCENE],
        target: animation.Scene | str | None = ...,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.ACTIVATE_PATH],
        target: motion.Path | str,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.DEACTIVATE_PATH],
        target: motion.Path | str | None = ...,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.SET_COORDINATE],
        target: Coord,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.SET_LAYER],
        target: int,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.CALLBACK],
        target: Callback,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.RESET_APPEARANCE],
        target: None = None,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.MOUNT],
        target: space3d.Mount,
    ) -> None: ...
    @typing.overload
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: typing.Literal[Action.UNMOUNT],
        target: space3d.Mount | None = ...,
    ) -> None: ...
    def register_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
        action: Action,
        target: animation.Scene | motion.Path | space3d.Mount | int | Coord | Callback | str | None = None,
    ) -> None:
        """Register an event to be handled by the EventHandler.

        Note: Action.RESET_APPEARANCE does not accept a target.
        For `PATH_ACTIVATED`, `PATH_COMPLETE`, `SCENE_ACTIVATED`, and `SCENE_COMPLETE`,
        `caller` may be the triggering object itself or its registered ID string.
        `PATH_HOLDING` and segment events require their corresponding object instances.
        For `ACTIVATE_PATH`, `DEACTIVATE_PATH`, `ACTIVATE_SCENE`, and `DEACTIVATE_SCENE`,
        string targets are resolved from registered path or scene IDs. `DEACTIVATE_PATH`,
        `DEACTIVATE_SCENE`, `UNMOUNT`, and `RESET_APPEARANCE` may use `None` where supported by the action.
        `MOUNT_COMPLETE` and `MOUNT_RELEASED` take the `Mount` as the caller.

        Args:
            event (Event): The event to register.
            caller (animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str): The object that triggers
                the event.
            action (Action): The action to take when the event is triggered.
            target (animation.Scene | motion.Path | space3d.Mount | int | Coord | Callback | str | None): The target
                of the action.

        Raises:
            EventRegistrationCallerError: If the caller object is not the required type for the
                specified event.
            EventRegistrationTargetError: If the target is not the correct type for the action or if
                ``Action.RESET_APPEARANCE`` is provided with a target.
            DuplicateEventRegistrationError: If the exact same event-caller-action-target combination
                has already been registered.

        Example:
            Register an event to activate a scene when a Path is complete:
            `event_handler.register_event(EventHandler.Event.PATH_COMPLETE, some_path,
                EventHandler.Action.ACTIVATE_SCENE, some_scene)`

        """
        # find caller Path when provided path_id
        if event in (EventHandler.Event.PATH_ACTIVATED, EventHandler.Event.PATH_COMPLETE) and isinstance(caller, str):
            if (path_query_result := self.character.motion.query_path(caller)) is None:
                raise PathNotFoundError(path_id=caller)
            caller = path_query_result

        # find caller Scene when provided scene_id
        elif event in (EventHandler.Event.SCENE_ACTIVATED, EventHandler.Event.SCENE_COMPLETE) and isinstance(
            caller,
            str,
        ):
            if (scene_query_result := self.character.animation.query_scene(caller)) is None:
                raise SceneNotFoundError(scene_id=caller)
            caller = scene_query_result

        if _EVENT_CALLER_TYPES[event] != caller.__class__:
            raise EventRegistrationCallerError(event, caller, _EVENT_CALLER_TYPES[event])

        # find target Path when provided path_id
        if action in (EventHandler.Action.ACTIVATE_PATH, EventHandler.Action.DEACTIVATE_PATH) and isinstance(
            target,
            str,
        ):
            if (path_query_result := self.character.motion.query_path(target)) is None:
                raise PathNotFoundError(path_id=target)
            target = path_query_result

        # find target Scene when provided scene_id
        elif action in (EventHandler.Action.ACTIVATE_SCENE, EventHandler.Action.DEACTIVATE_SCENE) and isinstance(
            target,
            str,
        ):
            if (scene_query_result := self.character.animation.query_scene(target)) is None:
                raise SceneNotFoundError(scene_id=target)
            target = scene_query_result

        elif (
            action
            in (EventHandler.Action.DEACTIVATE_PATH, EventHandler.Action.DEACTIVATE_SCENE, EventHandler.Action.UNMOUNT)
            and target is None
        ):
            pass

        elif (action is EventHandler.Action.RESET_APPEARANCE and target is not None) or (
            _ACTION_TARGET_TYPES[action] != target.__class__
        ):
            raise EventRegistrationTargetError(action, target, _ACTION_TARGET_TYPES[action])

        assert isinstance(caller, (motion.Path, animation.Scene, motion.Waypoint, space3d.Mount))
        new_event = (event, caller)
        new_action = (action, target)

        if new_event not in self.registered_events:
            self.registered_events[new_event] = []

        # Check for duplicate event-action-target combination
        if new_action in self.registered_events[new_event]:
            raise DuplicateEventRegistrationError(event, caller, action, target)

        self.registered_events[new_event].append(new_action)

    def _handle_event(
        self,
        event: Event,
        caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount,
    ) -> None:
        """Handle a registered event by executing all associated actions.

        This method processes an event triggered by a caller object (Scene, Waypoint, or Path) and
        executes all actions that were registered for this specific event-caller combination. If no
        actions are registered for the given event and caller, the method returns without doing anything.

        The method supports the following action types:
        - ACTIVATE_PATH: Activates a motion path for the character
        - ACTIVATE_SCENE: Activates an animation scene for the character
        - DEACTIVATE_PATH: Deactivates a specific motion path or, when the target is `None`,
          the currently active path
        - DEACTIVATE_SCENE: Deactivates a specific animation scene or, when the target is `None`,
          the currently active scene
        - RESET_APPEARANCE: Resets the character's appearance to its input symbol and,
          where applicable, its configured input colors
        - SET_LAYER: Sets the character's rendering layer
        - SET_COORDINATE: Sets the character's current coordinate
        - CALLBACK: Executes a custom callback function with the character and additional arguments
        - MOUNT: Mounts the character on a 3D anchor
        - UNMOUNT: Releases a specific mount or, when the target is `None`, any active mount

        Args:
            event (Event): The event to handle. Must be one of the Event enum values.
            caller (animation.Scene | motion.Waypoint | motion.Path | space3d.Mount): The object that triggered the
                event.
                The caller type must match the expected type for the given event (e.g., PATH_COMPLETE
                events must be triggered by motion.Path objects).

        Note:
            This method is typically called internally by the animation and motion systems when
            specific state changes occur. Events and their associated actions are registered using
            the register_event method.

        Example:
            When `Event.PATH_COMPLETE` is triggered for a registered path caller, all
            actions registered for that event/caller pair are executed in order.

        """
        event_actions = self.registered_events.get((event, caller))
        if event_actions is None:
            return
        for action, target in event_actions:
            if action is EventHandler.Action.ACTIVATE_PATH:
                self.character.motion.activate_path(target)  # type: ignore[arg-type]
            elif action is EventHandler.Action.ACTIVATE_SCENE:
                self.character.animation.activate_scene(target)  # type: ignore[arg-type]
            elif action is EventHandler.Action.DEACTIVATE_PATH:
                if target is None:
                    self.character.motion.deactivate_path()
                else:
                    self.character.motion.deactivate_path(target)  # type: ignore[arg-type]
            elif action is EventHandler.Action.DEACTIVATE_SCENE:
                if target is None:
                    self.character.animation.deactivate_scene()
                else:
                    self.character.animation.deactivate_scene(target)  # type: ignore[arg-type]
            elif action is EventHandler.Action.RESET_APPEARANCE:
                self.character.animation.set_appearance(self.character.input_symbol)
            elif action is EventHandler.Action.SET_LAYER:
                self.character.layer = target  # type: ignore[assignment]
            elif action is EventHandler.Action.SET_COORDINATE:
                self.character.motion.current_coord = target  # type: ignore[assignment]
            elif action is EventHandler.Action.CALLBACK:
                target.callback(self.character, *target.args)  # type: ignore[union-attr]
            elif action is EventHandler.Action.MOUNT:
                self.character.motion.activate_mount(target)  # type: ignore[arg-type]
            elif action is EventHandler.Action.UNMOUNT:
                self.character.motion.deactivate_mount(target)  # type: ignore[arg-type]

Action

Bases: Enum

Actions that can be taken when an event is triggered.

An Action is taken when an Event is triggered. Register Actions with the EventHandler using the register_event method of the EventHandler class.

Attributes:

Name	Type	Description
ACTIVATE_PATH	Action	Activates a path. The action target is the path itself or its ID.
ACTIVATE_SCENE	Action	Activates an animation scene. The action target is the scene itself or its ID.
DEACTIVATE_PATH	Action	Deactivates a path. The action target is the path itself, its ID, or None to deactivate the currently active path.
DEACTIVATE_SCENE	Action	Deactivates an animation scene. The action target is the scene itself, its ID, or None to deactivate the currently active scene.
RESET_APPEARANCE	Action	Resets the appearance of the character to the input symbol and color.
SET_LAYER	Action	Sets the layer of the character. The action target is the layer number.
SET_COORDINATE	Action	Sets the coordinate of the character. The action target is the coordinate.
CALLBACK	Action	Calls a callback function. The action target is an EventHandler.Callback object.
MOUNT	Action	Mounts the character on a 3D anchor. The action target is a Mount made with Space3D.new_mount.
UNMOUNT	Action	Releases the character from its 3D mount. The action target is the Mount, or None to release any active mount.

Source code in terminaltexteffects/engine/base_character.py

class Action(Enum):
    """Actions that can be taken when an event is triggered.

    An Action is taken when an Event is triggered. Register Actions with the EventHandler using the
    register_event method of the EventHandler class.

    Attributes:
        ACTIVATE_PATH (Action): Activates a path. The action target is the path itself or its ID.
        ACTIVATE_SCENE (Action): Activates an animation scene. The action target is the scene itself or its ID.
        DEACTIVATE_PATH (Action): Deactivates a path. The action target is the path itself, its ID,
            or None to deactivate the currently active path.
        DEACTIVATE_SCENE (Action): Deactivates an animation scene. The action target is the scene itself,
            its ID, or None to deactivate the currently active scene.
        RESET_APPEARANCE (Action): Resets the appearance of the character to the input symbol and color.
        SET_LAYER (Action): Sets the layer of the character. The action target is the layer number.
        SET_COORDINATE (Action): Sets the coordinate of the character. The action target is the coordinate.
        CALLBACK (Action): Calls a callback function. The action target is an EventHandler.Callback object.
        MOUNT (Action): Mounts the character on a 3D anchor. The action target is a `Mount` made with
            `Space3D.new_mount`.
        UNMOUNT (Action): Releases the character from its 3D mount. The action target is the `Mount`, or None
            to release any active mount.

    """

    ACTIVATE_PATH = auto()
    ACTIVATE_SCENE = auto()
    DEACTIVATE_PATH = auto()
    DEACTIVATE_SCENE = auto()
    RESET_APPEARANCE = auto()
    SET_LAYER = auto()
    SET_COORDINATE = auto()
    CALLBACK = auto()
    MOUNT = auto()
    UNMOUNT = auto()

Callback dataclass

A callback action target that can be taken when an event is triggered.

Register callback actions with the EventHandler using the register_event method of the EventHandler class.

The callback function will be called with the character and any additional arguments when the event is triggered. The character will be the first argument passed to the callback function followed by any additional arguments in the order they were passed to the Callback object.

Example

Create a callback to set the character's visibility to False. The following code would be used within an effect where 'self' is the EffectIterator instance:

cb = EventHandler.Callback(lambda c: self.terminal.set_character_visibility(c, is_visible=False))

Source code in terminaltexteffects/engine/base_character.py

@dataclass(init=False)
class Callback:
    """A callback action target that can be taken when an event is triggered.

    Register callback actions with the EventHandler using the register_event method of the EventHandler class.

    The callback function will be called with the character and any additional arguments when the event
    is triggered. The character will be the first argument passed to the callback function followed by any
    additional arguments in the order they were passed to the Callback object.

    Example:
        Create a callback to set the character's visibility to False. The following code would be
        used within an effect where 'self' is the EffectIterator instance:

            cb = EventHandler.Callback(lambda c: self.terminal.set_character_visibility(c, is_visible=False))

    """

    callback: typing.Callable
    args: tuple[typing.Any, ...]

    def __init__(self, callback: typing.Callable, *args: typing.Any) -> None:
        """Initialize the instance with the callback function and arguments.

        Args:
            callback (typing.Callable): The callback function to call.
            args (tuple[typing.Any,...]): A tuple of arguments to pass to the callback function. The first argument
                will be the character, followed by any additional arguments.

        """
        self.callback = callback
        self.args = args

__init__(callback, *args)

Initialize the instance with the callback function and arguments.

Parameters:

Name	Type	Description	Default
callback	Callable	The callback function to call.	required
args	tuple[Any, ...]	A tuple of arguments to pass to the callback function. The first argument will be the character, followed by any additional arguments.	()

Source code in terminaltexteffects/engine/base_character.py

def __init__(self, callback: typing.Callable, *args: typing.Any) -> None:
    """Initialize the instance with the callback function and arguments.

    Args:
        callback (typing.Callable): The callback function to call.
        args (tuple[typing.Any,...]): A tuple of arguments to pass to the callback function. The first argument
            will be the character, followed by any additional arguments.

    """
    self.callback = callback
    self.args = args

Event

Bases: Enum

An Event that can be registered with the EventHandler.

Register Events with the EventHandler using the register_event method of the EventHandler class.

Attributes:

Name	Type	Description
SEGMENT_ENTERED	Event	A path segment has been entered.
SEGMENT_EXITED	Event	A path segment has been exited.
PATH_ACTIVATED	Event	A path has been activated.
PATH_COMPLETE	Event	A path has been completed.
PATH_HOLDING	Event	A path has entered the holding state.
SCENE_ACTIVATED	Event	An animation scene has been activated.
SCENE_COMPLETE	Event	An animation scene has completed.
MOUNT_COMPLETE	Event	A 3D mount has finished blending, so the character rides its anchor. The caller is the Mount.
MOUNT_RELEASED	Event	The character has been released from a 3D mount. The caller is the Mount.

Source code in terminaltexteffects/engine/base_character.py

class Event(Enum):
    """An Event that can be registered with the EventHandler.

    Register Events with the EventHandler using the register_event method of the EventHandler class.

    Attributes:
        SEGMENT_ENTERED (Event): A path segment has been entered.
        SEGMENT_EXITED (Event): A path segment has been exited.
        PATH_ACTIVATED (Event): A path has been activated.
        PATH_COMPLETE (Event): A path has been completed.
        PATH_HOLDING (Event): A path has entered the holding state.
        SCENE_ACTIVATED (Event): An animation scene has been activated.
        SCENE_COMPLETE (Event): An animation scene has completed.
        MOUNT_COMPLETE (Event): A 3D mount has finished blending, so the character rides its anchor. The
            caller is the `Mount`.
        MOUNT_RELEASED (Event): The character has been released from a 3D mount. The caller is the `Mount`.

    """

    SEGMENT_ENTERED = auto()
    SEGMENT_EXITED = auto()
    PATH_ACTIVATED = auto()
    PATH_COMPLETE = auto()
    PATH_HOLDING = auto()
    SCENE_ACTIVATED = auto()
    SCENE_COMPLETE = auto()
    MOUNT_COMPLETE = auto()
    MOUNT_RELEASED = auto()

__init__(character)

Initialize the instance with the EffectCharacter object.

Parameters:

Name	Type	Description	Default
character	EffectCharacter	The character for which the EventHandler is handling events.	required

Source code in terminaltexteffects/engine/base_character.py

def __init__(self, character: EffectCharacter) -> None:
    """Initialize the instance with the EffectCharacter object.

    Args:
        character (EffectCharacter): The character for which the EventHandler is handling events.

    """
    self.character = character
    self.registered_events: dict[
        tuple[EventHandler.Event, animation.Scene | motion.Waypoint | motion.Path | space3d.Mount],
        list[
            tuple[
                EventHandler.Action,
                animation.Scene
                | motion.Waypoint
                | motion.Path
                | space3d.Mount
                | int
                | Coord
                | EventHandler.Callback
                | str
                | None,
            ]
        ],
    ] = {}

register_event(event, caller, action, target=None)

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.ACTIVATE_SCENE],
    target: animation.Scene | str,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.DEACTIVATE_SCENE],
    target: animation.Scene | str | None = ...,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.ACTIVATE_PATH],
    target: motion.Path | str,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.DEACTIVATE_PATH],
    target: motion.Path | str | None = ...,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.SET_COORDINATE],
    target: Coord,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.SET_LAYER],
    target: int,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.CALLBACK],
    target: Callback,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.RESET_APPEARANCE],
    target: None = None,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.MOUNT],
    target: space3d.Mount,
) -> None

register_event(
    event: Event,
    caller: animation.Scene
    | motion.Waypoint
    | motion.Path
    | space3d.Mount
    | str,
    action: typing.Literal[Action.UNMOUNT],
    target: space3d.Mount | None = ...,
) -> None

Register an event to be handled by the EventHandler.

Note: Action.RESET_APPEARANCE does not accept a target. For PATH_ACTIVATED, PATH_COMPLETE, SCENE_ACTIVATED, and SCENE_COMPLETE, caller may be the triggering object itself or its registered ID string. PATH_HOLDING and segment events require their corresponding object instances. For ACTIVATE_PATH, DEACTIVATE_PATH, ACTIVATE_SCENE, and DEACTIVATE_SCENE, string targets are resolved from registered path or scene IDs. DEACTIVATE_PATH, DEACTIVATE_SCENE, UNMOUNT, and RESET_APPEARANCE may use None where supported by the action. MOUNT_COMPLETE and MOUNT_RELEASED take the Mount as the caller.

Parameters:

Name	Type	Description	Default
event	Event	The event to register.	required
caller	Scene | Waypoint | Path | Mount | str	The object that triggers the event.	required
action	Action	The action to take when the event is triggered.	required
target	Scene | Path | Mount | int | Coord | Callback | str | None	The target of the action.	None

Raises:

Type	Description
EventRegistrationCallerError	If the caller object is not the required type for the specified event.
EventRegistrationTargetError	If the target is not the correct type for the action or if Action.RESET_APPEARANCE is provided with a target.
DuplicateEventRegistrationError	If the exact same event-caller-action-target combination has already been registered.

Example

Register an event to activate a scene when a Path is complete: event_handler.register_event(EventHandler.Event.PATH_COMPLETE, some_path, EventHandler.Action.ACTIVATE_SCENE, some_scene)

Source code in terminaltexteffects/engine/base_character.py

def register_event(
    self,
    event: Event,
    caller: animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str,
    action: Action,
    target: animation.Scene | motion.Path | space3d.Mount | int | Coord | Callback | str | None = None,
) -> None:
    """Register an event to be handled by the EventHandler.

    Note: Action.RESET_APPEARANCE does not accept a target.
    For `PATH_ACTIVATED`, `PATH_COMPLETE`, `SCENE_ACTIVATED`, and `SCENE_COMPLETE`,
    `caller` may be the triggering object itself or its registered ID string.
    `PATH_HOLDING` and segment events require their corresponding object instances.
    For `ACTIVATE_PATH`, `DEACTIVATE_PATH`, `ACTIVATE_SCENE`, and `DEACTIVATE_SCENE`,
    string targets are resolved from registered path or scene IDs. `DEACTIVATE_PATH`,
    `DEACTIVATE_SCENE`, `UNMOUNT`, and `RESET_APPEARANCE` may use `None` where supported by the action.
    `MOUNT_COMPLETE` and `MOUNT_RELEASED` take the `Mount` as the caller.

    Args:
        event (Event): The event to register.
        caller (animation.Scene | motion.Waypoint | motion.Path | space3d.Mount | str): The object that triggers
            the event.
        action (Action): The action to take when the event is triggered.
        target (animation.Scene | motion.Path | space3d.Mount | int | Coord | Callback | str | None): The target
            of the action.

    Raises:
        EventRegistrationCallerError: If the caller object is not the required type for the
            specified event.
        EventRegistrationTargetError: If the target is not the correct type for the action or if
            ``Action.RESET_APPEARANCE`` is provided with a target.
        DuplicateEventRegistrationError: If the exact same event-caller-action-target combination
            has already been registered.

    Example:
        Register an event to activate a scene when a Path is complete:
        `event_handler.register_event(EventHandler.Event.PATH_COMPLETE, some_path,
            EventHandler.Action.ACTIVATE_SCENE, some_scene)`

    """
    # find caller Path when provided path_id
    if event in (EventHandler.Event.PATH_ACTIVATED, EventHandler.Event.PATH_COMPLETE) and isinstance(caller, str):
        if (path_query_result := self.character.motion.query_path(caller)) is None:
            raise PathNotFoundError(path_id=caller)
        caller = path_query_result

    # find caller Scene when provided scene_id
    elif event in (EventHandler.Event.SCENE_ACTIVATED, EventHandler.Event.SCENE_COMPLETE) and isinstance(
        caller,
        str,
    ):
        if (scene_query_result := self.character.animation.query_scene(caller)) is None:
            raise SceneNotFoundError(scene_id=caller)
        caller = scene_query_result

    if _EVENT_CALLER_TYPES[event] != caller.__class__:
        raise EventRegistrationCallerError(event, caller, _EVENT_CALLER_TYPES[event])

    # find target Path when provided path_id
    if action in (EventHandler.Action.ACTIVATE_PATH, EventHandler.Action.DEACTIVATE_PATH) and isinstance(
        target,
        str,
    ):
        if (path_query_result := self.character.motion.query_path(target)) is None:
            raise PathNotFoundError(path_id=target)
        target = path_query_result

    # find target Scene when provided scene_id
    elif action in (EventHandler.Action.ACTIVATE_SCENE, EventHandler.Action.DEACTIVATE_SCENE) and isinstance(
        target,
        str,
    ):
        if (scene_query_result := self.character.animation.query_scene(target)) is None:
            raise SceneNotFoundError(scene_id=target)
        target = scene_query_result

    elif (
        action
        in (EventHandler.Action.DEACTIVATE_PATH, EventHandler.Action.DEACTIVATE_SCENE, EventHandler.Action.UNMOUNT)
        and target is None
    ):
        pass

    elif (action is EventHandler.Action.RESET_APPEARANCE and target is not None) or (
        _ACTION_TARGET_TYPES[action] != target.__class__
    ):
        raise EventRegistrationTargetError(action, target, _ACTION_TARGET_TYPES[action])

    assert isinstance(caller, (motion.Path, animation.Scene, motion.Waypoint, space3d.Mount))
    new_event = (event, caller)
    new_action = (action, target)

    if new_event not in self.registered_events:
        self.registered_events[new_event] = []

    # Check for duplicate event-action-target combination
    if new_action in self.registered_events[new_event]:
        raise DuplicateEventRegistrationError(event, caller, action, target)

    self.registered_events[new_event].append(new_action)