Tutorial:Pooled Resource Unit Costs

💬 Let's Talk Pooled Resources

Pooled Resources are an important part of what makes any faction unique. The problem is they're often not used for very much. This tutorial aims to fix that by explaining how to use Pooled Resources as costs using units in the main recruitment panel as an example. The theory used here can be applied to a range of other things such as RoRs, lords, agents, buildings, and technologies or anything you want really.

This guide is also my submission for Mod Jam #7, along with an example mod for making units cost Pooled Resources in the main recruitment panel.

🧑‍🎓 The Theory

If you're not familiar with Lua UI modding and UI components (UICs) then the UI Tutorial Series is a good place to start as this guide won't explain everything about UI, just the main things we need to know which are:

1. Building the UI: This involves finding existing UICs, creating / copying UICs, and repositioning them.
2. Handling the UI: This involves handling refreshes to the UI, making sure UIC are enabled / disabled, and have the right text, tooltips, and icons at the right time.
3. Handling the Cost: This involves taking away / returning the Pooled Resource to the player in a multiplayer-friendly way.

Some other things you will need are my example mod, Groove Wizard's Visual Studio development environment for scripting, Groove's Modding Development Tools: Lua Console, and Groove's scripting documentation (yes this man is a machine).

👷 Building the UI

🔍 Finding UI Components:

The first step in building the UI is figuring out where you want your Pooled Resource cost to appear. For units this will probably be in the same place as normal recruitment and upkeep costs — below the unit card.

In order to modify a part of the UI you need to find where it's located. To do this we can use the Context Viewer. To find a UIC, open the Context Viewer, position your mouse on the screen where you want your UIC to go, and click with your mouse wheel. This will take you most, if not all, of the way to the path of your UIC. So click on the unit card then expand the unit card UIC in the Context Viewer until you find the UIC for recruitment cost. Once you've found it, paste CopyFullPathToClipboard() in the expression tester box. This copies the path to that UIC which is how we find it in the script.

When copied it will look like this: ":root:units_panel:main_units_panel:..." and so on.

Referencing my example mod, to find the recruitment cost UIC with a script you write it like this:

local recruitment_uic = find_uicomponent(core:get_ui_root(), "units_panel", "main_units_panel", "recruitment_docker", "recruitment_options", "recruitment_listbox", "local1", "unit_list", "listview", "list_clip", "list_box", "wh_main_emp_inf_swordsmen_recruitable", "unit_icon", "RecruitmentCost")
. 

It is fine as it is however it can be split into smaller easier to access parts like this:

local recruitment_uic = find_uicomponent(core:get_ui_root(), "units_panel", "main_units_panel", "recruitment_docker", "recruitment_options", "recruitment_listbox", recruitment_type)
local listview_uic = find_uicomponent(recruitment_uic, "unit_list", "listview")
local unit_uic = find_uicomponent(listview_uic, "list_clip", "list_box", "wh_main_emp_inf_swordsmen_recruitable")
local recruitment_cost_uic = find_uicomponent(unit_uic, "unit_icon", "RecruitmentCost")

📷 Creating / Copying Components:

Next up you need to copy the recruitment cost UIC. To do that you

UIComponent(recruitment_cost_uic:CopyComponent("prestige_cost"))