EffectCharacter

Module: terminaltexteffects.engine.base_character

A class representing a single character from the input data.

EffectCharacters are created and managed by the Terminal and are used to apply animations and effects to individual characters. Additional non-input characters can be created with Terminal.add_character().

Methods:

Name	Description
tick	Progress the character's animation and motion by one step.

Attributes:

Name	Type	Description
character_id	int	The unique ID of the character, generated by the Terminal.
input_symbol	str	The symbol for the character in the input data.
input_coord	Coord	The coordinate of the character in the input data.
is_visible	bool	Whether the character is currently visible and should be printed to the terminal.
animation	Animation	The animation object that controls the character's appearance.
motion	Motion	The motion object that controls the character's movement.
event_handler	EventHandler	The event handler object that handles events related to the character.
layer	int	The layer of the character. The layer determines the order in which characters are printed.
is_fill_character	bool	Whether the character is a fill character. Fill characters are used to fill the empty cells of the Canvas.
uses_input_preexisting_colors	bool	Whether engine-level existing_color_handling="always" should treat this character as input-derived and therefore replace effect-owned colors with the parsed input fg/bg pair, even when that pair is empty.
links	set[EffectCharacter]	Linked neighboring characters used by spanning-tree algorithms.
neighbors	dict[str, EffectCharacter | None]	Adjacent characters keyed by direction ("north", "east", "south", "west").

Source code in terminaltexteffects/engine/base_character.py

class EffectCharacter:
    """A class representing a single character from the input data.

    EffectCharacters are created and managed by the Terminal and are used to apply
    animations and effects to individual characters. Additional non-input characters
    can be created with `Terminal.add_character()`.

    Methods:
        tick: Progress the character's animation and motion by one step.

    Attributes:
        character_id (int): The unique ID of the character, generated by the Terminal.
        input_symbol (str): The symbol for the character in the input data.
        input_coord (Coord): The coordinate of the character in the input data.
        is_visible (bool): Whether the character is currently visible and should be printed to the terminal.
        animation (animation.Animation): The animation object that controls the character's appearance.
        motion (motion.Motion): The motion object that controls the character's movement.
        event_handler (EventHandler): The event handler object that handles events related to the character.
        layer (int): The layer of the character. The layer determines the order in which characters are printed.
        is_fill_character (bool): Whether the character is a fill character. Fill characters are used to fill
            the empty cells of the Canvas.
        uses_input_preexisting_colors (bool): Whether engine-level `existing_color_handling="always"` should treat
            this character as input-derived and therefore replace effect-owned colors with the parsed input fg/bg
            pair, even when that pair is empty.
        links (set[EffectCharacter]): Linked neighboring characters used by spanning-tree algorithms.
        neighbors (dict[str, EffectCharacter | None]): Adjacent characters keyed by direction
            (`"north"`, `"east"`, `"south"`, `"west"`).

    """

    def __init__(self, character_id: int, symbol: str, input_column: int, input_row: int) -> None:
        """Initialize the character instance with the character ID, symbol, and input coordinates.

        Args:
            character_id (int): The unique ID of the character, generated by the Terminal.
            symbol (str): The symbol for the character in the input data.
            input_column (int): The column of the character in the input data.
            input_row (int): The row of the character in the input data.

        """
        self._character_id: int = character_id
        self._input_symbol: str = symbol
        self._input_coord: Coord = Coord(input_column, input_row)
        self._input_ansi_sequences: dict[str, str | None] = {"fg_color": None, "bg_color": None}
        self._is_visible: bool = False
        self.animation: animation.Animation = animation.Animation(self)
        self.motion: motion.Motion = motion.Motion(self)
        self.event_handler: EventHandler = EventHandler(self)
        self.layer: int = 0
        self.is_fill_character = False
        self.uses_input_preexisting_colors = False
        self.links: set[EffectCharacter] = set()
        self.neighbors: dict[str, EffectCharacter | None] = {}

    @property
    def input_symbol(self) -> str:
        """The symbol for the character in the input data."""
        return self._input_symbol

    @property
    def input_coord(self) -> Coord:
        """The coordinate of the character in the input data."""
        return self._input_coord

    @property
    def is_visible(self) -> bool:
        """Whether the character is currently visible and should be printed to the terminal."""
        return self._is_visible

    @property
    def character_id(self) -> int:
        """The unique ID of the character, generated by the Terminal."""
        return self._character_id

    @property
    def is_active(self) -> bool:
        """Returns whether the character is currently active.

        A character is active when its animation has an incomplete active scene or its
        motion has an incomplete active path.

        Returns:
            bool: True if the character is active, False if not.

        """
        return bool(not self.animation.active_scene_is_complete() or not self.motion.movement_is_complete())

    def tick(self) -> None:
        """Progress the character by one tick.

        Motion is advanced first, then animation is stepped so animation logic can react
        to the character's updated motion state for the same tick.
        """
        self.motion.move()
        self.animation.step_animation()

    def _link(self, char: EffectCharacter, *, bidirectional: bool = True) -> None:
        """Link this character with another character.

        Used for spanning-tree algorithms. When `bidirectional` is True, the reverse link
        is added to `char` as well. Links are stored in a set, so repeated links are
        idempotent.

        Args:
            char (EffectCharacter): Character being linked to this character.
            bidirectional (bool, optional): Apply the link on both characters. Defaults to True.

        """
        if bidirectional:
            char._link(self, bidirectional=False)
        self.links.add(char)

    def __hash__(self) -> int:
        """Return the hash value of the character."""
        return hash(self.character_id)

    def __eq__(self, other: object) -> bool:
        """Check if two EffectCharacter instances are equal based on their character_id."""
        if not isinstance(other, EffectCharacter):
            return NotImplemented
        return self.character_id == other.character_id

    def __repr__(self) -> str:
        """Return a string representation of the EffectCharacter instance."""
        return (
            f"EffectCharacter(character_id={self.character_id}, symbol='{self.input_symbol}', "
            f"input_column={self.input_coord.column}, input_row={self.input_coord.row})"
        )

