LSCS: Scriptable Objects

The heart of the Large Scale Combat System is its modular structure with Scriptable Objects. Instead of hard-coding values, you define the behavior and properties of your units in reusable asset files. This allows you to customize the balancing and AI of your game without changing a single line of code.

1. UnitTypeSO

The UnitTypeSO is the most basic building block of the entire system. It is like a simple „label“ that defines a category of units. It does not contain any complex data, but is only used to group units.

Purpose: Answers the question: „What kind of unit is this?“ (e.g. Light Infantry, Heavy Cavalry, Archers).
Application: Used by the DamageModifierSO to calculate bonuses and mali.

How to create a new type:

  • In the project window, right-click -> Create -> TopsonGames -> UnitType -> UnitType.
  • Name the new asset, e.g. „Spearman“.
  • In the Inspector, you can define a Type Icon for the UI and a Gizmos Color for easy recognition in the editor.
  • Create all the basic types for your game (e.g. swordsmen, longbowmen, heavy cavalry).

2. DamageModifierSO

This asset is the central database for your entire combat balancing. This is where you define the „rock, scissors, paper“ principle of your game.

  • Purpose: Answer the question: „Who is strong against whom?“
  • Application: There should only be one DamageModifierSO asset in your entire project. This is assigned later to the GameManager in the scene.

How to configure the modifiers:

  • Create the asset: Right-click -> Create -> TopsonGames -> DamageModifier -> DamageModifier.
  • Select the asset. In the Inspector, you will see the list of unit modifiers
  • Click Plus on the Unit Modifier to create a Modification
  • Add the unit as the „Attacker“ eg as the UnitType you want to know the modifcations of
  • Click plus on the Units
  • Adjust the Modifier, this is the actual damage modifier. <1 reduces damage, 1 stays the same and >1 improves the damage
  • Add Unit Types to the Array. Those will be affectedby the modifier
  • Minimum Damage: Damage Modifier when no Unit Type is found

Example: „Cavalry are strong against Archers (1,5x Damage), medium against other Cavalry (1x Damage) and bad against Melee (0,75x Damage)“

You can define complex relationships for all your unit types with this system.

3. CombatBehaviour

CombatBehaviours define the behavior of a formation on the battlefield. It is the combat AI for the individual soldier. It controls how he reacts in his states (Idle, Moving, Fighting), when he attacks and how he moves in direct combat. You can set values such as attackRange and cooldown here.

There are four premade Combat Behavious, each with their own logic: MeleeCombatSO, ArcherCombatSO, CavalryCombatSO and ElephantCombatSO.

Basic Values:

  • unitDetectionTimer: How many seconds between the detection of enemy units
  • formationDetectionTimer: How many seconds between the detection of enemy formations
  • engagementBreakDistance: For future developement -> distance when the combat will be exited
  • attackRange: When an enemy unit is in this range a attack will be performed
  • cooldown: Cooldown between attacks
  • raiseShieldTime: How long the shield will be up when arrows are detected
  • switchAnimationTimer: How many seconds until the next idle animation is choosen
  • switchAnimationProbability: Probability that the idle animation is changed every switchAnimationProbability cyclus

MeleeCombatSO

  • wanderRadius: Radius from its waypoint the Unit will wander while in combat (strafe movement while looking at its target)

ElephantCombatSO, CavalryCombatSO

  • wanderRadius: Radius from its waypoint the Unit will wander while in combat (strafe movement while looking at its target)
  • knockbackForce: Force which the enemy will be knocked back in combat
  • knockbackDuration: Duration of the knockback

ArcherCombatSO

  • archerDetectionRange: The maximum distance at which an archer can detect enemy units.
  • archerInnerAngle: The smaller, inner angle of the trapezoidal detection area.
  • archerOuterAngle: The larger, outer angle of the trapezoidal detection are
  • archerFrontOffset: The forward offset of the detection trapezoid from the formation’s center.
  • archerDetectionTimer: The time in seconds between each enemy detection check.
  • timeBetweenShots: The delay in seconds between consecutive shots.
  • ProjectileSpeed: Speed of the Projectile

Application: You choose from the included behaviors (Melee, Archer, Cavalry, Elephant) and / or adjust them or create your own by inheriting from the base classes.

4. CombatPlacement

This is the placement AI for the entire formation in combat. It controls how the formation as a whole holds or adjusts its position when it encounters an enemy. It uses boids logic to simulate a dynamic „push and pull“ at the front. There is also a „old“ version that uses an algorithmic approach if you prefer that.

Boid Settings

  • neighborRadius: Defines the radius within which a unit considers other friendly units its neighbors.
  • separationRadius: The minimum distance a unit tries to keep from its friendly neighbors to avoid crowding.
  • cohesionForce: Determines the strength of the pull a unit feels towards the average position of its neighbors.
  • separationForce: Sets the strength of the push a unit feels to move away from neighbors that are too close.
  • alignmentForce: Controls how strongly a unit tries to match the average direction of its neighbors.
  • formationCohesionForce: The strength of the force that pulls a unit back to its ideal designated spot in the formation.

