How to add an ancillary

[davidlallen]

This tutorial describes how to add one ancillary to the game. This tutorial assumes basic familiarity with PFM, and it is current as of patch 7, early August 2011.

The only tool you will need besides notepad is PFM. I have used version 1.66 with the additional data files I added in this thread. For basic instructions on PFM and creating mods, I recommend this thread. It is for NTW, but apart from some minor differences in pathnames, the steps apply to TWS2 also. I would like to keep this thread focused on ancillaries. So if you have not used PFM before, please try it out first and request PFM help in the PFM threads.

The key files are:
a. patch7.pack/db/ancillaries_tables. Defines the ancillary's icon.
b. patch7.pack/db/ancillary_to_effects_tables. Defines the ancillary's effects.
c. patch7.pack/db/ancillary_to_included_agents_tables. Defines the agent types which can have the ancillary.
d. patch7.pack/db/ancillary_included_subcultures_tables.
e. patch7.pack/db/ancillary_info_tables.
f. local_en_patch.pack/text/db/ancillaries.loc. Defines the ancillary's onscreen name and colour text.
g. patch5.pack/export_ancillary.lua. Defines the conditions under which the ancillary may be added to an agent.

The new ancillary we create will be a Barded Warhorse for a general, which gives the general's bodyguard a +1 charge bonus.

1. Create a temporary working folder. Using PFM, extract the files listed in (a-g) into this folder. I would like to keep this thread focused on ancillaries. So if you have not used PFM before, please try it out first and request PFM help in the PFM threads.

2. Use PFM to create a new pack file with the files (a-g). Rename each of the tables (a-e). For example, rename (a) from ancillaries to tut_ancillaries. Do not rename table (f) or lua file (g). Change the pack type to "movie".

3. Use PFM to open the table (a) in your new pack file. The first field gives the internal ID of the ancillary, and the second field gives the icon name. Scroll down a number lines to find the string "animal_horse" in the second field. Delete all the other lines except for this line. Change the first field of the line, which gives the internal ID of the ancillary, to "tut_barded_warhorse", and save the file. Here is a screenshot:



4. In PFM, open table (b) in your new pack file. The name of the effect we want is "general_bodyguard_charge_bonus". Finding useful effect names is outside the scope of this tutorial. Delete all but one of the lines from this table, and change the remaining line to have ID "tut_barded_warhorse", "general_bodyguard_charge_bonus", and the value "1".

5. In PFM, open table (c) in your new pack file. We want this ancillary to be available for generals. Delete all the lines and add one line with ID "tut_barded_warhorse" and the field "General".

6. In PFM, edit tables (d,e) so that they contain one data line, and change the first field of the data line to "tut_barded_warhorse".

7. For file (f), we need to add the onscreen name and colour text for the ancillary. Unlike the other tables, do not delete the other lines in this file. The lines of this table are not in any particular order. But for each ancillary, there are two strings defined: the "onscreen name" and the "colour text". At the bottom of the table, add these two lines:

ancillaries_onscreen_name_tut_barded_warhorse | Barded Warhorse | True
ancillaries_colour_text_tut_barded_warhorse | "On, Daiwa! To glory!" | True

8. In file (g), we need to allow the game to select this new ancillary. For reference, here is the code for the first ancillary in the file with some colors added. It seems the forum editor changed the tabs to spaces, so do not paste from here into the lua file.