character_id property

The unique ID of the character, generated by the Terminal.

input_coord property

The coordinate of the character in the input data.

input_symbol property

The symbol for the character in the input data.

is_active property

Returns whether the character is currently active.

A character is active when its animation has an incomplete active scene or its motion has an incomplete active path.

Returns:

Name	Type	Description
bool	bool	True if the character is active, False if not.

is_visible property

Whether the character is currently visible and should be printed to the terminal.

__eq__(other)

Check if two EffectCharacter instances are equal based on their character_id.

Source code in terminaltexteffects/engine/base_character.py

def __eq__(self, other: object) -> bool:
    """Check if two EffectCharacter instances are equal based on their character_id."""
    if not isinstance(other, EffectCharacter):
        return NotImplemented
    return self.character_id == other.character_id

__hash__()

Return the hash value of the character.

Source code in terminaltexteffects/engine/base_character.py

def __hash__(self) -> int:
    """Return the hash value of the character."""
    return hash(self.character_id)

__init__(character_id, symbol, input_column, input_row)

Initialize the character instance with the character ID, symbol, and input coordinates.

Parameters:

Name	Type	Description	Default
character_id	int	The unique ID of the character, generated by the Terminal.	required
symbol	str	The symbol for the character in the input data.	required
input_column	int	The column of the character in the input data.	required
input_row	int	The row of the character in the input data.	required

Source code in terminaltexteffects/engine/base_character.py

def __init__(self, character_id: int, symbol: str, input_column: int, input_row: int) -> None:
    """Initialize the character instance with the character ID, symbol, and input coordinates.

    Args:
        character_id (int): The unique ID of the character, generated by the Terminal.
        symbol (str): The symbol for the character in the input data.
        input_column (int): The column of the character in the input data.
        input_row (int): The row of the character in the input data.

    """
    self._character_id: int = character_id
    self._input_symbol: str = symbol
    self._input_coord: Coord = Coord(input_column, input_row)
    self._input_ansi_sequences: dict[str, str | None] = {"fg_color": None, "bg_color": None}
    self._is_visible: bool = False
    self.animation: animation.Animation = animation.Animation(self)
    self.motion: motion.Motion = motion.Motion(self)
    self.event_handler: EventHandler = EventHandler(self)
    self.layer: int = 0
    self.is_fill_character = False
    self.uses_input_preexisting_colors = False
    self.links: set[EffectCharacter] = set()
    self.neighbors: dict[str, EffectCharacter | None] = {}

__repr__()

Return a string representation of the EffectCharacter instance.

Source code in terminaltexteffects/engine/base_character.py

def __repr__(self) -> str:
    """Return a string representation of the EffectCharacter instance."""
    return (
        f"EffectCharacter(character_id={self.character_id}, symbol='{self.input_symbol}', "
        f"input_column={self.input_coord.column}, input_row={self.input_coord.row})"
    )

tick()

Progress the character by one tick.

Motion is advanced first, then animation is stepped so animation logic can react to the character's updated motion state for the same tick.

Source code in terminaltexteffects/engine/base_character.py

def tick(self) -> None:
    """Progress the character by one tick.

    Motion is advanced first, then animation is stepped so animation logic can react
    to the character's updated motion state for the same tick.
    """
    self.motion.move()
    self.animation.step_animation()