Total War Modding - User contributions [en]

Main Page

2025-09-30T01:18:28Z

Vandy: Add Discord links

== THIS IS A WIKI ==
Hi! Just wanted to shout that you can '''sign up for an account to help contribute any changes to the wiki!''' It's a wiki! It's not just one guy!

If you request an account, just let us know in the #modding_wiki channel in the [https://discord.gg/moddingden Modding Den Discord], and we'll let you in as soon as we can!

please help.
== Help Out ==
To give a hand, please check out the page [[Meta]] for the various bits of stuff we've marked as necessary. There are also pages in [[:Category:To Edit]] which have listed changes needed.

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/moddingden Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

MediaWiki:Sidebar

2024-07-06T16:12:22Z

Vandy:

* navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
** randompage-url|randompage
** helppage|help-mediawiki
** Special:GoogleCustomWikiSearch|Search
* TW Links
** https://discord.gg/dd4TUDm|Modding Den Discord
** https://www.totalwar.com/|Official TW Site
** https://chadvandy.github.io/tw_modding_resources/index.html|Creative Assembly Scripting Documentation
* TOOLBOX
* LANGUAGES

MediaWiki:Sidebar

2024-07-06T16:10:33Z

Vandy:

MediaWiki:Sidebar

2024-07-06T16:09:56Z

Vandy:

* navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
** randompage-url|randompage
** helppage|help-mediawiki
** Special:GoogleCustomWikiSearch
* TW Links
** https://discord.gg/dd4TUDm|Modding Den Discord
** https://www.totalwar.com/|Official TW Site
** https://chadvandy.github.io/tw_modding_resources/index.html|Creative Assembly Scripting Documentation
* SEARCH
* TOOLBOX
* LANGUAGES

Main Page

2024-07-06T00:38:11Z

Vandy: /* THIS IS A WIKI */

== THIS IS A WIKI ==
Hi! Just wanted to shout that you can '''sign up for an account to help contribute any changes to the wiki!''' It's a wiki! It's not just one guy!

If you request an account, just let us know in the #modding_wiki channel in the Modding Den Discord, and we'll let you in as soon as we can!

please help.
== Help Out ==
To give a hand, please check out the page [[Meta]] for the various bits of stuff we've marked as necessary. There are also pages in [[:Category:To Edit]] which have listed changes needed.

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

Main Page

2024-07-06T00:37:50Z

Vandy:

== THIS IS A WIKI ==
Hi! Just wanted to shout that you can '''sign up for an account to help contribute any changes to the wiki!''' It's a wiki! It's not just one guy!

If you request an account, just let us know in the #modding_wiki channel in the Modding Den Discord, and we'll let you in as soon as we can!

please help.
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

== Help Out ==
To give a hand, please check out the page [[Meta]] for the various bits of stuff we've marked as necessary. There are also pages in [[:Category:To Edit]] which have listed changes needed.

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

Main Page

2024-07-06T00:29:06Z

Vandy: /* NEW WEBSITE */

== THIS IS A WIKI ==
Hi! Just wanted to shout that you can '''sign up for an account to help contribute any changes to the wiki!''' It's a wiki! It's not just one guy!

If you request an account, just let us know in the #modding_wiki channel in the Modding Den Discord, and we'll let you in as soon as we can!
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

== Help Out ==
To give a hand, please check out the page [[Meta]] for the various bits of stuff we've marked as necessary. There are also pages in [[:Category:To Edit]] which have listed changes needed.

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

Category:DB Table

2024-05-29T20:57:03Z

Vandy: Created blank page

Tutorial:Pooled Resource Unit Costs

2023-07-14T00:00:42Z

Vandy: Vandy moved page Tutorial:Pooled Resource Costs to Tutorial:Pooled Resource Unit Costs over a redirect without leaving a redirect

= Total War: Warhammer 3 Guide by Pear =
This guide and the [[:File:!units_cost_pooled_resource.pack|example mod]] are my submission for '''Mod Jam #7'''.

