API Reference

Complete API documentation for all public classes, methods, and properties in Wayfinder.

Core ScriptableObjects

Ability (Abstract)

Base class for all abilities. Create subclasses for specific ability behaviors.


public abstract class Ability : ScriptableObject
{
    // Display
    public string Name;
    public Sprite Icon;
    public string Description;
 
    // Class/Type
    public List<Class> classes;  // Empty = universal ability
    public AbilityType AbilityType;
    public WeaponType WeaponType;
 
    // Basic Attack
    public bool isBasicAttack;
 
    // Range
    public int MinRange;
    public int MaxRange;
    public int MaxVerticalRange;
    public bool ignoresHeight;
 
    // Cost
    public int mpCost;
 
    // AoE
    public AoEData areaOfEffect;
 
    // Charging (FFT mechanic)
    public int chargeSpeed;  // 0 = instant, higher = faster charge
 
    // AI Behavior
    public AIBehaviorFlags aiBehaviorFlags;
 
    // Methods
    public abstract bool Perform(Unit target);
    public virtual bool Perform(Unit target, Unit caster);
 
    public virtual List<Tile> GetAffectedTiles(Tile centerTile);
    public virtual List<Unit> GetAffectedUnits(Tile targetTile, Unit caster);
 
    public virtual int GetMinRange(Unit user);
    public virtual int GetMaxRange(Unit user);
    public virtual int GetMaxVerticalRange(Unit user);
    public virtual AbilityType GetAbilityType(Unit user);
}

Key Methods:

Perform(Unit target) - Execute ability on target
GetAffectedTiles(Tile centerTile) - Calculate AoE tiles
GetAffectedUnits(Tile targetTile, Unit caster) - Get units hit by AoE
GetMinRange/GetMaxRange(Unit user) - Dynamic range (basic attacks use weapon range)

Item : Consumable

Healing and status-curing items.


public class Item : Consumable
{
    public int healAmount;
    public int manaRestoreAmount;
 
    public override bool Use(Unit user, Unit target);
    public override bool IsValidTarget(Unit user, Unit target);
}

Usage:


Item potion = GetPotionAsset();
bool success = potion.Use(caster, targetUnit);

Consumable (Abstract)

Base class for all consumable items.


public abstract class Consumable : ScriptableObject
{
    public string Name;
    public Sprite Icon;
    public string Description;
    public ConsumableType ConsumableType;
 
    // Range
    public int MinRange;
    public int MaxRange;
    public int MaxVerticalRange;
    public bool ignoresHeight;
 
    // Targeting
    public ConsumableTargetType TargetType;  // Ally, Enemy, Any, Self
 
    public abstract bool Use(Unit user, Unit target);
    public virtual bool IsValidTarget(Unit user, Unit target);
}

StatusEffectDefinition

Defines a status effect (Poison, Haste, Sleep, etc.).


public class StatusEffectDefinition : ScriptableObject
{
    // Display
    public string displayName;
    public Sprite icon;
    public string description;
    public int defaultDuration;  // -1 = permanent
 
    // Classification
    public bool isPositive;  // Buff vs Debuff
 
    // Per-Turn Effects
    public List<PerTurnEffect> perTurnEffects;
 
    // Combat Modifiers
    public float accuracyModifier;       // -1.0 to 1.0
    public float recoveryTimeModifier;   // -0.5 = Haste, +0.5 = Slow
    public float physicalDamageModifier; // 0.5 = Protect (50% damage)
    public float magicDamageModifier;    // 0.5 = Shell (50% damage)
    public float fireDamageModifier;     // 1.5 = Oil (150% fire damage)
 
    // Behavioral Flags
    public bool preventsMovement;
    public bool preventsActions;
    public bool preventsAbilities;
    public bool causesConfusion;
    public bool causesBerserk;
 
    // Special Properties
    public bool breaksOnDamage;
    public bool autoRevive;
    public bool reflectsMagic;
    public bool isFloating;
    public bool hasDeathCountdown;
    public int deathCountdownTurns;
}

Example: Create Poison


