feat: catalog curated abilities and definitions

src/Domain/AbilityCatalog.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+final class AbilityCatalog
+{
+    /**
+     * @return array<string, AbilityDefinition>
+     */
+    public static function definitions(): array
+    {
+        static $cache = null;
+
+        if ($cache !== null) {
+            return $cache;
+        }
+
+        $cache = [
+            AbilityId::Heal->value => new AbilityDefinition(
+                id: AbilityId::Heal,
+                label: 'Heal',
+                range: 2,
+                areaRadius: 0,
+                target: AbilityDefinition::TARGET_ALLY,
+                effect: AbilityDefinition::EFFECT_RESTORE_HEALTH,
+                effectValue: 5,
+            ),
+            AbilityId::AreaDamage->value => new AbilityDefinition(
+                id: AbilityId::AreaDamage,
+                label: 'Area Damage',
+                range: 3,
+                areaRadius: 1,
+                target: AbilityDefinition::TARGET_TILE,
+                effect: AbilityDefinition::EFFECT_DEAL_DAMAGE,
+                effectValue: 3,
+            ),
+            AbilityId::Buff->value => new AbilityDefinition(
+                id: AbilityId::Buff,
+                label: 'Rally',
+                range: 1,
+                areaRadius: 0,
+                target: AbilityDefinition::TARGET_ALLY,
+                effect: AbilityDefinition::EFFECT_APPLY_BUFF,
+                effectValue: 2,
+            ),
+        ];
+
+        return $cache;
+    }
+}

src/Domain/AbilityDefinition.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+use InvalidArgumentException;
+
+final readonly class AbilityDefinition
+{
+    public const TARGET_SELF = 'self';
+    public const TARGET_ALLY = 'ally';
+    public const TARGET_ENEMY = 'enemy';
+    public const TARGET_TILE = 'tile';
+
+    public const EFFECT_RESTORE_HEALTH = 'restore_health';
+    public const EFFECT_DEAL_DAMAGE = 'deal_damage';
+    public const EFFECT_APPLY_BUFF = 'apply_buff';
+
+    /** @var list<string> */
+    private const TARGETS = [self::TARGET_SELF, self::TARGET_ALLY, self::TARGET_ENEMY, self::TARGET_TILE];
+
+    /** @var list<string> */
+    private const EFFECTS = [self::EFFECT_RESTORE_HEALTH, self::EFFECT_DEAL_DAMAGE, self::EFFECT_APPLY_BUFF];
+
+    public function __construct(
+        public AbilityId $id,
+        public string $label,
+        public int $range,
+        public int $areaRadius,
+        public string $target,
+        public string $effect,
+        public int $effectValue,
+    ) {
+        if ($this->range < 0) {
+            throw new InvalidArgumentException('Ability range cannot be negative.');
+        }
+
+        if ($this->areaRadius < 0) {
+            throw new InvalidArgumentException('Ability area radius cannot be negative.');
+        }
+
+        if (!in_array($this->target, self::TARGETS, true)) {
+            throw new InvalidArgumentException("Unknown ability target: {$this->target}.");
+        }
+
+        if (!in_array($this->effect, self::EFFECTS, true)) {
+            throw new InvalidArgumentException("Unknown ability effect: {$this->effect}.");
+        }
+    }
+}

src/Domain/AbilityId.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BattleForge\Domain;
+
+enum AbilityId: string
+{
+    case Heal = 'heal';
+    case AreaDamage = 'area_damage';
+    case Buff = 'buff';
+}