events.CharacterRankUpNeedsAncillary[#events.CharacterRankUpNeedsAncillary+1] =
function (context)
 if conditions.CharacterType("geisha", context) and not conditions.CharacterInHomeRegion(context) and conditions.FactionwideAncillaryTypeExists("s2anc_ainu_servant", context) == false then
  if conditions.DateInRange(1500, 1900, context) then 
   effect.ancillary("s2anc_ainu_servant", 50,  context)
  end
  return true
 end
 return false
end

Using notepad on the file in your temporary working folder, duplicate this section of code in the file. Now, make a few changes in your copy. In blue is the agent type; change this to "General". In red are some other conditions; delete this text. In magenta is the ID of the ancillary; change this to tut_barded_warhorse.

9. Save this version of the file in a temporary location. We will want this file again later, after testing is complete.

10. For testing, we need to temporarily make sure that no other ancillaries are available. Otherwise, it might be quite some time in gameplay before the game engine randomly selected your new ancillary. In the reference code above, the green color is the start date. Global search and replace in this file and change all the "1500" to "1600", except for the tut_barded_warhorse entry you just added. With this change, no other ancillaries will be available at all! So this is a temporary change, which is why you created the backup in step 9.

11. In PFM, open your pack file and replace the file (g) with the modified file from the previous step. Now is also a good time to double check your work. Make sure that the tables (a-e) have only one line each; make sure the strings are spelled correctly; make sure the updated lua file is showing and there is only one string "1500" in the file. Make sure the mod is "movie" type.

12. Test the mod! Copy your new packfile into the game's data area. Start a game. One quick way to test is to choose Chosokabe, normal difficulty, and auto-resolve two battles against the rebels; your general should level up. When you level up, you should see only one ancillary choice, which is the new barded warhorse.

13. After the initial test, replace the file (g) with the modified file you created in step 9. This way, the new ancillary will be chosen occasionally, instead of being the only ancillary in the game.

14. (Optional) Come back to this post and add to my reputation by clicking the little green "+" button under my name at the left. This will help my standing in the forum.

[davidlallen]

reserved

[davidlallen]

In case anybody reads this and knows the answers, it would be really helpful to me. I posted these questions in the scripting sub-forum several weeks ago, but there was no answer.

For localization files, I tried adding a new file in text/db called newanc.loc which was supposed to add new definitions like text/db/ancillaries.loc; but my new values were ignored. So instead I put a full copy of the file ancillaries.loc, with my new rows added. This is risky, since if anybody else also mods ancillaries, the files will conflict.

==> Is there any way to override strings from text/db without copying the whole localization file?

In order to add the ancillaries, I have edited export_ancillaries.lua to put my calls to "events.CharacterRankUpNeedsAncillary" into the same place as all the base game calls. As above, this means if anybody else mods this file, our changes will conflict.

==> Is there any other safe place I can put this type of lua code, so that it will not conflict with other modders' code?

In the db table for effects we can see many interesting effects, such as "campaign_map_stealth" (enables army to lay ambush in any terrain). It isn't clear whether this can be added to an ancillary. For some other effects, the name has a prefix such as "clan_trait_shimazu_superior_katana_hero" and we could "assume" this can only be applied to a clan, not to a general, or building, or tech. I have tried adding some building effects to ancillaries. The effect shows up in the ancillary info card, but it doesn't seem to have any actual effect in the game. Performing playtests with each effect, and setting up a scenario where the effect should be visible, is too painful.

==> Is there any way to know which effects will actually work when applied to a certain object?

[Yarkis de Bodemloze]

As far as I know: No and no. As far as effects are concerned: There is no single list that tells you what works with what, so either test it out (which you should do anyway because not all effects that are in the effects table work) or check how the effect is used in the game. For example if I want a global effect I usually check what's used for techs, difficulty levels or effect bundles.

Nice tutorial btw.

[davidlallen]

Global effects are probably easier. I am specifically interested in ancillary effects. I have tried the following effects on ancillaries. They all show up with the proper text in the unit card, but they don't cause any visible change in gameplay:

building_mod_income_farms
enable_night_battles
mod_unit_upkeep_siege
repression_events_global
tech_clan_income_tax_mod

I was especially disappointed that the mod_unit_upkeep family did not work because one of the existing ancillaries uses mod_unit_accuracy_bow_samurai_infantry. There are at least a dozen other families of effects which "look interesting" to apply to ancillaries and I was hoping the info was in some other table somewhere.

[Yarkis de Bodemloze]

Effects of traits and agent skills should work with ancillaries. But then, if enable_night_battles does not.... Global effects will probably not work, only local ones. In the end there is no way around testing...

[MDegage]

Is there a way to restrict the ancillary to a faction?

[davidlallen]

I haven't tried it, but this "should be" easy. In step 8 of the OP I discuss about editing export_ancillaries.lua. Each entry has an "if" statement with clauses like: conditions.CharacterType("geisha", context). File campaigns/jap_shogun/scripting.lua contains other examples of these conditions. In particular, the clan-specific missions are set up using clauses like: conditions.FactionKeyIsLocal("chosokabe", context)

So I suppose that when you add an ancillary and you add the "if" statement, you could include this condition. If you try that and it works, please let me know!

[MDegage]

yeah David, I was thinking the same thing, but I never saw an example of the Faction condition, also what do you suppose the 50 relates to in the effect.ancillary? I noticed in one of the tables there was a value for I think "presidence" and everything was set to 1. It seems to be that some ancillaries appear more then others but according to that db table and the .lua there doesn't seem to be a higher chance of occurance, except towards the end when some of them have a 5 instead of 50.

It's interesting that some ancillaries and prereq's. On a side note, have you noticed the diplomacy is a bit glichy when it comes to applying ancillaries, i.e. diplomacy bonus? I know this has been an issue present in all TW games

[davidlallen]

I assume the "50" value is a weight. It's hard to tell how much is a random effect when ancillaries appear relatively rarely. I wish there was a good way to tell which effects are *supposed* to apply to ancillaries; I have tried a number of effects and many of them appear in the unit card, but don't make any actual difference in the game. Maybe there is code which looks for "some" effects but not "all" effects on ancillaries. We can't tell which ones the code actually looks for.

[MDegage]

Yeah, I've done some testing with auto-resolve - Level up, re-load. Some ancillaries seem to appear much more often, and I do believe that any that add diplomacy bonus is bugged, it works towards some factions but mostly not.

I will play with the 50 later and see what the results are. Thanks for the find on the FactionKeyIsLocal

[MDegage]

Geez, what a pain...there doesn't seem to be an easy way to make it more common. BTW, I discovered that you don't actually need to import the lua into the pack, if it sits in the Data folder it will be used

[MDegage]

Got it, the 50 number has to be very very high, I set it at 900 and now it comes up every time.

[MDegage]

BTW, there seems to be a difference between the selection of Ancillaries for autoresolve and actual battles. When I value my custom ancillaries at 900+ They will come up every single sime after an autoresolve battle, however, they will hardly ever come up if I actually fought the battle. You seem to get a "higher end" selection of ancillaries for battles you fight.

I haven't been able to discern where this process happens, I thought it might be the field "unique to work" but one that often makes an appearance is crime_gambler, and that is only unique to faction.

[MDegage]

Hey David,

Been playing around trying to bring in the effect mod_build_time into an ancillary. Have you had any luck or tried to import an effect thats not already used in any ancillary?

I created cust_build_time as an effect and made entries in effects_to_building_chains (<- think thats the table) to decrease build times, but I can't seem to get it work. There is a tech that decreases the build time of Sho_castle and there are 2 effects for build time, one global and one local.

[davidlallen]

To be honest, I found the same problem and mostly gave up. I tried a number of effects which were not already on ancillaries, and found that only one or two worked. It is fairly time-consuming to try different possibilities, given how long the game takes to load and get to a point you can test. I first discussed this in an older thread:
http://www.twcenter.net/forums/showthread.php?t=462313
And there is some discussion earlier in this thread. I suppose that in the hard-coded game source code, ancillaries are checked for "certain" effects, rather than all effects, but no modder knows how to tell which effects.

[MDegage]

Sometimes I get the feeling that they've actually gone out of their way to make it difficult to mod. Why on earth would they hard code something like that...

[davidlallen]

I agree. It is *possible* that this is available in a table somewhere; but I gave up trying to figure it out. This game is moddable, but not in the ways which I would find interesting.

[MDegage]

Hey David i know this is off-topic but I was hoping for your input on some scripting, I'll be sure to credit you in my mod. I'm want to script unit avaliability restricted to the player in campaign, so far this is what I have.

scripting.game_interface:add_restricted_unit_record("unit_name")
local ply_faction = CampaignUI.PlayerFactionId()
if conditions.FactionIsHuman(ply_faction, context) then
scripting.game_interface:remove_restricted_unit_record_for_faction("unit_name", ply_faction)

I'm not sure if PlayerFactionId will return the results I need or if there is a command to restrict a military group as opposed to listing each unit individually.

[MDegage]

David! I actually was able to create a new effect for mod_build_time and get it working temporarily and on a limited basis in an ancillary. It seem to be all about the number id in the effects table. I used an ID of 5 as does the tech for castle construction and it worked on a local level. So...it's about finding out what id will accept an ancillary from an agent and treat it globally. Most general ancillary effects have the id of 999, but that didn't seem to work at all

Will test more, this would be so much easier if we had some kind of map for mysterious values like this.