API Reference

ICombatant Interface

The interface users implement for their characters and enemies. Battle never modifies combatants directly — it calls TakeDamage() and Heal(), and your implementation decides what that means.

Member	Type	Description
Name	string (get)	Display name
IsAlive	bool (get)	Whether combatant is alive
Team	int (get)	Team identifier (0 = player)
Speed	float (get)	Speed stat for turn order
TakeDamage(int amount)	void	Reduce HP by amount
Heal(int amount)	void	Restore HP by amount

ITurnSystem Interface

The interface for turn order logic. Implement this to create custom turn systems, or use one of the built-in implementations.

Member	Type	Description
Init(List<ICombatant> combatants)	void	Initialize with combatant list
GetNextActor()	ICombatant	Get next combatant to act
GetTimeline()	IReadOnlyList<ICombatant>	Predicted turn order
OnActorDied(ICombatant)	void	Notify of combatant death
OnActorAdded(ICombatant)	void	Notify of combatant addition
OnTurnEnd()	void	Notify turn completed

Battle — Properties

Property	Type	Description
State	BattleState	Current battle state
TurnNumber	int	Current turn count
Combatants	List<ICombatant>	All combatants
TurnSystem	ITurnSystem	Active turn system
CurrentActor	ICombatant	Current acting combatant
Result	BattleResult?	Result after battle ends
History	IReadOnlyList<BattleHistoryEntry>	All recorded events

Battle — Methods

Method	Returns	Description
Start(List<ICombatant>, ITurnSystem)	void	Start battle
EndBattle(BattleState)	void	End battle with result
BeginNextTurn()	ICombatant	Start next turn, returns actor
EndTurn()	void	End current turn
DealDamage(ICombatant source, ICombatant target, int amount, string damageType = "", string element = "", bool isCrit = false)	void	Deal damage to single target
DealDamage(ICombatant source, IList<ICombatant> targets, int amount, string damageType = "", string element = "", bool isCrit = false)	void	Deal damage to multiple targets
Heal(ICombatant source, ICombatant target, int amount)	void	Heal single target
Heal(ICombatant source, IList<ICombatant> targets, int amount)	void	Heal multiple targets
Kill(ICombatant target, ICombatant killer = null)	void	Force KO
Revive(ICombatant target, int hpAmount)	void	Revive dead target
ApplyStatus(ICombatant source, ICombatant target, string statusId, int duration = -1)	void	Apply status effect
ApplyStatus(ICombatant source, IList<ICombatant> targets, string statusId, int duration = -1)	void	Apply status to multiple
RemoveStatus(ICombatant target, string statusId)	void	Remove status
ApplyBuff(ICombatant source, ICombatant target, string buffId, float amount, int duration = -1)	void	Apply buff
ApplyBuff(ICombatant source, IList<ICombatant> targets, string buffId, float amount, int duration = -1)	void	Apply buff to multiple
RemoveBuff(ICombatant target, string buffId)	void	Remove buff
Flee(ICombatant who)	void	Flee from battle
RemoveCombatant(ICombatant)	void	Remove from battle entirely
CheckBattleEnd()	bool	Check if battle should end
GetAlive(int team = -1)	List<ICombatant>	Get alive combatants
GetDead(int team = -1)	List<ICombatant>	Get dead combatants
GetEnemies(ICombatant)	List<ICombatant>	Get alive enemies
GetAllies(ICombatant, bool includeSelf = false)	List<ICombatant>	Get alive allies
GetTimeline()	IReadOnlyList<ICombatant>	Get turn order from turn system

Battle — Events