// In Unity Editor: Right-click > Create > Wayfinder > Status Effects > Status Effect Definition
// Configure:
displayName = "Poison"
defaultDuration = 5
isPositive = false
perTurnEffects = [ { targetStat: HP, calculationType: PercentOfMax, value: -12.5 } ]

ClassData

Display data for a character class.


public class ClassData : ScriptableObject
{
    public Class classType;
    public string className;
    public Sprite classIcon;
    public Sprite malePortrait;
    public Sprite femalePortrait;
}

Core MonoBehaviours

Unit

Represents a character in battle with all stats, equipment, and abilities.


public class Unit : MonoBehaviour
{
    // Identity
    public string unitName;
    public Class unitClass;
    public Sex sex;
    public UnitAffiliation affiliation;  // Ally, Enemy, Neutral
    public UnitControlType controlType;  // Player, AI
    public UnitStatus status;            // Alive, KO, Dead
 
    // Position
    public Tile currentTile;
    public Vector2Int location;
 
    // Level & Experience
    public int level;
    public int currentExperience;
    public int classLevel;
    public int currentClassPoints;
 
    // Resources
    public int currentHitPoints;
    public int maxHitPoints;
    public int currentMagicPoints;
    public int maxMagicPoints;
 
    // Movement Stats
    public int move;
    public int jumpUp;
    public int jumpDown;
 
    // Combat Stats
    public int strength;      // Melee attack
    public int vitality;      // Physical defense
    public int dexterity;     // Ranged attack
    public int agility;       // Accuracy
    public int intelligence;  // Magic attack
    public int resistance;    // Magic defense
    public int avoidance;     // Physical dodge
    public int mind;          // Magic dodge
 
    // Turn System
    public float currentRecoveryTime;
    public float baseRecoveryTime;
    public int weight;        // From equipment, slows turns
    public float MaxRecoveryTime { get; }  // Base RT + weight + status modifiers
 
    // Behavioral Stats (AI)
    public float courage;     // 0-1: Fight vs flee when hurt
    public float conviction;  // 0-1: Ability usage decisiveness
 
    // Derived Stats (read-only properties)
    public int MeleeAttackPower { get; }
    public int RangedAttackPower { get; }
    public int MagicAttackPower { get; }
    public int PhysicalDefense { get; }
    public int MagicDefense { get; }
    public int PhysicalAvoidance { get; }
    public int MagicAvoidance { get; }
 
    // Equipment
    public Head head;
    public Chest chest;
    public Hands hands;
    public Legs legs;
    public Feet feet;
    public Accessory accessory;
    public Weapon mainHand;
    public Weapon offHand;
    public List<Armor> equippedArmor;
    public List<Weapon> equippedWeapons;
    public Dictionary<GearBonusType, int> gearBonuses;
 
    // Abilities & Items
    public List<Ability> abilities;
    public Ability activeAbility;
    public Consumable activeConsumable;
 
    // Status Effects
    public List<StatusEffectData> activeStatusEffects;
    public event System.Action<Unit, StatusEffectDefinition> OnStatusEffectApplied;
    public event System.Action<Unit, StatusEffectDefinition> OnStatusEffectRemoved;
 
    // Events
    public event System.Action<Unit> OnKO;
    public event System.Action<Unit> OnDeath;
    public event System.Action<Unit> OnRevive;
 
    // === Methods ===
 
    // Health Management
    public void TakeDamage(float damage);
    public void Heal(float healAmount);
    public void BecomeKO();
    public void BecomeDead();
    public void Revive(int healAmount);
 
    // Equipment
    public void Equip(Armor armor);
    public void Equip(Weapon weapon);
    public void Unequip(Armor armor);
    public void Unequip(Weapon weapon);
 
    // Status Effects
    public bool HasStatusEffect(StatusEffectDefinition definition);
    public StatusEffectData GetStatusEffect(StatusEffectDefinition definition);
    public void ApplyStatusEffect(StatusEffectData effectData);
    public void ApplyStatusEffect(StatusEffectDefinition definition, int? customDuration = null);
    public void RemoveStatusEffect(StatusEffectDefinition definition);
    public void ClearAllStatusEffects();
    public void ProcessStatusEffectsEndOfTurn();
 
