Tutorial:Submodding

Originally written by Cataph

If you’re a modder, one of the most frequent comments next to romantical proposals (YMMV) will be “SFO/Radious/CTT/Lucky/yomama compatibility when”. Many modders don’t have an interest in making a submod simply because they don’t know and play a given overhaul and wouldn’t know how to balance it anyway.

So, what if it could be you making that submod? Or maybe you just want to make X mod work better with Y. Be the submodder you want to see in the world!

A few things first.

WHAT IS A SUBMOD?

Basically, an optional plugin designed to make mod X work or work better with mod Y, thanks to this mod Z. A user that wants to use X and Y together will download mod Z and keep all three enabled.

Can a submod be a standalone? Well, yes, but it wouldn’t be a submod then, would it? Besides, it’s normally a dick move to take mod X and fully reupload it with a few differences. Plus, it’s 90% never necessary and we’re going to see why.

Ok, but can I just edit a mod and keep it to myself? Sure, keep in mind that you should rename the pack into something else to avoid automatic updates to overwrite what you changed.

WHY IS A SUBMOD?

I need you to focus.

HOW IS A SUBMOD?

Fine, thank you. About how it’s made, we don’t necessarily need mod X and Y to make sweet love to each other but only you, bloke with a basic knowledge of RPFM and TW modding.

WHAT DO?

Ok, as a basic example let’s say we want a compatibility submod between the Sea Patrol mod and a fictional 2x unit size mod, so we want to grab whatever lines define unit numbers in the former and multiply those by 2. Daring.

First thing we open the first mod as a reference, then we create a new pack for the submod. We’ll call it seapatrol_yourname_unitsize.pack.

Upon viewing the db of Sea Patrol we see a whole lotta tables.

Since I am a bloke with basic knowledge of RPFM and TW modding, I know that unit sizes are in main_units.

Thus, in the submod I’ll import said table/s by right click>Add…>Add from Packfile, find the pack, find the table and double click it. Close the add from packfile panel and we’re good to go, we have Sea Patrol’s main_units in our shizzle. We go in there and edit the numbers we want to change, in this case we select any num_men that is not a hero/lord’s, right click, apply math as {x}*2 and done. Done? No, some of those units may be cavalry, so we need to adapt the number of mounts too. We import land_units as well and do the same thing on num_mounts. In the rarer case that there’s a multi-chariot unit, we leave mounts alone and multiply num_engines in land_units.

PRIORITY

But it’s a submod, and we want to make sure we’re overriding the original mod’s values. No, not with load order on the mod manager, and incidentally you shouldn't touch that and you should use KMM.

We currently have two tables, we select those table fragments (in this case, called “AK_seahelm”) and we rename them to take priority according to this alphanumerical order:

! # $ % & ‘ ( ) + , – ; = @ 0-9 a-z [ ] ^ _ ` { } ~ Where “!” wins over “a”.

Usually, adding a “!” in front does it. But we also want to make clear what submod this is for. Right click> Rename> type !{x}_unitsize, which will become “!AK_seahelm_unitsize”.

Note: DO NOT leave the table names as is, or you’ll crash. DO NOT leave a number as last character or it might glitch and crash anyway.

Aaaand, done! Now this submod of only two tables will correctly override unit sizes for a specific mod. Yeah, any non-vanilla key will be red in here, since you don’t define those in your pack, but no worries, it’s a submod that is designed to exist with the mod that actually has those keys.

Now, like with any mod we make a PNG icon and upload if we want to share it publicly. If you upload it on the workshop, add mods X and Y as required by clicking on Add/Remove Required Items. This will prompt a user to go and fetch those required mods as well. Most of them will somehow ignore it and crash, but at least you tried.

ADDENDUM: ETIQUETTE

By most accounts, a clean submod like the above doesn’t really need permission since you’re not stealing anything. However, you should still ask as good courtesy, and it can’t hurt to still let the og author know as they may link it in description, let you know about required changes, etc.

It’s also good practice not to add donation links to a submod.

ADDENDUM: UPDATING

It should be your interest and responsibility to stay up-to-date with the original mods as soon as you have time. For example if you’re submodding a unit mod and you see the ‘parent’ mod has updated with balance changes, some key changes or new units, you should definitely hear a couple bells ringing.

Sometimes the parent mod changes a few keys and then you might even crash until you update.

ADVANCED SUBMODDING: BALANCE OVERHAULS

The submodder should also be the one who is familiar with the overhaul they’re adapting a mod for. If you are at a loss about how to tweak some things, definitely consider asking one of the two original modders (depending on the kind of question) for advice on how to proceed. For example, “this unit is weird and I’m not sure what role it should keep”.

UNIQUE NUMERICAL IDs

In some tables, each line has a unique numerical id in front of it (or sometimes way off like in unit_special_abilities). That’s specific for each line, and it works like other important keys like those in land_units or main_units, as in there can only be one line about that key or num id.

Why am I saying all this? Because if in your submod you happen to need to add some lines in, for example, building_units_allowed, you’ll need your own unique num ids to make them work proppa. Pick any number below 2 billions and something and make sure they never repeat. This is important, do not continue off the num ids from the mod you’re submodding or you’ll cause issues at some point.