[https://tw-modding.com/wiki/Tutorial:Pooled_Resources_Updated Pooled Resources] are cool. The problem is their application is often limited. This tutorial aims to fix that by explaining how to use Pooled Resources as costs for units in the main recruitment panel and providing an [[:File:!units_cost_pooled_resource.pack|example mod]] for reference. The method used here can be applied to a range of other things such as RoRs, lords, agents, buildings, technologies, or anything like that.

There's currently nothing in the tables to make units cost Pooled Resources except for a few faction-specific things so we have to use Lua UI scripting instead. It works by checking when the player has clicked certain units, taking away the defined cost of those units, and creating some UI components (UICs) to visualise all this. The process consists of two main parts:

# [https://tw-modding.com/wiki/Tutorial:Pooled_Resource_Costs#%F0%9F%8E%A8_Making_the_UI '''Making the UI''']: making UICs, enabling and disabling UICs, and setting text, tooltips, and icons.
# [https://tw-modding.com/wiki/Tutorial:Pooled_Resource_Costs#%F0%9F%8E%AE_Triggering_the_UI '''Triggering the UI''']: creating the UI at the right time, accounting for UI refreshes, and taking away / returning the Pooled Resource to the player in a multiplayer-friendly way.

Before we get started I'd recommend using my [[:File:!units_cost_pooled_resource.pack|example mod]] as a reference, as well as Groove Wizard's [https://github.com/chadvandy/tw_autogen Visual Studio development environment] for your scripting, and Groove's [https://steamcommunity.com/sharedfiles/filedetails/?id=2791799449 Modding Development Tools: Lua Console] to test the code in game (yes this man is a machine). This guide assumes some knowledge of RPFM and scripting.

== 🧑‍🎓 Some UI Basics ==
If you're not familiar with UI modding then you may find this section useful. If you're too kool for skool, move along!

=== 🔍 Finding UI Components ===
[[File:Recruitment cost component.png|right|thumb|Recruitment Cost Component in the Context Viewer]]
In order to modify a part of the UI you need to find where it's located. To do this we can use the [https://tw-modding.com/wiki/Tutorial:Context_Viewer_(Warhammer_3) Context Viewer]. A quick way to do this is by having the Context Viewer open and clicking on the screen with your mouse wheel.

For the purpose of this tutorial, try clicking the unit card you want to add a Pooled Resource to then expanding the unit card path in the Context Viewer until you find the "RecruitmentCost" UIC. Once you've found it, paste <code>CopyFullPathToClipboard()</code> in the expression tester box. This copies the path to that UIC.

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

Referencing my example mod, you can write the path to the recruitment cost UIC for the Swordsmen unit like this:
<code>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")</code>

It is fine as it is however it can be split into smaller, easier-to-access parts like this:
<code>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")</code>

=== 📷 Creating / Copying Components ===
For our purposes we will probably only need to create copies of pre-existing UICs. To do that you need to use <code>[https://chadvandy.github.io/tw_modding_resources/WH3/campaign/uicomponent.html#function:uicomponent:CopyComponent uicomponent:CopyComponent()]</code> which is being used here to copy the recruitment cost UIC for the Swordsmen unit and naming the new UIC "prestige cost":
<code>UIComponent(recruitment_cost_uic:CopyComponent("prestige_cost"))</code>

Using the paths we've previously established, the path for this new "prestige_cost" UIC we've created is therefore:
<code>local prestige_cost_parent_uic = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")</code>

=== ⬇️ Repositioning Components ===
This part is a bit more tedious. You will need to use the console (shift + f3) from Groove's Modding Dev Tools to test where the new "prestige_cost" UIC we've created should be repositioned. To do that you need to use <code>[https://chadvandy.github.io/tw_modding_resources/WH3/campaign/uicomponent.html#function:uicomponent:SetDockOffset uicomponent:SetDockOffset()]</code>. Using the code below you can test coordinates e.g. x = 0, y = 5 until the new UIC looks like it's in the right place:
<code>local prestige_cost_parent_uic = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")
prestige_cost_parent_uic:SetDockOffset(x, y)</code>

If you ''really'' want to make sure it's in the right place take a screenshot and do a bit of pixel peeping in a photo editor and count the pixels between e.g. the original recruitment cost and the upkeep cost UICs and that's how many pixels your new component should be below the recruitment cost UIC.

Using my example mod, we can see that the correct coordinates for the new component in the normal recruitment panel are:
<code>prestige_cost_parent_uic:SetDockOffset(8, 19)</code>
this may change depending on the faction or panel e.g. RoRs or lords.

=== ↗️ Resizing Components ===
Resizing components may be necessary if you're adding UICs, especially resizing list clips which would otherwise cut off the new UICs you've made. To do that you need to use [https://chadvandy.github.io/tw_modding_resources/WH3/campaign/uicomponent.html#function:uicomponent:Resize Resize] like this:

<code>unit_uic:SetCanResizeHeight(true)
unit_uic:SetCanResizeWidth(true)
local width, height= unit_uic:Dimensions()
unit_uic:Resize(width, (height + + 10), false)</code>

=== 🪟 Finding panels ===
To find the name of the panel that you want to check is opened or closed you can check the log produced by Groove's Modding Dev Tools. In the log it will look something like this:

<code>[ui] <97.6s> Panel opened units_panel
[ui] <98.8s> Panel opened recruitment_options
[ui] <98.8s> Panel opened units_recruitment</code>

== 🎨 Making the UI ==
So let's start! First we'll be looking at two functions — <code>initialise_uics()</code> and <code>finalise_uics()</code> . In short, the two functions apply the UI knowledge we covered earlier (and a little extra) to create UICs, resize UICs, and set their docking points, text, and icons. The functions are seperated even though they do similar things because the first one has to run only when the panel is opened, whereas the second has to run every time the UI is refreshed while the panel is open. For the purpose of the guide we will be keeping the vanilla treasury costs and making one new Pooled Resource cost which will go below the unit card.

'''IMPORTANT''': Make sure you change the '''listener and saved value names''' from the examples to avoid incompatibilities.

=== 🚀 Initialising UICs ===
First, we need a table for the units we want to have Pooled Resource costs. It should contain the loc key for the unit's onscreen name, the unit's UIC (which is just the unit's key plus "_recruitable"), and the Pooled Resource cost. Together it should look like this:

<code>local pr_units = {
{unit_name_loc = "land_units_onscreen_name_wh_main_emp_inf_spearmen_1", unit_uic = "wh_main_emp_inf_spearmen_1_recruitable", prestige_cost = 18},
{unit_name_loc = "land_units_onscreen_name_wh_main_emp_inf_swordsmen", unit_uic = "wh_main_emp_inf_swordsmen_recruitable", prestige_cost = 19}
}</code>

This table is then used in the functions <code>initialise_uics()</code> and <code>finalise_uics()</code>.

The first function <code>initialise_uics()</code> handles resizing the parents for UICs to make sure the list clips are displaying our new components and everything else appears correctly. The first part of that runs in a loop, once for local and once for global recruitment if the UIC exists then it proceeds:

<code>local function initialise_uics()
out("PR UNIT COST LOG - Initialising components.")
local recruitment_type
local b
if cm:get_saved_value("EXAMPLE_ENCAMP_CLICKED") == true then
b = 2
else
b = 1
end
for g = b, 2 do
if g == 1 then
recruitment_type = "local1"
elseif g == 2 then
recruitment_type = "global"
end
local recruitment_uic = find_uicomponent(core:get_ui_root(), "units_panel", "main_units_panel", "recruitment_docker", "recruitment_options", "recruitment_listbox", recruitment_type)
if recruitment_uic then</code>

Next it finds the UICs we'll be using and deals with a weird UI quirk with changing stances several times:

<code>local recruitment_docker_uic = find_uicomponent(core:get_ui_root(), "units_panel", "main_units_panel", "recruitment_docker")
local unit_list = find_uicomponent(recruitment_uic, "unit_list")
local listview_uic = find_uicomponent(unit_list, "listview")
local hslider_uic = find_uicomponent(listview_uic, "hslider")
local list_clip_uic = find_uicomponent(listview_uic, "list_clip")
local list_box_uic = find_uicomponent(list_clip_uic, "list_box")
-- to prevent some weird quirk with UI when you switch between army stances several times
if recruitment_type == "global" and cm:get_saved_value("pr_cost_encamp_clicked") ~= true then
cm:set_saved_value("pr_cost_encamp_clicked", true)
end</code>

The next part uses a unit from our table as a reference. If none of the units exist, the function ends.
<code>local reference_unit
for i = 1, #pr_units do
reference_unit = pr_units[i].unit_uic
local unit_uic = find_uicomponent(list_box_uic, reference_unit)
if unit_uic then
break
elseif unit_uic == false then
reference_unit = nil
break
end
end
if reference_unit ~= nil then</code>

The next part makes the UIC's we found earlier able to be resized, and resizes according to the dimensions of adding another recruitment cost UIC and whether the slider for multiple units exists. There is also some fine-tuning to make sure the UI doesn't clip anything. Finally it then runs <code>finalise_uics()</code>.

<code>local unit_uic = find_uicomponent(list_box_uic, reference_unit)
local recruitment_cost_uic = find_uicomponent(unit_uic, "unit_icon", "RecruitmentCost")
-- dimensions for resizing components
local width_rcc, height_rcc = recruitment_cost_uic:Dimensions()
-- if the slider if there to scroll through multiple units we need to resize things differently
if hslider_uic then
-- resizing recruitment_docker
local width_rdc, height_rdc = recruitment_docker_uic:Dimensions()
recruitment_docker_uic:SetCanResizeHeight(true)
recruitment_docker_uic:SetCanResizeWidth(true)
recruitment_docker_uic:Resize(width_rdc, (height_rdc + (height_rcc * 4)), false)
-- resizing unit_list
local width_lrc, height_lrc = unit_list:Dimensions()
unit_list:SetCanResizeHeight(true)
unit_list:SetCanResizeWidth(true)
unit_list:Resize(width_lrc, (height_lrc + (height_rcc * 2)), false)
else
-- resizing recruitment_docker
local width_rdc, height_rdc = recruitment_docker_uic:Dimensions()
recruitment_docker_uic:SetCanResizeHeight(true)
recruitment_docker_uic:SetCanResizeWidth(true)
recruitment_docker_uic:Resize(width_rdc, (height_rdc + (height_rcc * 2)), false)
-- resizing unit_list
local width_lrc, height_lrc = unit_list:Dimensions()
unit_list:SetCanResizeHeight(true)
unit_list:SetCanResizeWidth(true)
unit_list:Resize(width_lrc, (height_lrc + height_rcc), false)
end
-- resizing list_clip
local width_lcc, height_lcc = list_clip_uic:Dimensions()
list_clip_uic:SetCanResizeHeight(true)
list_clip_uic:SetCanResizeWidth(true)
list_clip_uic:Resize(width_lcc, (height_lcc + (height_rcc * 2) + 5), false) -- the plus 5 is to make sure there's no clipping at the bottom of the upkeep cost component
end
end
end
-- handling pr cost components
out("PR UNIT COST LOG - finalise_uics() from initialise_uics().")
finalise_uics()</code>

=== 👋 Finalising UICs ===

The second function <code>finalise_uics()</code> handles the creation of our new UICs, setting the Pooled Resource costs, text, tooltips, icons, and handling anything that gets refreshed when UICs are clicked. The first part loops the whole function for local and global recruitment, if one of those doesn't exist in the UI then that part of the function doesn't run. So if your army is not encamped then it won't cause a script error by trying to run the global part of the function.

<code>local recruitment_type
for g = 1, 2 do
if g == 1 then
recruitment_type = "local1"
elseif g == 2 then
recruitment_type = "global"
end
local recruitment_uic = find_uicomponent(core:get_ui_root(), "units_panel", "main_units_panel", "recruitment_docker", "recruitment_options", "recruitment_listbox", recruitment_type)
if recruitment_uic then</code>

The next part finds the UICs we'll be using in the function and creates our new "prestige_cost" UIC:

<code>for i = 1, #pr_units do
local unit_name = common.get_localised_string(pr_units[i].unit_name_loc)
local prestige_cost = pr_units[i].prestige_cost
local listview_uic = find_uicomponent(recruitment_uic, "unit_list", "listview")
local hslider_uic = find_uicomponent(listview_uic, "hslider")
local unit_uic = find_uicomponent(listview_uic, "list_clip", "list_box", pr_units[i].unit_uic)
if unit_uic then
local recruitment_cost_uic = find_uicomponent(unit_uic, "unit_icon", "RecruitmentCost")
local upkeep_cost_uic = find_uicomponent(unit_uic, "unit_icon", "UpkeepCost")
local prestige_cost_uic_check = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")
if prestige_cost_uic_check == false then
UIComponent(recruitment_cost_uic:CopyComponent("prestige_cost"))
end</code>

The next part resizes and repositions the UICs we found above, including the new "prestige_cost" UIC we just created:

<code> -- dimensions for resizing components
local width_rcc, height_rcc = recruitment_cost_uic:Dimensions()
-- resizing unit component
local width_uc, height_uc = unit_uic:Dimensions()
unit_uic:SetCanResizeHeight(true)
unit_uic:SetCanResizeWidth(true)
unit_uic:Resize(width_uc, (height_uc + (height_rcc * 2) + 5), false)
-- repositioning list_view
listview_uic:SetDockOffset(0, -24)
-- repositioning cost components
local prestige_cost_parent_uic = find_uicomponent(unit_uic, "unit_icon", "prestige_cost")
local prestige_cost_uic = find_uicomponent(prestige_cost_parent_uic, "Cost")
prestige_cost_parent_uic:SetDockOffset(8, 19)
upkeep_cost_uic:SetDockOffset(8, 42)
-- repositioning the hslider_uic
if hslider_uic then
hslider_uic:SetDockOffset(8, 49)
end</code>

Finally, we then set the text, tooltip, and icon, disable the unit card UICs if the player doesn't have enough of the Pooled Resource, and hide the cost modified icon for ease.

<code>local faction = cm:get_faction(cm:get_local_faction_name(true))
local player_prestige = faction:pooled_resource_manager():resource("emp_prestige"):value()
if player_prestige >= prestige_cost then
-- setting cost text
prestige_cost_uic:SetStateText(tostring(prestige_cost), "")
else
-- setting cost text
prestige_cost_uic:SetStateText(tostring("[[col:red]]"..prestige_cost.."[[/col]]"), "")
local unit_uic_tooltip = unit_uic:GetTooltipText()
local cannot_recruit_loc = common.get_localised_string("random_localisation_strings_string_StratHudbutton_Cannot_Recruit_Unit0")
local insufficient_pr_loc = common.get_localised_string("pear_insufficient_pr_prestige_tooltip")
local unit_uic_tooltip_gsub = unit_uic_tooltip:gsub('[%W]', '')
local left_click_loc_gsub = (common.get_localised_string("random_localisation_strings_string_StratHud_Unit_Card_Recruit_Selection")):gsub('[%W]', '')
if string.match(unit_uic_tooltip_gsub, left_click_loc_gsub) then
unit_uic:SetTooltipText(unit_name.."\n\n"..cannot_recruit_loc.."\n\n"..insufficient_pr_loc, "", true)
out("PR UNIT COST LOG - Tooltip for just insufficient prestige.")
else
unit_uic:SetTooltipText(unit_uic_tooltip.."\n"..insufficient_pr_loc, "", true)
out("PR UNIT COST LOG - Tooltip for prestige plus stuff.")
end
-- disabling recruitment of unit
unit_uic:SetState("inactive")
unit_uic:SetDisabled(true)
end
-- setting cost icon
prestige_cost_uic:SetImagePath("ui/skins/default/prestige_bar_icon.png", 0)
-- setting cost tooltip
prestige_cost_parent_uic:SetTooltipText(common.get_localised_string("pear_pr_prestige_cost_tooltip"), "", true)
-- setting the cost modified icon to invisible as the CCO is still for recruitment cost so make it appear when intended
local cost_modified_icon_uic = find_uicomponent(prestige_cost_uic, "cost_modified_icon")
cost_modified_icon_uic:SetVisible(false)
end
end
end
end
end</code>

== 🎮 Triggering the UI ==
To make the UI components work we need listeners! The first one is <code>PanelOpenedCampaign</code>. We can use this to tell when the main recruitment panel <code>"units_recruitment"</code> is open so we can start setting up our UI. This is important because the UI usually refreshes when certain UICs are clicked which causes the panel to re-open. We also need a saved value to make sure the listener doesn't continually resize the parent UI components every time something is clicked. Together the listener looks like this:

<code> core:add_listener(
"EXAMPLE_PANEL_OPENED",
"PanelOpenedCampaign",
function(context)
return context.string == "units_recruitment"
end,
function()
out("PR UNIT COST LOG - units_recruitment panel opened.")
if cm:get_saved_value("EXAMPLE_UICS_INITIALISED") ~= true then
cm:set_saved_value("EXAMPLE_UICS_INITIALISED", true)
initialise_uics()
else
out("PR UNIT COST LOG - finalise_uics() from pr_unit_cost_units_recruitment_opened.")
finalise_uics()
end
end,
true
)</code>

A refresh to the UI occurs when switching army stance. This messes up the sizing of the parent panels. To account for this we need to use <code>ComponentLClickUp</code> which checks when the stance changes occur like this:

<code>core:add_listener(
"EXAMPLE_UICS_CLICKED",
"ComponentLClickUp",
true,
function(context)
if string.match(context.string, "button_MILITARY_FORCE_ACTIVE_STANCE_TYPE_SET_CAMP") then
cm:callback(
function()
if cm:get_saved_value("EXAMPLE_ENCAMP_CLICKED") ~= true then
cm:set_saved_value("EXAMPLE_ENCAMP_CLICKED", true)
initialise_uics()
else
out("PR UNIT COST LOG - finalise_uics() from pr_unit_cost_finalise_uics.")
finalise_uics()
end
end,
0.1
)
elseif string.match(context.string, "button_MILITARY_FORCE_ACTIVE_STANCE_TYPE") then
cm:callback(
function()
out("PR UNIT COST LOG - finalise_uics() from pr_unit_cost_finalise_uics.")
finalise_uics()
end,
0.1
)
end</code>

'''*'''This listener is '''used again later''' and combined with something else.

Now we need to use <code>PanelClosedCampaign</code> to reset our saved values when the entire <code>"units_panel"</code> closes.

<code>core:add_listener(
"EXAMPLE_PANEL_CLOSED",
"PanelClosedCampaign",
function(context)
return context.string == "units_panel"
end,
function()
out("PR UNIT COST LOG - units_panel panel closed.")
cm:set_saved_value("EXAMPLE_UICS_INITIALISED", false)
cm:set_saved_value("EXAMPLE_ENCAMP_CLICKED", false)
end,
true
)</code>

Next we need to use <code>ComponentLClickUp</code> and <code>UITrigger</code>. These listeners act as a pair — <code>ComponentLClickUp</code> sends a message using <code>TriggerCampaignScriptEvent</code> to the <code>UITrigger</code> to keep things multiplayer-friendly (for more info on how that works see [https://tw-modding.com/wiki/Multiplayer_Desyncs this guide]).

What is that message you may ask? Well, when the mouse hovers over a unit card, the stats panel for the unit becomes visible. At the moment the unit card is clicked, <code>ComponentLClickUp</code> gets the name of the unit from the stats panel and makes a saved value for it. It checks it against our onscreen name loc provided in our table and if they match then

[[File:klopp-boom2.gif|250px]]

<code>local unit_info_uic = find_uicomponent(core:get_ui_root(), "hud_campaign", "unit_info_panel_adopter", "unit_information_parent", "unit_info_panel_holder_parent", "unit_info_panel_holder", "unit_information", "info_parent", "info_panel", "tx_unit-type")
if unit_info_uic then
local unit_ui_name = unit_info_uic:GetStateText()
for i = 1, #pr_units do
local unit_name = common.get_localised_string(pr_units[i].unit_name_loc)
if unit_ui_name == unit_name then
cm:set_saved_value("EXAMPLE_UNIT_NAME", unit_name)
CampaignUI.TriggerCampaignScriptEvent(cm:get_faction(cm:get_local_faction_name(true)):command_queue_index(), context.string .."Clicked")
return
end
end
end
end,
true
)</code>

'''*'''This then combines with the encamp stance check into the same listener.

Finally, you have the <code>UITrigger</code> listener which receives the message. This then adds or subtracts the Pooled Resource from the player depending on whether they've recruited the unit or cancelled recruitment.

<code>core:add_listener(
"pr_unit_cost_handle_pr_cost_ui_trigger",
"UITrigger",
true,
function(context)
for i = 1, #pr_units do
local unit_name = common.get_localised_string(pr_units[i].unit_name_loc)
if unit_name == cm:get_saved_value("EXAMPLE_UNIT_NAME") then
local unit_uic = pr_units[i].unit_uic
local prestige_cost = pr_units[i].prestige_cost
if context:trigger() == unit_uic.."Clicked" then
local faction_cqi = context:faction_cqi();
local faction_key = cm:model():faction_for_command_queue_index(faction_cqi):name()
cm:faction_add_pooled_resource(faction_key, "emp_prestige", "events_negative", -prestige_cost)
return
elseif context:trigger():starts_with("Queued") then
local faction_cqi = context:faction_cqi();
local faction_key = cm:model():faction_for_command_queue_index(faction_cqi):name()
cm:faction_add_pooled_resource(faction_key, "emp_prestige", "events_negative", prestige_cost)
return
end
end
end
end,
true
)</code>

And that's it!

Main Page

2023-07-01T14:56:23Z

Vandy: /* Help Out */

== NEW WEBSITE ==
Yes, yes, we're on our sixth or seventh or eight iteration of this website!

This newest version is built upon MediaWiki (same thing Wikipedia uses), and is very much a work in progress, but it's hopefully a much better time all around.
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

== Help Out ==
To give a hand, please check out the page [[Meta]] for the various bits of stuff we've marked as necessary. There are also pages in [[:Category:To Edit]] which have listed changes needed.

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

Meta

2023-07-01T14:55:52Z

Vandy:

This is a meta-page about things involving the website itself. Pretty meta, huh?

[[:Category:To Edit]]

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.
* <s>Look into WYSIWYG editor for the wiki. Previously used version was buggy, but it might be better on the latest update of MediaWiki.</s>
** Works perfectly on the new version!
* Search for better moderation tools, more all-in-one packages.
* Setup a more robust sidebar, include links to the Modding Den and such.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Move". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

MediaWiki:Sidebar

2023-07-01T14:54:49Z

Vandy:

* navigation
** mainpage|mainpage-description
** recentchanges-url|recentchanges
** randompage-url|randompage
** helppage|help-mediawiki
* TW Links
** https://discord.gg/dd4TUDm|Modding Den Discord
** https://www.totalwar.com/|Official TW Site
** https://chadvandy.github.io/tw_modding_resources/index.html|Creative Assembly Scripting Documentation
* SEARCH
* TOOLBOX
* LANGUAGES

Main Page

2023-07-01T14:54:22Z

Vandy: /* Help Out */

== NEW WEBSITE ==
Yes, yes, we're on our sixth or seventh or eight iteration of this website!

This newest version is built upon MediaWiki (same thing Wikipedia uses), and is very much a work in progress, but it's hopefully a much better time all around.
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

== Help Out ==
[[Meta]]

There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!

- [[Tutorial:Main Page|Tutorials]] should be named "Tutorial:Tutorial Name Here"

- Any other page can be named anything else, it doesn't matter. Please mind that only one page can exist with that name, of course, so be proper with your names.

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

MediaWiki:Sidebar

2023-07-01T14:43:39Z

Vandy:

MediaWiki:Sidebar

2023-07-01T14:43:19Z

Vandy:

Lua/First Script

2023-06-11T22:51:30Z

Vandy:

In this first step tutorial, we're going to learn:

* How to load & run a custom Lua script
* How timing works, at a large level, with scripts
* How to print out game information to interrogate the state of the game
* How simple variables work

Let's create our first script together!

== Setup ==
First thing's first, let's crack open RPFM to create our new Mod. In RPFM, I'm going to use MyMod -> New MyMod, to create a new easy-to-use mod system. If you haven't already, follow the setup guides in [[RPFM]] for setting up preferences and paths.

[[File:First Script 01.png|frameless|712x712px]]

RPFM will then open up our new MyMod. Within it, use MyMod -> Export, which will unload the contents of the newly created (almost entirely empty) MyMod into your specified MyMods folder. I have this folder pinned to my quick access, but you can also get there with MyMod -> Open MyMod Folder, and navigating down to the newly created MyMod.

Now we can right click this folder and use the newly added "Open with Code" button, which will take the targeted mod folder and open it within Visual Studio Code!

== Visual Studio Code Navigation ==
When we open up in Visual Studio Code, we'll see something that looks a little bit like this - it might differ slightly, that's totally okay!
[[File:First script 2.png|none|thumb|1061x1061px|It might seem like quite a lot at first, but we'll get used to it! Just make sure to set the settings to dark mode if you're not insane.]]

Before we get too far, let's break down some of the parts of what we're looking at here, and set up our windows so we have everything we need.

=== Primary Bar ===
On the very left, we have what VSCode calls the "Primary Bar". It has a few things here - the top has the two files stacked on each other, a search button below that, three buttons we don't have to worry too much about yet, and a Bookmark button. The bottom has our Account and Manage button. '''If you haven't already''', click into the Manage button and set our Profile to the correct one. I have mine saved as "TW Lua".

The part of the primary bar we care most about is the top button, the "Explorer". Think of this as your file navigation - it's effectively the same as navigating the Windows File Explorer, but it has some extra goodies that will be nice for us.
[[File:First script 3.png|left|thumb|578x578px]]
At the top of the Explorer, we have "Open Editors". This will show us all of our actively opened files - we'll see this shortly!

Below that, we have a tab for the currently opened folder. My folder is named babys_first_script, so that's what shows as the name here. Inside are all of the folders AND files that exist within my folder on my PC. We can open, create, rename, and delete any file within to our heart's content, and edit as long as Visual Studio Code can edit it. VSCode can edit essentially any text file, which is what all code files are, effectively. Based on the type of text file, VSCode will handle it differently - it knows the difference between a .lua and a .json file, and will react accordingly to the specifications of either language.

Below that, we had "TODOs: Tree", which is an extension preloaded with our Profile. This is one of my favorite tabs, because I can leave notes for myself to do stuff later and they will be displayed in this window.

Below that are Outline and Timeline, which I rarely use but can sometimes be nice. Outline will show us the layout of our code, and Timeline will show us previous local history for saving/editing these files, and more details if we're using GitHub or another version control software.

The Search button is also incredibly useful, for reasons that may be obvious.

=== Menu Bar ===
On the very top, we have our conveniently named Top Bar, or Menu Bar. You've seen these a billion times before. There's a LOT of stuff up here, but in my five years of using this program for TW Lua I've only really cared about a couple buttons within.

"File" is going to be our best friend, for opening new windows, saving, and creating new files. Edit/Selection/View have a load of commands in them, and they may be good to reference often early on to see shortcuts for saving and other helpful code shortcuts, like duplicating text or renaming stuff.

For now, what we should do is click View -> Problems, which will open up a new bottom bar for us. We only care about the "Problems" tab that shows up.

=== Customizabilitization ===
Let's introduce the idea here that VSCode is '''super duper''' flexible with its layout. Anything on your screen right now can be put somewhere else, including individual tabs, buttons, anything. We can move Problems as a button to the Primary Bar, the Explorer as a tab on the bottom, and TODOs on the right all alone.
[[File:First script 4.png|thumb|824x824px]]
It's a bit clunky and not exactly what I need, but it's as good time as any to show you how flexible it can get.

For now, I'm going to plop Search and TODOs on my new right sidebar stacked on one another, I'm going to right click one of the tabs at the bottom and deselect "Terminal", "Output", and "Debug Console", and keep my left Primary Bar as is otherwise and open back up the Explorer.

== Script Creation ==
Okay, enough preamble. Let's get it started.

=== The Plan ===
Our standard first step for creating a new script is the first step we should do whenever making a new mod or system: having a plan, something we want. For this one, our goal is going to be simple. I want the following:

* When the game starts, I want to output a message to a text file that tells me the game started, and tells me where my starting faction leader and capital region are.
* On every turn after that, I want to give my faction some extra gold.
* If I'm playing as Karl Franz, I want to give my faction another two armies.
* I swear it's balanced.

=== Make It ===
[[File:First script 5.png|left|thumb|Second button from the left!]]
In VSC, go to the Explorer, and hover over the currently-opened-folder tab. You can either right click within the white space and press "New Folder", or press the New Folder button on the tab for the currently opened folder.

Name the empty folder that's created `script`. All scripts we write will be in this main folder. With this folder selected, create a new folder again, and call this one "campaign". Do it again, calling the third "mod", making our full path script/campaign/mod.<blockquote>'''NOTE:''' This folder path is one of several that is specified by Creative Assembly in more recent games, for modders to add scripts to which get automatically loaded. This behavior exists in Warhammer II, Warhammer III, Three Kingdoms, and Troy. It may continue for future games, but any game before Warhammer II needs a different way to load scripts.

For more information, check out [[Lua/Loading Scripts]].</blockquote>Within script/campaign/mod, now either right click the folder and press "New Text File", or use the first button on the tab to create a new file. I'm going to name mine "totally_not_cheats.lua". '''The .lua extension is required, don't skip it!'''

=== Start It ===
With our newly created file, our VSC layout will change ever so slightly. In "Open Editors", we'll see our fresh new baby script created; and in the central window, we'll see a new tab that's named the same as our new file, and an empty text file in the center with just the number "1" in it.
[[File:First script 6.png|none|thumb|894x894px|Notice the lil' moon symbol next to our file? That's because Lua is Portuguese for moon!]]
We'll kick off our script with the first piece of the puzzle, outputting some text to a file so we can read and interface with our scripts.

Let's get it going with a function called `out()`. This is a CA-defined function that they use all over their scripts, to print out to a text file various bits of info about the game, for debugging and logging purposes. It's a really handy system that'll let you know for certain what's actually going on in your scripts at runtime, since we can't truly test our script outside of the game.

To use the `out` function, we just have to write that word, put an open parenthesis, put in what we want to output, and then write a closing parenthesis. Let's try the old standard, and toss in the following:<blockquote>out( Hello World! )</blockquote>And we should be goo- oh no! Everything's red! Why are there so many problems?!
[[File:First script 7.png|thumb|563x563px|If you don't see the above problems or red text, you probably didn't do the setup correctly in the previous lesson. Do it!]]

=== Debugging ===
This will be something we'll see maybe a million times as we go forward, and it's important to not get too stressed out about it early on.

Because of our work in [[Lua/Setup]], we now have access to a right proper debugging system that will yell at us when we do something wrong.

There's a lot of confusing bits here, and honestly, none of the problems listed are going to be specific enough to tell us what to do to fix it - at least in this situation. Some of them are telling us that we're arguing too much, one is talking about undefined globals, and one is just absolute pig latin saying it expected <exp>. None of those mean anything to us, but let's check out something that does - some documentation!

If you hover over the word "out", you'll see a popup that gives us some information about the function `out`. The most important bit is the following:
[[File:First script 8.png|none|thumb]]
This is our '''function definition'''. It tells us what the function is called, and what it expects within the parentheses. It's asking for something it calls "output", and output is a string. '''String''' is the first of several Lua "types" we'll go over in this tutorial series. A '''string''' is text - and it's called such because it's a string of ''characters'' that make up a long piece of text. The issue we've had here is that, while `Hello World!` is text, Lua needs to be told that it's a string type. To do that, we just need to wrap quotation marks - either single or double, doesn't matter, but it can't be backticks or "pretty" quotations like what mobile phones default to. I learned that the hard way.

The easiest way to do that is to highlight the entirety of Hello World! and type in the quotation mark, just one. VSCode will plop a quotation mark on either part of your selection, and all SEVEN of our problems will vanish through air.
[[File:First script 9.png|thumb|The white dot on our tab means this is an unsaved file; use Ctrl+S to save it!]]

== Getting It In-Game ==
We have now an incredibly basic script that I'd like to test out.

Now, the `out` function is defined by Creative Assembly within their games, but it comes '''disabled by default''' for retail. That means that while your code runs, it won't actually write anything to a log file. That way they can have their debugging tools, and we can opt into it, but it doesn't automatically happen for every single user.

This disable-by-default can be overridden in different ways, depending on the game. As of the time of writing this guide, my favorite methods are:

* Using the [https://steamcommunity.com/sharedfiles/filedetails/?id=2927955021 Mod Configuration Tool]'s setting for enabling game logging, if available for that game.
* Using the [https://steamcommunity.com/sharedfiles/filedetails/?id=2789857593&searchtext=script+debug+activator Script Debug Activator] mod, if available for that game.
* Creating a file in your mod at `script/enable_console_logging`, with no extension. You can use VSCode and use add text file at that destination, add any text inside the file and save it.

These may change or evolve as time goes on.

=== Loading ===
Once you've got your script ready, and your game is set up to have script logs printed out, we'll want to load up our .pack file and get it set in game. For the sake of my soul and time, I'm going to assume we know how packs work, creating them and loading them, and the like.

Step one, we've got to save our stuff in VSCode. Use File -> Save All.<blockquote>Worth a shout here - I altered the shortcut in Visual Studio Code for Save All, since it's maybe my most-used shortcut combination.

If you go to Manage -> Keyboard Shortcuts and type in "save all" in the search bar, you can click on that shortcut and type in on your keyboard what you'd prefer. I use Ctrl+Alt+S, but set it to whatever makes you happy.</blockquote>Then, in RPFM, use MyMod -> Import. Again, I added a keyboard shortcut here through RPFM - I set Import/Export to Ctrl+Alt+I/E. You can get there through PackFile -> Preferences -> Shortcuts.

Import '''pulls in all the stuff from your MyMod folder into your pack''', while '''export does the opposite'''. I use these all the time, since I externally edit Lua files but internally edit database tables. You'll want to keep in mind where you're working, because if you edit a Lua file externally, and then a table file internally, without adding the changes from one to the other, you may end up overwriting some of your work. Because of that, I will only ever work in one sphere, then use Import/Export to make sure the folder and my .pack line up, and then edit in the other sphere.

Save in RPFM, and use PackFile -> Install to move your .pack to the game folder. Tick it in your mod manager of choice, and load up a fresh campaign!

=== Log File ===
The game-created log files will spit out in your game's folder - ie., steam/steamapps/common/Total War WARHAMMER III/. They are created as "script_log_DDMMYY_HHMM.txt". So if I made one right now, it'd be "script_log_100623_1320.txt", if you were wondering when I wrote this exact line.

The game creates a new log file every time we enter the main menu, every time we enter a campaign, and every time we enter a battle - so if you only just started using script logs, there should be two or three in there depending on if you quit to main menu or to desktop after loading up your new campaign. Navigate to the latest one and open it up.

Worth noting here, I have a file association set up to automatically open .txt files in Visual Studio Code, because I find it easier and quicker to navigate. If you right click the script log -> open with -> target Visual Studio Code, you can get it in that way. You can also simply grab the file from your file explorer and drag it into the main VSCode window, and it will be opened up within.

There's going to be... a ''lot'' of stuff in here. A lot a lot. CA uses double quindrillion calls to `out()` throughout the game. We'll actually find that it's pretty cumbersome to navigate, and later on we'll create our '''own custom log files!''' But for now, let's navigate this chonker.

=== Find Your Text ===
''Sounds kinda like a platitude you'd find on a pillow in Kohl's.''

In our opened new script log, we should search for the words "Hello World!". We can either do that using the Search tab we have set up, or clicking into the script log in the main window and using Ctrl+F.
[[File:First script 10.png|none|thumb|911x911px|Our first trigger of stuff in the game!Hey, did you put a naughty word instead of "Hello World!"? You lil nasty gremlin.]]
WE FUCKING DID IT HELL YES.

And that's it, you're ready to script on your own!

Bye!

== Timin' 'n Stuff ==
You'll probably maybe notice, this text is triggered very, very early on. While it's maybe ~1000 lines of text in, it's only 1.8s seconds (at least, for me, with no other mods enabled) after the script log is created. This is earlier than it might sound. At this time, the game is still going through its loading procedures - this text was triggered before the loading bar even got to 20%!
Because of how early this is, the game '''is not ready to be accessed yet'''. The game doesn't yet know what factions own what regions, what turn it is, who the player is controlling, or anything like that. The game doesn't have a map object, you can't trigger a new battle, nothin'.

What we need to do for our next step is '''learn how to listen''' and '''wait'''. Some of the most valuable things we can do in programming are listening and waiting for the right time.

=== Events ===
'''''NOTE:''''' ''Not to be confused with the "Events" in-game, the messages and such that hang out with missions.''

The game has a great deal of "events" that can be triggered. Events are a way for scripts to learn some information about things happening in the game - there are events that will inform us when a new turn has started, when a region has been destroyed, when a battle has ended, when a ritual has been completed, when a mission has been failed, among many many many more. We can even define our own - more on that later!

The first event we care about is one of the most important - FirstTickAfterWorldCreated. This event is triggered immediately after the game is ready to access - about 80% of the way through the loading bar before the game is interactable for the user.

Once this event happens, we can do things like ask the game what factions exist, what turn it is, where we are, who we are, etc. Before the world is created, we can only do a bare minimum of setting things up in advance.

=== Flying the Time ===
To achieve our first goal - spitting out some information about our player faction - we're going to use a first tick callback and trigger our very own function!

A first tick callback is a way to '''ask the game to run code on FirstTickAfterWorldCreated'''. Most of your mods will probably involve a first-tick-callback. We use them in the following format:
cm:add_first_tick_callback(function_to_call)
But first, we have to create our own function. To do that, we use the following:
local function my_function_name()
-- do stuff
end
where "my_function_name" can be anything you want. In this situation, I'm going to call the function "init", short for "initialization", because this is the startpoint of my entire script. Some people also prefer "main". Whatever you want really, just make it clear for yourself and anyone else.

''Eagle-eyed readers will notice that the two dashes they wrote in VSCode will be greyed out; these are called "comments". These are incredibly useful to leave notes to ourselves and other people reading our scripts, to inform yourself and others of what's going on and how things work in our code.''

To safely confirm that we're calling our new function at the right time, we're going to run our function, trigger another call to out(), and see if it works!
[[File:First script 11.png|thumb|418x418px]]

=== Getting Our Info ===
With our first tick callback loading up properly, let's hop in and try to get some information about our played faction!

In the beginning of our init() function, we need to define a fresh new variable which will allow us to hold the faction "object" in memory. A variable is a piece of memory that your computer is going to set aside to hold some data for us - a variable can be a number, text, a function, or game objects like the faction.

We'll get it using the get_local_player() function, which we can find in the scripting documentation: https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#function:campaign_manager:get_local_faction

We'll be learning a lot about how to use and read the script documentation going forward.

In our init() function, we need to add the following line of code:
local player_faction = cm:get_local_faction()
Where player_faction is the name of our new variable. It can be anything you want, much like init(), but it should '''make sense''' and '''be clear to read'''. It needs to be all one contiguous word, with only text, underscores, and non-leading numbers allowed (ie. my_faction_1 is allowed, 1_my_faction is not).

Visual Studio Code should automate it for you, but make sure that it's after the init() keyword, is one line after the out() call, is before the `end` keyword, and is one tab over. I like to space my code out thought-by-thought, so this will be a bit lower than my out() code.
[[File:First script 12.png|none|thumb]]
The way we get information about this game object will be to ask it questions, using functions, or in this case '''methods'''.

The first thing we want to ask is, hey, what's the faction's name please?

To ask the game object questions, we need to use the variable name followed by the : sign. Our VSCode plugin will then, thankfully, list us with a great deal of suggestions that we can use. We can also reference [https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html#FACTION_SCRIPT_INTERFACE the scripting documentation for game objects].

Thankfully, what we want isn't too far away:
[[File:First script 13.png|none|thumb|946x946px|The autofill will show us the description of this method, and what it returns - in this case, it returns a "string", as we see after the -> line.]]
Whenever we call a function, if the function gives us something back, we have to assign it to a variable or it will go away and vanish into the ether, with no memory on your PC being used to "hold" onto it. Do that with something simple:<syntaxhighlight lang="lua">
local name = player_faction:name()
</syntaxhighlight>I'll keep harping on it, but you can change `local name` to whatever you want - `local key`, `local bits`, `local ostrich_on_fire`, whatever.

'''''NOTE:''''' ''It keeps saying name, but its actually referring to the faction's "key" as we'll see in a second - the "code name" is has in factions_tables.''

Now that we have the information in our code, we can put it all together and print that out to the log file:<syntaxhighlight lang="lua" line="1">
out( "Hello World!" )

local function init()
out("New game triggered!")

local player_faction = cm:get_local_faction()
local key = player_faction:name()

out("Playing as " .. key)
end

cm:add_first_tick_callback(init)
</syntaxhighlight>

== Learnin' Info ==
We've got something good going on, with information being spat out from the game telling us who we're playing as after the game has "begun" proper. This might seem like we've barely done anything, but this is the starting block that every game-altering script needs. We're off to a great start!

Lua/First Script

2023-06-10T18:44:39Z

Vandy:

Lua/First Script

2023-06-10T18:43:16Z

Vandy:

In this first step tutorial, we're going to learn:

* How to load & run a custom Lua script
* How timing works, at a large level, with scripts
* How to print out game information to interrogate the state of the game
* How simple variables work

Let's create our first script together!

== Setup ==
First thing's first, let's crack open RPFM to create our new Mod. In RPFM, I'm going to use MyMod -> New MyMod, to create a new easy-to-use mod system. If you haven't already, follow the setup guides in [[RPFM]] for setting up preferences and paths.

[[File:First Script 01.png|frameless|712x712px]]

RPFM will then open up our new MyMod. Within it, use MyMod -> Export, which will unload the contents of the newly created (almost entirely empty) MyMod into your specified MyMods folder. I have this folder pinned to my quick access, but you can also get there with MyMod -> Open MyMod Folder, and navigating down to the newly created MyMod.

Now we can right click this folder and use the newly added "Open with Code" button, which will take the targeted mod folder and open it within Visual Studio Code!

== Visual Studio Code Navigation ==
When we open up in Visual Studio Code, we'll see something that looks a little bit like this - it might differ slightly, that's totally okay!
[[File:First script 2.png|none|thumb|1061x1061px|It might seem like quite a lot at first, but we'll get used to it! Just make sure to set the settings to dark mode if you're not insane.]]

Before we get too far, let's break down some of the parts of what we're looking at here, and set up our windows so we have everything we need.

=== Primary Bar ===
On the very left, we have what VSCode calls the "Primary Bar". It has a few things here - the top has the two files stacked on each other, a search button below that, three buttons we don't have to worry too much about yet, and a Bookmark button. The bottom has our Account and Manage button. '''If you haven't already''', click into the Manage button and set our Profile to the correct one. I have mine saved as "TW Lua".

The part of the primary bar we care most about is the top button, the "Explorer". Think of this as your file navigation - it's effectively the same as navigating the Windows File Explorer, but it has some extra goodies that will be nice for us.
[[File:First script 3.png|left|thumb|578x578px]]
At the top of the Explorer, we have "Open Editors". This will show us all of our actively opened files - we'll see this shortly!

Below that, we have a tab for the currently opened folder. My folder is named babys_first_script, so that's what shows as the name here. Inside are all of the folders AND files that exist within my folder on my PC. We can open, create, rename, and delete any file within to our heart's content, and edit as long as Visual Studio Code can edit it. VSCode can edit essentially any text file, which is what all code files are, effectively. Based on the type of text file, VSCode will handle it differently - it knows the difference between a .lua and a .json file, and will react accordingly to the specifications of either language.

Below that, we had "TODOs: Tree", which is an extension preloaded with our Profile. This is one of my favorite tabs, because I can leave notes for myself to do stuff later and they will be displayed in this window.

Below that are Outline and Timeline, which I rarely use but can sometimes be nice. Outline will show us the layout of our code, and Timeline will show us previous local history for saving/editing these files, and more details if we're using GitHub or another version control software.

The Search button is also incredibly useful, for reasons that may be obvious.

=== Menu Bar ===
On the very top, we have our conveniently named Top Bar, or Menu Bar. You've seen these a billion times before. There's a LOT of stuff up here, but in my five years of using this program for TW Lua I've only really cared about a couple buttons within.

"File" is going to be our best friend, for opening new windows, saving, and creating new files. Edit/Selection/View have a load of commands in them, and they may be good to reference often early on to see shortcuts for saving and other helpful code shortcuts, like duplicating text or renaming stuff.

For now, what we should do is click View -> Problems, which will open up a new bottom bar for us. We only care about the "Problems" tab that shows up.

=== Customizabilitization ===
Let's introduce the idea here that VSCode is '''super duper''' flexible with its layout. Anything on your screen right now can be put somewhere else, including individual tabs, buttons, anything. We can move Problems as a button to the Primary Bar, the Explorer as a tab on the bottom, and TODOs on the right all alone.
[[File:First script 4.png|thumb|824x824px]]
It's a bit clunky and not exactly what I need, but it's as good time as any to show you how flexible it can get.

For now, I'm going to plop Search and TODOs on my new right sidebar stacked on one another, I'm going to right click one of the tabs at the bottom and deselect "Terminal", "Output", and "Debug Console", and keep my left Primary Bar as is otherwise and open back up the Explorer.

== Script Creation ==
Okay, enough preamble. Let's get it started.

=== The Plan ===
Our standard first step for creating a new script is the first step we should do whenever making a new mod or system: having a plan, something we want. For this one, our goal is going to be simple. I want the following:

* When the game starts, I want to output a message to a text file that tells me the game started, and tells me where my starting faction leader and capital region are.
* On every turn after that, I want to give my faction some extra gold.
* If I'm playing as Karl Franz, I want to give my faction another two armies.
* I swear it's balanced.

=== Make It ===
[[File:First script 5.png|left|thumb|Second button from the left!]]
In VSC, go to the Explorer, and hover over the currently-opened-folder tab. You can either right click within the white space and press "New Folder", or press the New Folder button on the tab for the currently opened folder.

Name the empty folder that's created `script`. All scripts we write will be in this main folder. With this folder selected, create a new folder again, and call this one "campaign". Do it again, calling the third "mod", making our full path script/campaign/mod.<blockquote>'''NOTE:''' This folder path is one of several that is specified by Creative Assembly in more recent games, for modders to add scripts to which get automatically loaded. This behavior exists in Warhammer II, Warhammer III, Three Kingdoms, and Troy. It may continue for future games, but any game before Warhammer II needs a different way to load scripts.

For more information, check out [[Lua/Loading Scripts]].</blockquote>Within script/campaign/mod, now either right click the folder and press "New Text File", or use the first button on the tab to create a new file. I'm going to name mine "totally_not_cheats.lua". '''The .lua extension is required, don't skip it!'''

=== Start It ===
With our newly created file, our VSC layout will change ever so slightly. In "Open Editors", we'll see our fresh new baby script created; and in the central window, we'll see a new tab that's named the same as our new file, and an empty text file in the center with just the number "1" in it.
[[File:First script 6.png|none|thumb|894x894px|Notice the lil' moon symbol next to our file? That's because Lua is Portuguese for moon!]]
We'll kick off our script with the first piece of the puzzle, outputting some text to a file so we can read and interface with our scripts.

Let's get it going with a function called `out()`. This is a CA-defined function that they use all over their scripts, to print out to a text file various bits of info about the game, for debugging and logging purposes. It's a really handy system that'll let you know for certain what's actually going on in your scripts at runtime, since we can't truly test our script outside of the game.

To use the `out` function, we just have to write that word, put an open parenthesis, put in what we want to output, and then write a closing parenthesis. Let's try the old standard, and toss in the following:<blockquote>out( Hello World! )</blockquote>And we should be goo- oh no! Everything's red! Why are there so many problems?!
[[File:First script 7.png|thumb|563x563px|If you don't see the above problems or red text, you probably didn't do the setup correctly in the previous lesson. Do it!]]

=== Debugging ===
This will be something we'll see maybe a million times as we go forward, and it's important to not get too stressed out about it early on.

Because of our work in [[Lua/Setup]], we now have access to a right proper debugging system that will yell at us when we do something wrong.

There's a lot of confusing bits here, and honestly, none of the problems listed are going to be specific enough to tell us what to do to fix it - at least in this situation. Some of them are telling us that we're arguing too much, one is talking about undefined globals, and one is just absolute pig latin saying it expected <exp>. None of those mean anything to us, but let's check out something that does - some documentation!

If you hover over the word "out", you'll see a popup that gives us some information about the function `out`. The most important bit is the following:
[[File:First script 8.png|none|thumb]]
This is our '''function definition'''. It tells us what the function is called, and what it expects within the parentheses. It's asking for something it calls "output", and output is a string. '''String''' is the first of several Lua "types" we'll go over in this tutorial series. A '''string''' is text - and it's called such because it's a string of ''characters'' that make up a long piece of text. The issue we've had here is that, while `Hello World!` is text, Lua needs to be told that it's a string type. To do that, we just need to wrap quotation marks - either single or double, doesn't matter, but it can't be backticks or "pretty" quotations like what mobile phones default to. I learned that the hard way.

The easiest way to do that is to highlight the entirety of Hello World! and type in the quotation mark, just one. VSCode will plop a quotation mark on either part of your selection, and all SEVEN of our problems will vanish through air.
[[File:First script 9.png|thumb|The white dot on our tab means this is an unsaved file; use Ctrl+S to save it!]]

== Getting It In-Game ==
We have now an incredibly basic script that I'd like to test out.

Now, the `out` function is defined by Creative Assembly within their games, but it comes '''disabled by default''' for retail. That means that while your code runs, it won't actually write anything to a log file. That way they can have their debugging tools, and we can opt into it, but it doesn't automatically happen for every single user.

This disable-by-default can be overridden in different ways, depending on the game. As of the time of writing this guide, my favorite methods are:

* Using the [https://steamcommunity.com/sharedfiles/filedetails/?id=2927955021 Mod Configuration Tool]'s setting for enabling game logging, if available for that game.
* Using the [https://steamcommunity.com/sharedfiles/filedetails/?id=2789857593&searchtext=script+debug+activator Script Debug Activator] mod, if available for that game.
* Creating a file in your mod at `script/enable_console_logging`, with no extension. You can use VSCode and use add text file at that destination, add any text inside the file and save it.

These may change or evolve as time goes on.

=== Loading ===
Once you've got your script ready, and your game is set up to have script logs printed out, we'll want to load up our .pack file and get it set in game. For the sake of my soul and time, I'm going to assume we know how packs work, creating them and loading them, and the like.

Step one, we've got to save our stuff in VSCode. Use File -> Save All.<blockquote>Worth a shout here - I altered the shortcut in Visual Studio Code for Save All, since it's maybe my most-used shortcut combination.

If you go to Manage -> Keyboard Shortcuts and type in "save all" in the search bar, you can click on that shortcut and type in on your keyboard what you'd prefer. I use Ctrl+Alt+S, but set it to whatever makes you happy.</blockquote>Then, in RPFM, use MyMod -> Import. Again, I added a keyboard shortcut here through RPFM - I set Import/Export to Ctrl+Alt+I/E. You can get there through PackFile -> Preferences -> Shortcuts.

Import '''pulls in all the stuff from your MyMod folder into your pack''', while '''export does the opposite'''. I use these all the time, since I externally edit Lua files but internally edit database tables. You'll want to keep in mind where you're working, because if you edit a Lua file externally, and then a table file internally, without adding the changes from one to the other, you may end up overwriting some of your work. Because of that, I will only ever work in one sphere, then use Import/Export to make sure the folder and my .pack line up, and then edit in the other sphere.

Save in RPFM, and use PackFile -> Install to move your .pack to the game folder. Tick it in your mod manager of choice, and load up a fresh campaign!

=== Log File ===
The game-created log files will spit out in your game's folder - ie., steam/steamapps/common/Total War WARHAMMER III/. They are created as "script_log_DDMMYY_HHMM.txt". So if I made one right now, it'd be "script_log_100623_1320.txt", if you were wondering when I wrote this exact line.

The game creates a new log file every time we enter the main menu, every time we enter a campaign, and every time we enter a battle - so if you only just started using script logs, there should be two or three in there depending on if you quit to main menu or to desktop after loading up your new campaign. Navigate to the latest one and open it up.

Worth noting here, I have a file association set up to automatically open .txt files in Visual Studio Code, because I find it easier and quicker to navigate. If you right click the script log -> open with -> target Visual Studio Code, you can get it in that way. You can also simply grab the file from your file explorer and drag it into the main VSCode window, and it will be opened up within.

There's going to be... a ''lot'' of stuff in here. A lot a lot. CA uses double quindrillion calls to `out()` throughout the game. We'll actually find that it's pretty cumbersome to navigate, and later on we'll create our '''own custom log files!''' But for now, let's navigate this chonker.

=== Find Your Text ===
''Sounds kinda like a platitude you'd find on a pillow in Kohl's.''

In our opened new script log, we should search for the words "Hello World!". We can either do that using the Search tab we have set up, or clicking into the script log in the main window and using Ctrl+F.
[[File:First script 10.png|none|thumb|911x911px|Our first trigger of stuff in the game!Hey, did you put a naughty word instead of "Hello World!"? You lil nasty gremlin.]]
WE FUCKING DID IT HELL YES.

And that's it, you're ready to script on your own!

Bye!

== Timin' 'n Stuff ==
You'll probably maybe notice, this text is triggered very, very early on. While it's maybe ~1000 lines of text in, it's only 1.8s seconds (at least, for me, with no other mods enabled) after the script log is created. This is earlier than it might sound. At this time, the game is still going through its loading procedures - this text was triggered before the loading bar even got to 20%!
Because of how early this is, the game '''is not ready to be accessed yet'''. The game doesn't yet know what factions own what regions, what turn it is, who the player is controlling, or anything like that. The game doesn't have a map object, you can't trigger a new battle, nothin'.

What we need to do for our next step is '''learn how to listen''' and '''wait'''. Some of the most valuable things we can do in programming are listening and waiting for the right time.

=== Events ===
'''''NOTE:''''' ''Not to be confused with the "Events" in-game, the messages and such that hang out with missions.''

The game has a great deal of "events" that can be triggered. Events are a way for scripts to learn some information about things happening in the game - there are events that will inform us when a new turn has started, when a region has been destroyed, when a battle has ended, when a ritual has been completed, when a mission has been failed, among many many many more. We can even define our own - more on that later!

The first event we care about is one of the most important - FirstTickAfterWorldCreated. This event is triggered immediately after the game is ready to access - about 80% of the way through the loading bar before the game is interactable for the user.

Once this event happens, we can do things like ask the game what factions exist, what turn it is, where we are, who we are, etc. Before the world is created, we can only do a bare minimum of setting things up in advance.

=== Flying the Time ===
To achieve our first goal - spitting out some information about our player faction - we're going to use a first tick callback and trigger our very own function!

A first tick callback is a way to '''ask the game to run code on FirstTickAfterWorldCreated'''. Most of your mods will probably involve a first-tick-callback. We use them in the following format:
cm:add_first_tick_callback(function_to_call)
But first, we have to create our own function. To do that, we use the following:
local function my_function_name()
-- do stuff
end
where "my_function_name" can be anything you want. In this situation, I'm going to call the function "init", short for "initialization", because this is the startpoint of my entire script. Some people also prefer "main". Whatever you want really, just make it clear for yourself and anyone else.

''Eagle-eyed readers will notice that the two dashes they wrote in VSCode will be greyed out; these are called "comments". These are incredibly useful to leave notes to ourselves and other people reading our scripts, to inform yourself and others of what's going on and how things work in our code.''

To safely confirm that we're calling our new function at the right time, we're going to run our function, trigger another call to out(), and see if it works!
[[File:First script 11.png|thumb|418x418px]]

=== Getting Our Info ===
With our first tick callback loading up properly, let's hop in and try to get some information about our played faction!

In the beginning of our init() function, we need to define a fresh new variable which will allow us to hold the faction "object" in memory. A variable is a piece of memory that your computer is going to set aside to hold some data for us - a variable can be a number, text, a function, or game objects like the faction.

We'll get it using the get_local_player() function, which we can find in the scripting documentation: https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#function:campaign_manager:get_local_faction

We'll be learning a lot about how to use and read the script documentation going forward.

In our init() function, we need to add the following line of code:
local player_faction = cm:get_local_faction()
Where player_faction is the name of our new variable. It can be anything you want, much like init(), but it should '''make sense''' and '''be clear to read'''. It needs to be all one contiguous word, with only text, underscores, and non-leading numbers allowed (ie. my_faction_1 is allowed, 1_my_faction is not).

Visual Studio Code should automate it for you, but make sure that it's after the init() keyword, is one line after the out() call, is before the `end` keyword, and is one tab over. I like to space my code out thought-by-thought, so this will be a bit lower than my out() code.
[[File:First script 12.png|none|thumb]]
The way we get information about this game object will be to ask it questions, using functions, or in this case '''methods'''.

The first thing we want to ask is, hey, what's the faction's name please?

To ask the game object questions, we need to use the variable name followed by the : sign. Our VSCode plugin will then, thankfully, list us with a great deal of suggestions that we can use. We can also reference [https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html#FACTION_SCRIPT_INTERFACE the scripting documentation for game objects].

Thankfully, what we want isn't too far away:
[[File:First script 13.png|none|thumb|946x946px|The autofill will show us the description of this method, and what it returns - in this case, it returns a "string", as we see after the -> line.]]
Whenever we call a function, if the function gives us something back, we have to assign it to a variable or it will go away and vanish into the ether, with no memory on your PC being used to "hold" onto it. Do that with something simple:
local name = player_faction:name()
I'll keep harping on it, but you can change `local name` to whatever you want - `local key`, `local bits`, `local ostrich_on_fire`, whatever.

'''''NOTE:''''' ''It keeps saying name, but its actually referring to the faction's "key" as we'll see in a second - the "code name" is has in factions_tables.''

Now that we have the information in our code, we can put it all together and print that out to the log file:

<code>out("Hello World!")</code>

out( "Hello World!" )

local function init()

out("New game triggered!")

local player_faction = cm:get_local_faction()

local key = player_faction:name()

out("Playing as " .. key)

end

cm:add_first_tick_callback(init)

File:First script 13.png

2023-06-10T18:29:21Z

Vandy:

faction name

File:First script 12.png

2023-06-10T18:26:19Z

Vandy:

getting player faction

Lua/First Script

2023-06-10T18:16:51Z

Vandy:

File:First script 11.png

2023-06-10T17:58:23Z

Vandy:

First first tick callback

Lua/First Script

2023-06-10T17:38:10Z

Vandy:

File:First script 10.png

2023-06-10T17:36:40Z

Vandy:

Hello World! trigger

File:First script 9.png

2023-06-10T16:54:56Z

Vandy:

Functioning Hello World!

File:First script 8.png

2023-06-10T16:51:04Z

Vandy:

out function params

File:First script 7.png

2023-06-10T16:46:15Z

Vandy:

everything exploded

Lua/First Script

2023-06-10T16:34:35Z

Vandy: starting progress so I don't lose it all to a power outage

File:First script 6.png

2023-06-10T16:28:54Z

Vandy:

first script who dis

File:First script 5.png

2023-06-10T16:19:34Z

Vandy:

New folder in Explorer.

File:First script 4.png

2023-06-10T15:41:51Z

Vandy:

A reworked main window of Visual Studio Code.

File:First script 3.png

2023-06-10T15:29:10Z

Vandy:

Close-up look at the Explorer menu.

File:First script 2.png

2023-06-10T15:21:13Z

Vandy:

Default opening view of Visual Studio Code.

File:First Script 01.png

2023-06-10T15:06:15Z

Vandy:

MyMod popup for the first script mod.

MediaWiki:Sidebar

2023-06-10T14:49:43Z

Vandy:

Lua

2023-06-08T01:32:20Z

Vandy:

Welcome to the landing page of all things Lua - at least, in the context of the Total War series. Enjoy your stay!

== What It Is ==
'''Lua''' is a ''scripting language'' - which is a type of programming language that is not precompiled. That's fancy jargon for "it isn't translated into computer-speak until we run it". It's a super flexible language with a lot of quirks, designed to be an easy-to-approach language for people who aren't programmers but want to do some programming. Therefore it consists of very few forced assumptions or designs, most of its syntax is plain-English, and for the most part it doesn't have a ''lot'' going on within.

Why do we care? Lua is the embedded scripting language within most Total War games, and it's a super flexible toolkit that allows us to interact with the game in dynamic and complex ways.

Some highlighted features of things that are ''scripted'':

* Every Quest Battle (the actions and responses taken by the AI armies, the objectives and how they react to the flow of battle)
* Varied start positions (ie. a faction owning one or another region based on the player's starting faction)
* LOADS of in-game mechanics:
* Rites/Rituals
* Many Missions
* Dynamic encounters
* Story-driven experiences (Attila: The Last Roman, Warhammer III: Prologue, Troy)

Scripting is a design tool that is used whenever you want to have the following system:<blockquote>When [something happens], do [something else].</blockquote>Lua is run by the game through individual text files, with the *.lua extension. Each of these files is called a "script". And we'll call writing up these files, you guessed it, scripting!

== How To Use It ==
As we can see, Lua is a useful tool! It can provide a lot of power in the hands of a modder with some big dreams and some time to kill, and maybe some tears here and there.

But the good news is that Lua is also a great and powerful language, with MANY tools available to easily debug and resolve issues you might have with your scripts, and the TW Lua environment is rife with example scripts, from Creative Assembly and many modders throughout the game series.

In pages to follow, we'll go over writing our first script, some details of how the Lua language works, how to debug, how to dream big and small, but before we go anywhere else we have to start at the beginning:

[[Lua/Setup|Let's get set up!]]

[[Category:Lua]]
[[Category:Tutorial]]

Main Page

2023-06-08T01:06:34Z

Vandy:

== NEW WEBSITE ==
Yes, yes, we're on our sixth or seventh or eight iteration of this website!

This newest version is built upon MediaWiki (same thing Wikipedia uses), and is very much a work in progress, but it's hopefully a much better time all around.
== Hello ==
Welcome to the very in-progress Total War: Modding Wiki! Maintained by Vandy, filled in by anyone!

This Wiki is intended to be as good of a one-stop-shop as possible for modding the Total War series, when it comes to walkthroughs for early set-up and understanding, or tutorials to do specific tasks, or general wiki pages as an overview for various modding and game concepts. It should contain all the resources and tutorials really needed to go forward in modding - when all is said and done.

This project is born out of the members of the [https://discord.gg/dd4TUDm Modding Den Discord channel], which is focused on the Total War: Warhammer side of the franchise due to its original founding by two popular Warhammer modders - but other Total Wars are more than welcome here!

The [https://www.totalwar.com/ Total War] Franchise is a product of [https://www.creative-assembly.com/home Creative Assembly], they own it and other important legal business here.

== Navigation ==

=== All available [[Tutorial:Main Page|Tutorials]]: ===
{{Special:Prefixindex/Tutorial:}}

[[:Category:Tools & Resources|Tools & Resources]]
===Tutorial Series===

==== Lua Tutorial Series, by Vandy: ====
{{Special:Prefixindex/Lua:}}

==== UI Tutorial Series, by Vandy: ====
{{Special:Prefixindex/UI:}}

==== Battle Map Tutorial Series, by Frodo: ====
{{Special:Prefixindex/Battle Maps:}}
=== All Pages ===
{{Special:AllPages}}

=== External Tutorials ===

* [https://steamcommunity.com/sharedfiles/filedetails/?id=1698960734 Abilities]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761202425 Ancillaries (Items, Mounts, etc)]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 Character Skills]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Creating Custom Units]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 Effects]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2180764161 Modding 101/FAQs]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=2233644229 Modding Etiquette and Guidelines]

== Help Out ==
There's a lot to do to help out! Most importantly, '''share what knowledge you have.''' If you are very knowledgeable about some subject, write a few new pages about it. Make edits to existing pages. Add new categories, fill out details. This is a communal effort, and while I'll be trying to shepherd it along and keep everything relatively organized, this is very intentionally a group effort!

''Note: Only verified accounts can make edits. Just register a new account with your username and log in, and you can make edits. They will currently enter approval queue to prevent spam.''

'''To make a new page:''' You just have to search for a page in the search bar. The website will ask "Do you want to create a page with name X?" or something similar - click the red link, and start creating a new page from there!

- [[Tutorial:Main Page|Tutorials]] should be named "Tutorial:Tutorial Name Here"

- Any other page can be named anything else, it doesn't matter. Please mind that only one page can exist with that name, of course, so be proper with your names.

==Helpful Links For Now==
*[[mediawikiwiki:Help:Editing_pages|Best practices for editing pages]]
*[[mediawikiwiki:Help:Formatting|A How-To on using the MediaWiki Formatting]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Configuration_settings|Configuration settings list]]
*[[mediawikiwiki:Special:MyLanguage/Manual:FAQ|MediaWiki FAQ]]
*[https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
*[[mediawikiwiki:Special:MyLanguage/Localisation#Translation_resources|Localise MediaWiki for your language]]
*[[mediawikiwiki:Special:MyLanguage/Manual:Combating_spam|Learn how to combat spam on your wiki]]

Lua

2023-06-08T00:51:25Z

Vandy:

Welcome to the landing page of all things Lua - at least, in the context of the Total War series. Enjoy your stay!

{{Special:PrefixIndex/Lua/}}

[[Category:Lua]]
[[Category:Tutorial]]

MediaWiki:Sidebar

2023-06-08T00:47:36Z

Vandy:

MediaWiki:Sidebar

2023-06-08T00:46:46Z

Vandy:

Meta

2023-06-08T00:15:14Z

Vandy: /* Wiki */

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.
* <s>Look into WYSIWYG editor for the wiki. Previously used version was buggy, but it might be better on the latest update of MediaWiki.</s>
** Works perfectly on the new version!
* Search for better moderation tools, more all-in-one packages.
* Setup a more robust sidebar, include links to the Modding Den and such.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Move". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

Meta

2023-06-08T00:14:49Z

Vandy: /* Wiki */

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.
* <s>Look into WYSIWYG editor for the wiki. Previously used version was buggy, but it might be better on the latest update of MediaWiki.</s>
** Works perfectly on the new version!
* Search for better moderation tools, and more all-in-one packages.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Move". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

Lua/Setup

2023-06-06T23:46:39Z

Vandy:

So you're ready to start programming in Lua - you've got [[RPFM]] set up, you're ready to go. Let's just crack open the text editor in RPFM and get going! Right?

NO. DAMN IT, ABSOLUTELY NOT.

== Why ==
This setup is, to put it lightly, ''extremely'' beneficial for long-term enjoyment and efficiency in programming Lua in Total War.

There are features we'll get access to that will make life much simpler, including:
* A prettier color scheme that feels good to look at!
* Access to many life-preserving shortcuts.
* Easy ways to reference other parts of other scripts that you have opened.
* And best of all, ''a system that will yell at you whenever you fuck up!''

This setup I've found is absolutely crucial to writing code. '''Even if you're a beginner, do not skip this step.''' You will regret it later, for sure.

TODO add in some example images here of things VSC can do for us.

== What You Need ==
First off, if you don't already have it, actually go get [[RPFM]] and set it up. Go ahead, I'll wait until you come back.
* You'll want to make sure RPFM's preferences for "MyMod" and "Game Paths" are all setup, before we go too far forward!

Next, you'll want to install [https://code.visualstudio.com/ Visual Studio Code]. Grab the version that's right for you - 99.999% of the time you can just use the default build for Windows - and install it.
* Make sure you flag all the options in the install parameter as yes; "Open with Code" action, "Register Code", and "Add to PATH" are all helpful options here.
* Install it wherever you'd like; it shouldn't matter too much where it is.

We will be using Visual Studio Code to write our scripts. The main purpose of RPFM is to create and edit our .pack files, but Visual Studio Code is a much more robust ecosystem for editing code files, and to top it all off there's a plugin and some resources that we can use to put a load of tools and automation in our arsenal.

== Visual Studio Code Setup ==
Grab RPFM and open it up. Frodo has built-in, thankfully, a command to download a file that basically contains all of a game's Lua definitions - this is necessary for the debugger we're setting up to know what can and can't be used. If that doesn't make sense, don't worry - it will soon!
* Plop open RPFM.
* Go to About -> Check TW Autogen Updates.
* If it says there's something available, press download!
* Use "Game Selected -> Open RPFM's Config Folder", and just have that open in the background.

Now, open up Visual Studio Code. You should be able to just search its name in your Windows search bar to open up the program. I find it incredibly convenient to have it pinned to my taskbar, but I use it nearly every time I turn on my PC - YMMV.

You'll probably be honestly pretty overwhelmed. There's a lot going on! Good news, there's an easy set up that you have to do. I have made a file that's a "profile" of my most-recommended settings for Visual Studio Code with TW Lua. You'll import this profile, it'll install a few plugins within VSCode, it'll apply a few settings, and you can go off to the races!

* Download [[:File:TW_Lua.zip|this file]]
* Select that file using File Explorer, press the file in your Downloads folder, press the "Extract - Compressed Folder Tools" on the top bar, and use "Extract All".
* In VSCode, use the "Manage" cog button on the bottom left.
* Hover on "Profiles (Default)", and use "Import Profiles."
* Press "Create from profile template file", which will prompt you to select a file on your computer; navigate to the TW_Lua.code-profile file that's within the .zip above.
* Make decisions if you want to keep or remove some of the things in my profile; I have a few optional extensions that I put into the code-profile. '''''Do NOT remove the Lua extension.'''''
* Press "Create Profile" on the next prompt, and Visual Studio Code will then handle installing the extensions and setting up your different settings in the background.

One beautiful thing with Profiles is that they are just that - a profile! If you happen to program multiple TW games, or you end up using VSCode for other languages, or already use VSCode and don't want to clog up your existing beautiful systems, you can make a new profile and keep everything nice and contextualized.

And that's almost it! We just have one more step to take.
* Go to the "Manage" button on the bottom left again, and go to "Settings" within.
* On the topbar that says "Search settings", type in "Lua.workspace.library". This is a setting that tells the debugger extension we'll be using where to look for our definition files.
* In RPFM, use: Game Selected -> Open RPFM's Config Folder
* In the folder that opens up, navigate to tw_autogen -> output -> find the game that you're interested in.
* Open up the game folder, and press into the folder path in File Explorer to get the full path to the files.[[File:VSC2.png|thumb|none|693x693px]]
*Return to VSCode, and in the "Lua.workspace.library" setting, press the edit button and fill in the path to the game in question, and press 'OK'.
[[File:VSC3.png|thumb|none|731x731px]]

And there we are. All the tools and settings you need for starting up on TW Lua scripting!

== Working With Visual Studio Code ==
[TODO]

User:Vandy

2023-06-06T23:41:00Z

Vandy: Created page with "hi"

Meta

2023-06-06T23:38:37Z

Vandy:

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.
* Look into WYSIWYG editor for the wiki. Previously used version was buggy, but it might be better on the latest update of MediaWiki.
* Search for better moderation tools, and more all-in-one packages.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Move". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

Meta

2023-06-06T23:30:24Z

Vandy:

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.
* Look into WYSIWYG editor for the wiki. Previously used version was buggy, but it might be better on the latest update of MediaWiki.
* Search for better moderation tools, and more all-in-one packages.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Rename". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

Meta

2023-06-06T23:25:12Z

Vandy:

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Rename". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.
* Pages for each tool - RPFM, Assembly Kit, mod manager[s], etc. Sections for installation, usage, glossary, and helpful tips (ie. MyMod in RPFM)

Meta

2023-06-06T23:23:51Z

Vandy:

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
** Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Rename". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
** Groove Wizard will take point here
** Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
** Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.

Meta

2023-06-06T23:23:08Z

Vandy: Created page with "This is a meta-page about things involving the website itself. Pretty meta, huh? == To Do == Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard. === Wiki === * Set up the scripting documentation and other external documentation into this website's..."

This is a meta-page about things involving the website itself. Pretty meta, huh?

== To Do ==
Ongoing list of things that need doing with the website. '''If you're able to help with something listed below''', simply edit this page and make a note there that says "[username] will help with this!" If you need any guidance, please feel free to reach out to Groove Wizard.

=== Wiki ===
* Set up the scripting documentation and other external documentation into this website's hierarchy, instead of relying on hosting it separately. Will probably be as simple as hosting on the web server I have and having a link on the sidebar to documentation, though maybe there's an internal MediaWiki system for working with documentation
* Groove Wizard will do this
* Find someone way more experienced in web dev that can give Groove Wizard some insight into various trouble spots.
* Go through https://www.mediawiki.org/wiki/Category:Stable_skins and find any that are specifically appealing and might work well for the wiki.

=== Organization ===
* Go through existing categories, and create any more that are necessary. Make new categories for "spheres" of modding (modeling, map making, scripts, db, planning, etc.)
* Move old Tutorials out of their current location, which is "Tutorial:Tutorial Name", and move them to a new page using "Edit -> More -> Rename". Then properly categorize the tutorials, including marking them as "outdated", "needs review", the game it works for, and whatever else.

=== Topics ===
* Go through the Lua tutorial series and clean it up.
* Groove Wizard will take point here
* Could use a couple of hands with review, editing, grabbing pictures, writing sections, etc.
* Deep dive on TWUI XML stuff
* Groove Wizard again, probably much later.
* Overview of missions / dilemmas / events / incidents / messages / payloads / options / cdir at large.
* Dark secrets of animation unveiled.
* Lua - Overwriting / intercompatibility w/ vanilla and other scripts, etc.

Lua/Setup

2023-06-06T23:09:41Z

Vandy: /* Why */

So you're ready to start programming in Lua - you've got [[RPFM]] set up, you're ready to go. Let's just crack open the text editor in RPFM and get going! Right?

NO. DAMN IT, ABSOLUTELY NOT.

== Why ==
This setup is, to put it lightly, ''extremely'' beneficial for long-term enjoyment and efficiency in programming Lua in Total War.

There are features we'll get access to that will make life much simpler, including:
* A prettier color scheme that feels good to look at!
* Access to many life-preserving shortcuts.
* Easy ways to reference other parts of other scripts that you have opened.
* And best of all, ''a system that will yell at you whenever you fuck up!''

This setup I've found is absolutely crucial to writing code. '''Even if you're a beginner, do not skip this step.''' You will regret it later, for sure.

TODO add in some example images here of things VSC can do for us.

== What You Need ==
First off, if you don't already have it, actually go get [[RPFM]] and set it up. Go ahead, I'll wait until you come back.
* You'll want to make sure RPFM's preferences for "MyMod" and "Game Paths" are all setup, before we go too far forward!

Next, you'll want to install [https://code.visualstudio.com/ Visual Studio Code]. Grab the version that's right for you - 99.999% of the time you can just use the default build for Windows - and install it.
* Make sure you flag all the options in the install parameter as yes; "Open with Code" action, "Register Code", and "Add to PATH" are all helpful options here.
* Install it wherever you'd like; it shouldn't matter too much where it is.

We will be using Visual Studio Code to write our scripts. The main purpose of RPFM is to create and edit our .pack files, but Visual Studio Code is a much more robust ecosystem for editing code files, and to top it all off there's a plugin and some resources that we can use to put a load of tools and automation in our arsenal.

== Visual Studio Code Setup ==
Grab RPFM and open it up. Frodo has built-in, thankfully, a command to download a file that basically contains all of a game's Lua definitions - this is necessary for the debugger we're setting up to know what can and can't be used. If that doesn't make sense, don't worry - it will soon!
* Plop open RPFM.
* Go to About -> Check TW Autogen Updates.
* If it says there's something available, press download!
* Use "Game Selected -> Open RPFM's Config Folder", and just have that open in the background.

Now, open up Visual Studio Code. You should be able to just search its name in your Windows search bar to open up the program. I find it incredibly convenient to have it pinned to my taskbar, but I use it nearly every time I turn on my PC - YMMV.

You'll probably be honestly pretty overwhelmed. There's a lot going on! Good news, there's an easy set up that you have to do. I have made a file that's a "profile" of my most-recommended settings for Visual Studio Code with TW Lua. You'll import this profile, it'll install a few plugins within VSCode, it'll apply a few settings, and you can go off to the races!

* Download [[:File:TW_Lua.zip|this file]]
* Select that file using File Explorer, press the file in your Downloads folder, press the "Extract - Compressed Folder Tools" on the top bar, and use "Extract All".
* In VSCode, use the "Manage" cog button on the bottom left.
* Hover on "Profiles (Default)", and use "Import Profiles."
* Press "Create from profile template file", which will prompt you to select a file on your computer; navigate to the TW_Lua.code-profile file that's within the .zip above.
* Make decisions if you want to keep or remove some of the things in my profile; I have a few optional extensions that I put into the code-profile. '''''Do NOT remove the Lua extension.'''''
* Press "Create Profile" on the next prompt, and Visual Studio Code will then handle installing the extensions and setting up your different settings in the background.

One beautiful thing with Profiles is that they are just that - a profile! If you happen to program multiple TW games, or you end up using VSCode for other languages, or already use VSCode and don't want to clog up your existing beautiful systems, you can make a new profile and keep everything nice and contextualized.

And that's almost it! We just have one more step to take.
* Go to the "Manage" button on the bottom left again, and go to "Settings" within.
* On the topbar that says "Search settings", type in "Lua.workspace.library". This is a setting that tells the debugger extension we'll be using where to look for our definition files.
* In RPFM, use: Game Selected -> Open RPFM's Config Folder
* In the folder that opens up, navigate to tw_autogen -> output -> find the game that you're interested in.
* Open up the game folder, and press into the folder path in File Explorer to get the full path to the files.
[[File:VSC2.png|thumb|left]]
* Return to VSCode, and in the "Lua.workspace.library" setting, press the edit button and fill in the path to the game in question, and press 'OK'.
[[File:VSC3.png|thumb|left]]

And there we are. All the tools and settings you need for starting up on TW Lua scripting!