    // Status Effect Queries
    public bool CanMove();
    public bool CanAct();
    public bool CanUseAbilities();
    public float GetRecoveryTimeModifier();
    public float GetPhysicalDamageModifier();
    public float GetMagicDamageModifier();
    public float GetAccuracyModifier();
    public bool IsConfused();
    public bool IsBerserked();
    public bool HasAutoRevive();
    public bool ReflectsMagic();
    public bool IsFloating();
 
    // Utility
    public void FaceTile(Tile tile);
    public void SetDirection(UnitDirection direction);
    public bool IsControllableByLocalPlayer();
}

Common Patterns:

Apply Status Effect:


// Method 1: From definition
StatusEffectDefinition poison = GetPoisonDefinition();
unit.ApplyStatusEffect(poison);  // Uses default duration
 
// Method 2: Custom duration
unit.ApplyStatusEffect(poison, 3);  // 3 turns
 
// Method 3: From data
StatusEffectData poisonData = StatusEffectData.Create(poison, 5);
unit.ApplyStatusEffect(poisonData);

Check Status:


if (!unit.CanAct())
{
    Debug.Log("Unit is stopped/petrified!");
}
 
if (!unit.CanUseAbilities())
{
    Debug.Log("Unit is silenced!");
}
 
if (unit.IsConfused())
{
    // Attack random target
}

Tile

Represents a single grid tile.


public class Tile : MonoBehaviour
{
    public enum TileStatus { Passable, Blocked, InAbilityRange, InAoEPattern }
 
    public Vector3Int gridLocation;   // 3D position (x, y, z)
    public Vector2Int grid2DLocation; // 2D position (x, y)
    public float height;
    public UnitStateManager currentUnit;
    public TileStatus status;
 
    // Pathfinding (internal use)
    public int G;  // Cost from start
    public int H;  // Heuristic to goal
    public int F { get; }  // G + H
    public Tile previous;
 
    public void Show();
    public void Hide();
    public void SetStatus(TileStatus status);
}

Grid System

TileManager

Manages the tilemap and tile lookups.


public class TileManager : MonoBehaviour
{
    public Dictionary<Vector2Int, Tile> map;
    public Dictionary<Vector2Int, Tile> tilesToSearch;
 
    public Vector3 GetTilemapCenter();
    public Tile GetAdjacentTile(Tile currentTile, int xDiff, int yDiff);
    public List<Tile> GetNeighborTiles(Tile currentTile, Unit unit,
                                       List<Tile> searchableTiles, bool ignoreHeight);
    public Tile GetUnitCurrentTile(UnitStateManager unit);
}

Pathfinder

A* pathfinding for unit movement.


public class Pathfinder
{
    public List<Tile> FindPath(TileManager tileManager, Unit unit,
                               Tile start, Tile end, List<Tile> searchableTiles,
                               bool ignoreHeight, int minRange = 0);
 
    public int GetPathDistance(TileManager tileManager, Unit unit,
                               Tile start, Tile end, bool ignoreHeight);
 
    public bool IsTileWithinAbilityRange(Unit currentUnit, Unit targetUnit, Ability ability);
}

Range

Movement and ability range calculation.


public class Range
{
    public List<Tile> GetTilesWithinRange(Tile fromTile, int minRange, int maxRange,
                                          Unit unit, bool ignoreHeight);
 
    public List<Tile> GetReachableTiles(Tile fromTile, int minRange, int maxRange,
                                        Unit unit, bool ignoreHeight);
}

Combat System

CombatCalculator

Singleton that handles all combat calculations.


public class CombatCalculator : MonoBehaviour
{
    public static CombatCalculator Instance { get; }
 
    // Damage & Healing
    public float CalculateDamage(Unit attacker, Unit target, Ability ability);
    public float PreviewDamage(Unit attacker, Unit target, Ability ability);
    public float CalculateHealing(Unit healer, Unit target, Ability ability);
    public float PreviewHealing(Unit healer, Unit target, Ability ability);
 
