Total War Modding - User contributions [en]

Tutorial:RPFM For Dummies

2024-03-14T17:11:23Z

Grimmys: Add more formatting, some ressources links and update for more recent versions of RPFM

Subtitle: ''A Reasonably Lengthy And Not-At-All Short Guide to Modding with RPFM – With Pictures''

Also an introduction to Zeldrake's usage of Mediawiki. To be honest, I'm surprised at how little broke and how everything's working... it's suspicious. Anyway, on with the guide!

= Chapter 0 - Introduction =

What are WH2 (or WH3) mods and what can they do?

Broadly speaking, mods are .pack files which contain basically every piece of WH2 (or WH3) data you’ll need – models, stats, text, animations, spells, scripts, numbers. RPFM, Rusted Pack File Manager, is a tool to edit pack files. Therefore, you need to use RPFM for basically every WH2 (or WH3) mod you'll make. This guide will be aimed at WH2, but the ideas are the same for the other games (it has been tested for WH3 as well).

It’s also possible to edit pack files with PFM (Pack File Manager) or the TW: Assembly Kit (fondly called asskit), but neither of these are recommended: the former is just old and has a habit of eating your entire mod up, and the second just doesn’t work well for modders. If a guide references PFM a lot it’s quite outdated and you should probably search around for a more updated one.

Also, before you begin, I recommend setting up a folder somewhere to stash your mods, RPFM, and other stuff. We’ll need it later. Mine is
<code>C:\REDACTED\OtherGameStuff\Warhammer2ExceptNeat</code>

= Chapter 1 - Getting RPFM =

