Guide: The Complete Guide to Plugins

[Squid]

Modding Resource Header

Title: Guide: The Complete to Plugins
Posted by: Squid
Modding area: Buildings, Descr_Stat
Required programmes: Notepad (or other text editor)
Summary: An in-depth explanation of plugins in RTW/BI/Alex

Complete Guide to Plugins for RTW
By: Squid & Gotthard

Modders: Please help make this the one-stop source for plugin-related information. You can post your comments, corrections and additions on its associated forum of the Modding Questions at: https://forums.totalwar.org/vb/showthread.php?p=1879226

The plug-ins system is legacy from early in development. The code is still there to allow you to specify building plug-ins, but there is no display for them in the game anymore, which means that you cannot see wether any are built, build new ones through the UI, or look at any descriptions on the campaign map. Certainly the AI won't build them if you were to add some to the game... Best to just stick to buildings and upgrades, really

Up until now, this quote from Jerome was taken as gospel, plugins are legacy code and do not work. I didn't quite buy this because there's a lot about plugins that he doesn't say cannot be done. He says you can add the code to specify them, he doesn't say they can't be built, just you can't build them through the UI. It seems no one wanted to look into what actually could be done with the plugin system. The answer is lots.

I originally started figuring our what could be done with plugins while trying to figure out how I could tweak the core_building tree. This fell by the way side as other projects and priorities came up. Then Gotthard joined the RS team and he asked what appeared to be an innocent question about plugins as we were discussing what we were discovering by exploring the .exe files, and my previous work suddenly jumped out at me. Between the two of us the following is what we have so far discovered, and I'm pretty sure there will be more, how much who knows but we'll see.

Plugins in EDB

First if you are unfamiliar with the EDB (export_descr_buildings.txt), I suggest you read the Guide: The Completed Guide to EDB written by Dol Guldur.

To attach a plugin to a building you need to add the correct code to the plugin sections of the building you want the plugin associated with.

    plugins 
    {
    }

Code similar to this is what you find at the end of every building tree. The following code is what you'd add the enable a 1 level bowyer plugin.

    plugins bowyer
    {
        bowyer
        {
                levels bowyer
                {
                        bowyer requires factions { roman, }
                        {
                                building_min practice_field
                                construction  2 
                                cost  2500 
                                settlement_min village
                                upgrades
                                {
                                }
                        }
                }
        }
    }

On the plugins line is the list of plugins associated with the building tree. After that each plugin is specified like a building, with two key differences, there's no capability section, and there's the new building_min line. The building_min line specifies what level of the corresponding building is required to be able to build that level of the plugin.

Plugins in export_buildings.txt

Similar to buildings, it appears you need the same text extries for each plugin and plugin level. Each plugin needs a _name entry and each level needs its three entries. An errorless CTD results if any of these are missing.

{bowyer_name}
Bowyer

{bowyer}    Bowyer

{bowyer_desc}
WARNING! This baseline description should never appear on screen!

{bowyer_desc_short}
WARNING! This baseline short description should never appear on screen!

Plugins in descr_stat.txt

The key to being able to use plugins is getting them into the game, to add a plugin to a building you'll use code like the following:

    building
    {
        type missiles practice_field
        plugin bowyer bowyer
    }

Plugins and Scripts:

The create_building console command can be extended to place a plugin into a settlement using the following sytax:

console_command create_building practice_field bowyer

This will add a practice_field with a bowyer plugin to the settlement.

Plugins and Conditions:

GovernorPlugInExists works as expected
GovernorPlugInFinished hasn't been tested for functionality yet (I'm not sure if building with a console command would trigger this condition or not)

Known factors:

• Upgrading a building with a plugin does not destroy the plugin
• 9 plugins per building tree
• 9 levels per plugin

Uses:

• Can be used to store/pass additional information about settlements/regions to other files such as traits/ancillaries (e.g. every region with iron gets an iron plugin, etc to pass information about resources/hidden resources).
• Simplify tests to determine where on the map the character is (e.g. if you want to know if a character is in greece you create a greece plugin and add it to all settlements in greece in descr_stat)
• Others I'm sure that will be though of

Unknowns:

• As yet unknown how to link building capabilities and/or construction to presence of a plugin, if this is discovered the number of uses drastically increases, even if building through the UI can't be enabled (e.g. extra virtually unlimited hidden_resources, used for reform type script events, etc)
• Can a building have more than one plugin

[Nero]

This is really awesome! Will test this straight away, thanks for the findings! Have you tested if the building_present_min_level thing responds to plugins?
EDIT: just noticed that I shouldn't be posting in this thread. Also tried many different implementation methods of the building_present_min_level thing - none of them worked, like expected. But still the amount of possibilities for traits etc increase significantly. Will keep on experimenting ;)

[wlesmana]

This is really awesome and opens up many possibilities.
So what can the plugin offer other than the name? Can it act as a sub-building with building-like capabilities (bonuses, unit recruitment, etc)?

[Dol Guldur]

Just a reminder that the discussion/comment thread for this tutorial is here: https://forums.totalwar.org/vb/showthread.php?p=1879226