    // Hit Chance
    public float GetHitChance(Unit attacker, Unit target, Ability ability);
 
    // Full Combat Result
    public CombatResult CalculateFullCombatResult(Unit attacker, Unit target, Ability ability);
    public CombatResult PreviewFullCombatResult(Unit attacker, Unit target, Ability ability);
 
    // Utility
    public bool WouldDefeatTarget(Unit attacker, Unit target, Ability ability);
    public float GetAbilityEffectiveness(Unit user, Unit target, Ability ability);
}

Usage:


float damage = CombatCalculator.Instance.PreviewDamage(attacker, target, ability);
float hitChance = CombatCalculator.Instance.GetHitChance(attacker, target, ability);
 
if (damage >= target.currentHitPoints)
{
    Debug.Log("This attack would defeat the target!");
}

CombatConfiguration

ScriptableObject defining combat formulas and modifiers.


public class CombatConfiguration : ScriptableObject
{
    // Hit Chance
    public float baseHitChance;
    public float minHitChance;
    public float maxHitChance;
    public float agilityToAccuracy;
 
    // Damage Formulas
    public float physicalBase;
    public float magicalBase;
    public float strengthScaling;
    public float intelligenceScaling;
    public float weaponPowerScaling;
 
    // Defense
    public DefenseFormula defenseFormula;  // Subtractive, Percentage, Hybrid
    public float defenseEffectiveness;
    public float defenseDivisor;
    public float maxDamageReduction;
    public float minDamage;
 
    // Height Modifiers
    public ElevationModifiers elevationModifiers;
 
    // Healing
    public float healingMultiplier;
    public float healingMaxHPScaling;
 
    // Behavioral Stats
    public bool useCourageSystem;
    public bool useConvictionSystem;
    public float couragePhysicalScaling;
    public float convictionMagicScaling;
    public float convictionHealingBonus;
}

AI System

AIBrain

Component that makes AI decisions for a unit.


public class AIBrain : MonoBehaviour
{
    public AIDecision CurrentDecision { get; }
    public List<Unit> AlliedUnits { get; }
    public List<Unit> EnemyUnits { get; }
 
    public AIDecision MakeDecision();
}

Usage:


AIBrain brain = unit.GetComponent<AIBrain>();
AIDecision decision = brain.MakeDecision();
 
// Execute decision
switch (decision.actionType)
{
    case AIActionType.Attack:
        // Move to position and attack
        break;
    case AIActionType.UseAbility:
        // Use ability on target
        break;
}

AIConfiguration

ScriptableObject with all AI scoring values.


public class AIConfiguration : ScriptableObject
{
    // Buff Scoring
    public float hasteBaseScore;
    public float protectBaseScore;
    public float shellBaseScore;
    public float regenBaseScore;
    // ... many more buff scores
 
    // Debuff Scoring
    public float hardCCBaseScore;
    public float silenceBaseScore;
    public float blindBaseScore;
    // ... many more debuff scores
 
    // Combat Action Scoring
    public float attackDamageMultiplier;
    public float finisherBonus;
    public float healingValueMultiplier;
    // ... many more combat scores
 
    // AoE Scoring
    public float aoeEnemyHitMultiplier;
    public float aoeFriendlyFirePenalty;
    // ... many more AoE scores
 
    // Target Priority
    public float healerTargetBonus;
    public float lowHPTargetBonus;
    // ... many more target scores
 
    // Movement Scoring
    public float moveIntoRangeScore;
    public float heightAdvantageMultiplier;
    // ... many more movement scores
}

Battle Management

BattleStateManager

Singleton managing the battle flow and state machine.


public class BattleStateManager : MonoBehaviour
{
    public static BattleStateManager Instance { get; }
 
    public BattleBaseState currentState;
    public BattleBaseState previousState;
 
    public List<UnitStateManager> units;
    public TileManager tileManager;
    public UIStateManager uiStateManager;
    public BattleCursorController cursorController;
    public UnitStateManager activeUnit;
 
