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) or scripting in general 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

The first step in building the UI is figuring out where you want your Pooled Resource cost to appear. Do you want to keep the vanilla treasury recruitment cost? Do you want several Pooled Resource costs? Do you want it below the unit card like normal treasury costs or on the side of the unit card like the Wood Elves' Amber resource?

If you don't want a recruitment cost and only want a Pooled Resource cost then you can technically skip most of this section and just reuse the vanilla Recruitment Cost UIC, however I would highly recommend still reading this section to better understand the process.

For the purpose of this guide we will be making one new Pooled Resource cost in addition to the vanilla costs which will go in the same place, below the unit card.

🔍 Finding UI Components:

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 need to use uicomponent:CopyComponent() and name the new UIC e.g. "prestige cost" like this:

UIComponent(recruitment_cost_uic:CopyComponent("prestige_cost"))

Using the paths we've previously established, the path for this new "prestige_cost" UIC we've created is therefore:

local prestige_cost_parent_uic = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")

⬇️ Repositioning Components:

This part is a bit more tedious. You will need to use the console (shift + f3) from Groove's Modding Development Tools to reposition the new "prestige_cost" UIC we've created. To do that you need to use uicomponent:SetDockOffset() like this:

local prestige_cost_parent_uic = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")
prestige_cost_parent_uic:SetDockOffset(8, 19)

The coordinates of x = 8, y = 19 are where I've worked out it needs to go but to play around with this yourself or for example for a different UIC such as lords you will need to choose some numbers and see where it ends up. Start small and work up. If you 'really' want to make sure it's in the right place you can do a bit of pixel peeping and count the pixels between e.g. the recruitment cost UIC and the upkeep cost UIC and that's how many pixels your new component should be below the recruitment cost UIC. This all changes however if you don't want any treasury recruitment cost at all and you only want the Pooled Resource cost. You wouldn't have to copy or reposition any UICs you could just reuse the existing recruitment cost UIC and follow the rest of the guide but now we're getting ahead of ourselves!

Next you need to move

UIComponent(recruitment_cost_uic:CopyComponent("prestige_cost"))