Setup Unit Creator
1. Overview
Now that we have a fully functional and movable unit that is placed by default in the map scene, we want to allow the tutorial_building to produce instances of the tutorial_unit. To achieve this, we need to use the Unit Creator component.
Go ahead and open the tutorial_building prefab object and add this component to the the building_components child object.
In the beginning of this component's inspector, you can see the following:
Entity Component (Source: IFactionEntity)
This means that this component can be used for faction entities (any entities that implement the IFactionEntity interface) including units and buildings.
2. Pending Tasks Handler
The Unit Creator creates units by launching pending tasks which take time to run and complete before actually producing a unit. Therefore, the Pending Tasks Handler component must be attached either to the main building's prefab object or any of its children objects in order to be able to process pending tasks. In this case, we can simply add it to the tutorial_building's parent object.
The Pending Tasks Handler component handles any pending task tied to the faction entity that it is attached to so when adding another entity component that launches pending tasks, you do not need to add another instance of this pending tasks handler. It only has one field that you can assign, and that is the Max Count that represents the total maximum amount of pending tasks that the entity can have at any given time.
3. Unit Creator Component
Now back to the building_components child object of the tutorial_building and specifically to the Unit Creator component's inspector.
3.1 General
- Code: Provide a unique code that distinguishes this component from other entity components attached to the same building.
- Is Active: Make sure this is active to enable the component.
Spawn Transform: Create a child object of the tutorial_building prefab, call it unit_spawn_position then drag and drop it into this field. Make sure to have it placed where you would like the units to spawn when they are created (for example, set its position to (0, 0, -2) so that it is placed in front of the building's model door).
3.2 Tasks
In the Tasks tab, we can define the actual tasks that would appear on the tutorial_building task panel when it is selected to allow for unit creation.
Go ahead and and add one new element to the Creation Tasks array:
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 unit creation 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_create_unit_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.
- 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 the icon of the unit creation task that will be drawn on the task panel. Since we will be creating the tutorial_unit using this task then we can use its own icon, which is available within the demo game files under the name archer_level1_icon.
- 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 0 which means that the task will be drawn on the first category of the tasks panel.
- Force Slot/Slot Index: We want to have this task drawn on the first task slot of the first task panel category, therefore we set the Slot Index field to 0 (first slot) and enable the Force Slot field. This is of course only an example of how you can configure these two fields.
- 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 disable the Hide Tooltip On Click field so that the tooltip remains appearing even when the player clicks on the task to launch unit creation tasks.
- Reload Time: This field represents the time that is required between launching the unit creation task and the unit being actually created and available for the faction to use. This field is only relevant for pending tasks which is the case for unit creation tasks. Assign 3 to this field so that it takes only 3 seconds for the unit to be created.
- 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_create_unit_task UI task asset should look 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.
Allowed Faction Types: Pick the faction types that are allowed to execute this task. If the faction entity does not have a matching faction type, the task will be hidden.
- Required Resources: We will get back to this field once we have gone through resources in later tutorials. For now keep this array empty.
- 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 create the unit associated with the 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 other types can be produced. 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 you 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 Unit Creation Task Properties
- Prefab Object: Drag and drop the tutorial_unit prefab (one we created in past tutorials) into this field. This defines the actual unit that will be produced through this unit creation task.
Limit: You can define limitations on each unit creation task.
- None: No limitations would be applied.
- Launch Times: The unit creation task can only be launched a limited amount of times, which you can define in the Max Amount field.
- Active Instances: The unit creation task would be disabled once the currently active amount of units for the faction reaches a certain amount, otherwise the task remains available to be launched. That amount if defined in the Max Amount field.
To keep things simple in this tutorial, we will keep the Limit set to None.
This is how the Tasks tab look after the above modifications. We are now done defining the task in the Unit Creator component.
As for the Upgrade Target Creation Tasks, that array is reserved for re-defining the unit creation tasks' data when one of the units is upgraded. For now, we haven't dealt with upgrades so we will come back to this in later tutorials.
4. Testing
Launch the tutorial_map scene which has the tutorial_building prefab as a faction entity spawned by default for the player faction. Select the tutorial_building and you should be able to see the tutorial_unit creation task in the tasks panel (in the first slot, in the first category). Hover over the task and you should see the descriptive test appear above it.
Now click on the task and the task would launch and be available in the pending tasks slots on the right panel in the bottom (as long as the building is still selected). You can follow the progress of the task by the progress bar. If you click on the pending task (that has the progress bar), you can cancel its progress and the unit would not be created. When the 3 seconds reload time has passed, the unit would spawn in the spawn position that we assigned earlier relative to the position of the tutorial_building instance.
Download Files
You can download the results of this tutorial here.