Combat

com.cupkekgames.combat — turn-based combat framework. Provides CombatUnit (with Health / Mana / Buffs / Shield / StatusEffects / AI sub-systems), CombatActionSO action behaviour-trees, target selection, projectiles, threat tables, and the role-keyed attribute pipeline. Designed to be content-driven: most authoring happens in catalogs and ScriptableObject assets, not code.

Catalog-driven content

All combat content is referenced by CatalogKey (see Data Package), so saved state and authored data live in catalog assets rather than direct SO references. Six framework catalog ids are reserved in CombatConstants:

Domain games can add their own catalogs alongside these; framework code only reads the reserved ids.

Role-keyed attributes

Combat stats are keyed by role (string), not positional index. The reserved roles live in CombatRoles:

CombatAttributeRegistrySO maps each role to the game-specific CupkekGames.RPGStats.AttributeDefinitionSO so domain games choose their own underlying stat schema while combat code stays role-generic. Add custom roles (e.g. Stamina) by registering new entries on the registry.

CombatUnit + sub-systems

CombatUnit wraps a Unit (identity + IUnitFeature composition from CupkekGames.Units) and adds combat-specific sub-systems:

• CombatUnitHealth — HP pool with damage application
• CombatUnitMana — MP pool with action cost gating
• CombatUnitBuffSystem — stat modifiers
• CombatUnitStatusSystem — status effects + tick lifecycle
• CombatUnitShield / CombatUnitShieldNode — layered shields
• CombatUnitAI — turn decision-making
• CombatUnitThreatTable — aggro tracking
• CombatUnitView (MonoBehaviour) — visual side: highlight, hit reaction, AI hookup

Combat-specific data lives on the unit's UnitDefinitionSO as IUnitFeatureDefinition entries (CombatAttributesDefinition, CharacterDefinition).

Actions as behaviour trees

CombatActionSO extends CupkekGames.BehaviourTrees.BehaviourTree. Authored action graphs compose damage / heal / shield / status-effect / projectile / indicator nodes; placeholders like {node3}, {skillLevel}, {range} are substituted at runtime so a single tree powers level-up scaling.

Descriptions

CombatActionSO.Description is plain prose with placeholders and no rich-text tags: {node3} inserts the fragment node 3 produces ("18 (10 + 8) physical damage", "restores 40 health", "stun T2"), {node3_dur} its duration, {skillLevel} and {range} are literal. GetDescription(skillLevel, rules, caster) resolves them; with a caster the numbers include that unit's attribute scaling.

Colours and inline icons are data, never typed by hand. Damage fragments take theirs from the DamageTypeDefinitionSO (display name, rich-text colour, sprite tag, attack and defense attributes). Heal, shield, status and duration fragments read a CombatDescriptionStyleSO that maps each role to a colour and a sprite name in the panel's sprite asset, and owns the number format (bold total, breakdown at a reduced size). Attribute buffs and debuffs use the positive and negative colours of AttributeDisplayConfigSO. Any node can contribute a fragment by implementing ICombatActionNodeDescription, which receives the style.

A style is one surface's set of colours. ICombatRules.DescriptionStyle is the default surface; when the same skills are read somewhere else (a light panel next to dark tooltips, where the tooltip's bright colours would wash out), author a second style with darker shades and pass it: GetDescription(skillLevel, rules, caster, style). Besides its role colours, a style can list a colour per damage type (a type it does not list keeps its own colour) and name the AttributeDisplayConfigSO its buffs and debuffs use (left empty, they use ICombatRules.AttributeDisplayConfig). Calls that pass no style read exactly as before.

CombatTargetSelection is a [SerializeReference] field on each action — drop in a target-selection strategy (single, line, area, all enemies, …) without subclassing.

Status effects via composable behaviors

StatusEffectSO references behavior via the IStatusEffectBehaviorFeature interface composed as [SerializeReference] entries. Multiple behaviors run concurrently with their own OnStart / OnTick / OnEnd hooks. Built-ins:

• DamageOverTimeBehavior — periodic damage tick
• DisableBehavior — block actions for the duration

Add new behaviors by implementing IStatusEffectBehaviorFeature — no SO subclassing.

Extension points

The package never reaches into game-specific systems directly. Bring-your-own:

• ICombatSettings — global combat config (attribute registry, defaults)
• ICombatRules — game-specific rule hooks (turn order, victory conditions)
• ICombatVisualSettings — VFX/SFX bindings
• IAutobattlerSettings — AI heuristics
• ICombatManager — orchestrator (provides IPopupManager, CinemachineManager, IIndicatorPool, etc.)
• ICombatUnitManager — spawning + lifecycle
• IUnitSOProvider — resolves CombatUnitReference → UnitDefinitionSO
• IPowerLevelCalculator — game-specific power scoring
• IDamageModifier / IAttributeModifier — pluggable buff/debuff math

What's inside

• CombatUnit, CombatUnitView, CombatUnitPool, CombatUnitPoolManager, CombatUnitHighlightController
• Sub-systems: CombatUnitHealth, CombatUnitMana, CombatUnitBuffSystem, CombatUnitStatusSystem, CombatUnitShield, CombatUnitAI, CombatUnitThreatTable
• CombatActionSO, CombatActionRunner, CombatActionContext, CombatActionCatalog, action Nodes/
• CombatTargetSelection (+ strategies under TargetSelection/)
• Projectile + ProjectileCollisionHandler
• CombatRoles, CombatAttributeRegistrySO, CombatAttributeDataEffectRuntime, CombatAttributeDataEffectVisual
• StatusEffectSO + IStatusEffectBehaviorFeature (DamageOverTimeBehavior, DisableBehavior)
• FactionSO, FactionCatalog, CombatUnitTierSO, CombatUnitTierCatalog
• CombatConstants (catalog id strings)
• CombatUltimateManager (under Ultimate/), level/rewards under Level/ and Rewards/

Asmdef + namespace

CupkekGames.Combat (runtime).

Dependencies

• com.cupkekgames.units, com.cupkekgames.character, com.cupkekgames.rpgstats
• com.cupkekgames.behaviourtrees, com.cupkekgames.data, com.cupkekgames.services
• com.cupkekgames.timesystem, com.cupkekgames.cameras, com.cupkekgames.shapedrawing, com.cupkekgames.textpopup, com.cupkekgames.vfx, com.cupkekgames.inventory

Repository

Cupkek-Games/CupkekGames-Combat