Enemy Interaction

  • enemyAttractionForce: Sets the strength of the magnetic pull that draws units towards the enemy.
  • enemySeparationRadius: The minimum distance a unit tries to keep from individual enemy units.
  • enemySeparationForce: Determines the strength of the powerful push a unit feels to avoid colliding with enemy units.
  • engagementDistance: The range at which your formation will break its standard formation to actively engage the enemy.
  • arrivalDistance: Specifies the distance from a target at which a unit begins to slow down for a smooth stop.
  • stopDistanceToEnemy: The final distance a unit will attempt to maintain from an enemy unit once engaged.

AdvancedEnemyInteraction

  • enemyFrontlineSampleSize: The number of closest enemies used to calculate the center of the enemy’s frontline for a more focused attack.

Application: You choose from the included behavior and / or adjust it or create your own by inheriting from the base classes.

4. UnitDataSO

The UnitDataSO is the centerpiece and the most important building block. It is the „vehicle registration document“ or the complete blueprint for a finished unit. Everything is put together here.

Purpose: Defines a complete unit from A to Z.
Application: You create a separate UnitDataSO for each unit type in your game (Roman Legionary, Egyptian Chariot, etc.).

This is how you configure a unit:

  • Create the asset: Right-click -> Create -> TopsonGames ->Unit Data -> UnitDataSO.
  • Select the asset and fill in the fields in the Inspector

General info

  • unitIcon: This is the 2D sprite that will be used for the unit’s user interface icon.
  • description: A short text that provides a description of the unit.
  • formationPrefab: The visual model or prefab that represents a single unit in the game world (will be made later).
  • Cost: Defines the resource cost required to purchase or deploy this unit (for your own / future developements).

Combat Stats

  • maxHealth: The total amount of damage the unit can sustain before being defeated.
  • Armor: Reduces the amount of incoming damage from each attack.
  • baseDamage: The initial damage dealt by the unit’s attacks before any other calculations.
  • armorPenetration: The amount of the enemy’s armor that this unit’s attacks will ignore.
  • shieldMeleeBlockChance: The percentage chance (from 0.0 to 1.0) for the unit to block a melee attack.
  • shieldArrowBlockChance: The percentage chance (from 0.0 to 1.0) for the unit to block a ranged arrow attack.
  • Arrows: The total amount of ammunition the unit carries for its ranged weapon.
  • unitType: A data asset that defines the unit’s general category, such as „Heavy Infantry“ or „Archer“.

Animations

  • idleAnimations: The number of different idle animation variations the unit can play.
  • attackAnimations: The number of different attack animation variations the unit can play.

Formation Settings

  • formationWidth: Sets the number of units that form the front rank or width of the formation.
  • formationSpacing: The distance kept between individual units within the formation.
  • formationMoveSpeed: The standard movement speed for the entire formation.
  • formationTurnSpeed: How quickly the entire formation can rotate to face a new direction.
  • unitRotationSpeed: How quickly an individual unit can turn on the spot.

Cohesion Settings

  • unitCatchUpFactor: Determines how quickly lagging units accelerate to rejoin their spot in the formation.
  • unitSlowDownFactor: Determines how strongly units that are too far ahead will brake to get back into position.
  • maxSpeedMultiplier: The top speed a unit can reach when catching up, as a multiple of the base speed.
  • minSpeedMultiplier: The slowest speed a unit can move at when slowing down, as a multiple of the base speed.
  • stoppingDistance: The distance from its destination at which a unit will start to decelerate to a stop.

Detection Settings

  • colliderOverhang: How much the formation’s detection box extends beyond the front and back units.
  • maxColliderSize: The maximum possible width and depth for the formation’s detection collider.
  • colliderHeight: The vertical height of the collider used for detecting other formations.
  • centerSmoothingSpeed: How smoothly the calculated center point of the formation updates as units move.

Behaviour

  • combatBehaviour: Assigns a scriptable object that defines the unit’s specific actions and decisions in combat.
  • placementBehaviour: Assigns a scriptable object that dictates how the unit positions itself relative to enemies.

Debugging

  • Troops: Displays the maximum amount of troops

Once you have configured these four types of Scriptable Objects, you have created the entire data foundation of your game. The rest is just putting these „Lego bricks“ together in the scene.

5. ArmySO

The ArmySO is the actual Army. It stores which Formations (UnitData) the army has and how many of its Units are alive.

Purpose: Defines a complete Army.
Application: You create a separate ArmyData for the player as well as the Enemy

Create the asset: Right-click -> Create -> TopsonGames ->Army.
Select the asset and fill in the fields in the Inspector

  • Element Data: Each „Element Data“ or List Element stores data for one Formation.
    • Unit: The previously created UnitData
    • Troops: The Troops (Units) that are actually „alive“ and usable for the Formation. Can be set manually but also by the editor. Each Unit death substracts from it.
    • InGameFormation: The actual in Game Formation. Set automatically by the GameManager

Troops Amount Setup: To make it easier to set the troop amount to its maximum you can rightclick in the upperpart of the scruptable object (next to its icon) and click on „Execute Spawn Army“ – this will set the Troops Integer to its maximum amount

Previous: Tutorial
Next: Unit and Formation