ADVANCED SUBMODDING: STICKY TABLES

Some tables and related features are slightly more complicated to submod. For example, you want to remove a unit from a certain building level. Easy, go in building_units_allowed again. Remember those unique ids? Keep that exactly intact (so it still refers to that specific line from the original mod or vanilla line) and change the building to something that has no chance of being available, such as wh_main_chs_port_ruin or change the unit instead to a unit that is completely unavailble as well for anybody who has access to the given building. You could change both to be sure, but it's more confusing down the line.

Until WH2, you could have typed random gibberish in the building key to better track your changes (e.g., add "_removed" to building keys), but in WH3 that causes a crash as both fields need to be valid.

The underlying logic is that you're hijacking a precise data line (due to the unique id, numerical or not) and telling it to do something impossible.

Harder example: I really don’t want any of these units to have the new-fangled Edgelord Deluxe passive ability, which is added by this mod. Cool, that means I can kill that ability from existence without it ever affecting anything else. We do that by:

• grabbing its line from unit_abilities, we make it hidden in UI.
• grabbing its line from unit_special_abilities, we make it a passive (boolean). Make sure you remove any activated projectile/bombardment/summon etc from here too.
• grabbing its line in special_ability_to_special_ability_phase_junctions. Change the phase to a new special_ability_phase that we created and that does absolutely nothing. There, done. The ability still exists, but does nothing and is invisible. In my own private jargon this is called a pillow. Again, notice that you’re neutering this ability for any unit that happens to get it.

Even harder example: I want this unit to not have the Regeneration passive ability. Oooh, that’s a vanilla ability, isn’t it? We can’t just dumpster it. Either we tolerate it or…

ADVANCED SUBMODDING: DEPENDENCY MANAGER

This is a RPFM feature. USE WITH CAUTION. We enable it by right clicking on the packfile itself in tree view (not on a table, not on anything else, literally the very first line in tree view), Open>Open Dependency Manager. We add a line as if it was a table (ctrl+shift+A) and type EXACTLY the pack name of the mod we want to override. As in “AK_seahelm.pack”. From this point onwards, everything we do in the submod will completely override content from the parent mod no matter the load or table order for stuff with the same name. Example, I can import a table, not change its name and completely delete its content. This would normally crash, but not with DepManager. I said use this with caution because if you do this you REALLY need to stay up-to-date with the og mod. For example, you can remove the line that gives unit A the Regen passive, and it will work. However, any further update from the parent mod in that table won’t take place unless you also mirror it. Again, this is normally not remotely required and you should steer clear of it because it’s just as bad as leaving a vanilla table called “data__”.

Additionally, this will auto-enable the linked mod as soon as it’s in data/ as if it was a movie pack. As such, you don’t want to do this unless you’re doing a submod that already requires that linked mod. Because having stuff popping up even when you’ve disabled a mod is the worst.

ADVANCED SUBMODDING: BACKGROUND TABLES

Let's say we aren't doing a submod whose only purpose is changing unit size for that other mod, but it's our own standalone mod A and we're doing some compatibility stuff to make it work better with B, without needing a separate submod C that requires both. For example, we want something from B in A, if B is also enabled. Sometimes we can do that without C.

Let's say I add some new units in A, and mod B adds fancy officers to all units. Officers are connected to the unit in db/land_units, but if we just pasted B's officer key in there, A would go boom if B is not enabled. We don't want that, and we may not want to force people to use B. So we paste that officer key there, replacing A_blank_record, but we also check what table that key relies on by hovering on its top (title, header, whatever), which is... db/land_units_officers. Without it, that officer key is going to go boom, because it's not a tolerant key, at all, to the point that even a non-existant officer needs an actual key called A_blank_record, which does exist.

What we do is create land_units_officers, add that officer key under key, keep personality location as front or rear (honestly don't know if that crashes if left blank, don't care), but we leave the officer 1 etc columns empty. IMPORTANT: we rename this table fragment with something like zzzzz_mod_a_mod_b. Notice the zeds? Keep those in mind.

So, what is this doing? It's telling the unit that it's going to use that officer group, but it's got nothing in it, no actual officers (battle_personalities). By using our mod A without B, the game finds an empty box for this officer, shrugs, and doesn't replace unit models with any officer personality. The game moves on without crashing, because that key exists. Basically, we created another blank record, but this very specific one gets filled in when B is enabled.

Remember those zeds? They are there so that our blank record gets overridden by B's table (which we assume has a higher alphabetical priority than a bunch of zeds, unless B's author is not trying hard enough). Keep in mind that if B's author ever changes those officer keys you won't crash, but you'll still need to adapt because your blank record would stay blank.

This can be done in a bunch of situations, but you'll need some specific knowledge of how specific contexts work. You could want to use this method to nerf some effects from mod B, in which case you might need more than one background table (the zzzzz boys), including db/effects, which by itself does absolutely nothing, but using an effect key that doesn't exist in there will go kaboom.

ADVANCED SUBMODDING: SCRIPTS

Uhh, sorry, not my field, but you can certainly do stuff. Either a scripty fella writes this or you have to ask in Discord about the specific case you’re facing.