Setup Close-Range Melee Unit Attack
In this tutorial, we will be adding an attack component for a unit entity which would allow it to deal damage to enemy faction entities.
First, open the tutorial_unit prefab and add a new child object to it under the name of unit_attack.
Then add the Unit Attack component to the unit_attack child object and let's start configuring it to setup a direct attack type that does not rely on a projectile to deal damage.
1. Configure Attack
1.1 General Tab
- Code: Choose a unique code for the component to differentiate it from other entity components attached to the same entity. For example, we will call this attack_component_direct.
- Is Locked: Keep this field disabled so that the attack component can be used.
- Is Active: An attack component can only be used when it is active so make sure this field is enabled. A unit entity can have multiple Unit Attack components attached to it and at any point of time, only one of them is active.
- Require Idle Entity: Enable to require that the unit is in an idle state before it engages into combat with an enemy entity.
- Revert: In case there are multiple attack components attached to the entity, the one that has this field enabled will be the one that gets activated whenever a cycle of another attack is performed. This allows to have a basic attack component and other attack types that can represent abilities for the entity which you can fire once each time before reverting back to the main basic attack type.
Formation:
Defines the unit's stopping distance when it is actively engaging a target entity and determines what multiple entities of the same type would use as a formation when they are actively engaging a target together.
- Unit Stopping Distance: The unit's attack path destination stopping distance when it is attacking a target unit. Since this is a close-range melee attack, we can set it up to be in the range of (0, 1). This means that the tutorial_unit can only attack a target unit if its position is with a range of 1 of it.
- Unit Enable Distance: Distance at which the attack gets enabled when the target is a unit entity, this value must fit in the min and max bounds of the unit stopping distance.
- Building Stopping Distance: The unit's attack path destination stopping distance when it is attacking a target building. Since this is a close-range melee attack, we can set it up to be in the range of (0, 1.5). This means that the tutorial_unit can only attack a target unit if its position is with a range of 1.5 of it.
- No Target Stopping Distance: You can configure the attack to not require an actual target to launch an attack. Attacks can be launched on positions on the map. The latter is useful when you are setting up an area of effect attack for example. For this setup, we will be requiring the tutorial_unit to always have a target so this field is irrelevant in this case.
- Minimum Stopping Distance: Enabling the Enforce Min Stopping Distance option would force the attacker to always respect the Min Stopping Distance when it is finding a path destination when moving towards its target. In this case, if the attacker unit is engaging a target and the target moves closer to the attacker lowering its distance with the attacker to a value less of the one specified in the Min Stopping Distance then the attacker would also recalculate its attacking position and moves further away from the target in order to respect the minimum enforced distance. In this example, we will keep Min Stopping Distance as we allow the stopping distance for unit and building targets to be 0 at least.
- Stop Movement On Target In Range: Stop the unit movement when it enters the valid range for engaging a target.
- Update Mvt Distance: When the attacker unit has an active target, this is the distance that the target is allowed to move before the attacker unit has to recalculate its attacking position to accommodate for the new target position. Please note that if the target leaves the attack stopping distance, the attacker unit would automatically find a new attacking position. This feature also allows the target unit to keep track of its target changing position if the target is escaping or moving away from the attacker. We can assign the value of 2 to this field for example.
- Movement Formation: This field allows to determine how attack positions of multiple units of the same type will be generated when they are asked to engage with the same target entity. There are two predefined formation types. You can also create your own custom formation type and write a script that allows to generate the movement positions but we will not go through that in this tutorial. Instead we will search the RTS Engine -> Core -> Movement -> Formations path within the Project tab and we will find two movement formation type assets: circular_movement_formation_type and row_movement_formation_type. The former will make units form a circle in the target destination while the latter will generate attack path destinations in a row form. For this tutorial_unit, we will go for the circular formation. Therefore, drag and drop the circular_movement_formation_type into the Movement Formation field of the movement component (you can also pick it from the dropdown menu!). When the formation's Type is assigned, the Properties array field will display the properties/options of this formation that will be considered when generating the path destinations:
- Float Properties: These properties allow you to input float values. The spacing property defines the space between the path destinations.
- Int Properties: This formation type does not have any integer properties.
Engage Options:
The options in this field define the behavior of the attacker unit when it is searching or actively engaging with an active target:
- Engage On Assign: Engage when the local player assigns a target?
- Engage When Attacked: Allow the unit to attack back any unit or building that attacks it first, when the attacker does not have an active target while it is being attacked?
- Engage Once: When enabled, the attacker will only launch one iteration of its attack towards the target and will then require the target to be re-assigned.
- Engage Friendly: When enabled, the attacker will be able to attack friendly faction entities.
- Auto Ignore Angle LOS: Auto-engage entities that are blocked by the LOS angle (attacker not looking at target)? This only applies for auto-targeting entities. When disabled, the attacker will not be able to auto-engage with an enemy if it does not see it within its line of sight which is defined in the LOS Tab.
- Auto Ignore Obstacle LOS: Auto-engage entities that are blocked by obstacles? This only applies for auto-targeting entities. When disabled, the attacker will not be able to auto-engage with an enemy if it is behind an obstacle for example. What defines an obstacle can be specified in the LOS Tab. We can keep the default settings for this field, meaning only Engage On Assign, Engage When Attacked and Auto Ignore Obstacle LOS are enabled.
Move On Attack: When enabled, the attacker unit will be able to launch its attack while moving. We want this to remain disabled so that the tutorial_unit can only attack when it is not moving.
Target Finder Data: This field allows the attacker to automatically look for potential enemy faction entities to attack within a specific range without the player commanding them to do so. When enabled, you need to set the following properties:
- Reload Time: Period of time (in seconds) before the entity searches automatically for a target in its range.
- Range: The size of the target search range.
- Idle Only: When enabled, the automatic target search executed by this component can only happen if the entity is idle, meaning that no other target component attached to the entity has an active target. We want this option enabled with a Range of 10 and a Reload Time of 3 with Idle Only enabled.
Follow Distance: If the target leaves the attack range then this field represents how far is the attacker willing to follow their target before giving up on them.
- Require Target: We want to setup this attack so that it is only launched when the attacker has an active target. Therefore we enable this option.
- Allow Multiple Terrain Attacks: When enabled, the attacker is able to keep launching terrain attack iterations. Otherwise, the attacker will launch one terrain attack iteration then stop.
- Target Picker: This field defines what faction entities the attacker is allowed to attack. To keep things simple, we will leave the Type assigned to All to allow the tutorial_unit to attack any type of enemy faction entities. The Engage Units and Engage Buildings fields allow to toggle attack engagement for all unit and building types respectively.
- Reload Duration: When an attack's iteration is over, this is the time required for the attacker to wait before it can enter into its next attack iteration. We are now setting up a close-range melee attack which we want the unit to execute with small delays between each attack iteration so a reload duration of 0.5 is suitable.
- Delay Time: When having an active target, this field represents the amount of time (in seconds) that delays the launch of the attack iteration. This is particularly useful when you have an attack animation with some build up and you want to sync the attack with that animation. In this case, we will leave at 0, meaning there is no delay.
- Delay Trigger Enabled: If enabled, then another component must call the 'TriggerAttack()' method in the attack component to trigger the attack launch in each iteration. When enabled, this options gives you greater control over when to launch the attack as you can sync the delay triggering with custom behavior in your code's logic. In this example however, we would like to keep things more simple and therefore keep this field disabled.
- Cooldown: When enabled, the attack cooldown is triggered after each launched attack iteration and it blocks the attack from proceeding until the cooldown time is over. This is useful when you have multiple attack components attached to the same entity, assuming one of the attacks is the primary one, you can have a more powerful special attack that has a cooldown attached to it so that there is a limitation on when it is launched.
- Attack Override Controller: To allow the attacker unit to have unique animations that play while it is actively engaging a target, we need to assign it a full animator override controller that replaces the default one. We went through creating the animator override controllers for units in the unit creation tutorial in full details. But in short, find a path in the project tab and right click then choose: Create -> Animator Override Controller and assign the EmptyInProgressAnim with an animation clip to play for the attacker unit while it is engaging a target. For a close-range melee attack, we can use the override controller from the demo files under the name of heavy_infantry_attack_animator. The Fetch Type field in this case is irrelevant since we only have one override controller.
1.2 Launcher Tab
We are setting up a close-range melee attack with no projectile. This tab allows to define settings for launching a projectile, known in the RTS Engine as an Attack Object. We will be covering this in the next section of the attack tutorials but for now, keep the Use Attack Objects field disabled.
1.3 Damage Tab
- Deal Damage: In order for the attack to deal an actual damage, this field must be enabled.
- Data: This field defines the damage points that the attacker can inflict on its target. You can pick a base damage value for units and buildings respectively, which we can set to 10 for both. The Custom sub-field allows you to define damage points specific to faction entity types or categories.
- Area Attack Enabled: This attack is not an area of effect attack so keep this option disabled.
- Dot Enabled: This option allows for the attack to deal damage over time. We will however keep it disabled for now.
- Effect: Appears on the target when damage is dealt to it.
- Reset Damage Dealt: The attack component keeps track of the damage points it has dealt to enemy entities. When this option is disabled, the damage dealt log is reset every time the attacker has a new target. You can access this value through code.
1.4 Weapon Tab
Assigning a child object of the attacker to the Weapon Object field would allow you to control the rotation of the weapon object according to the attack state. This is useful when you have a tank unit and you would like to control the rotation of its barrel independent of the rotation of the whole vehicle. For this case, we will keep the Weapon Object field unassigned.
The entity's child objects assigned to the Toggable Objects field are the objects, other than the main weapon object, that are enabled when the attack type is activated and disabled otherwise.
1.5 LOS Tab
To keep things simple, we will have line of sight options disabled. This means that the target being in the line of sight of the attacker or not is irrelevant for the attacker to engage with the target as long as it is in its attack or search range.
1.6 Attack-Move Tab
We will keep the default configurations in this tab and come back to the attack-move commands in the Advanced Attack Options guide.
1.7 UI Tab
- Set Target Task UI: An entity component with an ability to set a target allows the player to set that target either by a right-mouse click on the target while the entity is selected or by a dedicated task that appears in the dedicated UI task panel when the entity is selected as well. The data that defines the task are assigned here. We went through setting up such a task in the Add Movement Task section. However we will leave this component without a dedicated target assignment task.
- Switch Attack Task UI: If the attacker has multiple attack components attached to it. This field allows to define a task in the attacker's task panel that allows to deactivate all attack components and enable the one that corresponds to it. This makes switching between attack types possible. Since we are only dealing with one attack component in this case, we will keep this field unassigned.
- Switch Attack Cooldown UI Data: This field allows to change the attack switch task data (assigned in the above field) when the attack is in cooldown and switching to it is not possible. If the Icon field is assigned then the icon will completely replaced and if not, the original icon will be colored with the color assigned in the Color field.
- Cancel Attack Task UI: This field allows to define a task in the attacker's task panel that appears when the attacker is actively engaging in combat with a target. When enabled, the tasks stops the currently in progress attack.
1.8 Audio Tab
This tab allows to define audio clips to be played when the attacker enters the range of its target, when it is ordered by the local player to attack a target entity and when an attack iteration is complete.
1.9 Events Tab
This tab includes Unity Event fields that are invoked in different stages of an attack iteration. These events allow you to extend the behavior of the attack component through your custom logic.
2. Testing
Open the tutorial_map scene and play it. Select one or more instances of the tutorial_unit entity. Move the attack units towards towards the enemy faction unit and building that we setup in previous tutorials and right click on one of them to launch an attack. The tutorial_unit instance should then move within a close distance of their targets and will damage it with 10 points periodically until the target is destroyed.
Download Files
You can download the results of this tutorial here.