Event	Signature	When
OnBattleStart	Action<Battle>	Battle.Start() called
OnBattleEnd	Action<Battle, BattleState>	Battle ends
OnTurnStart	Action<TurnEvent>	BeginNextTurn() called
OnTurnEnd	Action<TurnEvent>	EndTurn() called
OnBeforeDamage	Action<BeforeDamageEvent>	Before damage applied (cancellable)
OnDamageDealt	Action<DamageEvent>	After damage applied
OnBeforeHeal	Action<BeforeHealEvent>	Before heal applied (cancellable)
OnHealed	Action<HealEvent>	After heal applied
OnKO	Action<KOEvent>	Combatant knocked out
OnRevived	Action<ICombatant>	Combatant revived
OnStatusApplied	Action<StatusEvent>	Status applied
OnStatusRemoved	Action<ICombatant, string>	Status removed
OnBuffApplied	Action<BuffEvent>	Buff applied
OnBuffRemoved	Action<ICombatant, string>	Buff removed
OnFled	Action<ICombatant>	Combatant fled
OnCombatantRemoved	Action<ICombatant>	Combatant removed
OnGroupDamageDealt	Action<GroupDamageEvent>	Multi-target damage
OnGroupHealed	Action<GroupHealEvent>	Multi-target heal
OnGroupStatusApplied	Action<GroupStatusEvent>	Multi-target status
OnGroupBuffApplied	Action<GroupBuffEvent>	Multi-target buff

BattleEvents — Structs

DamageEvent

Field	Type	Description
Source	ICombatant	Who dealt the damage
Target	ICombatant	Who received the damage
Amount	int	Damage amount
DamageType	string	Pass-through damage type
Element	string	Pass-through element
WasCrit	bool	Whether the hit was critical

HealEvent

Field	Type	Description
Source	ICombatant	Who performed the heal
Target	ICombatant	Who was healed
Amount	int	Heal amount

StatusEvent

Field	Type	Description
Source	ICombatant	Who applied the status
Target	ICombatant	Who received the status
StatusId	string	Pass-through status identifier
Duration	int	Duration in turns (-1 = permanent)

BuffEvent

Field	Type	Description
Source	ICombatant	Who applied the buff
Target	ICombatant	Who received the buff
BuffId	string	Pass-through buff identifier
Amount	float	Numeric value (user-interpreted)
Duration	int	Duration in turns (-1 = permanent)

KOEvent

Field	Type	Description
Target	ICombatant	Who was knocked out
Killer	ICombatant (nullable)	Who caused the KO (null if none)

TurnEvent

Field	Type	Description
Actor	ICombatant	Whose turn it is
TurnNumber	int	Current turn number

GroupDamageEvent

Field	Type	Description
Source	ICombatant	Who dealt the damage
Hits	IReadOnlyList<DamageEvent>	Individual damage events
TotalDamage	int	Sum of all damage dealt

GroupHealEvent

Field	Type	Description
Source	ICombatant	Who performed the heals
Heals	IReadOnlyList<HealEvent>	Individual heal events
TotalHealed	int	Sum of all HP restored

GroupStatusEvent

Field	Type	Description
Source	ICombatant	Who applied the statuses
Applications	IReadOnlyList<StatusEvent>	Individual status events

GroupBuffEvent

Field	Type	Description
Source	ICombatant	Who applied the buffs
Applications	IReadOnlyList<BuffEvent>	Individual buff events

BattleHistoryEntry

Field	Type	Description
Sequence	int	Global sequence number
TurnNumber	int	Turn when event occurred
EventType	string	Type of event recorded
Event	object	The event data (cast to specific type)

BattleResult

Field	Type	Description
Outcome	BattleState	Victory, Defeat, or Fled
TotalTurns	int	Total turns taken
Survivors	List<ICombatant>	Combatants still alive at end
History	IReadOnlyList<BattleHistoryEntry>	Complete battle event log

BattleEvents — Before-Events (Classes)

Before-events are mutable classes (not structs) that allow subscribers to modify or cancel actions before they execute.

BeforeDamageEvent

Field	Type	Description
Source	ICombatant	Who is dealing the damage
Target	ICombatant	Who will receive the damage
Amount	int (settable)	Damage amount — modify to change final damage
DamageType	string	Pass-through damage type
Element	string	Pass-through element
IsCrit	bool	Whether the hit is critical
Cancel	bool (settable)	Set to true to prevent damage entirely

BeforeHealEvent

Field	Type	Description
Source	ICombatant	Who is performing the heal
Target	ICombatant	Who will be healed
Amount	int (settable)	Heal amount — modify to change final heal
Cancel	bool (settable)	Set to true to prevent heal entirely

BattleState Enum

Value	Description
NotStarted	Battle has not begun yet
WaitingForCommands	Waiting for the next turn to begin
Executing	A turn is in progress
Victory	Player team won
Defeat	Player team lost
Fled	A combatant fled the battle