Create Entity Component Upgrade
Upgrades can be applied on faction entities (units and buildings) and they can be applied on the whole faction entity (entity upgrade) or just a component that belongs to it (entity component upgrade). In this tutorial, we will be setting up an upgrade for an component of one of the entities and create and handle the task that launches and triggers the entity component upgrade.
We will focus on creating an upgrade for the tutorial_unit entity movement component which has an increased movement speed.
1. Create Entity Component Upgrade Target
Create an empty object as a prefab, call it tutorial_unit_movement_upgraded, and add the Unit Movement component. You can copy the fields from the tutorial_unit movement component into this one and change the following fields:
- Code: Change it to movement_component_upgraded.
- Speed: Increase it from 10 to 20 for example.
2. Add Entity Component Upgrade Component
If the tutorial_unit has the Entity Upgrade component from the previous tutorial where we went through whole entity upgrades then remove it, then you can add this Entity Component Upgrade component on an empty object prefab. Both upgrade components have a dedicated field to assign the upgrade entity source and can function without being tied or attached to the upgrade entity source prefab. Since in the last tutorial, we added the Entity Upgrade component to the unit's main prefab object, let's go ahead and create an empty object, call it tutorial_unit_component_upgrades make it as a prefab and add the Entity Component Upgrade component to it.
We will update the fields of the component like the following:
- Source Entity: Drag and drop the tutorial_unit prefab into this field to mark it as the upgrade source.
- Source Instance Only: Enable if you only want to have the upgrade launched on the one instance that holds this component and leave it disabled to enable the upgrade on the source entity type as a whole. If disabled, then newly created instances of the same type will not have their component upgraded. For this guide's sake, we will leave this option disabled.
- Update Spawned Instances: Enable this option to immediately upgrade all already-created instances of the source entity type when the upgrade is completed. Or have it disabled to keep the spawned instances without upgrading the target component. For this guide's sake, we will leave this option enabled.
- Upgrades: This fields allows us to define all of the possible upgrades that can be launched from this upgrade component. In this case, we only want to define one upgrade target, so add one element to this array field and let's define it:
- Source Component Code: This is the code of the component in the tutorial_unit that would be upgraded. This would be the movement_component code.
- Upgrade Target: Drag and drop the tutorial_unit_movement_upgraded prefab we created in [the first section](##1. Create Entity Component Upgrade Target) that includes the upgraded Unit Movement.
3. Add Upgrade Task
Open the tutorial_building prefab and navigate to the building_components child object where we added the Upgrade Launcher component in the last section. The Upgrade Launcher is a component that can launch pending tasks that execute upgrades.
In the Tasks tab, add a new element to the Upgrade Tasks array filed and configure it:
3.2.1 General Task Properties
- Task UI: In the Add Movement Task tutorial, we went through creating an Entity Component Task UI asset which defines data required to draw a movement task in the task panel for the tutorial_unit. The process of defining the UI data for the upgrade execution task is fairly similar. Therefore, we will not be covering the creation of the UI task data in the same details so make sure to refer back to that tutorial for more details.
Right click on the Project tab and Create -> RTS Engine -> Entity Component Task UI Asset and call it tutorial_component_upgrade_task.Select the newly created asset and input its fields with the following:
- Code: Set to a unique code that differentiates it from other task UI assets, such as tutorial_component_upgrade_task.
- Enabled: Make sure this is enabled to allow the task to be drawn.
- Display Type: Choose Single Selection because we want the task to be drawn only when the tutorial_building is the only selected entity.
- Icon: This is the icon of the upgrade task that will be drawn on the task panel.
- Panel Category: In the tutorial_map created and configured in the past tutorials, we kept the four default task panel categories. We can set this value to 1 which means that the task will be drawn on the second category of the tasks panel.
- Force Slot/Slot Index: We want to have this task drawn on the second task slot of the second task panel category, therefore we set the Slot Index field to 1 (first slot) and enable the Force Slot field. This is of course only an example of how you can configure these two fields. The reason behind setting the slot ID to the second one is because the first one is occupied by the upgrade task we created in the previous tutorial.
- Tooltip: The descriptive text that appears when the player hovers their mouse over the task can be assigned in the Description field. Make sure that Tooltip Enabled is enabled for the text to actually appear and enable the Hide Tooltip On Click field so that the tooltip is hidden as soon as the player clicks on the upgrade task since it is not launchable multiple times.
- Reload Time: This field represents the time that is required between launching the upgrade task and the upgrade being executed. This field is only relevant for pending tasks which is the case for upgrade tasks. Assign 3 to this field so that it takes only 3 seconds for the upgrade to complete.
- Cursor: This field is irrelevant for the unit creation tasks. You can checkout the Add Movement Task tutorial where more details are provided on the use case of this field. This how the inspector of the tutorial_component_upgrade_task UI task asset should look like after the modifications above. Now drag and drop it into the Task UI field, find and select it in the dropdown menu of that field or search for it in that field and select it.
- Required Resources: Leave this array to keep things simple and so that the upgrade task would not cost anything.
- Faction Entity Requirements: This field allows you to define a series of faction entities (units or buildings) that the faction slot must have created prior to attempting to launch the upgrade task. This is especially useful when one of the requirements in your game is having certain units or buildings created and available for a faction before being able to launch upgrades on those faction entity types. To keep the tutorial simple, we will also be keeping this array empty.
- Missing Requirement Data: This field affects the visual aspect of the task on the task panel when the player does not have the required resources or faction entity requirements to launch it. The Icon field allows to change the icon defined in the task UI asset in case the requirements are not met. When the Icon field is not assigned, the Color is then used to change the color of the original task UI to indicate to the player that the launch requirements are not met. In this case, we will want to have the task icon appear in red color when requirements are lacking. Therefore, keep the Icon field empty and set the Color field to red (make sure that the alpha channel is not 0 so that the task icon does not become entirely transparent).
3.2.2 Upgrade Task Properties
- Prefab Object: Drag and drop the tutorial_unit_component_upgrades prefab that has the Entity Component Upgrade into this field. This will fetch the upgrade component attached to the prefab.
- Upgrade Index: The Entity Component Upgrade allows to define multiple potential upgrades in an array. This field defines the index of the target upgrade to launch using this task. In this guide, [we only defined one target upgrade element](##2. Add Entity Upgrade Component) that upgrades the movement component so make sure the index is set to 0, signifying the first element.
This is how the Tasks tab look after the above modifications:
5. Testing
Open the tutorial_map, select the tutorial_building and launch the movement speed upgrade task.
When the upgrade task is completed, move the units and you'd notice that they now move much faster. Even if the units were moving before the upgrade is complete, they would continue on their same path towards the same destination but with the new assigned speed.
In the hierarchy, you can inspect that the tutorial_unit instances now have the new Unit Movement component attached to a child object.
Download Files
You can download the results of this tutorial here.