    public float battleRecoverySpeed;
 
    // AI Timing
    public float aiTurnStartDelay;
    public float aiAnalyzeDelay;
    public float aiMoveStartDelay;
    public float aiPreExecuteDelay;
    public float aiPostExecuteDelay;
 
    // State Management
    public void SwitchState(BattleBaseState state, bool force = false);
    public bool CheckBattleEndConditions();
 
    // Events
    public event System.Action<BattleBaseState> OnStateChanged;
}

Enums

Class


public enum Class
{
    Fighter,
    Archer,
    Knight,
    Mage,
    Priest
}

AbilityType


public enum AbilityType
{
    Melee,
    Ranged,
    AttackMagic,
    HealingMagic,
    InflictStatusMagic,
    HealStatusMagic
}

AoEPattern


public enum AoEPattern
{
    None,
    Square2x2,
    Square3x3,
    Square4x4,
    Square5x5,
    Cross3,
    Cross5,
    Line3,
    Line5,
    AllMap,
    Custom
}

UnitAffiliation


public enum UnitAffiliation
{
    Ally,
    Enemy,
    Neutral
}

UnitStatus


public enum UnitStatus
{
    Alive,
    KO,
    Dead
}

WeaponType


public enum WeaponType
{
    None,
    Sword,
    Bow,
    Staff,
    Shield
}

Data Structures

AoEData

Configuration for Area of Effect abilities.


[System.Serializable]
public class AoEData
{
    public AoEPattern pattern;
 
    // Targeting Rules
    public bool affectsFriendlies;
    public bool affectsEnemies;
    public bool affectsSelf;
 
    // Height Restrictions
    public bool affectsAllHeights;
    public int verticalRange;
 
    // Custom Pattern
    public List<Vector2Int> customTiles;
 
    // Damage Falloff
    public bool useDamageFalloff;
    public float centerDamageMultiplier;
    public float edgeDamageMultiplier;
}

StatusEffectData

Runtime status effect data tracking.


[System.Serializable]
public class StatusEffectData
{
    public StatusEffectDefinition definition;
    public int turnsRemaining;  // -1 = permanent
    public List<PerTurnEffect> perTurnEffects;
 
    // Modifiers (copied from definition)
    public float accuracyModifier;
    public float recoveryTimeModifier;
    public float physicalDamageModifier;
    public float magicDamageModifier;
 
    // Behavioral flags
    public bool preventsMovement;
    public bool preventsActions;
    public bool preventsAbilities;
    public bool causesConfusion;
    public bool causesBerserk;
 
    // Methods
    public static StatusEffectData Create(StatusEffectDefinition definition, int? customDuration = null);
    public bool ProcessTurnEnd(Unit unit);
    public string GetDescription();
}

PerTurnEffect

Defines per-turn stat changes for status effects.


[System.Serializable]
public class PerTurnEffect
{
    public enum TargetStat { HP, MP, CT, Strength, Vitality, Dexterity, Agility, Intelligence, Mind }
    public enum CalculationType { Static, PercentOfMax, PercentOfCurrent }
 
    public TargetStat targetStat;
    public CalculationType calculationType;
    public float value;  // Positive = increase, negative = decrease
    public string description;
 
    public float CalculateAmount(Unit unit);
    public void Apply(Unit unit, string statusName);
}

Utility Classes

DebugLogger

Filtered debug logging system.


public static class DebugLogger
{
    public static void AI(string message);
    public static void Combat(string message);
    public static void StateMachine(string message);
    public static void Pathfinding(string message);
    public static void StatusEffect(string message);
}

Usage:


DebugLogger.Combat($"{attacker.unitName} attacks {target.unitName} for {damage} damage!");
DebugLogger.AI($"AI chose to heal {ally.unitName}");

Colors

Color constants for tile overlays.


public static class Colors
{
    public static Color overlayBlue;    // Movement range
    public static Color overlayRed;     // Blocked/Enemies
    public static Color overlayYellow;  // Ability range
    public static Color overlayGreen;   // Allies/Heal targets
}

Next Steps

Grid System Installation Getting Started