The best place to get your hands on RPFM is by checking the '''#rpfm''' channel on ''Da Modding Den'' Discord server. Chances are the latest version is pinned in the pinned. However, you should also be able to get it from [https://github.com/Frodo45127/rpfm/releases/latest this link]. Which, at the moment, looks a bit like this:

[[File:RPFMForDummiesImage 01.png|700px]]

At the time of writing (which is outdated already), the current version is v2.3.2. RPFM will doubtlessly have more additions and changes as time goes on (the change from RPFM v1 to v2 was quite something), but the idea should still be the same: it does things with Pack Files. The buttons might move about, but they should do the same stuff.

As for downloading it: assuming you’re on Windows, it’s the download that has ‘rpfm-something-something-windows’ in it:

[[File:RPFMForDummiesImage 02.png|350px]]

At the moment, RPFM is nicely packaged into a .zip folder, which you can extract with almost anything, but previous versions were packaged into a .7z folder. I recommend unpacking these with [https://www.7-zip.org/download.html 7zip]. 7zip is pretty straightforward to download and install: just grab any of the ones that say "windows" and, if it doesn’t seem to work, try the next one. In any case, 7-zip is beyond the scope of this guide.

Anyway, extract RPFM into your mod folder and you should end up with something like this:

[[File:RPFMForDummiesImage 03.png|700px]]

It’s not truly necessary, but we’ll make a shortcut to RPFM so we don’t have to get lost down this rabbit hole of folders each time we want to open it (and you’ll want to open it a lot). Find rpfm.exe (that’s the program – I don't know what the other ones do. In earlier, or perhaps later, versions of RPFM the executable name might change. Try running things until it works), right-click, and Create Shortcut:

[[File:RPFMForDummiesImage 04.png|600px]]

'''Update: on some newer version, the executable has been renamed rpfm_ui.exe'''

Select that and move it to somewhere memorable. Desktop works fine – at the moment mine is in my WH2 mods folder:

[[File:RPFMForDummiesImage 05.png|600px]]

That’s RPFM! Open it up and – for this version, in any case – it should look at least a little like:

[[File:RPFMForDummiesImage 06.png|700px]]

(though the icon in the middle of the screen might be different).

= Chapter 2 - Setting RPFM Up =

Before we start running down rabbit holes of modding, we still need to do a bit with RPFM to get it set up so Everything Works Nicely. Go under PackFile -> Preferences

[[File:RPFMForDummiesImage 07.png|500px]]

and a big box should open up! Don’t worry, we don’t need to worry about most of the stuff in here, but some stuff is very important:

[[File:RPFMForDummiesImage 08.png|700px]]

It’s critically important to fill out the boxes I’ve outlined in red. The first points RPFM to WH2’s mod directory: it’s just the folder where the .exe is (as the handy tooltip demonstrates!) The second points to a fancy shmancy “MyMod” folder. You’ll need to create this and put it somewhere safe - it can be anywhere that isn’t in Program Files. Making a nice big WH2/WH3 folder under Documents or somewhere to put everything WH2/WH3-related is a good idea.

The blue box isn’t critical, but it’ll save you a bit of effort: defaulting RPFM to WH2 or WH3 (it’s probably on Three Kingdoms) means less clicks when we start up. The remaining settings can be left at defaults, you don’t need them. From here, everything else is optional. As you can see, I also filled out my path for Troy, because I like to mod that a little, but it’s not needed – we’re modding WH so only WH needs to be set up! There’s also “Use Dark Theme” hiding in the checkbox list on the left, which is good for modding at 3am when you’re feeling vampiric and bright light destroys you.

Close RPFM and restart it again, just for good measure. (It’s not actually needed for these settings, contrary to the red warning text, but saves us a little bit of clicking).

There’s one more thing we’ll need to do to get RPFM working properly and that is install the Total War: Warhammer 2 Assembly Kit (same for Warhammer 3). There’s a neat guide on how to do this by CA [https://www.totalwar.com/blog/total-war-warhammer-assembly-kit-terry-quick-start-guide/ here] but in short, Steam -> Library -> Tools then install the TW: Assembly Kit.

[[File:RPFMForDummiesImage 09.png|400px]]

It’s important (for RPFM) that the Assembly Kit is installed on the same drive as WH2/WH3. Once it’s downloaded, boot up RPFM again and hit Special Stuff -> Warhammer 2 / Warhammer 3 -> Generate Dependencies Cache. (If the button’s greyed out, just open any WH2/WH3 packfile you care to name; easily done with Open From Data and clicking on whatever you like).

[[File:RPFMForDummiesImage 10.png|615px]]

It’ll take a minute, but this is really helpful for RPFM’s diagnostic tool that tells you when your keys don’t match up (in short, it lets you know where you goofed up).

= Chapter 3 - Making a Mod =

Before we begin, it’s worth noting what sort of stuff mods do, and what can even be done:
* '''Table editing'''. Simplest and easiest. A lot of Warhammer 2/Warhammer 3 information like unit health, building recruitments, what spells do what, what skillpoints do what, dilemmas: almost all data for that is stored in tables.
* '''Graphics, Model, Animation, and Effects Editing'''. I have absolutely no clue how this works so if somebody else could fill in this blank I’d appreciate it. I know textures exist, models exist, and animations exist, but that's about it.
** You can make new units! From “Handgunners but they’re blue instead of red” to “Treemen with Great Bows” to “Entirely custom floating ships as Tomb King character mounts,” you can basically do anything with the new tools of Phazer’s tools and h3ro’s Asset Editor (fondly nicknamed ‘assed’).
** You can make new effects (think the shiny things that go off when a spell activates).
** You can reassign and add new animations, if you’re feeling dedicated enough.
** What I do know about the above is that it’s all quite difficult, and I would not recommend someone starting out modding to start with this. Search up for other guides – there are some good modding guides on WH2’s Steam mod page.
* '''Scripts'''. While tables specify what stuff exists, scripts can specify how stuff happens. For instance, the Chaos invasion in Mortal Empires is almost entirely script-based. So is Hellebron’s Death Night. Even Encounters at Sea (the ones where you can fight a whole bunch of vampirates) is script. Wood Elf Forest Encounters, Empire Count dilemmas – the list of script-based functionality goes on. Quite often these link into database stuff (sometimes moreso than others – for instance, traits are entirely database defined but actually gaining any trait is script-based)
* '''UI Script'''. Still strictly speaking the realm of script, but stuff that has lots of pretty buttons to press, like the Mortuary Cult crafting, the Wood Elf Forge of Daith, Throt’s Flesh Lab; this kind of stuff. Unfortunately, I’m not familiar with any of it and my understanding is it can be quite difficult to adapt to what you want to do.
** Again, if someone was willing to fill out a bit more information I’d appreciate it!
* '''Startpos'''. This specifies how things are set up at turn 1 in a campaign. If you’re really screwing with the game (eg: adding new factions) this is necessary, and it’s an absolute pain, earning it the nickname ‘asspos.’ Being a startpos mod also makes it fundamentally incompatible with any other startpos mod, as you can only have one way things are set up in the start of a campaign! Fortunately, if you just want to move a character to a new spot you can do that with script, which is much nicer. There's almost no good reason to mod startpos, so if you are, you shouldn't be.

RPFM’s speciality is '''table editing'''. It can handle scripts pretty well, but ultimately you’re better off writing them somewhere else ([https://code.visualstudio.com/ Visual Studio Code] is good for dedicated scripters), then pasting them into RPFM when done. Additionally, RPFM as a tool combines all the above together – you may have your fancy model and Chaos Knights (Ratling Guns), but you’ll need to put this into RPFM to turn it into a pack file to make it a mod.

RPFM cannot edit startpos (... well, yet) and you’ll need the Total War Assembly Kit to do that, but you should stay away from that unless you have a really good reason to do it (and most reasons aren’t good enough).

With all of this in mind, we’re going to make ''two simple mods''.
Firstly, we’ll increase Lord Skrolk’s melee attack to 100. This is going to be a '''table edit'''.
Secondly, we’re going to make him start in Caledor, instead of where he normally is. You could do that with startpos, but I can’t stress how much of a bad idea that is, so we’re going to use script. We can put these both together in a single mod.

Well, what are we waiting for? Start RPFM from that handy shortcut you made earlier, and beeeeefore we begin, we need to check one thing:

[[File:RPFMForDummiesImage 11.png|700px]]

WH2/WH3 needs to be the Game Selected. We are, of course, making a mod for WH! If this isn’t correct a bunch of silly stuff will happen.

Now, let’s make a mod in RPFM! You can do this the old-fashioned way by PackFile -> New PackFile but RPFM’s MyMod functionality makes everything so much cleaner: open the MyMod menu and hit New MyMod!

[[File:RPFMForDummiesImage 12.png]]

A small box will come up that’s pretty self-explanatory.

[[File:RPFMForDummiesImage 13.png]]

All the text there explains itself. As for name, I like to start with my username, then use underscores to describe a bit about the mod. So I’ll call it aidenpons_lord_skrolk_yes_yes , hit Save, and let’s go!

[[File:RPFMForDummiesImage 14.png]]

Now, we wanted to change Skrolk’s melee attack. That’s going to be in some form of table. So I need to right-click the mod, click Create (not Add! that’s a different table), and then DB (short for database, aka table)

[[File:RPFMForDummiesImage 15.png]]

Click that and a box with a bajillion things in its dropdown box comes up!

[[File:RPFMForDummiesImage 16.png]]

That’s no good, we want melee attack, not fonts! We need to know what table it’s in, and to find this, we have a couple of choices:
# Poke the folks on Da Modding Den using one of the '''#modding-tech''' channels – a valid call if you’re doing something complicated
# Find it yourself like an independent and capable person!

I recommend b) where possible. Don’t worry though, it’s not too difficult. What do we know about melee attack? It might not be called that in the game files though, so we don’t want to search it by name. What else do we know? Well, we know Lord Skrolk has a melee attack. So let’s just run a search through the original CA data and see where he turns up.

Put this aside, and open another instance of RPFM by clicking on that handy shortcut you made previously. After making sure Game Selected is the correct Warhammer, left click on PackFile. We have a couple of choices here...

[[File:RPFMForDummiesImage 17.png]]

We want to load WH2/WH3’s data so we can search through it all to find what we want. Thanks to improvements in RPFM, we no longer have to worry about thinking which packfile we specifically want: we can just open them all at once using the “Load All CA Packfiles” button.

It’s also worth mentioning ''Open from Content'' will open from Steam’s workshop content: handy if you want to check a mod’s pack file, but we don’t want that. ''Open From Data'' opens from game’s data folder, where both the game’s pack files and mod pack files reside, which explains the massive box that pops up should you hover over it.

Anyway, Load All CA PackFiles, give it a bit to load – it’s a lot of big packs, and we should have something like this:

[[File:RPFMForDummiesImage 18.png]]

'''Update: on some newer version, Load All CA Packfiles is automatically done after generating dependencies cache. So if the button is disabled for you, don't panic; it may means you don't need to do this step because CA Packfiles are already loaded.'''

... well, that’s not very big! Click on the little > arrow next to the .pack, and a load of folders should expand! Expand the db folder (the folder where all the tables are), and even more folders should come up! ... Okay, that’s why it took this long to load. Expand a random folder and click on its data__ (they all have that name):

[[File:RPFMForDummiesImage 19.png]]

This is a table. In this case, it’s the table that governs how fatigue happens in battle: so you can see climbing walls nukes fatigue at 10,000, when idle changes fatigue by -18 (which probably means fatigue goes down, which checks out with game knowledge).

Anyway, we wanted Lord Skrolk’s melee attack. Well, we know Lord Skrolk has a melee attack. So let’s try finding him! To do that, we’ll use RPFM’s incredibly handy Global Search. Hit View -> Toggle Global Search Window to bring it up.

[[File:RPFMForDummiesImage 20.png]]

(Note: In RPFM v1-ish - which is totally obselete - Global Search was accessed by right-clicking anywhere in the folder view on the left. We’re working with more modern tech though!) A box on the right should pop up as part of RPFM:

[[File:RPFMForDummiesImage 21.png|450px]]

Let’s put ''Lord Skrolk'' in the Search bar, hit Search and see what happens!
After waiting a bit (around 7s on my machine – shouldn’t take more than a minute by any means), we get some results:
(Note: Results may differ depending on what version of RPFM and WH is being used, but either way, the idea of global searching still works).

[[File:RPFMForDummiesImage 22.png]]

Huh. Let’s examine one of these more: Click on the > next to the db/character_skills_tables/data__ to expand it, and see what it found.

[[File:RPFMForDummiesImage 23.png]]

Hrm. Double-click that and the table will open.

[[File:RPFMForDummiesImage 24.png|700px]]

Well, we at least got Lord Skrolk. This is clearly a description for something, not melee attack. But if we scroll around left and right, we can see from the '''Key''' - which is what a lot of WH tables use to refer to something unique (eg: units have keys, projectiles have keys, dilemmas have keys, regions have keys, provinces have keys, building have keys, etc etc etc) that WH doesn’t use spaces like we searched and instead uses underscores. So, with that in mind, let’s try searching ''lord_skrolk'' instead!

Wait a couple of seconds, and, wow, what a bunch more results! I guess that makes sense for the leader of an entire faction – model, audio, events, and all! And one of these tables is hopefully melee attack...

[[File:RPFMForDummiesImage 25.png]]

We’re currently hunting in db but it’s worth giving a mention to the other tabs. Loc Matches searches inside WH2/WH3’s complex text database, and is a really good way to get started on finding something if all you know is its in-game name. Text Matches searches, among other things, script and the bit of a model called a “variantmesh” (don’t ask me what this means because I don’t know) – good if you’re hunting script or models, which we aren’t, so we can ignore it. I have no clue what Schema Matches does and have never needed it so we can hopefully ignore it.

Additionally, feel free to resize the window (drag on various handles that pop up), if you’ve got the screen real estate for it. Anyway, we wanted melee attack. There’s no table that looks like melee_attack, but, scrolling a bit up from the bottom, let’s try main_units_tables?

[[File:RPFMForDummiesImage 26.png]]

land_unit! That’s something! Double-click on that and a new tab in RPFM should open and scroll down to the line needed.

[[File:RPFMForDummiesImage 27.png|700px]]

''(Addendum: WH2, this guide, and RPFM have had so very many updates since things began. If you have a keen eye, you’ll see that the top left is called data.pack not warhammer_2, and that Skrolk is at line 709 when currently he’s at line 789. Things change, and I genuinely cannot keep this guide perfectly up to date. When modding, if nothing else, it’s important to be able to think on your feet as things keep changing around you.)''

You can see our previous character_skills_tables open in a non-active tab. We really don’t need that anymore and you can close it if you want, we’re taking a look at main_units now.

Scrolling across, we see things like Upkeep Cost, Multiplayer Cost, some voice-over stuff, but nothing that looks like melee attack. Well, this ''does'' look like Lord Skrolk (the wh2_main_skv_cha_lord_skrolk seems about right), so we’re probably on the right track. What about that Land Unit? If we hover over the column header in RPFM, it’ll tell us which table this is referencing. (Some columns in tables link other tables together, like this one – but obviously Upkeep Cost doesn’t reference a table!)

[[File:RPFMForDummiesImage 28.png|700px]]

Huh, a table called land_units. Would be nice to find that quickly. There are two ways you can do this: one, fishing the table out by hand. This is actually pretty speedy since if we select a random folder on the left and hit L (for Land_units), the folder view will scroll to the first match of L. (You can type even quicker if you want, typing L A N D _ U N I T S , but that’s too much typing for my fingers).

[[File:RPFMForDummiesImage 29.png]]

Well, lab_settings is definitely not what we want, but if we scroll down a bit, we’ll find land_units_tables.

The other – and much speedier – option is to use RPFM’s handy Go To functionality. Right-click on the cell and Go To -> Go To Definition, and fazam, RPFM will take you right there!

[[File:RPFMForDummiesImage 30.png|700px]]

Either way, we’ve now got land_units_tables open in front of us:

[[File:RPFMForDummiesImage 31.png|700px]]

Now, we really don’t want to scroll through all ten bazillion lines of this table to find Skrolk, but instead RPFM has a handy Filter section just below the table view. Type skrolk in that and it’ll only show rows that match skrolk in the Key section. (We wouldn’t want to search for skrolk in the Category section!) There’s tons of superpowerful stuff you can do with more detailed filters (they support Regex, very powerful for searching), but this simple filter will do:

[[File:RPFMForDummiesImage 32.png|700px]]

Only one hit? That’s usually pretty good, as it suggests this is a Master Node of some sort, linking a lot of things together. Scroll across the table and we some things about mounts, morale, armor, melee weapon, and – what’s this? Melee attack! We found it!

[[File:RPFMForDummiesImage 33.png|700px]]

Now, before we get too excited, this is the data packs of the game themselves. Editing these is a terribly bad idea as it makes there be no way to revert to unmodded short of reinstalling the game, and the reason RPFM won’t let you save your changes if you try. Instead, that’s why we created a mod!

Hop back to the instance of RPFM that has your mod open (or open it again, if you closed it). If you did close it, there’s a super-nifty RPFM trick that allows you to open it super quickly, and it’s under the MyMod menu:

[[File:RPFMForDummiesImage 34.png]]

Super speedy and super handy. Anyway, we’d shut that because we didn’t know what table we wanted, but now we know we want land_units table! So again, right-click, create, create DB...

[[File:RPFMForDummiesImage 35.png]]

... and this time we know what table we want – it’s the ''land_units'' table! Typing in land_units doesn’t quite land the hit we need, but it’s easy to find it from the four in the dropdown box:

[[File:RPFMForDummiesImage 36.png]]

The new_file in the first line will be the name of your table. This isn’t super important – except that it shouldn’t end with a number and should have no spaces in it – but I like to, again, preface it with my name and then have something about the table. So aiden_land_units will do just fine.

[[File:RPFMForDummiesImage 37.png]]

Hit Create, open it up, and it’s blank. Well, of course it’s blank – we haven’t added anything to it!

[[File:RPFMForDummiesImage 38.png]]

Well, we want to put the line about Lord Skrolk in here and change his melee attack. I guess you could re-type everything out by hand if you were feeling like you wanted some bonus suffering, but I like my modding to be an enjoyable experience (which is why I don’t touch startpos), and in RPFM, we can copy and paste rows (and much more!) over!
Hop back to RPFM that has data.pack open, and it should be right where we left it.
Now – just like Excel – if you click on the row number the entire row will be selected. Right-click somewhere in that row, select Copy, then Copy (the other option we don’t need for this):

[[File:RPFMForDummiesImage 39.png|700px]]

Now hop back to our mod, right-click anywhere in the table view, and hit Paste as New Row!

[[File:RPFMForDummiesImage 40.png]]

Results should look like this!

[[File:RPFMForDummiesImage 41.png|700px]]

Stuff’s a bit squished, but it’s there! Now scroll over to the Melee Attack, double-click to select it, put our nice modded 100 value in, hit Enter, and, that’s done!

[[File:RPFMForDummiesImage 42.png]]

But before we get toooooo excited about using an overpowered Lord Skrolk, there’s two more things we need to do:

The first is save the mod! Ctrl+S does the trick, or PackFile -> Save. The second’s more important: to copy the mod to game’s data directory so the mod managers actually pick it up. Instead of fishing up the packfile manually and pasting it over, RPFM does this all with two mouse clicks: PackFile -> Install !

[[File:RPFMForDummiesImage 43.png]]

''(Addendum: Previous versions of RPFM had this under the MyMod menu. Again, the buttons might move around and about – it’s important to think on your feet)''

Oh, by the way, if you get an error that looks like this:

[[File:RPFMForDummiesImage 43b.png]]

Now our nice little packfile is sitting in WH2’s data directory ready for either the CA mod loader (affectionately called George) or [https://tw-modding.com/wiki/Category:Tools_%26_Resources#Kaedrin%E2%80%99s_Mod_Manager Kaedrin’s Mod Manager (KMM)] to pick it up. It’s vitally important to play-test your mods first (and, if nothing else, make sure they load and the game doesn’t crash!), so we’ll do that.

While KMM is definitely superior for managing large amounts of mods and its Profile feature is a godsend, we do actually need the CA mod loader to upload a mod (more on that later), so for this I’ll be using the CA mod loader. Boot it up, and if you scroll down, tadaaaaaaa!

[[File:RPFMForDummiesImage 44.png|700px]]

Enable that, hit Play, hit Play on the obligatory “warning you are modded” menu (does anyone besides me actually read that?), and WH2/WH3 boots up with our mod in tow! :D

We could start a new campaign to check things out, but we could also be lazy, and just check things in Custom Battles instead. And will you look at that!

[[File:RPFMForDummiesImage 45.png|700px]]

''It woooooooooooooorks!'' :D

= Chapter 4 - Script =

''To Be Continued...''

[[Category: Tools & Resources]]

Tutorial:RPFM For Dummies

2024-03-11T22:09:45Z

Grimmys: Fix typos, be more inclusive for WH3, update regarding new name of executable

Subtitle: ''A Reasonably Lengthy And Not-At-All Short Guide to Modding with RPFM – With Pictures''

Also an introduction to Zeldrake's usage of Mediawiki. To be honest, I'm surprised at how little broke and how everything's working... it's suspicious. Anyway, on with the guide!

= Chapter 0 - Introduction =

What are WH2 (or WH3) mods and what can they do?

Broadly speaking, mods are .pack files which contain basically every piece of WH2 (or WH3) data you’ll need – models, stats, text, animations, spells, scripts, numbers. RPFM, Rusted Pack File Manager, is a tool to edit pack files. Therefore, you need to use RPFM for basically every WH2 (or WH3) mod you'll make. This guide will be aimed at WH2, but the ideas are the same for the other games (it has been tested for WH3 as well).

It’s also possible to edit pack files with PFM (Pack File Manager) or the TW: Assembly Kit (fondly called asskit), but neither of these are recommended: the former is just old and has a habit of eating your entire mod up, and the second just doesn’t work well for modders. If a guide references PFM a lot it’s quite outdated and you should probably search around for a more updated one.

Also, before you begin, I recommend setting up a folder somewhere to stash your mods, RPFM, and other stuff. We’ll need it later. Mine is
C:\REDACTED\OtherGameStuff\Warhammer2ExceptNeat

= Chapter 1 - Getting RPFM =

The best place to get your hands on RPFM is by checking the #rpfm channel on ''Da Modding Den'' Discord server. Chances are the latest version is pinned in the pinned. However, you should also be able to get it from [https://github.com/Frodo45127/rpfm/releases/latest this link]. Which, at the moment, looks a bit like this:

[[File:RPFMForDummiesImage 01.png|700px]]

At the time of writing (which is outdated already), the current version is v2.3.2. RPFM will doubtlessly have more additions and changes as time goes on (the change from RPFM v1 to v2 was quite something), but the idea should still be the same: it does things with Pack Files. The buttons might move about, but they should do the same stuff.

As for downloading it: assuming you’re on Windows, it’s the download that has ‘rpfm-something-something-windows’ in it:

[[File:RPFMForDummiesImage 02.png|350px]]

At the moment, RPFM is nicely packaged into a .zip folder, which you can extract with almost anything, but previous versions were packaged into a .7z folder. I recommend unpacking these with [https://www.7-zip.org/download.html 7zip]. 7zip is pretty straightforward to download and install: just grab any of the ones that say "windows" and, if it doesn’t seem to work, try the next one. In any case, 7-zip is beyond the scope of this guide.

Anyway, extract RPFM into your mod folder and you should end up with something like this:

[[File:RPFMForDummiesImage 03.png|700px]]

It’s not truly necessary, but we’ll make a shortcut to RPFM so we don’t have to get lost down this rabbit hole of folders each time we want to open it (and you’ll want to open it a lot). Find rpfm.exe (that’s the program – I don't know what the other ones do. In earlier, or perhaps later, versions of RPFM the executable name might change. Try running things until it works), right-click, and Create Shortcut:

[[File:RPFMForDummiesImage 04.png|600px]]

'''Update: on some newer version, the executable has been renamed rpfm_ui.exe'''

Select that and move it to somewhere memorable. Desktop works fine – at the moment mine is in my WH2 mods folder:

[[File:RPFMForDummiesImage 05.png|600px]]

That’s RPFM! Open it up and – for this version, in any case – it should look at least a little like:

[[File:RPFMForDummiesImage 06.png|700px]]

(though the icon in the middle of the screen might be different).

= Chapter 2 - Setting RPFM Up =

Before we start running down rabbit holes of modding, we still need to do a bit with RPFM to get it set up so Everything Works Nicely. Go under PackFile -> Preferences

[[File:RPFMForDummiesImage 07.png|500px]]

and a big box should open up! Don’t worry, we don’t need to worry about most of the stuff in here, but some stuff is very important:

[[File:RPFMForDummiesImage 08.png|700px]]

It’s critically important to fill out the boxes I’ve outlined in red. The first points RPFM to WH2’s mod directory: it’s just the folder where the .exe is (as the handy tooltip demonstrates!) The second points to a fancy shmancy “MyMod” folder. You’ll need to create this and put it somewhere safe - it can be anywhere that isn’t in Program Files. Making a nice big WH2/WH3 folder under Documents or somewhere to put everything WH2/WH3-related is a good idea.

The blue box isn’t critical, but it’ll save you a bit of effort: defaulting RPFM to WH2 or WH3 (it’s probably on Three Kingdoms) means less clicks when we start up. The remaining settings can be left at defaults, you don’t need them. From here, everything else is optional. As you can see, I also filled out my path for Troy, because I like to mod that a little, but it’s not needed – we’re modding WH2/WH3 so only WH2/WH3 needs to be set up! There’s also “Use Dark Theme” hiding in the checkbox list on the left, which is good for modding at 3am when you’re feeling vampiric and bright light destroys you.

Close RPFM and restart it again, just for good measure. (It’s not actually needed for these settings, contrary to the red warning text, but saves us a little bit of clicking).

There’s one more thing we’ll need to do to get RPFM working properly and that is install the Total War: Warhammer 2 Assembly Kit (same for Warhammer 3). There’s a neat guide on how to do this by CA [https://www.totalwar.com/blog/total-war-warhammer-assembly-kit-terry-quick-start-guide/ here] but in short, Steam -> Library -> Tools then install the TW: Assembly Kit.

[[File:RPFMForDummiesImage 09.png|400px]]

It’s important (for RPFM) that the Assembly Kit is installed on the same drive as WH2/WH3. Once it’s downloaded, boot up RPFM again and hit Special Stuff -> Warhammer 2 / Warhammer 3 -> Generate Dependencies Cache. (If the button’s greyed out, just open any WH2/WH3 packfile you care to name; easily done with Open From Data and clicking on whatever you like).

[[File:RPFMForDummiesImage 10.png|615px]]

It’ll take a minute, but this is really helpful for RPFM’s diagnostic tool that tells you when your keys don’t match up (in short, it lets you know where you goofed up).

= Chapter 3 - Making a Mod =

Before we begin, it’s worth noting what sort of stuff mods do, and what can even be done:
* '''Table editing'''. Simplest and easiest. A lot of Warhammer 2 information like unit health, building recruitments, what spells do what, what skillpoints do what, dilemmas: almost all data for that is stored in tables.
* '''Graphics, Model, Animation, and Effects Editing'''. I have absolutely no clue how this works so if somebody else could fill in this blank I’d appreciate it. I know textures exist, models exist, and animations exist, but that's about it.
** You can make new units! From “Handgunners but they’re blue instead of red” to “Treemen with Great Bows” to “Entirely custom floating ships as Tomb King character mounts,” you can basically do anything with the new tools of Phazer’s tools and h3ro’s Asset Editor (fondly nicknamed ‘assed’).
** You can make new effects (think the shiny things that go off when a spell activates).
** You can reassign and add new animations, if you’re feeling dedicated enough.
** What I do know about the above is that it’s all quite difficult, and I would not recommend someone starting out modding to start with this. Search up for other guides – there are some good modding guides on WH2’s Steam mod page.
* '''Scripts'''. While tables specify what stuff exists, scripts can specify how stuff happens. For instance, the Chaos invasion in Mortal Empires is almost entirely script-based. So is Hellebron’s Death Night. Even Encounters at Sea (the ones where you can fight a whole bunch of vampirates) is script. Wood Elf Forest Encounters, Empire Count dilemmas – the list of script-based functionality goes on. Quite often these link into database stuff (sometimes moreso than others – for instance, traits are entirely database defined but actually gaining any trait is script-based)
* '''UI Script'''. Still strictly speaking the realm of script, but stuff that has lots of pretty buttons to press, like the Mortuary Cult crafting, the Wood Elf Forge of Daith, Throt’s Flesh Lab; this kind of stuff. Unfortunately, I’m not familiar with any of it and my understanding is it can be quite difficult to adapt to what you want to do.
** Again, if someone was willing to fill out a bit more information I’d appreciate it!
* '''Startpos'''. This specifies how things are set up at turn 1 in a campaign. If you’re really screwing with the game (eg: adding new factions) this is necessary, and it’s an absolute pain, earning it the nickname ‘asspos.’ Being a startpos mod also makes it fundamentally incompatible with any other startpos mod, as you can only have one way things are set up in the start of a campaign! Fortunately, if you just want to move a character to a new spot you can do that with script, which is much nicer. There's almost no good reason to mod startpos, so if you are, you shouldn't be.

RPFM’s speciality is '''table editing''''. It can handle scripts pretty well, but ultimately you’re better off writing them somewhere else (Visual Studio Code is good for dedicated scripters), then pasting them into RPFM when done. Additionally, RPFM as a tool combines all the above together – you may have your fancy model and Chaos Knights (Ratling Guns), but you’ll need to put this into RPFM to turn it into a pack file to make it a mod.

RPFM cannot edit startpos (... well, yet) and you’ll need the Total War Assembly Kit to do that, but you should stay away from that unless you have a really good reason to do it (and most reasons aren’t good enough).

With all of this in mind, we’re going to make ''two simple mods''.
Firstly, we’ll increase Lord Skrolk’s melee attack to 100. This is going to be a '''table edit'''.
Secondly, we’re going to make him start in Caledor, instead of where he normally is. You could do that with startpos, but I can’t stress how much of a bad idea that is, so we’re going to use script. We can put these both together in a single mod.

Well, what are we waiting for? Start RPFM from that handy shortcut you made earlier, and beeeeefore we begin, we need to check one thing:

[[File:RPFMForDummiesImage 11.png|700px]]

WH2 needs to be the Game Selected. We are, of course, making a mod for WH2! If this isn’t correct a bunch of silly stuff will happen.

Now, let’s make a mod in RPFM! You can do this the old-fashioned way by PackFile -> New PackFile but RPFM’s MyMod functionality makes everything so much cleaner: open the MyMod menu and hit New MyMod!

[[File:RPFMForDummiesImage 12.png]]

A small box will come up that’s pretty self-explanatory.

[[File:RPFMForDummiesImage 13.png]]

All the text there explains itself. As for name, I like to start with my username, then use underscores to describe a bit about the mod. So I’ll call it aidenpons_lord_skrolk_yes_yes , hit Save, and let’s go!

[[File:RPFMForDummiesImage 14.png]]

Now, we wanted to change Skrolk’s melee attack. That’s going to be in some form of table. So I need to right-click the mod, click Create (not Add! that’s a different table), and then DB (short for database, aka table)

[[File:RPFMForDummiesImage 15.png]]

Click that and a box with a bajillion things in its dropdown box comes up!

[[File:RPFMForDummiesImage 16.png]]

That’s no good, we want melee attack, not fonts! We need to know what table it’s in, and to find this, we have a couple of choices:
# Poke the folks on Da Modding Den using one of the #modding-tech channels – a valid call if you’re doing something complicated
# Find it yourself like an independent and capable person!

I recommend b) where possible. Don’t worry though, it’s not too difficult. What do we know about melee attack? It might not be called that in the game files though, so we don’t want to search it by name. What else do we know? Well, we know Lord Skrolk has a melee attack. So let’s just run a search through the original CA data and see where he turns up.

Put this aside, and open another instance of RPFM by clicking on that handy shortcut you made previously. After making sure Game Selected is Warhammer 2, left click on PackFile. We have a couple of choices here...

[[File:RPFMForDummiesImage 17.png]]

We want to load WH2’s data so we can search through it all to find what we want. Thanks to improvements in RPFM, we no longer have to worry about thinking which packfile we specifically want: we can just open them all at once using the “Load All CA Packfiles” button.

It’s also worth mentioning ''Open from Content'' will open from Steam’s workshop content: handy if you want to check a mod’s pack file, but we don’t want that. ''Open From Data'' opens from WH2’s data folder, where both the game’s pack files and mod pack files reside, which explains the massive box that pops up should you hover over it.

Anyway, Load All CA PackFiles, give it a bit to load – it’s a lot of big packs, and we should have something like this:

[[File:RPFMForDummiesImage 18.png]]

... well, that’s not very big! Click on the little > arrow next to the .pack, and a load of folders should expand! Expand the db folder (the folder where all the tables are), and even more folders should come up! ... Okay, that’s why it took this long to load. Expand a random folder and click on its data__ (they all have that name):

[[File:RPFMForDummiesImage 19.png]]

This is a table. In this case, it’s the table that governs how fatigue happens in battle: so you can see climbing walls nukes fatigue at 10,000, when idle changes fatigue by -18 (which probably means fatigue goes down, which checks out with game knowledge).

Anyway, we wanted Lord Skrolk’s melee attack. Well, we know Lord Skrolk has a melee attack. So let’s try finding him! To do that, we’ll use RPFM’s incredibly handy Global Search. Hit View -> Toggle Global Search Window to bring it up.

[[File:RPFMForDummiesImage 20.png]]

(Note: In RPFM v1-ish - which is totally obselete - Global Search was accessed by right-clicking anywhere in the folder view on the left. We’re working with more modern tech though!) A box on the right should pop up as part of RPFM:

[[File:RPFMForDummiesImage 21.png|450px]]

Let’s put ''Lord Skrolk'' in the Search bar, hit Search and see what happens!
After waiting a bit (around 7s on my machine – shouldn’t take more than a minute by any means), we get some results:
(Note: Results may differ depending on what version of RPFM and WH2 is being used, but either way, the idea of global searching still works).

[[File:RPFMForDummiesImage 22.png]]

Huh. Let’s examine one of these more: Click on the > next to the db/character_skills_tables/data__ to expand it, and see what it found.

[[File:RPFMForDummiesImage 23.png]]

Hrm. Double-click that and the table will open.

[[File:RPFMForDummiesImage 24.png|700px]]

Well, we at least got Lord Skrolk. This is clearly a description for something, not melee attack. But if we scroll around left and right, we can see from the '''Key''' - which is what a lot of WH2 tables use to refer to something unique (eg: units have keys, projectiles have keys, dilemmas have keys, regions have keys, provinces have keys, building have keys, etc etc etc) that WH2 doesn’t use spaces like we searched and instead uses underscores. So, with that in mind, let’s try searching ''lord_skrolk'' instead!

Wait a couple of seconds, and, wow, what a bunch more results! I guess that makes sense for the leader of an entire faction – model, audio, events, and all! And one of these tables is hopefully melee attack...

[[File:RPFMForDummiesImage 25.png]]

We’re currently hunting in db but it’s worth giving a mention to the other tabs. Loc Matches searches inside WH2’s complex text database, and is a really good way to get started on finding something if all you know is its in-game name. Text Matches searches, among other things, script and the bit of a model called a “variantmesh” (don’t ask me what this means because I don’t know) – good if you’re hunting script or models, which we aren’t, so we can ignore it. I have no clue what Schema Matches does and have never needed it so we can hopefully ignore it.

Additionally, feel free to resize the window (drag on various handles that pop up), if you’ve got the screen real estate for it. Anyway, we wanted melee attack. There’s no table that looks like melee_attack, but, scrolling a bit up from the bottom, let’s try main_units_tables?

[[File:RPFMForDummiesImage 26.png]]

land_unit! That’s something! Double-click on that and a new tab in RPFM should open and scroll down to the line needed.

[[File:RPFMForDummiesImage 27.png|700px]]

''(Addendum: WH2, this guide, and RPFM have had so very many updates since things began. If you have a keen eye, you’ll see that the top left is called data.pack not warhammer_2, and that Skrolk is at line 709 when currently he’s at line 789. Things change, and I genuinely cannot keep this guide perfectly up to date. When modding, if nothing else, it’s important to be able to think on your feet as things keep changing around you.)''

You can see our previous character_skills_tables open in a non-active tab. We really don’t need that anymore and you can close it if you want, we’re taking a look at main_units now.

Scrolling across, we see things like Upkeep Cost, Multiplayer Cost, some voiceover stuff, but nothing that looks like melee attack. Well, this ''does'' look like Lord Skrolk (the wh2_main_skv_cha_lord_skrolk seems about right), so we’re probably on the right track. What about that Land Unit? If we hover over the column header in RPFM, it’ll tell us which table this is referencing. (Some columns in tables link other tables together, like this one – but obviously Upkeep Cost doesn’t reference a table!)

[[File:RPFMForDummiesImage 28.png|700px]]

Huh, a table called land_units. Would be nice to find that quickly. There are two ways you can do this: one, fishing the table out by hand. This is actually pretty speedy since if we select a random folder on the left and hit L (for Land_units), the folder view will scroll to the first match of L. (You can type even quicker if you want, typing L A N D _ U N I T S , but that’s too much typing for my fingers).

[[File:RPFMForDummiesImage 29.png]]

Well, lab_settings is definitely not what we want, but if we scroll down a bit, we’ll find land_units_tables.

The other – and much speedier – option is to use RPFM’s handy Go To functionality. Right-click on the cell and Go To -> Go To Definition, and fazam, RPFM will take you right there!

[[File:RPFMForDummiesImage 30.png|700px]]

Either way, we’ve now got land_units_tables open in front of us:

[[File:RPFMForDummiesImage 31.png|700px]]

Now, we really don’t want to scroll through all ten bazillion lines of this table to find Skrolk, but instead RPFM has a handy Filter section just below the table view. Type skrolk in that and it’ll only show rows that match skrolk in the Key section. (We wouldn’t want to search for skrolk in the Category section!) There’s tons of superpowerful stuff you can do with more detailed filters (they support Regex, very powerful for searching), but this simple filter will do:

[[File:RPFMForDummiesImage 32.png|700px]]

Only one hit? That’s usually pretty good, as it suggests this is a Master Node of some sort, linking a lot of things together. Scroll across the table and we some things about mounts, morale, armor, melee weapon, and – what’s this? Melee attack! We found it!

[[File:RPFMForDummiesImage 33.png|700px]]

Now, before we get too excited, this is the data packs of the game themselves. Editing these is a terribly bad idea as it makes there be no way to revert to unmodded short of reinstalling the game, and the reason RPFM won’t let you save your changes if you try. Instead, that’s why we created a mod!

Hop back to the instance of RPFM that has your mod open (or open it again, if you closed it). If you did close it, there’s a super-nifty RPFM trick that allows you to open it super quickly, and it’s under the MyMod menu:

[[File:RPFMForDummiesImage 34.png]]

Super speedy and super handy. Anyway, we’d shut that because we didn’t know what table we wanted, but now we know we want land_units tables! So again, right-click, create, create DB...

[[File:RPFMForDummiesImage 35.png]]

... and this time we know what table we want – it’s the ''land_units'' table! Typing in land_units doesn’t quite land the hit we need, but it’s easy to find it from the four in the dropdown box:

[[File:RPFMForDummiesImage 36.png]]

The new_file in the first line will be the name of your table. This isn’t super important – except that it shouldn’t end with a number and should have no spaces in it – but I like to, again, preface it with my name and then have something about the table. So aiden_land_units will do just fine.

[[File:RPFMForDummiesImage 37.png]]

Hit Create, open it up, and it’s blank. Well, of course it’s blank – we haven’t added anything to it!

[[File:RPFMForDummiesImage 38.png]]

Well, we want to put the line about Lord Skrolk in here and change his melee attack. I guess you could re-type everything out by hand if you were feeling like you wanted some bonus suffering, but I like my modding to be an enjoyable experience (which is why I don’t touch startpos), and in RPFM, we can copy and paste rows (and much more!) over!
Hop back to RPFM that has data.pack open, and it should be right where we left it.
Now – just like Excel – if you click on the row number the entire row will be selected. Right-click somewhere in that row, select Copy, then Copy (the other option we don’t need for this):

[[File:RPFMForDummiesImage 39.png|700px]]

Now hop back to our mod, right-click anywhere in the table view, and hit Paste as New Row!

[[File:RPFMForDummiesImage 40.png]]

Results should look like this!

[[File:RPFMForDummiesImage 41.png|700px]]

Stuff’s a bit squished, but it’s there! Now scroll over to the Melee Attack, double-click to select it, put our nice modded 100 value in, hit Enter, and, that’s done!

[[File:RPFMForDummiesImage 42.png]]

But before we get toooooo excited about using an overpowered Lord Skrolk, there’s two more things we need to do:

The first is save the mod! Ctrl+S does the trick, or PackFile -> Save. The second’s more important: to copy the mod to WH2’s data directory so the mod managers actually pick it up. Instead of fishing up the packfile manually and pasting it over, RPFM does this all with two mouse clicks: PackFile -> Install !

[[File:RPFMForDummiesImage 43.png]]

''(Addendum: Previous versions of RPFM had this under the MyMod menu. Again, the buttons might move around and about – it’s important to think on your feet)''

Oh, by the way, if you get an error that looks like this:

[[File:RPFMForDummiesImage 43b.png]]

Now our nice little packfile is sitting in WH2’s data directory ready for either the CA mod loader (affectionately called George) or Kaedrin’s Mod Manager (KMM) to pick it up. It’s vitally important to playtest your mods first (and, if nothing else, make sure they load and the game doesn’t crash!), so we’ll do that.

While KMM is definitely superior for managing large amounts of mods and its Profile feature is a godsend, we do actually need the CA mod loader to upload a mod (more on that later), so for this I’ll be using the CA mod loader. Boot it up, and if you scroll down, tadaaaaaaa!

[[File:RPFMForDummiesImage 44.png|700px]]

Enable that, hit Play, hit Play on the obligatory “warning you are modded” menu (does anyone besides me actually read that?), and WH2 boots up with our mod in tow! :D

We could start a new campaign to check things out, but we could also be lazy, and just check things in Custom Battles instead. And will you look at that!

[[File:RPFMForDummiesImage 45.png|700px]]

''It woooooooooooooorks!'' :D

= Chapter 4 - Script =

''To Be Continued...''

[[Category: Tools & Resources]]

Category:Tools & Resources

2024-03-11T21:45:10Z

Grimmys: Fix typo

Every modder needs proper tools, just like every lumberjack needs a swing set. This list does not claim to be a sure-fire solution to every single issue a modder might face, nor an impervious list of perfect programs, designed to cater your every need. This list does have a lot of value in it, I believe, and if used correctly, a lot can be achieved.

You’ll also notice that this section has random housed tutorials in it, that don’t fit in any particular place with the larger-scale tutorials. The author and summary of each will be listed and maintained here!
====Kaedrin’s Mod Manager====
[https://github.com/Kaedrin/warhammer-mod-manager/releases Warhammer Mod Manager Releases] – Kaedrin’s Mod Manager is a very useful alternative mod manager that works for all Total War games since Total War: Empire.

You can get in contact with the creator, ''Kaedrin'', in the Modding Den’s channel '''#kaedrin_mod_manager'''.
====Frodo’s Rusted Pack File Manager====
[https://github.com/Frodo45127/rpfm/releases/ RPFM Releases] – RPFM is a great pack-file managing tool, essential for any modder. Active development has new features coming regularly, as well as constant bug fixes or bug squashings.

You can find its documentation here: [https://frodo45127.github.io/rpfm/ RPFM Documentation]
. Or you can also check [https://tw-modding.com/wiki/Tutorial:RPFM_For_Dummies this tutorial].

Get in contact with the creator, ''Frodo'', in the Modding Den’s channel '''#rpfm'''.
==== Phazer's Rigid Model Editing Tool====
[https://github.com/mr-phazer/RME_Release/releases RME Tool Releases] – A tool to quickly edit rigid models using a visual UI rather than having to use clunky hex editing.

Get in contact with the creator, ''Phazer'', in the Modding Den's channel '''#phazer_tools'''.
====Ole's Asset Editor====
[https://github.com/olekristianhomelien/TheAssetEditor/releases/ Asset Editor Releases] – A tool for kitbashing and animation splicing using vanilla assets.

You can check [https://tw-modding.com/wiki/Tutorial:AssetEditor this tutorial] for learning more about it.

Get in contact with the creator, ''Ole'', in the Modding Den's channel '''#asset_editor'''.
====Thegroovewizard's LUA Debugging Setup====
[https://github.com/chadvandy/tw_autogen Setup for debugging LUA scripts] – A setup for debugging LUA scripts in [https://code.visualstudio.com/ Visual Studio Code].

Get in contact with the creator, ''Thegroovewizard'', in the Modding Den's channel '''#groove_tower'''.
====Interactive Maps for Total War: Warhammer II====
[https://imrz.github.io/tww-interactive-map/latest/#/ Mortal Empires / Eyes of the Vortex interactive maps] – Web application for checking the position of every settlements, regions and ressources on both maps of ''Total War: Warhammer II''.
====Imagemin App (PNG Compressor)====
[https://github.com/imagemin/imagemin-app/ Imagemin App] – An application to lower the size of your mod .png, because they have to be less than 1Mb.
====Video Tutorials====
[https://www.youtube.com/watch?v=pzqTFR32tl8&feature=youtu.be Setting Up GitHub Desktop for Total War] – A rundown on how to setup GitHub Desktop for use with the Assembly Kit.
====Scripting Resources====
[https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html Script Doc Warhammer 3 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH2/scripting_doc.html Script Doc Warhammer 2 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 3 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/WH2/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 2 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/index.html Warhammer 2 & 3 CA Documentation]

[https://chadvandy.github.io/tw_modding_resources/3k/scripting_doc.html Three Kingdoms CA Documentation]
==Tools & Resource Posts:==
*[[Troubleshooting]] by Vandy and Cataph
*[[Modding Glossary]] by Vandy and Cataph
*[[Campaign Map Coordinates]] by Marthenil by Vandy

Category:Tools & Resources

2024-03-11T21:44:16Z

Grimmys: Add links to internal pages of some tools

Every modder needs proper tools, just like every lumberjack needs a swing set. This list does not claim to be a sure-fire solution to every single issue a modder might face, nor an impervious list of perfect programs, designed to cater your every need. This list does have a lot of value in it, I believe, and if used correctly, a lot can be achieved.

You’ll also notice that this section has random housed tutorials in it, that don’t fit in any particular place with the larger-scale tutorials. The author and summary of each will be listed and maintained here!
====Kaedrin’s Mod Manager====
[https://github.com/Kaedrin/warhammer-mod-manager/releases Warhammer Mod Manager Releases] – Kaedrin’s Mod Manager is a very useful alternative mod manager that works for all Total War games since Total War: Empire.

You can get in contact with the creator, ''Kaedrin'', in the Modding Den’s channel '''#kaedrin_mod_manager'''.
====Frodo’s Rusted Pack File Manager====
[https://github.com/Frodo45127/rpfm/releases/ RPFM Releases] – RPFM is a great pack-file managing tool, essential for any modder. Active development has new features coming regularly, as well as constant bug fixes or bug squashings.

You can find its documentation here: [https://frodo45127.github.io/rpfm/ RPFM Documentation]
Or you can also check [https://tw-modding.com/wiki/Tutorial:RPFM_For_Dummies this tutorial].

Get in contact with the creator, ''Frodo'', in the Modding Den’s channel '''#rpfm'''.
==== Phazer's Rigid Model Editing Tool====
[https://github.com/mr-phazer/RME_Release/releases RME Tool Releases] – A tool to quickly edit rigid models using a visual UI rather than having to use clunky hex editing.

Get in contact with the creator, ''Phazer'', in the Modding Den's channel '''#phazer_tools'''.
====Ole's Asset Editor====
[https://github.com/olekristianhomelien/TheAssetEditor/releases/ Asset Editor Releases] – A tool for kitbashing and animation splicing using vanilla assets.

You can check [https://tw-modding.com/wiki/Tutorial:AssetEditor this tutorial] for learning more about it.

Get in contact with the creator, ''Ole'', in the Modding Den's channel '''#asset_editor'''.
====Thegroovewizard's LUA Debugging Setup====
[https://github.com/chadvandy/tw_autogen Setup for debugging LUA scripts] – A setup for debugging LUA scripts in [https://code.visualstudio.com/ Visual Studio Code].

Get in contact with the creator, ''Thegroovewizard'', in the Modding Den's channel '''#groove_tower'''.
====Interactive Maps for Total War: Warhammer II====
[https://imrz.github.io/tww-interactive-map/latest/#/ Mortal Empires / Eyes of the Vortex interactive maps] – Web application for checking the position of every settlements, regions and ressources on both maps of ''Total War: Warhammer II''.
====Imagemin App (PNG Compressor)====
[https://github.com/imagemin/imagemin-app/ Imagemin App] – An application to lower the size of your mod .png, because they have to be less than 1Mb.
====Video Tutorials====
[https://www.youtube.com/watch?v=pzqTFR32tl8&feature=youtu.be Setting Up GitHub Desktop for Total War] – A rundown on how to setup GitHub Desktop for use with the Assembly Kit.
====Scripting Resources====
[https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html Script Doc Warhammer 3 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH2/scripting_doc.html Script Doc Warhammer 2 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 3 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/WH2/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 2 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/index.html Warhammer 2 & 3 CA Documentation]

[https://chadvandy.github.io/tw_modding_resources/3k/scripting_doc.html Three Kingdoms CA Documentation]
==Tools & Resource Posts:==
*[[Troubleshooting]] by Vandy and Cataph
*[[Modding Glossary]] by Vandy and Cataph
*[[Campaign Map Coordinates]] by Marthenil by Vandy

Tutorial:AssetEditor

2024-03-11T21:38:31Z

Grimmys: Add tools category

The AssetEditor is a poor man's 3d program for Total war games (currently only supports WH2).

It aims at trying to recreate the Kit bashing feeling you get when working with plastic models.

'''Download link''': [https://github.com/olekristianhomelien/TheAssetEditor/releases/latest https://github.com/donkeyProgramming/TheAssetEditor/releases/latest]

'''Youtube tutorials:''' https://www.youtube.com/channel/UCXnf2q9fRNYlMn4XULPLKgg

'''Beginner tutorial by FaallenOon:''' [https://docs.google.com/document/d/1QZefJwJLvG_ny2MUMZZvvxV-4o2AAuSCmmiA-twAIXw/edit https://docs.google.com/document/d/1QZefJwJLvG_ny2MUMZZvvxV-4o2AAuSCmmiA-twAIXw]

'''Disclaimer''': I am not good at technical writing or enjoy it, so if someone feels the desire to improve this, then please!

==The Basics==

===Creating a New Packfile===
To create a new packfile go to the top left corner of the program and click file then select New Packfile and a window will open asking you to enter a name, once you have entered a name press ok and your packfile will be created in the file browser to the left and will be marked as active which is identified by '''bold''' text.

===Opening a Model ===
To get started working with models navigate to the file browser on the left and open the All CA Packs folder, scroll down to variantmeshes, into wh_variantmodels and browse through the list for a model of your choosing and once you have found the model that you seek you can double click upon the rigid_model_v2 file to open the model within the 3d viewer.

====How to find a Model====
If you have an idea of what kind of model you are looking for you can use the Search Filter box at the top of the file browser to try and narrow down the amount of folders you need to search through but if you do not then you can take a rough guess at where models are located by the folder names which correspond to the models skeleton for example:

*hu1 = humanoid01 - which are associated with male humans.

*hu1b = humanoid01b - which are associated with female humans and female elves.

*hu1c = humanoid01c - which are associated with norscan and chaos humans.

Etc, you'll quickly become familiar with these while modding.

===Camera Controls===
While in the visual work space you can navigate the 3d area by placing your mouse cursor within the window and using the following:

*Holding down Alt + Left Mouse Button (LMB) will move the camera around a fixed point.

*Holding down Alt + Scrolling the Mouse Wheel up will zoom in towards the fixed point and scrolling it back will zoom out.

*Holding down Alt + Right Mouse Button (RMB) will allow you to reposition the fixed point.

===Saving a Model===
To save your freshly acquired model to your packfile navigate to the tool bar at the top of the screen and hit the save icon (Ctrl+S) at which point you will see the model appear under your packfile in the file browser marked in red which means that you have saved the models current state but this does not save your packfile and closing the program before doing so will delete any work you have done up to this point.

If you are working with multiple packfiles at the same time you must switch to the correct packfile before saving your models or they will save in the wrong place, to do this right click an inactive pack in the file browser and select Set as Editable Pack.

===Saving a Packfile===
To save your packfile navigate to the file browser and right click your packfiles name, select Save or Save As and select a location for your file then hit save again, your packfile is now saved and it is safe to close the program.[[File:SavePackfile.png|thumb|alt=|none]]

== Sub Tools==

=== Kitbash Editor===
Select a .rmv2 file to open the Kitbash Editor

Find your self a model to play with. Go to:

variantmeshes/

wh_variantmodels/

There is folders named after skeletons. hu1 is for humans.

In hu1 you have files for each factions that use it.

Look for a file that ends with .rigid_model_V2

Ignore the .wsmodels for now

Youtube tutorial: https://www.youtube.com/watch?v=LeObDGqV2PM

====Re-Regging====
One of the key parts of the Kitbash editor is the ability to re-rig a mesh from one skeleton to an other. If this is not done, the mesh will turn into spaghetti when an animation is applied.

It works by doing a 1:1 mapping between bones in the original skeleton (left side) and the target skeleton (right side)

It works by selecting bones one by one on the left side and then selecting a bone on the right side. When this is done the column on the left side that says -1 should turn into the same the bone selected on the right side.

The tool can also attempt to auto fit the mesh onto the skeleton by selecting the "Fit mesh to skeleton" checkbox.

[[File:ReriggingImage.png|none|thumb]]
[[File:RemappingBoneSelected.png|none|thumb|Bone selected and mapped correctly]]
[[File:Remapping.png|none|thumb|Old and messy tutorial]]

====BMI tool====
The BMI editor allows the scaling of a mesh along its normals. This gives the impression of adding or removing thickness to and object.

All the bones that are selected in the tree view is applied to the scale when the apply button is pressed.[[File:BmiTool before.png|none|thumb|Before]]
[[File:BmiTool After.png|none|thumb|After]]

===Mount Animation Creator===
The tool also allows for attaching an animation to a vertex on an other skeleton. This is useful for creating mount animations for mount that does not exist in the game.

An example of this would be adding a Squig mound to Karl Franze or a Lion animation to the High Elf Princess. https://www.youtube.com/watch?v=4dKFXAu4R1Y

'''Excellent, must read tutorial for how to use the tool''': https://docs.google.com/document/d/123LZH16sY2EGRJWwTH4T3XvT0ENUUQXLLfL6tVUtezk/edit

A run-through of the UI components:

#Information about the rider and mount (mesh, skeleton and animation)
#Control how the rider is attached to the mount
#*Rider root bone (probably never change this)
#*Leg animation (disabled for now)
#*The vertex the rider is attached to. Select the mount, press F3 then select the vertex that the rider should be select to and press Set. The first selected vertex is used if multiple vertexes are selected
#Settings for the animation - Hopefully pretty intuitive
#Rider and mount animation fragment and active slots
#*Mount is the animation fragment used by the mount
#*Rider is the animation fragment used by the rider
#*Mount animation tag is the animation used by the mount
#Save and Preview:
#*Update the preview to reflect changes done in the animation settings view
#*Active fragment to add items to
#*Slot in the active fragment to add to
#*Batch process based on the values in "Mount link shortcut view"
#Drawing related things
[[File:Mount tool defaultworkflow.png|none|thumb|Screenshot]]
[[File:Image2.png|none|thumb|Selecting vertex]]

====Workflow====
#Select rider and mount meshes
#Select attachment point
#Select rider and mount fragment
#Play around with the settings until you are happy with how it looks
#Press Batch prosess to generate animpack, bin and fragment.
#Look at the report to see if manual tweaks are needed.
#If manual tweaks are needed:
##Load the new fragment into "selected fragment"
##Find a slot that needs to be fixed.
##Select the correct Mount tag for the selected rider slot
##Select a rider tag that looks good
##Press add to fragment
##Repeat
[[File:Mount tool defaultworkflow fixstuff.png|none|thumb]]

====Sliding====
If the rider is sliding around or popping, make sure that the scale of the mount is correct.

====Matched animations====
Matched animations does not work well right now, I recommend deleting them.

===Anm.Meta files Editor===
The tool can display and edit most meta file, more information will be added later[[File:ImageMeta.png|none|thumb]]

=== AnimPack Editor ===
The tool comes with an animation pack editor. The animpack is the file which controls how animations are configured.

Refer to the "animation and you" tutorial for more information about how they are structured

[[File:Images.png|alt=|1226x1226px]]

==== How to create a new fragment (animation set) for a unit ====

Go to '''File -> Create -> New AnimPack(game''') and enter a name when prompted. This gives you a very basic example of how the file works. For more information I recommend looking into the existing game animpack

By default the tool creates a placeholder bin entry[[File:CustomAnimPack.png|left|alt=|1373x1373px]]

Create a new fragment by going to '''File->New AnimationSet(Game)''' inside the animpack editor. This gives you the fragment where the animation information about the unit is stored

Edit the bin to to be sensible values. Best way to do this is by copying a bin which is the closest to what you want to do. In this case it was the "hu2_orc_2handed_axe" entry and then I replaced the "hu2_orc_2handed_axe" names with the new name of the fragment.

'''Save the bin.'''

[[File:BinValues.png|alt=|1376x1376px]]

Go the the frag, it contains some example data. Replace it with the data you want. Typically this means copy pasting in the fragment the closest to what you want, then updating it. In this case it was the "hu2_orc_2handed_axe" and I updated some of the meta files to use the new files I have created (Note, the files on the left in the tree view has not yet been renamed!)

'''Save the frg, then save the animpack by going to File->Save'''
[[File:EditAndSaveFrg.png|thumb|alt=|none|1375x1375px]]Now your animpack is done, but you need to link it to a unit. Dindi has kindly created an example animpack for how to do this!
[[File:Anim db example.pack|none|thumb]]

[[Category:Tools & Resources]]

Mods

2024-03-11T21:35:34Z

Grimmys: Add workshop link for TW:WH3

A mod is any alteration to the base game, through [[modding]].

Mods are made up of a single .pack file, which contains all the changes for that mod, and a single .png file of the same name - which is just used as the thumbnail within Steam and the Total War Launcher.
== Finding Mods ==
Most mods that you will find can be discovered on the Steam Workshop page, for each Total War game.

* [https://steamcommunity.com/app/594570/workshop/ Total War: Warhammer 2 Steam Workshop]
* [https://steamcommunity.com/app/1142710/workshop/ Total War: Warhammer 3 Steam Workshop]
* Etc.

Point of assistance here - you'll have a better time either Googling for the mods you're looking for (ie., "total war warhammer 2 greenskin units mods"), or searching for a collection on the Workshop. Steam Workshop is... a subpar searching service. Ironically.

== Installation ==
When you find a mod you like in the Steam Workshop, you simply press the "Subscribe" button - '''making sure to download all required items for that mod!''' - and let Steam download it in the background. Next time you load up the game, you will see it available in the launcher's mod manager. Simply tick the mod in the manager, and it will be enabled next time you press play!

Important note here: Don't faff around with [[Troubleshooting#How_to_Load_Order|load order]]. Mods are sorted alphanumerically by default, and modders are aware of the priorities needed between mods most of the time, when it comes to [[Tutorial:Submodding#WHAT_IS_A_SUBMOD.3F|submods]] or similar.

== Troubleshooting ==

If a mod doesn't appear to work or update, you can try to unsubscribe and re-subscribe, though in some instances this may not be enough and you may need to Clear the Steam Download Cache, see this [https://support.steampowered.com/kb_article.php?ref=3134-TIAL-4638 article]

See also: [[Troubleshooting]]

== Compatibility ==

Lua/First Script

2024-03-11T21:31:50Z

Grimmys: Add LUA tutorial category

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 ===
<small>''Sounds kinda like a platitude you'd find on a pillow in Kohl's.''</small>

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 <u>variable</u> 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!

[[Category:Lua Tutorials]]

Lua:Debugging

2024-03-11T19:29:13Z

Grimmys: Add LUA tutorial category

As you write Lua, you’ll find that errors aren’t uncommon. Something will go wrong, code is ignored, and you’re a sad panda. Thankfully, the language has a rigorous self-checking system implemented that can be used to catch any errors within lines and print out the exact line that caused an error. On top of this, it’s also important to include your own error checking systems as your write your own custom scripts to make sure your stuff is running properly!

==== Outputs! ====
As we’ve covered a bunch in this tutorial series, we can get some CA script logs using the script debug activator mod, and we can add stuff to that output log using the function <code>out()</code>.

A really remedial use of this function is to check exactly where in our script something is breaking. Your script just ISN’T working, and you don’t know which exact line isn’t working. Let’s take an example (it’s actually perfectly valid code, but let’s pretend it isn’t):
<code>function example()
local empire = cm:get_faction("wh_main_emp_empire")
local character = empire:faction_leader()
local region = character:region():name()
cm:apply_effect_bundle_to_region("testing_bundle", region, 10)
end</code>
Say these lines haven’t been running for you, and you don’t know why! A very simple, very easy way to test is to edit it to the following, run the game, check the script logs and see where the block failed:
<code>function example()
out("VANDY: example() called!")
local empire = cm:get_faction("wh_main_emp_empire")
out("VANDY: empire called!")
local character = empire:faction_leader()
out("VANDY: character called!")
local region = character:region():name()
out("VANDY: region called!")
cm:apply_effect_bundle_to_region("testing_bundle", region, 10)
out("VANDY: apply effect bundle called!")
end</code>
You’ll notice a couple of things here. I called out() for every function that I called, for every line of “do something”. This can be overkill, but in this situation, I want to see the exact very line where something went wrong, and the outputs will stop being called after this block is aborted due to failed code. I also added an easy-to-find tag to all my outputs, “VANDY”, so I can quickly Ctrl+F them within the script_log.txt file.

This is a super simple, super easy, and super handy way to quickly debug failing code and find the EXACT line that isn’t working for you. But… it’s a little clunky. I mean, come on, you have to scroll through thousands of lines of CA outputs just to find your five lines? What are you, a CA employee? Thankfully, with just a few more lines, we can make our own output files.

==== Our Own Output Files ====
Yep! Now with 100% less fat!

I use custom output files all the time, for all of my mods. It takes no time at all to set one up, it doesn’t require any editing of CA scripts, and you can easily set it up so you have your own “dev mode”, which will be just like how CA does it – a boolean variable set to true when you want to have files printed, and false when you don’t.

Your local output function will look something like this. I’ll display it first, then we can start to take it apart.
<code>local function Log(text)
if type(text) == "string" then
local file = io.open("name_of_file.txt", "a")
file:write(text.."\n")
file:close()
end
end</code>
And boom. Just like that, anytime within the local env that you call Log(), it will automatically open up a file called “name_of_file.txt”, located in the same folder as the CA script log, and automatically write in your text. Pretty awesome, huh? Now, let’s break it down a little bit.

That first line here, we call a basic Lua library function, which is <code>type()</code>. This returns the type, obviously, of a variable. This isn’t needed here, as I could more-smartly use a <code>tostring()</code> call, but I’m doing some playful foreshadowing at better debugging practices. This line runs, checks to make sure the “text” parameter is a valid string, and if it is, it continues!

Following that, we call the Lua <code>io</code> library, which stands for “Input/Output”, a simple file manipulation library that gives us power over text editing files. io.open is used to open a file – which is named whatever the first arg is – and then the second argument determines the type of operation. We have several options here, which can be found in this handy page. We are using “a”, which calls the append operation. Basically, we’re gonna add on to our file every time we call Log().

Next are two simple and easy function. <code>file:write()</code>, which just takes a string, does the actual typing for us like a sweetie; <code>file:close()</code> operates on self and closes the file.

And, just like that, we have our own, personalized log file. Whenever Log() is called, it’ll print that line for us on “name_of_file.txt”, and next time we call it it’ll be set on the very next line. Very cool. Let’s take a look at this in practice and take a look at some simple code and how we can de-clutter our output log by using our very own. Yay.

[[Category:Lua Tutorials]]

Lua:Advanced Conditionals

2024-03-11T19:28:27Z

Grimmys: Add LUA tutorial category

==== By DrunkFlamingo ====
I’m guest writing this to clear up some common confusions and problems I see with people writing conditional statements. As Vandy made clear, conditionals are what your script is built with, but as you work more with Lua you’ll begin to see that tables are what makes the language work. Combining the two is the key to writing better script.

==== A Quick Refresher ====
A conditional statement is any statement of Lua that is either true or false. For our purposes, conditionals tend to look like this:
<code>return context:faction():name() == "wh_main_emp_empire"</code>
Or like this:
<code>if context:faction():name() == "wh_main_emp_empire" then</code>
In either case, it’s either true or it isn’t!

But those are pretty basic, and you can probably write those by the time you get here. The purpose of this chapter is to walk through doing some more advanced things with conditionals. Starting with the most common mistake I see being made by new scripters: how to check a large number of individually valid items. You see this when doing tasks like:

# singling out groups of factions
# singling out lord types
# singling out specific regions

==== Using Tables and Loops to match many things ====
Let’s take a pretty simple example. Imagine we have a scripted mechanic. This mechanic only applies to human players, and it is initiated by calling the function “my_mechanic” and giving it the faction key we want the mechanic to happen for.

A huge mistake I see in a lot of new scripters code is stuff like this:
<code>if cm:get_faction("wh_main_emp_empire"):is_human() then
my_mechanic("wh_main_emp_empire")
elseif cm:get_faction("wh_main_brt_bretonnia"):is_human() then
my_mechanic("wh_main_brt_bretonnia")
else
-- this goes on for quite a while
end</code>
This is bad for a few reasons. Its bad for performance, but that doesn’t matter as much as the fact that it requires a crapton of typing on your part. You’ve written 5 lines for only two factions! To get every good guy playable that’s gonna be more than 30 lines. It also means if you want to check whether factions have a mechanic, you can’t reuse any of this code. Finally, it means your code is a pain for other people to read.

So how do we solve this? The simplest and best way is to use a table to check them. In this scenario, we’re going to first introduce one that CA defines for us.
<code>local humans = cm:get_human_factions()</code>
This returns a list of the humans in the game. That sounds much better, but let’s write our code.
<code>for i = 1, #humans do
local current_human = humans[i]

if current_human == "wh_main_emp_empire" then
my_mechanic("wh_main_emp_empire")
elseif current_human == "wh_main_brt_bretonnia" then
my_mechanic("wh_main_brt_bretonnia")
else
-- blah blah blah
end
end</code>
That’s not any better. We’re on the right track, but we haven’t actually eliminated that many checks.

Remember that in our use case we need to know three things:

# We need to know if a faction is human, this changes based on the game.
# We need to know if a faction can use our mechanic at all. We define this ourselves.
# We need to know the exact faction key by the end so we can start our mechanic.

So how can we improve this code? Well, we started by introducing the humans table to deal with condition #1, but condition #2 is still causing us grief. The answer, of course, is another table.

We will start with what that table looks like:
<code>local my_mechanic_factions = {}</code>
local my_mechanic_factions = {} So what data do we need in this table? Probably the faction keys. When I said table, you might have wanted to try something like this:
<code>local my_mechanic_factions = {
"wh_main_emp_empire",
"wh_main_emp_brt_bretonnia"
}</code>
But now let’s try to write a conditional statement using that. We’ll probably end up with something like this:
<code>local humans = cm:get_human_factions()
for i = 1, #humans do
local current_human = humans[i]
for j = 1, #my_mechanic_factions do
local current_faction_key = my_mechanic_factions[j]
if current_human == current_faction_key then
my_mechanic(current_faction_key)
end
end
end</code>
That’s much better than before. It saves us a lot of typing to add more factions, but it isn’t very efficient. If we add, lets say, 25 factions to our mechanic list, then we’re looping 25 times in a single player game and 50 times in a coop game. It probably won’t be too noticeable, but we can do better.

==== The Right Answer ====
Instead of using an array table (one that is a list of items with integer keys; if you use Kailua you’ll know this as a vector), lets try using a map table (one that associates a key and a value which we set explicitly) instead. These kinds of tables are extremely powerful when writing conditionals, so lets see why.
<code>local my_mechanic_factions = {
["wh_main_emp_empire"] = true,
]"wh_main_emp_brt_bretonnia"] = true
}</code>
How can that possibly help? Well, let’s think about our condition #2. We want the smallest possible thing which can take a faction as an input and give back whether they are valid for our mechanic. These factions are true in relation to the mechanic. Any other faction will return “nil” if we ask for its entry in this table, because no entry for it exists. Lets see how that works in action:
<code>local humans = cm:get_human_factions()
for i = 1, #humans do
local current_human = humans[i]
if my_mechanic_factions[current_human] then
my_mechanic(current_human)
end
end</code>
And there we go, finally something efficient, small, easy to modify, and easy to read. If the faction isn’t in our table, then the “if” statement will be nil, which doesn’t proceed. If the faction is there, we will proceed and fire off the mechanic. Now, no matter how many factions we want our mechanic to use, we’ll only be looping once in a single player game, and twice in an MP game. For a mechanic which launches once or twice, that’s the ideal number.

We can also reuse this code elsewhere. Now, if we want to check whether a faction fits a mechanic or not at any time, it’s only a single check away. We could even formalize this into a function:
<code>function does_faction_have_my_mechanic(faction_key)
return (my_mechanic_factions[faction_key] and cm:get_faction(faction_key):is_human()
end</code>
And check whether any given faction fits our criteria from any place in our code.

[[Category:Lua Tutorials]]

Lua:Commands, Interfaces & Listeners

2024-03-11T19:27:34Z

Grimmys: Add LUA tutorial category

For today’s lesson, the subject is three-fold: commands, interfaces, and listeners. The three of these are our introduction to messing with the game itself, and making real change. Every worthwhile Lua mod on the market has these in it! Anything else just concatenates strings or applies arithmetic or some nonsense.

==== Commands ====
A command, at its bearest-bones, is a ''CA-defined Lua function'' that does stuff that we can’t see. They function (hah) identically to the functions we’ve already covered; some have parameters, some have return values, they all do stuff. Whenever we use commands, we’re treating them like ''function calls''; they’re a statement. Commands are used to communicate between the Lua environment and the actual Total War Engine – the base C++ code that defines the majority of the game.

Through these commands, we can script a whole lot of stuff! From character spawns, to new effects applied to characters and factions and armies, to quest battles, to unlocking rites, and so on.

In big part, commands make or break what can be done with scripts. Commands are the driving force of most any script. At this point, though, you might be asking – “how the HECK do I find out what the commands are?” And that, my friend, is why you’re reading this lesson. Or maybe you got lost when you were just trying to find funny videos about cats. Either way, next paragraph!

So, once more in the “Tools & Resources” page on this site, there’s a section within called “Scripting Resources”. We’ll look at, first, the “Scripting Doc (CM Functions)” file. Open it up!

Now, before we go on, one thing MUST be covered. EVERY command in this document needs to have a prefix of <code>cm:</code>. Those two letters stand for “campaign_manager”, and it’s the big object that holds most all information we could want within the campaign game-mode.

''NOTE:'' ''The campaign manager is ONLY usable in the campaign game-mode!''

In this document, let’s take a look at two example commands to breakdown.
<code>Command: transfer_region_to_faction
Description: Transfer a region ownership to a faction.
Usage: transfer_region_to_faction("region", "faction")</code>
This is relatively straightforward. The <code>Command:</code> line tells you what to affix to <code>cm:</code>, so this would be <code>cm:transfer_region_to_faction</code>. Since it’s a ''function call'', which we learned about just last episode and you wouldn’t dare forget so soon, we add the brackets to it: <code>cm:transfer_region_to_faction()</code>.

We can see in <code>Usage:</code> that it takes TWO parameters. They seem to be strings, one of which says “region”, the other “faction”. It’s easy enough to tell that means “the region key in string”, and “the faction key in string”. So, overall, the command call would look like this: <code>cm:transfer_region_to_faction("wh2_main_vor_phoenix_gate", "wh2_main_hef_eataine")</code>.
<code>Command: create_force
Description: create a navy or army at a position. Final parameter specified whether the command goes via the command queue
Usage: create_force("faction_key", "unit_list", "region_key", x_position, y_position, exclude_named_characters, "id", true)</code>
The same applies here. <code>cm:create_force()</code>, with a bunch of parameters. However, there’s one caveat here – using cm:create_force() with those parameters will crash-bang-boom the game! Let’s back up and talk about why.

The commands in this document are commands to the ''game interface'', something that you really should never, ever touch directly, for fear of crashing the game if you mess something up. These functions –<code>cm:create_force()</code> – are ''wrappers'', over that base command, so we don’t have to directly touch the game interface. Using the CA functions will quickly error-check our code, and prevent any such crashes (when wrappers for those commands exist!). But what do I mean? Let’s open up our script dump and go to script/_lib/lib_campaign_manager.lua, and search for <code>create_force(</code>.

We’ll see a line that looks similar to what I have already shown you – <code>function campaign_manager:create_force(faction_key, unit_list, region_key, x, y, exclude_named_characters, success_callback)</code>. This is the ''wrapper''. Within this function, lower down at the bottom, we can see the call to the game interface – <code>self.game_interface:create_force(faction_key, unit_list, region_key, x, y, id, exclude_named_characters, true);</code>. This looks a lot closer to the definition CA has in their documentation, and I belive it was the definition they were trying to go with. Not sure though, it’s still a ''little'' wrong!

In these situations, it pays to be careful. I advise you to use the CM Scripting Doc cautiously. It isn’t fool-proof, and every change that CA has made over the years hasn’t been recorded in there – there are commands listed that haven’t been functional since Total War: Empire. This is when I point you back to the setup lesson, if you haven’t done that, and tell you to go do it. There are three hyper important tricks in there that will help you understand what to do in a situation like this:

# Check the lib files! Most functions in this document will be in <code>lib_campaign_manager.lua</code>. Bonus, as you could see with the above example, CA gives a quick explanation for what the function does and what the types are, and where they are found. This is always my first check. Do note that not every campaign_manager function is listed in that file; there are a bunch that are defined in the game-engine, have no wrapper in this lib file, and aren’t documented.
# Use the script dump! All you have to do is use “Find In Files … ” within Notepad++, type in the name of the command (ie. <code>create_force</code>), and wait for it to search all the files. It will come up with some hits, and you can read through CA scripts to see what they do and how it’s used. This is really handy for any undocumented functions, or if you’d like to get ideas on how a command is used. I do this all the time!
# Use Kailua! It might take some time to fully understand the <code>ca_types.lua</code> file that we’ve made for TW:WH2, but it should be pretty easy to ''read'' it if you want to know the parameters of a function. Open <code>ca_types.lua</code>, within VSCode (or whatever), search for the name of the command again (<code>create_force</code>), and it will show you some neat stuff. I’ll go over what it looks like now, just so you know:

<code>--# assume CM.create_force: method(
--# faction_key: string,
--# unitstring: string,
--# region_key: string,
--# xPos: number,
--# yPos: number,
--# exclude_named_chars: boolean,
--# callback: (function(CA_CQI))?
--# )</code>
Each of these lines is a ''parameter'', and it’s split into a name and a type. The name is just a description of what should go there – a faction key, a region key, etc., – and the type defines, of course, the type!

There’s a third example I’d like to go into, which is return types via the CA commands. It works just like regular return values (seen from the last lesson), but sometimes the return value is vague, and it’s really hard to read using CA’s scripting doc. Again, utilize the script dump and Kailua. In Kailua, it’ll look a little different – let’s grab an example of a command with a return value.
<code>--# assume CM.get_saved_value: method(valueKey: string) --> WHATEVER</code>
''NOTE: <code>WHATEVER</code> is a beautiful keyword in Kailua that lets you not define the type of a value, instead of saying “return a number” it says “return literally whatever”''

Some functions in the ca_types files have a <code>--></code> to their end; on the right side of that arrow is the return value. Easy enough to read!

And that’s my explanation of CA commands! Hope you had as much fun as I did.

==== Interfaces ====
Similar to commands, script interfaces are a way to access some game data with some Lua. We looked at them previously – in the second lesson, we used a <code>FACTION_SCRIPT_INTERFACE</code>, which we got by using the command <code>cm:get_faction("faction_key")</code>.

Script interfaces are objects that we can apply some functions ''to'' (functions applied to an object are known as methods, but we’ll talk about that terminology later). For example, let’s build up something small:
<code>local faction_name = "wh2_main_hef_eataine"
local faction = cm:get_faction(faction_name)
if faction:is_dead() == true then
-- sadface
end</code>
In this example, <code>cm:get_faction()</code> has a ''return value'' of a <code>FACTION_SCRIPT_INTERFACE</code>, which we assign to the local variable <code>faction</code>. <code>FACTION_SCRIPT_INTERFACES</code> have a method called <code>is_dead()</code>, which lets us read if the faction is, well… dead. But how did I know to use that? ''gasp''

Also similar to commands, script interfaces are documented with a slightly-questionable CA file, though this one is typically waaaay more reliable, if a bit inconsistent with some naming. We can, again, grab it from the Tools & Resources page, this time under the title “Scripting Doc (Events & Interfaces). Our big focus for now is the latter half of that name – Interfaces – though we’ll be getting into events right in the next section below!

Open your newest Scripting Doc, and search for <code>FACTION_SCRIPT_INTERFACE</code>. It should be towards the top of the document, right near the word “Interfaces” in big boldage. Like this: Interfaces. Cool, found it? Click it!

You should get a big, long list of blue links, followed by more clear definitions. A typical entry here would look similar to the follows (because the following ''is'' an entry):
<code>Function: holds_entire_province
Description: Does this faction hold the entire specified province? Also may include vassals
Parameters: holds_entire_province(String province, bool include_vassals)
Return: bool</code>
As before, like the commands above were done with a prefix of <code>cm:</code>, these interface functions are done with a prefix of that script interface. But it won’t just be <code>FACTION_SCRIPT_INTERFACE:holds_entire_province</code>, that makes no sense! In our previous, Tyrion-based example, it would look like the following:
<code>local faction_name = "wh2_main_hef_eataine"
local faction = cm:get_faction(faction_name)
if faction:holds_entire_province("wh2_main_vor_phoenix_gate", true) then
-- do stuff!
end</code>
The second line – description – is quite obvious. It’s just a description. Read it, don’t read it, I don’t care.

Third line: Parameters! We talked about this recently, you remember it right? It’ll be a type and a very brief stand-in name to explain what should go there. In this case, you can tell that it wants the key of the province, as a string, and a boolean that determines whether or not you’d like to include vassals in the check. Sometimes, they’ll just put the stand-in name in quotation marks to show that it should be a string.

Return values are much the same. Sometimes there will be returns of other script interfaces, and that’s how you can start getting some fun stuff. With a <code>FACTION_SCRIPT_INTERFACE</code>, you can use <code>character_list()</code> to get a <code>CHARACTER_LIST_SCRIPT_INTERFACE</code>, and then use <code>item_at()</code> to get a <code>CHARACTER_SCRIPT_INTERFACE</code>, and then use <code>get_forename()</code> to get a string. That’ll look like:
<code>local faction_name = "wh2_main_hef_eataine"
local faction = cm:get_faction(faction_name)
local character_list = faction:character_list() -- assign the CHARACTER_LIST_SCRIPT_INTERFACE to the variable "character_list"
local character = character_list:item_at(0) -- assign the CHARACTER_SCRIPT_INTERFACE, at index "0", to the variable "character"
local forename = character:get_forename() -- assign the string for the character's forename to variable "forename"</code>
I will note that you don’t have to assign everything a local variable here. It can look, albeit much uglier and less safe, like this:
<code>local faction_name = "wh2_main_hef_eataine"
local forename = cm:get_faction(faction_name):character_list():item_at(0):get_forename()</code>
But I do not recommend doing something like this, until you’re very comfortable with the language. I do it very, very, very rarely, only when it makes perfect sense to do it, and that’s lie-talk for “when I’m tired and it makes perfect sense to my tired brain”.

Script interfaces are stupidly, stupidly powerful, and using all these smartly allows you to make some serious change within the game, and to read a lot more details, from “how many units are in this army” to “what level is this character” to “how many armies were in the last battle?” But, above all, these interfaces are used ''best'' and ''most powerfully'' when used in conjunction with listeners and events.

What are listeners and events? Ah, well…

==== Listeners and Events ====
A listener is an important script command that, simply, waits for something to happen – or, listens for something to happen – in the game, and then triggers something else. Using a listener, we can listen for an event such as the creation of an army, the occupation of a city, or even a battle, and then we use the information from that situation, check for something specific, and run our code if the event matches our criteria. For example: we may be looking for Mannfred to occupy Altdorf. In this case we’d have to use a listener to “listen” for a city being occupied, but we don’t want to listen for just any city being occupied. In our example, we have to listen for Altdorf being occupied, and for Mannfred doing the occupying. The listener will listen for every single time a city is occupied, and once those two conditions are met – ''Mannfred'' occupying ''Altdorf''… Clue, anyone? – then our listener will trigger some code. In layman’s code, our listener will ''do a thing!''

Overall, it is a very valuable connection between Lua and game data, and any scripter should understand the in’s and out’s of a listener.

Let’s break down the basics of a listener. Here is it, at its most basic form:
<code>core:add_listener(
"listener_name",
"event_name",
boolean1,
function(context)
end,
boolean2
)</code>

* “listener_name”: Can be whatever you want it to be! (Keep in mind if you share the same listener_name as another listener, and that name is called with core:remove_listener(“listener_name”), one of those listeners will be removed, and it’d be hard to tell which would be. Use unique names!)
* “event_name”: This must be one within a set of Events that CA defines. You can view this list here. We’ll cover this list more in depth later on.
* boolean1: This is the “conditional” boolean. If it is set to true, the function to execute will execute; if it is set to false, the function will not execute.
* function: This is the “callback” function, which only runs if the conditional boolean returns as true. Can be whatever valid function you want! Note that it MUST have the format of <code>function(context) --<nowiki>[[ do stuff ]]</nowiki> end,</code>
* boolean2: This is the “persistence” boolean. If it is set to true, the listener will continue listening. If it is set to false, the listener will be removed from the game data.

=== CA Events ===
Let’s talk more in detail about the Events I mentioned.

As previously clarified, Events are predefined objects that are used exclusively in tandem with Listeners. A full list of Events, and all of their methods, and all of the interfaces, can be found [https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html here]. Let’s go over how to use this document!

At the top of the document is a long list of Events, each clickable to divert to another part of the document. Each of these Events have specific usage. It should be noted here that documentation on some events is rather light, ie. when to use certain ones versus others, but a lot can be found out by looking at vanilla scripts or other mods.

I want to start a new function after the player takes over Altdorf. After searching the term “Occu”, the event “GarrisonOccupiedEvent” is highlighted. This looks promising! After clicking, the available functions are “garrison_residence” and “character”, which seem to be the region that was occupied, and the character that led the assault, in order.

=== Conditional Coding ===
Remember “boolean1” from up above? If that is set to true/false, it’s not really effective code. We can replace that true/false with a function that returns a true/false value, and that way we can actually check the event, see if a specific thing happened in that event, and then spit out a boolean to trigger the callback function.
<code>function(context)
return context:[thing we want to check]
end,</code>
In essence, the above is the foundation for what all effective conditional functions in a listener should be. Context, in the context of listeners, is an object which contains all the data that occurred within the Event. But let’s back up. Remember on the document, we found <code>GarrisonOccupiedEvent</code>? Let’s go back to it and click it again. We see two options, as mentioned before – “garrison_residence” and “character”. As our intention is to find a specific region being occupied – Altdorf – we need to use that former path.

At this point, our WIP code looks like the following:
<code>function(context)
return context:garrison_residence()
end,</code>
For the conditional function, you always want to start with “return context:”, and the next method can only be one of the methods that is accessible by that Event – which is where this document comes SO in handy. For other examples, click around the different Events listed at the top. Each “Function” underneath each Event after clicking it is a valid method for the context of that Event. The “RegionSelected” event only has access to a “region” function, which means the only valid method is to use “context:region()”. “DilemmaChoiceMadeEvent”, however, has access to “faction”, “choice”, “campaign_model”, and “dilemma”, so those four are all valid methods.

''NOTE: Yes, you have to add “()” to the end of the function’s name.''

Back to our example – you’ll see the garrison_residence has <code>GARRISON_RESIDENCE_SCRIPT_INTERFACE</code> beneath it. Looking in the “GARRISON_RESIDENCE_SCRIPT_INTERFACE”, I don’t see a “key” or “name”. Matter of fact, the most likely path is “region()”. That brings our code to…
<code>function(context)
return context:garrison_residence():region()
end,</code>
After checking the <code>REGION_SCRIPT_INTERFACE</code>, we finally see the “name” method, which allows us to fully check our context. Our line of code is finally built to:
<code>function(context)
return context:garrison_residence():region():name() == "wh_main_reikland_altdorf"
end,</code>
But that’s not all! All this does is to check if the Altdorf region is being occupied, but it says nothing about Mannfred! We’ll go back to the very beginning – find the GarrisonOccupiedEvent on the document, and return to its functions, which were garrison_residence() and character(). We want to build an “and” sentence for our conditional, so that it only triggers the function when Altdorf is occupied AND when it’s occupied by Mannfred. Let’s try to plot our trajectory a little. We should try to find a script_interface that allows us to reference an agent_subtype key, which is the cleanest and most mod-friendly way to search for Mannfred. Looking at <code>CHARACTER_SCRIPT_INTERFACE</code>, I see two functions – character_subtype() and character_subtype_key(). The latter is used to return a string – ie., it doesn’t check for a specific subtype key, but it will tell us what the characters subtype key is. We need to ''check'' for a specific subtype key, “vmp_mannfred_von_carstein”.
<code>function(context)
return context:garrison_residence():region():name() == "wh_main_reikland_altdorf" and context:character():character_subtype("vmp_mannfred_von_carstein")
end,</code>
Note here that the first line of context, that ends in “:name()”, needs to have an equal-to check because we don’t want to return the ''name'' of the region, but we want to return a value of true or false if the name of the region is equal to the string we define – “wh_main_reikland_altdorf”. We can read this as “return true if the region’s name is Altdorf, and if the character is Mannfred; else, return false.”

A strong conditional function is very important to writing good listeners, as listeners can be very performance-heavy if there are many triggering at once, and the more that are whittled away via a strong conditional, the better performance will be. Be mindful of your conditionals!

=== Callback Functions ===
At this point in the walkthrough, we have about 60% of our listener completed! It’s not bad, let’s take a quick look at what we actually have written:
<code>core:add_listener(
"MannfredOccupiesAltdorf",
"GarrisonOccupiedEvent",
function(context)
return context:garrison_residence():region():name() == "wh_main_reikland_altdorf" and context:character():character_subtype("vmp_mannfred_von_carstein")
end,
function(context)
-- code to execute
end,
boolean2
)</code>
I’d like to point out a couple quick notes. To start off – yes, your listener_name can be anything you want, as long as it’s a string. You need a comma after ''every argument'' in the command, of which there are five that are detailed way at the top – listener_name, name, conditional boolean, callback, and persistence boolean. The code above is written the way it is because that’s a common application of it, and allows it to be easily read, but realistically this can all be written on one line.

Alright, so we are on the function to execute block, known as the callback function. Here, we have much more freedom than the conditional function, as we can do whatever is needed with this block. For instance, we can have a callback function that triggers an event (like a dilemma or a message), or grants a unit/experience/ancillary, or unlocks something like a Rite or a Legendary Lord. For our instance, I want to just give Mannfred’s army a new unit and a new effect bundle.

''NOTE: For our sake, we’re going to assume the new unit and new effect bundle are already defined.''

Looking up in our commands document, I see a grant_unit_to_character to command. Checking vanilla usage, I see it takes two args – a char_lookup_str and a unit_key string. The unit_key string – which refers to the main_units_tables – is, in our situation, <code>tutorial_big_bat</code>. To find a char_lookup_str, we have to first find the character’s cqi.

''For more information on char_lookup_str and cqi:'' ''this link here.''

Thankfully for us, we can go back to where we were before and use the context of the Event to find all the info from before. Looking at the <code>CHARACTER_SCRIPT_INTERFACE</code>, we see a direct link to cqi, with the method “command_queue_index()”. For this, we define our local values as such:
<code>local char_cqi = context:character():command_queue_index()
local char_lookup_str = cm:char_lookup_str(char_cqi)</code>
With this, we find the CQI first of the character, and then apply that to find the character’s lookup string, which is the type needed for grant_unit_to_character.

Before we apply that command though, we should find the arguments we need for apply_effect_bundle_to_force(), which is our command that will give an effect bundle to Mannfred’s army. We first need our effect bundle; we’ll use <code>tutorial_free_hair</code>. The second argument is a military force CQI, and our third argument is a number of turns. We’ll make it five turns long.

To find the military force CQI, we use something similar as above. We will go from character to military force, and then find the CQI there. We can use something like the following:
<code>local mf_cqi = context:character():military_force():command_queue_index()</code>
Alright, now we have all we need to build our callback function! Let’s mush it all together real quickly.
<code>function(context)

local char_cqi = context:character():command_queue_index()
local char_lookup_str = cm:char_lookup_str(char_cqi)
local mf_cqi = context:character():military_force():command_queue_index()

cm:grant_unit_to_character(char_lookup_str, "tutorial_big_bat")
cm:apply_effect_bundle_to_force("tutorial_free_hair", mf_cqi, 5)

end,</code>
And that’s a quick walkthrough on how to assemble your callback function! Please note, you can have whatever you want here, and there’s nothing saying you ''must'' restrict yourself to the context of the event. As an example, I can do the same thing without context, like so:
<code>function(context)

local mannfred_faction = cm:get_faction("wh_main_vmp_vampire_counts")
local mannfred = mannfred_faction:faction_leader()

local char_cqi = mannfred:cqi()
local char_lookup_str = cm:char_lookup_str(char_cqi)
local mf_cqi = mannfred:military_force():command_queue_index()

cm:grant_unit_to_character(char_lookup_str, "tutorial_big_bat")
cm:apply_effect_bundle_to_force("tutorial_free_hair", mf_cqi, 5)

end,</code>
This takes a little bit longer than using context, but it is a solution to applying commands to objects that aren’t involved in the context. So if, for example, you wanted to give all Vampire factions – aside from Mannfred’s own – an <code>effect_bundle</code> that increases their diplomatic relations with Mannfred after he conquers Altdorf, you can. The world is your oyster when it comes to listeners.

=== Persistence ===
One last thing, and it’s gonna be much quicker than the last two. The final boolean – persistence – can be set to true, or false. True means that the listener will fire more than once; false means that, once the entire code is run through, the listener is removed from the game state and won’t be called again. This only gives two options – once, or infinite. There is a third option, by using core:remove_listener(“listener_name”). At whichever point this code is called, the listener with the matching “listener_name” is removed from the game state, and won’t be called again. A remove_listener statement like this can be used after enabling a counter that listens for the listener firing five times, or to cancel the listener if the turn is beyond 100, or much else.

Keep in mind that, to “fire”, only the conditional needs to return true. If there’s more if statements in your callback function, and they fail, but your persistence is set to false, the listener will remove itself.
<code>core:add_listener(
"my_listener",
"GarrisonOccupiedEvent",
true,
function(context)
if this_is_done then
--stuff happens
end;
end,
false
)</code>
So this listener will cancel after one use if “GarrisonOccupiedEvent” is triggered, regardless of whether or not “this is done” returns as true or false.

=== Summary ===
Overall, there’s a lot of power to understanding these big three, and it takes your Lua knowledge from “adding and multiplying numbers” to “affecting the game in a real, and personable way”. Make sure this stuff is good and mastered, and if you ever find confusion, come back and reread this stuff.

[[Category:Lua Tutorials]]

Lua:Functions, Arguments & Parameters (Also Returns)

2024-03-11T19:26:51Z

Grimmys: Add LUA tutorial category

Welcome back! On today’s lesson, we’re going to cover one of the most fundamental types in Lua much further, and that type is, if you can read, ''functions''. Everybody loves functions.

Functions are a special data type in Lua. Functions have two specific stages: definition, and call. A function can be defined as many times as one would like, but it will not do anything until the function is ''called''. Quick look, followed by a breakdown:
<code>-- DEFINE the function, which we can call and trigger later on, as much as we'd like
function example_function()
out("This is your example function") -- at this point, nothing is output
end

-- actually calling the function to trigger the out!
example_function() → This is your example function</code>
And that’s the basics of it! We should note that in this example, <code>example_function</code> is actually a variable name. The above is syntactic sugar for the following:
<code>example_function = function()
out("This is your example function")
end</code>
But the other way is a lot more common, and probably prettier for all eyes. On the case of syntactic sugar, you can simply put the keyword <code>local</code> prior to the keyword <code>function</code>, and it will make it a local variable. I’ll be doing that from now on, to beat that idea in your own head.

Since the name of a function is just a variable, it can be redefined, and even as a different type. If a variable is defined more than once, the latest definition will “win”.
<code>local function example_function()
out("This is your example function")
end

example_function = 10 -- Why would ANYONE do this?!

example_function() → attempt to call global `example_function`, a number value</code>
The term “call” here is what I mentioned earlier – the ''call'' phase of a function. A call to a function is triggered by those two brackets – <code>()</code>.

At this point, we have a function that prints the same text over and over again. Let’s give it some way to change the text based on some dynamism!
<code>local function example_function(text)
out(text)
end

example_function("Testing") → Testing
example_function("Example!") → Example!</code>
The term “text” is a <code>local variable</code> for that function, available in the entirety of that function’s scope. It goes “out of scope” (as the cool kids say) by the <code>end</code> keyword. This is another clever shorthand that the Lua languages gives to us. Use it!

A clarity-for-clarity’s-sake note here: in the above example, “text” is a ''parameter'', which is the fancy word for a local variable assigned to the function’s scope. The string “Testing”, or the string “Example!”, are ''arguments'', which is a variable or value that is “passed” into the function and takes the place of the parameter at runtime. We can think of a parameter as a “fill-in-the-blank” space on an entry form, and the argument as whatever we fill in there.

One final thing we should know about before we go on is ''return values''. In the above, we’re just passing stuff ''into'' a function. But what if I want to take stuff ''out'' of a function? Well, return values, of course!

The keyword <code>return</code> is neat, and two-fold. Its first, and primary purpose, is to take whatever is to the right of it and shoot it back out, if the function is called. Its second, and still very-important, purpose is to stop the function once the keyword is called. Let’s take a look at a common example of return values:
<code>local function double(num)
-- if the parameter is not a number type, then output some text and then STOP the function, to prevent it from going on
if not is_number(num) then
out("double() called, but you didn't supply a number! Aborting function!")
return
end

-- if the parameter is a number type, then double it and return it! (we can safely assume that "num" IS a number, because otherwise the function wouldn't go this far)
local val = num * 2
return val
end

local a = 2
out(a) → 2

-- define a local variable as the RESULT of "double(a)"
local b = double(a)
out(b) → 4</code>
You can return any type, and you can even return multiple values at once. Say you wanted to take the above function, but instead of just doubling the number, you ''also'' tripled it, and wanted to get both values.
<code>local function double_and_triple(num)
-- if the parameter is not a number type, then output some text and then STOP the function, to prevent it from going on
if not is_number(num) then
out("double_and_triple() called, but you didn't supply a number! Aborting function!")
return
end

local double = num * 2
local triple = num * 3

-- this is it, just separate the return values or variables with a comma!
return double, triple
end

local number = 5

local d, t = double_and_triple(number)
out(d) → 10
out(t) → 15</code>
I’d like to point out that I’m changing the names of my variables to point out that ''the name of parameters can be whatever you want''. Don’t be confused by me defining the function as <code>local function double_and_triple(num)</code> and calling it using <code>double_and_triple(number)</code>. <code>num</code> is a local variable, available only in the SCOPE of the function, whereas <code>number</code> is a ''different'' local variable, available to a higher scope but below the function definition.

At this point, we’ve got all the background knowledge really needed to start doing some more cool stuff! In the next lesson, we’ll learn more about script interfaces, we’ll go in-depth about listeners, and we’ll talk about commands and how to check for existing ones! You probably don’t know what any of those three things mean, but basically, ''this is where you start doing stuff in-game''.

==== Challenge ====
Define a function for each of the following:

* Takes two numerical parameters, adds them together, and prints the result, with error-checking in case the parameters supplied aren’t numbers
* Takes one string parameter, and concatenates it with a defined string variable ''within'' the function’s scope
* Takes three parameters of any type, and attaches them to a table at indexes 1, 2, 3, and returns that table

[[Category:Lua Tutorials]]

Lua:Tables & Loops

2024-03-11T19:26:20Z

Grimmys: Add LUA tutorial category

Alright, here we go – tables, and loops. We’ve covered tables in a good depth so far, but this should get you to full comfort. We’ll also talk about loops, and iterating through tables, and using maps. It’ll be cool. Let’s start with arrays and looping.

==== Arrays and Looping ====
Arrays, for those who don’t recall, are tables with incremental indexes starting at <code>1</code>. Lua automatically assigns values to an index, not the Lua-author. An example would be:
<code>local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1</code>
Arrays are always numbered incrementally. It’s easy enough to assign new values to existing arrays – and, after all, that’s 90% of their usefulness.
<code>local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1

out(example_array[6]) → nil -- doesn't exist!

example_array[6] = 20
out(example_array[6]) → 20</code>
Say you don’t know how many indexes there currently are in an array; say you’ve edited it a bunch of times, and there’s no easy way to read how many indexes there are (which is the norm). You can add on to the end of an array using the following:
<code>local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1

out(example_array[6]) → nil -- doesn't exist!

-- some stuff that randomizes the array, woo hoo

example_array[#example_array + 1] = 20 -- #example_array would be the current number of indexes; +1 is incrementing it, assigning '20' to an unused index
out(example_array[#example_array]) = 20 -- now #example_array is one higher than the previous statement, due to the assignment of '20'!</code>
Remember that the # operator returns the ''number of indexes in that array'', and that it ''should not be used with maps''.

With that remembered, let’s look at a loop!
<code>local example_array = {5, 4, 3, 2, 1}

for i = 1, #example_array do
out(example_array[i]) → 5, 4, 3, 2, 1
end</code>
And that’s really it! The keyword <code>for</code> is hyper important, and allows us to loop over various indexes in an array. <code>for</code> defines a local variable – in this case, <code>i</code>, though it can be WHATEVER – to a minimum value, and a maximum value. In this instance, the minimum value of <code>i</code> is ''1'', while the maximum value of <code>i</code> is ''5''. And then, it runs the <code>for</code> chunk ''once for each value of <code>i</code>''. That means, it runs <code>out(example_array[i])</code> once with i == 1, then once with i == 2, with i == 3, i == 4, and i == 5.

Loops for arrays like this are super useful, as I’ve hinted at. But how does this matter for Total War, you might be asking? Well, look no further! List interfaces!

Remember the script interface chapter, we saw something called a <code>CHARACTER_LIST_SCRIPT_INTERFACE</code>? List interfaces are common, and they’re a cool type of array that we can kinda use just like the above one, but differently. Since it’s an ''object'', not just an ''array'', we have to do a couple of different things. I’ll show you, then we’ll talk, kay?
<code>local faction_name = cm:get_local_faction()
local faction = cm:get_faction(faction_name)

local character_list = faction:character_list()
for i = 0, character_list:num_items() - 1 do
local character = character_list:item_at(i)
-- check stuff about the character
end</code>
There are THREE important distinctions to make here.

First off – the ''minimum'' is <code>0</code>, NOT <code>1</code>, and the maximum has to be the ''number of items in that list minus one''. That’s because these lists are defined in C++, where indexes start at 0, unlike Lua where indexes start at 1.

Secondly – the maximum can’t be defined as <code>#character_list</code>, because it’s not an array! <code>character_list:num_items()</code> returns the total number of items in that array, and there’s a <code>num_items()</code> method for every list interface.

Thirdly – you can’t use <code>character_list[i]</code> to read the index. IT’S NOT AN ARRAY! <code>character_list:item_at(i)</code> grabs the item at the index in the array; there’s an <code>item_at()</code> method for every list interface.

Arrays are really common in the CA script interfaces, and having a healthy grasp of them will allow you to do much more with your scripts.

==== Maps and Looping ====
While maps aren’t used in CA script interfaces, like arrays kinda are, they’re still really vital and can allow some super ease of scripting.

Reminder for what maps are: they’re tables ''with user-defined indexes''.

<code>local example_map = {
["first"] = 1,
["second"] = 5,
["third"] = 10
}

out(example_map["first"]) → 1</code>
Looping in maps is pretty similar to arrays, though you have to define ''two'' local variables, instead of just one.

<code>local example_map = {
["first"] = 1,
["second"] = 5,
["third"] = 10
}

for key, value in pairs(example_map) do
out(value) → 1, 5, 10
end</code>
As before, we define the local variables with <code>for</code>. Those local variables are <code>key</code> and <code>value</code> – though, just like <code>i</code> in the above example, those variables can be named whatever you’d like. Using <code>key</code> and <code>value</code> is simply convention, same with <code>i</code>.

Using the keyword <code>in</code> is syntax here, it’s necessary between the two variables, and the pairs() function call. The function <code>pairs</code> basically defines that you want to iterate through the table (provided as a parameter to <code>pairs</code>). It doesn’t require understanding – just know that, to iterate through a map, use the above.

Now, where’s the usefulness? There’s a LOAD.

For one, a map loop is ''quicker'' than an array loop, and easier to write using Excel
<code>-- you
local lame_units = {"wh_dlc02_vmp_cav_blood_knights_0", "wh_dlc04_vmp_veh_corpse_cart_0", "wh_dlc04_vmp_veh_corpse_cart_1", "wh_dlc04_vmp_veh_corpse_cart_2", "wh_main_vmp_inf_crypt_ghouls", "wh_main_vmp_mon_crypt_horrors", "wh_main_vmp_mon_vargheists", "wh_main_vmp_mon_varghulf", "wh_main_vmp_mon_varghulf"}

for i = 1, #lame_units do
cm:add_event_restricted_unit_record_for_faction(lame_units[i], "wh2_dlc11_vmp_the_barrow_legion")
end

-- the guy she told you not to worry about
local kill_units = {
["wh_dlc02_vmp_cav_blood_knights_0"] = true,
["wh_dlc04_vmp_veh_corpse_cart_0"] = true,
["wh_dlc04_vmp_veh_corpse_cart_1"] = true,
["wh_dlc04_vmp_veh_corpse_cart_2"] = true,
["wh_main_vmp_inf_crypt_ghouls"] = true,
["wh_main_vmp_mon_crypt_horrors"] = true,
["wh_main_vmp_mon_vargheists"] = true,
["wh_main_vmp_mon_varghulf"] = true,
["wh_main_vmp_veh_black_coach"] = true
}

for unit, _ in pairs(kill_units) do
cm:add_event_restricted_unit_record_for_faction(unit, "wh2_dlc11_vmp_the_barrow_legion")
end</code>
For another, it allows you to iterate through a ''lot'' of data at once, with real ease. (the following is a further example from the Return of the Lichemaster mod!)

<code>local subtypes = {
["AK_hobo_nameless"] = {
["forename"] = "names_name_666777891",
["family_name"] = "names_name_666777892",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_nameless",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_nameless"
},
["AK_hobo_draesca"] = {
["forename"] = "names_name_666777893",
["family_name"] = "names_name_666777894",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_draesca",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_draesca",
["ancillary1"] = "AK_hobo_draesca_helmet"
},
["AK_hobo_priestess"] = {
["forename"] = "names_name_666777895",
["family_name"] = "names_name_666777896",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_priestess",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_priestess",
["ancillary1"] = "AK_hobo_priestess_trickster",
["ancillary2"] = "AK_hobo_priestess_charms"
}
}

for key, subtype_data in pairs(subtypes) do
cm:spawn_character_to_pool(
"wh2_dlc11_vmp_the_barrow_legion",
subtype_data.forename,
subtype_data.family_name,
subtype_data.clan_name,
subtype_data.other_name,
subtype_data.age,
subtype_data.is_male,
subtype_data.agent_type,
subtype_data.agent_subtype,
subtype_data.is_immortal,
subtype_data.art_set_id
)
end</code>
Yep! You can have tables within tables, maps within maps, loops within loops.

And yes, you can access an index using <code>table.index_key</code>, if that index is a ''string''. You obviously can’t do that with a number. That syntax is really common – using <code>table["index_key"]</code> to define an index’s value, and then accessing that using <code>table.index_key</code>, though you can use them interchangeably; they’re literally the exact same thing, no functional difference.

==== Other Loops ====
There are a couple other ways to loop, that don’t involve tables.

The most common other one – especially in the Total War context – is a <code>while</code> loop. For instance, we can see the following example in the wh_main_chs_chaos_start.lua file:
<code>local x = desired_spawn_point[1]
local y = desired_spawn_point[2]
local valid = false

while not valid do
if is_valid_spawn_point(x, y) then
valid = true
else
x = x + 1
y = y + 1
end
end</code>
In this instance, the <code>while</code> chunk is run once entirely through, continuously, until “not valid” returns ''false'' – aka, until <code>valid</code> is <code>true</code>.

Don’t be frivolous with your use of <code>while</code> loops – they should last no more than, like, 0.05s. Using them causes the rest of the Lua environment to come to a screeching halt, as basically nothing else can happen during a while loop.

Similarly, you can use a <code>repeat</code> loop, which is the same functionally – runs until a condition is met – except a <code>repeat</code> loop will always run AT LEAST once, whereas a <code>while</code> loop won’t run at all if the condition isn’t met. Let’s spy another CA example, this time in wh2_dlc11_treasure_maps.lua:
<code>repeat
random_number = cm:random_number(#level)
ancillary = level[random_number]
until(context:faction():ancillary_exists(ancillary) == false)</code>
Which is loud-person talk for “go through random numbers until we find an ancillary in this array which doesn’t exist in this faction”.

Again, repeat is pretty performance-heavy, as it holds up basically everything else. Don’t do big repeat loops, please. Please. PLEASE.

Or, do. I don’t really care.

==== CA Loops and Timing ====
There are some CA-defined methods to do a repeated function, or to delay a function, which do ''not'' hold up the entire environment like the above two loops. These callbacks are super helpful for repeated constant operation; for instance, I used a repeat_callback recently to print out the camera coordinates every half a second, so I could work on a custom cutscene. There was absolutely no performance drop, because Lua is beautiful.

The two types are ''callback'' and, spoiler alert, ''repeat_callback''. The former simply delays a function by a time; the latter delays a function by that time, and repeats that same delay and function over and over again.
<code>cm:callback(function()
-- run this chunk ONCE after five seconds
end,
5)

cm:repeat_callback(function()
-- run this chunk every five seconds
end,
5)</code>
For the campaign manager, these two functions are wrapped and the final parameter is in ''seconds''. However, for battle and frontend, these would be milliseconds.

<code>-- BATTLE
bm:callback(function()
-- run this chunk ONCE after five seconds
end,
5000)

bm:repeat_callback(function()
-- run this chunk every five seconds
end,
5000)

-- FRONTEND
local timer_obj = get_tm()
timer_obj:callback(function()
-- run this chunk ONCE after five seconds
end,
5000)

timer_obj:repeat_callback(function()
-- run this chunk every five seconds
end,
5000)</code>
There are lots of uses for these; namely, waiting for some UI to load, putting a timer on a quest battle for deployments, disabling/reenabling event feeds of a certain type, cutscene timing, and much else!

[[Category:Lua Tutorials]]

Lua:Scopes & Stuff

2024-03-11T19:25:43Z

Grimmys: Add LUA tutorial category

A super important concept in Lua is the concept of ''scope''. Every single variable made has a ''scope'', which is used to define where a variable can be accessed.

By default, all variables are <code>global</code>, which means they’re in the entire global environment. The global environment is a slightly-fancy way of saying “available within the entire program”. When writing Total War scripts, it’s a little suboptimal to use global variables, for a few reasons – 1) What if someone else wants to use a variable named <code>a</code>, and you do as well? This would force you to have a fully unique name for every single variable everywhere. Kinda a pain! 2) Saving that variable globally is taking up memory, since that variable will never be destroyed. It will take a lot of work to actually cause performance issues, but it’s good to be mindful of. 3) What if we want our variable to be a secret? Huh? They can’t get our birthday present! ''gollum''

And all this is where the keyword <code>local</code> comes in. The <code>local</code> keyword defines a specific scope for a variable, and prevents them from being a global variable.
<code>function example()
local var = "Hello World!"
out(var)
end

example() → Hello World!
out(var) → nil -- the variable "var" doesn't exist here!</code>
In this example, the variable <code>var</code> is defined within the function <code>example</code>‘s definition. That means that <code>var</code> is only available from ''where it is defined'' (ie. local var =) to ''where the scope ends''. In this case, the scope ''ends'' at the <code>end</code> keyword.

This is as good a time as any to look at the other ways scope can be defined. A variable can be scoped to the ''root'' of a script, or any number of nestled scopes within that root.

Other key-words other than <code>function</code> that define a scope (and their end point) are as follows:

* do –<nowiki>[[ the scope ]]</nowiki> end
* function function_name() –<nowiki>[[ the scope ]]</nowiki> end
* if –<nowiki>[[ whatever ]]</nowiki> then –<nowiki>[[ the scope ]]</nowiki> end
* while –<nowiki>[[ whatever ]]</nowiki> then –<nowiki>[[ the scope ]]</nowiki> end

Let’s take a slightly-complicated look at that:
<code>local a = 5 -- visible to everything BELOW this line!

function example_thing()
local b = a -- visible to everything BELOW this line, until the "end" that matches "function"
do
local c = 15 -- visible to everything BELOW this line, until the "end" that matches "do"
out(c) → 15
out(b) → 5
end
out(b) → 5
-- c is NOT available here!
end

-- b and c are NOT available here!
out(a) → 5</code>
This is a good point as any to explain two things, and issue two directives:

# ALWAYS use the keyword <code>local</code>.
# ALWAYS use good indentations! Scopes should be easily detected.

Be smart with where exactly the term “local” is used – you’ll pick up how later on as you go and pick my brain, but for now, understand that you must ALWAYS put the keyword <code>local</code> before a variable!

As you can see with the example_thing() function above, proper indentation is a GREAT way to visibly see scopes and quickly tell where a variable is and isn’t available.

[[Category:Lua Tutorials]]

Lua:Expressions & Operators

2024-03-11T19:25:06Z

Grimmys: Add LUA tutorial category

As we’ve seen, Lua is made up of <code>chunks</code> and <code>statements</code>. Statements can contain variables, and all variables have a type, though it can change at any point.

Expressions are the section of a statement that, essentially, tell Lua ''what to do''. They come in a billion different shapes and sizes. For now, we’ll cover all the basics you’ll need, and some basics you really don’t need but I’ll hand it to you anyway, and we’ll go back and review some older stuff. Here we go!

==== Math Operators ====
Sweet. This is what all of those quizzes in grade school trained you for. We have the big four from algebra – addition, subtraction, multiplication, and division.
<code>out(2 + 3) → 5
out(5 - 1) → 4
out(16 * 3) → 48
out(9 / 3) → 3</code>
We can also use a <code>-</code> to ''negate'' a value, or, in simple terms, turn a positive number into a negative and vice versa.
<code>a = 10
b = -20
out( -a ) → -10
out( -b ) → 20</code>
We also have a couple other fun math things. We can raise numbers to any power, using an exponential expression.
<code>a = 2
b = 4
c = 3
out( a^a ) → 4
out( b^c ) → 64
out( 64^0.5 ) → 8 -- getting the square root of a number!</code>
We can also use some modulo math. It’s a way of dividing two numbers that gives you the amount ''remaining'', and it’s a great way to read if a number is a ''multiple'' of another.
<code>out(8 % 2) → 0 -- 8/2 = 4, and divides evenly, so nothing is remaining!
out(7 % 2) → 1 -- 7/2. "6/2" divides evenly, so we subtract 6 from 7, and get "1" as the remainder!
out(8 % 3) → 2 -- 8/3. "6/3" divides evenly, so we subtract 6 from 8, and get "2" as the remainder.</code>
As said, it’s a great way to read if a number is a multiple of another. If a modulo expression returns “0”, that means it divided evenly, and is therefore a multiple of the number divided by.

And that’s math!

==== Comparison Operators ====
This sounds a lot more complicated than “math”, eh? It’s not that complicated – we’re comparing how two variables relate to one another, using expressions we’ve all seen before. The list of comparison operators are as follows:

* < — “less than”
* > — “greater than”
* <= — “less than or equal to”
* >= “greater than or equal to”
* == “equal to”
* ~= “not equal to”

All of these expressions result in a boolean value, that is, it tells you if the result of what you're saying is true or false.
<code>a = 10
b = 7 + 3
out(a == b) → true -- they ARE equal!
out(a ~= b) → false -- they ARE NOT not equal (weird, I know)!

c = 8
d = 7

out(c > d) → true -- 8 is greater than 7
out(c < d) → false -- 8 is NOT less than 7</code>
It’s important to note that Lua will consider different types to be different values. A string (ie a group of characters, like the word "hello" or the character sequence "15") and a number will always be different. Lua will throw an error if you attempt to compare – using less-than or greater-than – any two separate types. Lua will not throw an error for “==” and “~=”, and if they are separate types, they will always be inequal.
<code>a = 15
b = "15"
out(a == b) → false -- they are different types!
out(a >= b) → error (attempt to compare number with string)</code>
Do note that you can compare strings using greater or less than, but it compares the alphanumerical order of the first character. “0” is less than every number or letter, whereas “a” is greater than every number and less than every letter, and “z” is greater than every number or letter. Again, not really important, but you came here to read me ramble on about random stuff.

And that ends our comparison operators!

==== Logical Operators ====
Next up are our logical operators! We have three operators to concern ourselves with here: ''and'', ''or'', and ''not''.

''Not'', as a logical operator, is pretty simple and super handy. It basically converts the value to the right of it into a boolean, and reverses it. Any value other than <code>nil</code> or <code>false</code> will be converted into <code>false</code>; <code>nil</code> or <code>false</code> will be converted to <code>true</code>. Let’s take a look:
<code>a = true
b = nil
out(not b) → true -- prints a double negative - not false, so true
out(not a) → false -- reverses the value of "true"

c = 100
out(c) → 100
out(not not c) → true -- c is a number, "not c" would become "false", and "not false" would become "true"</code>
The operators ''and'' and ''or'' are the hearts of a lot of logic in Lua. “If this and this, then do this”.
<code>a = 15
b = false
if a == 15 and not b then -- "if a is equal to the number fifteen, and "not b" returns true, then ... "
out("It does the thing!") -- " ... print the text! "
end</code>
You’ll practically always see these two used in this way, for ''conditional statements'' like that – if these conditions work out, then do this other thing.

==== Homeless Operators ====
I don’t really have a category for these two operators, but they’re incredibly important.

First off, we have concatenation, which we’ve seen before. It’s a way to add two strings of characters together, and make them into one happy family, using a simple pair of dots.
<code>a = "Hello"
b = "World!"
out(a .. " " .. b) → Hello World!</code>
A couple of notes real quick – I have the blank space in a string in the middle, to make sure it doesn’t print “HelloWorld!”. Also, I like to add spaces on either side of my concatenation operator, but that’s personal taste, this would also be valid:
<code>out(a.." "..b) → Hello World!</code>
And lastly, we have one more operator, and this time for the table type. The character <code>#</code> can be used to read the number of entries within an array (NOTE: an array is a set of different elements under one variable name).
It’s pretty awesome, let me show you:
<code>table = {"this", "is", "an", "example", "array"}
out(#table) → 5 -- there are five strings within the table!</code>
Please note that you really shouldn’t use the <code>#</code> operator if the table is not definitely an array. I’ll show you why using it on maps might mess something up:
<code>table = {
[1] = "test",
[2] = "example",
[5] = "boom",
[7000] = "woo",
[3] = "argh"
}

out(#table) → 7000</code>
In technicalities, it’s doing that because it’s reading the ''highest index in that table'', or the highest numerical key. Those are assigned automatically, in order, for arrays; in maps, there’s no such guarantee.

==== Challenge 1 ====
As before, go to repl.it and mess with everything.

Some suggestions on what to try:

* Make an array out of various strings, concatenate them together using <code>table[1]</code> and so on.
* Apply arithmetic to a series of 3 or more numbers
* Compare the length of two separate tables

[[Category:Lua Tutorials]]

Lua:Variables & Types

2024-03-11T19:23:58Z

Grimmys: Add LUA tutorial category

''NOTE: I recommend you have the Devtool Console handy to mess around with some of the stuff covered here.''

Following the concept of chunks and statements, the next most important subject to cover is variables, and types.

Variable: A custom-made keyword that can be used to represent a value

Type: The sort of value that is in a variable. Lua types include: boolean, string, number, table, nil, function. There are more, but we won’t need them.

But before going deeper into a definition, let’s look at an example:
<code>a = 10
b = 5
c = a + b</code>
We can see that each of those letters in the chunk above is a variable, which are each assigned a value. In this case, variable <code>a</code> is assigned the value <code>10</code>, variable <code>b</code> is assigned the value <code>5</code>, and the variable <code>c</code> is assigned the <code>value of a plus the value of b</code>. This instance (c = a + b) works a lot like algebra – you aren’t making “c = ab”, but you’re adding the value of a (10) to the value of b (5), to get the result of 15.

The coolest thing about variables is their dynamism. They can be assigned to any type, change to any type, and they can infinitely change values. Let’s take the above code, and mess with it a little bit.

''NOTE: From this point on, you’ll see → after out() calls. This is to specify what text is actually output.''
<code>a = 10
b = 5
c = a + b

out(a) → 10
out(b) → 5
out(c) → 15

a = 25
out(a) → 25

out(c) → 15

c = a + b
out(c) → 30</code>
I wanted to point out an important thing with this example. If a variable is assigned to the values of some other variables (c = a + b), it will do the calculation and assignment the moment that the statement is called. If either variable (a or b) is changed after the assignment statement, the assigned variable’s (c) value (15) won’t change. It takes the ''variable’s value'', not the ''variable itself''.

So, we see here that variables can be numbers, which is one of the primary types in Lua.

Number: ''any'' numerical value, within a specific number range (a much bigger number than needs to be worried about)

As we saw above, we can perform some basic arithmetic on numbers.
<code>a = 5
b = 2 - 0.34
c = a + b
d = c * 2
e = d / 3

out(c) → 7.56
out(d) → 15.12
out(e) → 5.04</code>
String: ''any'' alphanumerical value, within quotation marks (“” or ”). Similar to numbers, size ''does not matter'', Lua can handle millions of characters within a string.

Like arithmetic for numbers, one can concatenate strings (along with many other stuffs!) to combine several, using the <code>..</code> operator.
<code>a = “This “; b = “is “; c = “an “; d = “example.”
out(a .. b .. c .. d) → This is an example.</code>
''NOTE: Yes, you can have several statements on the same line in Lua! The semi-colons are not necessary, I added them for extra readability.''

While on the subject, you can concat (cool-kid for concatenate) string literals and variables.
<code>a = "example"
out("This is an " .. a) → This is an example</code>
Boolean: a <code>true</code> or <code>false</code> value.
<code>a = false
out(a) → false
out(a == false) → true</code>
The above probably looks a little weird, but that’s because we’re learning a new operator! The <code>==</code> operator checks for ''equality'', whereas the <code>=</code> operator ''assigns a value''. The final statement above reads “output the result of a == false”. Since <code>a</code> DOES equal false, it prints “true”.

It’s very important to note that any variable can be ''treated'' as a boolean, such as when using the “if something then” statement, or by comparing it to a boolean. If a non-boolean variable is treated as a boolean, it will be converted to <code>false</code> if the value is <code>nil</code> or <code>false</code>; otherwise, it will be converted to <code>true</code>.
<code>a = 0
b = nil
out(a) → 0
out(a == false) → false
out(b == false) → true</code>
In this case, <code>a</code> does NOT equal <code>false</code>, because it has a value to it that isn’t <code>false</code> or <code>nil</code>. By the same card, <code>b</code> DOES equal <code>false</code>.

You’re probably asking by now, what IS nil? I’ve mentioned it a number of times already, you’re probably ready to lear about it. Here we go!

Nil: the absence of data.

If one were to try to print a ''non-existent'' variable, the result would be <code>nil</code>. That’s because there is no data for that variable.
<code>out(a) → nil
a = 5
out(a) → 5</code>
Nil is a good way to check whether or not something exists, and we’ll, towards the bottom of this lesson, talk about how to type-check this data in our scripts to see if variables are NOT nil, and thus exist.

Nil is also a good way to clear away variables that you don’t want to use anymore. There’s a more realistic way of doing it, and this probably won’t be necessary for most of what you will be doing, but I like to give a full knowledge.
<code>a = 5
out(a) → 5
a = nil -- Memory deallocated, bye "a"!
out(a) → nil</code>
Lastly, it’s important to note that <code>nil</code> is not the same as <code>null</code>, though they look quick similar. We’ll cover that soon-ish, when we get into more CA script interfaces (like FACTION_SCRIPT_INTERFACE that we saw a few lessons ago).

Function: a definition for a chunk that can be called at any point, after being defined.

There are two types of functions – an anonymous function, and a named function. An anonymous function has no name (clearly), so it cannot be called further on in the script. We use anonymous functions relatively frequently, but our focus now will be on named functions, which are functions assigned to a variable.
<code>a = 10
example = out
example(a) → 10</code>
Yes, that’s valid! You can actually assign a variable to a function like, it’s pretty cool! We have syntactic sugar for assigning a variable to a function, however, and it’s more common to see script like that:
<code>function example(text)
out(text)
end

example("Testing!") → Testing!

example("A Cooler Test!") → A Cooler Test!</code>
As an added bonus, we’re getting a quick sneak peak at one of the upcoming tutorials: parameters and arguments, for functions. In the above function, “text” is a parameter for <code>example()</code>, which is then passed along to <code>out</code> and triggers that function within the chunk.

Table: a collection of more than one piece of data.

There are several types of tables, which we’ll cover later on. I’d like to first look at the ''array'' version of tables, the simplest and most common.
<code>a = 5
b = 10
c = 17

table = {
a,
b,
c
} -- assign the three *values* of the variables to the table

out(table[1]) → 5 -- Lua tables start at index 1: we're showing the first element of our table, that is, the item on index 1!
out(table[2]) → 10
out(table[3]) → 17
out(table[4]) → nil -- doesn't exist!</code>
''NOTE for programmers:'' ''Arrays in Lua start at index ONE, not index ZERO. <code>table[0]</code> would be invalid in the above example! If you get into other programming languages, you'll understand why explaining this was important.''

Arrays are numbered automatically, so it really reads “the first index of table is 5, the second index of table is 10”, and so on. You ''access'' those indexes by using the <code>[num\]</code> operator, which we’ll look further at in the next tables tutorial later on. The reason this works, however, is because Lua is automatically numbering these values, giving them a ''key''. When you make an array like that, Lua reads it more like the following:
<code>a = 5
b = 10
c = 17

table = {
[1] = a,
[2] = b,
[3] = c
}</code>
The other major type of tables is a map, which works by manually assigning the key of a value instead of letting Lua automatically number them, like in arrays.
<code>a = 5
b = 10
c = 15

table = {
["five"] = a,
["ten"] = b,
["fifteen"] = c
}

out(table["five"]) → 5
out(table["ten"]) → 10
out(table["fifteen"]) → 15</code>

Maps will come into some great use pretty soon, but for now I just wanted to introduce you to how they look.

For now, you’ve done well, and I haven’t even challenged you yet!

==== Challenge 1 ====
Go to repl.it (covered in the Foreword), and mess with all this stuff! Use <code>print(whatever)</code>, where whatever is what you want to print, in lieu of <code>out()</code>.

==== Type-Checking ====
And before we say goodbye, let’s look at a few more CA functions. These ones can type-check for us, seeing if a variable is, for instance, a string.

The list is as follows:

* is_nil(variable)
* is_string(variable)
* is_number(variable)
* is_boolean(variable)
* is_function(variable)
* is_table(variable)

<code>a = 5
b = nil
c = {1, 2, 3, 5, 70}
function d() end

out(is_number(a)) → true
out(is_nil(b)) → true
out(is_table(c)) → true
out(is_function(d)) → true</code>

[[Category:Lua Tutorials]]

Lua:Chunks & Statements

2024-03-11T19:23:25Z

Grimmys: Add LUA tutorial category

The first two terms we’ll look at are chunks and statements. When Lua is brought to its basic skeletal structure, that’s all it is – chunks of statements.

Statement: A declaration, a thing-to-be-done, a command that Lua will run Chunk: A sequence of statements, from an entire file to a single line of data

Every chunk is a to-do list, and a statement is an objective on that list. You can have to-do lists of all shapes and sizes, and each thing that needs to be done can be small – “brushing your teet” – or huge – “spend way too much money on transmission repairs”. No, I’m not still salty about the money I spent on transmission repairs, why do you ask?

The Lua interpreter divides everything it takes into specific chunks, which we’ll look at later on. For now, we understand the term chunk – a to-do list.

Within each chunk is one or more statements. A statement is one coherent thought or action within Lua. Something like this can be one statement:
<code>a = 1</code>
Or, this can be one statement:
<code>a = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 - 1 / 70 * 300 + 5180 - 418 + 405</code>
That is, one bit of data that Lua has to evaluate and run.

Remember the term “chunk” – we’ll be covering how they’re defined later on, when we look at some more keywords.

[[Category:Lua Tutorials]]

Lua:Essential Setup

2024-03-11T18:11:52Z

Grimmys: Add LUA tutorial category

Step one – we’ve gotta grab some tools!

I’ll be covering a handful of setups that I find vital for programming in Lua. First off, I’ll talk about a pretty well-known product – Notepad++. I personally no longer use it, and at this point prefer Visual Studio Code for all my Lua needs, but I’ll go over both for taste. They’ll both be able to do what you need.

This tutorial assumes you already have RPFM downloaded. If you don’t yet, go grab it.

==== Notepad++ Setup ====
One of the most well-known text editing products out there is Notepad++. As the name implies, it’s kinda like regular Notepad, but actually good and can do stuff. It has features like global searching, opening a folder and viewing the contents as a tree-view, and is all around a pretty solid product.

I’ve never used Notepad++ for actually writing and editing .lua files – it was for a while primarily what I used to search through and read CA .lua files. I now use VSCode for both of those efforts – editing and searching through files – but many people prefer to use Notepad++ so here I am discussing it.

If interested, grab Notepad++. Download it, install it wherever.

While you wait for Notepad++ to finish installing, we’re gonna make a script dump – a location on your PC where you put all of CA’s scripts, so you can quickly reference them. You should open RPFM, and use the <code>"Open All CA Packs"</code> command (after making sure you have the proper game selected, under, well, Game Selected).

Now, go find a spot to create a script dump folder. You’ll need to grab all CA’s vanilla scripts and put them somewhere on your PC – I recommend an HDD, if you have two drives! – in order to easily browse through their files. Once you have one created and pinned and you know where it is (mine is S:/Total War Dumps/Script Dumps), go back to RPFM, and go find the main “script” directory. Right-click it and select “Extract”, and target the new folder you just made.

And, boom! You now have a script dump. I personally organize it as follows:

<code>S:/Total War Dumps/Script Dumps/WH2/%today's date or patch name%/script</code>. I’ll use /3K/ or else for whatever game I’m using. This helps me quickly keep track of older patches, when I need to compare files between versions.

Lastly, open up Notepad++, and use <code>"File -> Open Folder As Workspace..."</code>. Target your renamed “script” folder within the script dump directory, and you’ll notice that the directory appears on the left-hand side. If you right-click the main folder over there, and press <code>"Find in Files..."</code>, you’ll be able to global-search all CA scripts. Incredibly handy for looking at their usage of commands, or to see any references to, say, an agent subtype key.

And that’s Notepad++! You can make scripts in there as well, using “File -> New” and naming it “whatever_you_want.lua” when saving. Though, I personally prefer using Visual Studio Code for programming in Lua (and it’s what I’m typing this tutorial in), and that’s where I have my IDE setup. If you’re interested in VSCode, continue reading, if not carry on to the Hello World tutorial!

==== Visual Studio Code Setup ====
Clearly, one needs Visual Studio Code. Go get Visual Studio Code.

You got it? No? Why are you reading this?

Okay, now you’re ready? Good.

Visual Studio Code (VSC or VSCode, also) is a super nice program in my opinion, and a nice big brother to Notepad++. It has a lot of extra functionality that NP++ does not, and allows a lot of flexibility in that regard. VSC has greater tab support and multi-window support, it’s easier to use Workspaces in VSC (again in my opinion) than in NP++, and the extensions and further features and settings add a lot that helps me with my programming.

You can save “code workspace” files, which allow you to easily access several folders or files that you have saved for one project, as well as have different settings for different workspaces. I can jump really easily between, say, my Return of the Lichemaster code workspace, my CA Script Dump workspace, and my Other Currently Secret Things code workspace, with only a couple clicks. It has a really pretty dark mode, and the syntax highlighting for Lua is gorgeous, in my opinion.

You can save “code workspace” files, which allow you to easily access several folders or files that you have saved for one project, as well as have different settings for different workspaces. I can jump really easily between, say, my Return of the Lichemaster code workspace, my CA Script Dump workspace, and my Other Currently Secret Things code workspace, with only a couple clicks. It has a really pretty dark mode, and the syntax highlighting for Lua is gorgeous, in my opinion.

To use VSCode to its fullest, I suggest solid integration within your RPFM MyMod folder. In my MyMod folder, I have a folder for each of the mods, and then the .pack that RPFM tracks and saves, and also a .code_workspace for each important workspace. I can use <code>File -> Open Workspace...</code> for each of those files, or simply use <code>File -> Open Folder...</code> to directly open the MyMod folder. I use the Workspaces so I can hide files in each of the folders, depending on the mod – I don’t need to see the /db/ folder in VSC, for instance.

Within VSCode now, you can create new folders, open extras, and all, and it will be within the same code workspace!

And that’s it, VSCode is really simple to use (for our application atm). I recommend at this point downloading the <code>vscode-lua</code> extension, which enables some error logging within VSC (for when you forget some syntax or add an extra comma) and enables coloring and other fun stuff. Link to extension here.

[[Category:Lua Tutorials]]

Lua:Main Page

2024-03-11T18:02:26Z

Grimmys:

Howdy, internet stranger, and welcome. My name’s Vandy, and I’ll be guiding you through this new chapter of your life. This section of the Total War Modding Resources is dedicated to the learning and appreciation of the Lua language.

==== What Is Lua? ====
One of the primary types of modding, in Total War, is the use of the programming language <code>Lua</code>. In case you were wondering, Lua is Portugese for ‘moon’, and the dude who made the language was born in 1960, and at the time of this writing the language is only 26 years old.

Using Lua, you can establish chains of events, create flexibility on when units can be recruited or when lords are spawned, and you can set up new quest battles. The entire Chaos Invasion mechanic from WH2 is scripted; from 3K, the randomly-spawned ancillaries from master-craftsmen buildings are scripted.

Unlike db entries, which are compiled during the initial loading screen of the game and turned into engine data, and are often static with few exceptions, Lua is a dynamic energy within the game, and is the only direct way to access a multitude of game features, background data, and more.

==== From Poop To OOP ====
From here to the end of this series, the goal is to get you from writing poop – or, in some of your cases, absolutely nothing – to writing in OOP, like a true-blooded programmer, though that’s by no means necessary and you can stop any time prior to that.

To begin, I’m going to take you on a quick field-trip as we download some new software that will help us write better code using smart programs, and we’ll talk about some really easy ways to test Lua code.

After that, our next journey is through the Lua basics. We’ll learn about strings, and booleans, and functions, and tables, and loops, and return values. All of the basic details of the knowledge that are necessary for even the simplest scripts.

Next, we turn to Total War specifics. There are some concepts that we need to cover while writing Lua in Total War, such as events, interfaces, when to call your scripts, stuff like that.

Towards the end, I’ll progress from simple scripting to some more high-minded scripting, using what the biz refers to as “Object-Oriented Programming”. It’s a more advanced topic that won’t do well being talked about here, but getting a firm grasp on it will help propel your scripting to a new level.

All throughout this series, I’ll seek to keep the information as game-agnostic as possible, I’ll seek to cover all gaps of knowledge and point out any common troubleshooting tips where necessary, and I’ll be covering these topics in the order of which I believe they should be learned. It is highly recommended you don’t skip around or skip ahead, the order of these tutorials are deliberate.

=== Order ===
[[Lua:Essential Setup]]

[[Lua:Chunks & Statements]]

[[Lua:Variables & Types]]

[[Lua:Expressions & Operators]]

[[Lua:Scopes & Stuff]]

[[Lua:Keywords]]

[[Lua:Tables & Loops]]

[[Lua:Functions, Arguments & Parameters (Also Returns)]]

[[Lua:Commands, Interfaces & Listeners]]

[[Lua:Calling Scripts]]

[[Lua:Advanced Conditionals]]

[[Lua:Debugging]]

[[Category:Lua Tutorials]]

Category:Tools & Resources

2024-03-11T16:56:08Z

Grimmys: Add more tools the list, and introduce some more formatting (italic & bold).

Every modder needs proper tools, just like every lumberjack needs a swing set. This list does not claim to be a sure-fire solution to every single issue a modder might face, nor an impervious list of perfect programs, designed to cater your every need. This list does have a lot of value in it, I believe, and if used correctly, a lot can be achieved.

You’ll also notice that this section has random housed tutorials in it, that don’t fit in any particular place with the larger-scale tutorials. The author and summary of each will be listed and maintained here!
====Kaedrin’s Mod Manager====
[https://github.com/Kaedrin/warhammer-mod-manager/releases Warhammer Mod Manager Releases] – Kaedrin’s Mod Manager is a very useful alternative mod manager that works for all Total War games since Total War: Empire.

You can get in contact with the creator, ''Kaedrin'', in the Modding Den’s channel '''#kaedrin_mod_manager'''.
====Frodo’s Rusted Pack File Manager====
[https://github.com/Frodo45127/rpfm/releases/ RPFM Releases] – RPFM is a great pack-file managing tool, essential for any modder. Active development has new features coming regularly, as well as constant bug fixes or bug squashings.

You can find its documentation here: [https://frodo45127.github.io/rpfm/ RPFM Documentation]

Get in contact with the creator, ''Frodo'', in the Modding Den’s channel '''#rpfm'''.
==== Phazer's Rigid Model Editing Tool====
[https://github.com/mr-phazer/RME_Release/releases RME Tool Releases] – A tool to quickly edit rigid models using a visual UI rather than having to use clunky hex editing.

Get in contact with the creator, ''Phazer'', in the Modding Den's channel '''#phazer_tools'''.
====Ole's Asset Editor====
[https://github.com/olekristianhomelien/TheAssetEditor/releases/ Asset Editor Releases] – A tool for kitbashing and animation splicing using vanilla assets.

Get in contact with the creator, ''Ole'', in the Modding Den's channel '''#asset_editor'''.
====Thegroovewizard's LUA Debugging Setup====
[https://github.com/chadvandy/tw_autogen Setup for debugging LUA scripts] – A setup for debugging LUA scripts in [https://code.visualstudio.com/ Visual Studio Code].

Get in contact with the creator, ''Thegroovewizard'', in the Modding Den's channel '''#groove_tower'''.
====Interactive Maps for Total War: Warhammer II====
[https://imrz.github.io/tww-interactive-map/latest/#/ Mortal Empires / Eyes of the Vortex interactive maps] – Web application for checking the position of every settlements, regions and ressources on both maps of ''Total War: Warhammer II''.
====Imagemin App (PNG Compressor)====
[https://github.com/imagemin/imagemin-app/ Imagemin App] – An application to lower the size of your mod .png, because they have to be less than 1Mb.
====Video Tutorials====
[https://www.youtube.com/watch?v=pzqTFR32tl8&feature=youtu.be Setting Up GitHub Desktop for Total War] – A rundown on how to setup GitHub Desktop for use with the Assembly Kit.
====Scripting Resources====
[https://chadvandy.github.io/tw_modding_resources/WH3/scripting_doc.html Script Doc Warhammer 3 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH2/scripting_doc.html Script Doc Warhammer 2 (Events & Interfaces)]

[https://chadvandy.github.io/tw_modding_resources/WH3/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 3 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/WH2/campaign/campaign_manager.html#class:campaign_manager Script Doc Warhammer 2 (Campaign Manager Functions)]

[https://chadvandy.github.io/tw_modding_resources/index.html Warhammer 2 & 3 CA Documentation]

[https://chadvandy.github.io/tw_modding_resources/3k/scripting_doc.html Three Kingdoms CA Documentation]
==Tools & Resource Posts:==
*[[Troubleshooting]] by Vandy and Cataph
*[[Modding Glossary]] by Vandy and Cataph
*[[Campaign Map Coordinates]] by Marthenil by Vandy

Category:Tools & Resources

2024-03-05T23:07:56Z

Grimmys: Replaced dash by wider dash for consistency

Category:Tools & Resources

2024-03-05T23:04:29Z

Grimmys: Fix resources links and add link to each tool project page