Skip to content

Competence

src.model.competence

Abstract competence model shared by attacks and defenses.

A competence represents an action available to a unit. It defines common metadata such as name, power, effect zone, activation speed, and range, while leaving the activation behavior to concrete subclasses.

The documentation follows Google-style docstrings so tools such as pdoc, Sphinx Napoleon, or MkDocs-based pipelines can expose parameters, return values, and side effects in a consistent HTML API reference.

Competence

Bases: ABC

Abstract base class for all unit competences.

A competence describes an action that has a power value, an effect zone, an activation speed, and a range. Subclasses provide the concrete activation logic for offensive or defensive behavior.

Attributes:

Name Type Description
name str

Display name.
power int

Base strength value.
effect_zone tuple[int, int, int]

Effect-zone constraints.
speed int

Activation or animation speed.
range tuple[int, int, int]

Range constraints.
Notes

This class is documented as part of the public project API and is intended to be readable in generated HTML documentation.

Source code in src\model\competence.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class Competence(ABC):
    """Abstract base class for all unit competences.

    A competence describes an action that has a power value, an effect zone, an
    activation speed, and a range. Subclasses provide the concrete activation logic
    for offensive or defensive behavior.

    Attributes:
        name (str): Display name.
        power (int): Base strength value.
        effect_zone (tuple[int, int, int]): Effect-zone constraints.
        speed (int): Activation or animation speed.
        range (tuple[int, int, int]): Range constraints.

    Notes:
        This class is documented as part of the public project API and is intended to be readable in generated HTML documentation."""

    def __init__(self, name: str, power: int, effect_zone: Tuple[int, int, int], speed: int, range: Tuple[int, int, int]):
        """Initialize shared competence metadata.

        Args:
            name (str): Name identifying the asset, unit, competence, or registered resource.
            power (int): Base numeric strength of the competence.
            effect_zone (Tuple[int, int, int]): Tuple defining the area influenced by the competence.
            speed (int): Movement or playback speed value used by the unit or competence.
            range (Tuple[int, int, int]): Tuple defining vertical, horizontal, and diagonal range constraints.

        Raises:
            ValueError: Raised when provided gameplay configuration values are invalid.

        Side Effects:
            Initializes instance attributes and keeps references to shared runtime objects."""
        if power < 0 or any((dim < 0 for dim in effect_zone + range)) or speed <= 0:
            raise ValueError('Power, effect-zone, range, and speed values must be positive.')
        self.__name = name
        self.__power = power
        self.__effect_zone = effect_zone
        self.__speed = speed
        self.__range = range

    @property
    def name(self):
        """Return the display name.

        Returns:
            str: Display name."""
        return self.__name

    @property
    def power(self):
        """Return the configured power value.

        Returns:
            object: Value produced by the underlying game or rendering operation."""
        return self.__power

    @property
    def effect_zone(self):
        """Return the configured effect zone.

        Returns:
            object: Value produced by the underlying game or rendering operation."""
        return self.__effect_zone

    @property
    def speed(self):
        """Return the speed value.

        Returns:
            int: Configured speed value."""
        return self.__speed

    @property
    def range(self):
        """Return the configured range limits.

        Returns:
            object: Value produced by the underlying game or rendering operation."""
        return self.__range

    def is_within_range(self, user_position: Tuple[int, int], target_position: Tuple[int, int]) -> bool:
        """Check whether a target position is inside the competence range.

        Args:
            user_position (Tuple[int, int]): Source position expressed as an ``(x, y)`` tuple.
            target_position (Tuple[int, int]): Target position expressed as an ``(x, y)`` tuple.

        Returns:
            bool: ``True`` when the target satisfies the competence range constraints."""
        distance_x = abs(target_position[0] - user_position[0])
        distance_y = abs(target_position[1] - user_position[1])
        diagonal_distance = max(distance_x, distance_y)
        in_range = distance_x <= self.range[0] and distance_y <= self.range[1] and (diagonal_distance <= self.range[2])
        print(f'[LOG] Range check: X={distance_x}, Y={distance_y}, Diagonal={diagonal_distance}, Result={in_range}')
        return in_range

    @abstractmethod
    def activate(self, user, target):
        """Activate the competence.

        Subclasses must implement the concrete gameplay behavior.

        Args:
            user: Unit that owns or activates the competence.
            target: Target unit affected by an attack or competence.

        Returns:
            None: This method is executed for its side effects.

        Side Effects:
            Applies gameplay effects defined by the concrete competence.

        Notes:
            Concrete subclasses define whether activation changes health, damage, or visual effects."""
        pass

    def __str__(self):
        """Return a concise debug representation of the object.

        Returns:
            str: Human-readable debug representation of the instance."""
        return f'Competence -- [Name: {self.name} | Power: {self.power} | Zone: {self.effect_zone} | Speed: {self.speed} | Range: {self.range}]'

name property

Return the display name.

Returns:

Name Type Description
str

Display name.

power property

Return the configured power value.

Returns:

Name Type Description
object

Value produced by the underlying game or rendering operation.

effect_zone property

Return the configured effect zone.

Returns:

Name Type Description
object

Value produced by the underlying game or rendering operation.

speed property

Return the speed value.

Returns:

Name Type Description
int

Configured speed value.

range property

Return the configured range limits.

Returns:

Name Type Description
object

Value produced by the underlying game or rendering operation.

is_within_range(user_position, target_position)

Check whether a target position is inside the competence range.

Parameters:

Name Type Description Default
user_position Tuple[int, int]

Source position expressed as an (x, y) tuple.

 required
target_position Tuple[int, int]

Target position expressed as an (x, y) tuple.

 required

Returns:

Name Type Description
bool bool

True when the target satisfies the competence range constraints.
Source code in src\model\competence.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def is_within_range(self, user_position: Tuple[int, int], target_position: Tuple[int, int]) -> bool:
    """Check whether a target position is inside the competence range.

    Args:
        user_position (Tuple[int, int]): Source position expressed as an ``(x, y)`` tuple.
        target_position (Tuple[int, int]): Target position expressed as an ``(x, y)`` tuple.

    Returns:
        bool: ``True`` when the target satisfies the competence range constraints."""
    distance_x = abs(target_position[0] - user_position[0])
    distance_y = abs(target_position[1] - user_position[1])
    diagonal_distance = max(distance_x, distance_y)
    in_range = distance_x <= self.range[0] and distance_y <= self.range[1] and (diagonal_distance <= self.range[2])
    print(f'[LOG] Range check: X={distance_x}, Y={distance_y}, Diagonal={diagonal_distance}, Result={in_range}')
    return in_range

activate(user, target) abstractmethod

Activate the competence.

Subclasses must implement the concrete gameplay behavior.

Parameters:

Name Type Description Default
user

Unit that owns or activates the competence.

 required
target

Target unit affected by an attack or competence.

 required

Returns:

Name Type Description
None

This method is executed for its side effects.
Side Effects

Applies gameplay effects defined by the concrete competence.

Notes

Concrete subclasses define whether activation changes health, damage, or visual effects.

Source code in src\model\competence.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
@abstractmethod
def activate(self, user, target):
    """Activate the competence.

    Subclasses must implement the concrete gameplay behavior.

    Args:
        user: Unit that owns or activates the competence.
        target: Target unit affected by an attack or competence.

    Returns:
        None: This method is executed for its side effects.

    Side Effects:
        Applies gameplay effects defined by the concrete competence.

    Notes:
        Concrete subclasses define whether activation changes health, damage, or visual effects."""
    pass