Hi all - first tutorial here, so hope it goes smoothly. I've been seeing requests for this, and since I figured out how to do it for myself, I figured I might as well write this up - now I'll be able to refer to it myself until I can do it from memory, too
If there are any questions, feel free to post em, and I'll see what I can do to answer them.
I tried to keep it from being a giant wall of text, but, there's not a whole lot of screenshotting I could do, so hopefully you can all follow along.
Now, since adding new models is at present outside our (or at least my) abilities, this will deal with creating a unique vanilla unit. For this example, I'll be creating a special Uesugi version of the naginata warrior monk cavalry, and setting it up to be recruitable in-game.
First, you're going to need the following tables:
DBs:
building_units_allowed (this tells the game what buildings are required for the unit to be created)
cdir_unit_qualities (this tells the game what type of unit it is)
uniforms (this tells the game where to find the models for the game)
unit_required_technology_junctions (this tells the game what arts need to be mastered before you can recruit the unit)
unit_stats_land (this tells the game what the units' combat stats are, as well as animation and other miscellaneous info)
unit_to_unit_abilities_junctions (this tells the game what abilities the unit will have)
units (this tells the game various info about the unit, mostly related to the campaign map and multiplayer. Essentially, the non-combat version of units_stats)
units_to_exclusive_faction_permissions (this tells the game, predictably, who can use the unit. If it's not listed here, no one can use it)
units_to_groupings_military_permissions (very similar to the above, this tells the game who can use the unit)
as well as the text db units.loc (this tells the game the information about the unit, such as its name, and description)
Extract all those, create a new pack, and add them to your mod. This will include all the entries in the respective tables, so you'll want to trim them down to the essentials after you're finished.
Attachment 155968
Normally, we'd start from the top. But if we jump to units first, that'll make things easier in the long run. So let's go there.
Go to the entry of the unit you're making a variant of, and click Clone Row at the top. You then need to give your unit a unique name. Really, this can be anything, but it's easier to keep it the stock name system with _<faction's name> at the end. Next column over is the unit's screen name, but don't mistake this for the name of the unit showing up on the battlefield for instance, that's contained under unit localization. This is sort of an internal unit name.
Category and class should be left as the default, or changed to whatever is the closest approximation for your unit.
The rest of the info in this table is pretty self-explanatory, but a few things to note:
For unique variants of units, the discount is typically 25-50 koku on recruitment in the campaign, and +25-50 koku for multiplayer recruitment. Upkeep is a 25-50 koku discount.
Dojo Required allows you to set a second required building, not the primary. Like our case, where you need both a buddhist monastery and a naginata dojo. So, here is where I set the naginata dojo. Religion Required allows you to set only Christian, Buddhist, or Ikko-Ikki factions to be able to recruit this unit. I'm making it Buddhist.
At the very end, is Index. This lists the number of the entry - you'll want to change it to a unique number. Doesn't matter if it's consecutive, so I tend to use high numbers that I know won't conflict with anything.
That's it for units. Now, open up building_units_allowed.
We're going to make our naginata cavalry recruitable, and it normally isn't. So here, you have to decide what you want the primary requisite building to be. For right now, just find an entry with your unit's building in the list. For instance, we're going to require a Buddhist Monastery. So, we find an entry with that requirement, and copy it.
*Side note: The difference between primary and secondary required buildings is, primary buildings display the unit in the production queue even if you don't have the secondary dojo. It will be greyed out, and have a dojo icon in the corner. That is the secondary dojo required. If you only have the second dojo, the unit won't show up in the production queue.
Now you should have a new row with all the same info. All you need to do is change the Unit ID Ref, and the third Unknown variable, another unique ID. Again, it doesn't have to be consecutive, so I start high.
You need to do this for all the buildings in that chain, starting from the lowest level you want your unit to be recruitable at. So I have to have an entry for SHO_Buddhist_2_Monastery, SHO_Buddhist_3_Temple_Complex, and SHO_Buddhist_4_Legendary_Temple. For each level above the starting, you typically add 2 and 4 experience respectively. So a level 2 building adds 0 bonus levels, a level 3 building adds 2 bonud levels, etc. If you started at SHO_Buddhist_3_Temple_Complex though, you would only get 2 bonus levels with a legendary temple.
That's it for building_units_allowed.
Now, cdir_unit_qualities. This one's very simple. All you do, is copy an entry, and change the first entry to your faction's name, the second to its type, and the third to its unique ID. I don't think the last variable has any real significance, but if it does, feel free to let me know
Best I can figure is it's a weighting variable for the AI to build it, a sort of prioritization number. The higher quality units, like katana heroes, have values of 1000 for some factions, and 900 for others. Meanwhile, Ashigaru typically have numbers in the 200's for everyone.
You only need to add an entry for the factions you want to be able to recruit this, so I only need one for the Uesugi.
Now, Uniforms!
Uniforms allows you to set the look of your unit. Since we're using a standard unit, we just have to find and copy it. Set the Uniforms ID Ref to <default>_<unit name>_<faction>. In Uniform Variant, you can use a custom variant list to make, for example, a heavily armored monk with no exposed skin, a light monk with no armor, etc. This tutorial isn't about uniform_variants really, but suffice it to say, it's pretty straightforward. If you can edit it in PFM, all the better, but sometimes you have to use TAW's conversion tools to convert it to a txt. From there, it's a simple setup of adding in different parts and their textures which the game assembles a soldier out of randomly. One part in each category = cookie-cutter soldiers. A million parts in each = no two soldiers are the same.
Unit ID Ref is obvious, and after that is - I believe - the unit that represents the general or captain of that unit. Setting it to Samurai_Gen_Mori_Motonari would make Motonari lead your unit, while Samurai_Inf_Matchlock_Ashigaru loads a samurai to lead a company of ashigaru.
Next is - I believe - the model for the standard-bearer. This always seems to be some kind of ashigaru, and cavalry don't have standard bearers. So for our purposes, leave this blank.
The final entry is the face of the leader of your entire army that's shown in the bottom left corner of the battle HUD. You only see this when you have an army led by a captain, not a general. Since our group is warrior monks, we set it to warrior_monk.
Unit_required_technology_junctions is next. This is where you'd set whatever art you want mastered before you can recruit the unit - but since ours is already determined through the necessary dojos (which require arts to build), we won't mess with that. For the sake of example, gunpowder units would be set to shogun_military_musket_teppo_mastery. That way, even the required buildings wouldn't be enough to build the unit. Using all the requirements (and AI weighting) you can set exactly how common or rare you'd like the unit to be. Or at least, how soon before it shows up.
Unit_stats_land is next, and it's a bit of a doozy. There's a lot of info in this bad boy. After creating your new entry with your Unit ID Ref, you can set the number of soldiers, number of horses for cavalry units, number of artillery pieces, etc. Officer, I'm not sure what it does. It may do the same thing as the entries we saw before in uniforms, it may not. I don't know for sure.
Same with standard bearer.
Model Name I don't believe is used anymore, considering it's shogun_samurai_test for so many of the entries.
Infantry Battle Entity is related to the animations of the soldiers, I believe. Shogun_inf_samurai is what you want most of them to be.
Further down, you come across horse 1, cavalry battle entity, and horse 3. These are all used to determine the models of the horses. Another holdover from Empire and Napoleon, there's only horses in this game.
Even further, you'll come across Artillery 1, and Artillery 2. Artillery 2 is important because that's what determines ranged weaponry. You need Artillery 2 for ranged units, or they won't be very ranged.
Drill Set and Training I don't believe really make a difference in-game. At least my testing hasn't shown anything.
Then you get some spacing variables, to set how loose or close you want your units to stand to each other. I wouldn't mess with that for most purposes. I only mention it for future reference, I'm sure someone will want it sometime
A few ability modifiers later, and you come across the Spotting Value variables. These determine how close or far you have to be to the army before you can see its unit card on the campaign map. I'm not sure which is which, but I believe one is for standard military troops, one is for agents who aren't ninja, and remaining one is for ninja.
There's also an Immune to Attrition variable in here, which is usually reserved for rebels. If you wanted to make kisho ninja immune to attrition though, here's where to do it.
The last part of this table is reserved for either sound effects, scripts, or general animation. I haven't tested it yet.
Now we're finally done with units_stats_land. Onto unit_to_unit_abilities_junctions. The list of abilities can be found in unit_abilities, but usually you'll have what you need there. We're giving our guys wedge formation and warcry. A simple clone and change of the Unit ID, and we're done. Much simpler after the unit stats tables, eh?
We're getting close to being done, now! Units_to_exclusive_faction_permissions is next. Another simple one, all we need to do is copy anything from our faction. Change your ID, make sure it's set to True, and then you're done. However, since our unit replaces another unit (or at least it would in theory) for this faction, we need to make another row. On this one, you copy the default version's ID, and set it to False. That way our faction will be able to recruit Cav_Spear_Naginata_Warrior_Monk_Cavalry_Uesugi, but not Cav_Spear_Naginata_Warrior_Monk_Cavalry.
Attachment 155969
Units_to_groupings_military_permissions is theoretically unecessary for the most part, but I can't seem to get the unit to be truly unique to a faction without it. Just copy a row, set the unit ID, and change the Group to your faction's name.
Now, the very last table: units.loc! Getting tired yet?
A note before we get started with this one: if you extract this from data.pack and use it in your own pack without renaming it, it will overwrite the default. However, unlike with most other tables, if an entry isn't here, it won't read it from data.pack either. In other words, if you use this without renaming it, and delete everything but your new unit's entry, that will be the only unit with a name. All others will be blank. So make sure you rename it!
Now, the syntax here is as follows:
units_on_screen_name_<unit ID>
and
unit_description_texts_description_text_<unit ID>
On screen name is the actual name of the unit as it shows up on the battle map.
Description text is the tool tip that shows up underneath the name. If you want to copy something from another unit, you can find the standard units.loc (for on screen name) and unit_description_texts.loc (for the tooltip) in the localisation_en.pack (or whatever your game's language).
Now, with all those changes complete, save the pack! You may want to change it to a movie pack, or a mod, or whatever works for you. After that, you're ready to go! If everything is done correct, your new unit will show up on screen, in all its glory
Shiny new unit...
Attachment 155970
...That doesn't replace the original for all factions.
Attachment 155971
Troubleshooting:
The easiest way to test this is in the custom battle setup. You'll have the opportunity to notice several problems along the way:
- If your game doesn't load and crashes before reaching the cutscenes / main menu, you likely have the wrong pack type, or something's wrong with your user.scripts.
- If your unit doesn't show up at all, check to make sure you set it to recruitable.
- If your unit shows up, but doesn't have a portrait, I unfortunately don't know what to do - I've only run into that problem once, and I don't remember how I fixed it, unfortunately. It's fixable, and hopefully someone else can post exactly how
- If you can add your unit to your custom army and it has its portrait, but the game crashes after you try and load the battle, there's an error in one of the tables. Usually something in the uniforms, units, or unit_stats_land. I've noticed that PFM can be rather finicky at times with what it saves - sometimes it forgets to set one or two changes you've made. It particularly seems to forget what you've set your horse models to under stats_land, for example.
It'll almost never work 100% the very first time, so just remember to stick with it, and you'll get it. Also, for reference, I'm using the additional units mod, which is how the Mori got the monks. So you can mod even with other unit packs running, as long as everything has its own ID.