Total War: WARHAMMER II

Total War: WARHAMMER II

Not enough ratings
Script Mods for TW:WH How to make your script readable.
By IfThenOrElse
This basic guide provides tips for those authors of mods that utilise scripts, so that their scripts are well documented with minimal effort.
   
Award
Favorite
Favorited
Unfavorite
Preface:
This is not a guide on scripting (hopefully these will come along in the near future from the growing scripting community) and assumes you have a basic understanding of mod scripts for Total War.
Introduction:
The world of script modding for Total War: Warhammer is a wonderful area of potential – that is also very dense, with scripts getting more and more complicated as new layers of conditions, checks and bug fixes are added onto the core workings that the script sets out to achieve.

As such, a completed mod script can be hard to read. This little guide aims to give the novice script writer a few tips to help make their work more transparent.
Section 1: But why?
  • By ensuring the changes you have made are well documented, you can quickly edit or improve your work after a break because at a glance you can see what your script does.

  • By making your script easy to understand, others who wish to learn how to script can understand how you achieved success and apply it to their own work – instead of copy pasting redundant code because they do not fully understand what you did.

  • Other mod authors can see how your script works and ensure that they can build theirs to avoid conflicts.
Section 2: When editing vanilla game scripts
First and foremost – if you can avoid editing vanilla scripts you should do so. Not only can you inadvertently interfere with the games scripts, but you also risk the chance of conflicting with other mods.

If however you need to mod a vanilla script here are some tips.
  • At the very top of the script, document the line numbers you have edited or added so that people know exactly where to find your changes. This avoids the nasty situation where people cannot distinguish what you wrote and what was in the base game.

  • If editing a value or changing a condition in a vanilla script – ensure you document the original value.

  • Try to detail what each edit does as best you can.


  • With all commenting, try to use a 'tag' that can be easily searched for so that every edit is easy to find. You may have noted in the examples above, I used "sd_Tutorial" with every edit I made.
Section 3: Your own custom scripts
  • Check out examples of LUA coding conventions. They all apply to Total War scripts (which are made with LUA). LINK[www.mediawiki.org]

  • When naming your variables, try to prefix them with an identifier for your mod. "myModAbbreviation_factionName"
    "myModAbbreviation_RegionToCheck"

    You should also name your variables in a way that describes what they do. For example "varaibleOne" could do anything whereas "factionName" informs you that the variable is likely to be holding a name of a faction.

    Not only does this make searching for your variables easier, it also reduces risk of creating varaibles that other mods might also use (and conflict with).

  • Create clear headers for each "block" of code. In my mod, "Summon the Elector Counts" I create clear headers that allow me to get a top level view of what everything is at a single glance.

Section 4: Additional tips
--
"If you write more comments than code, you need to re-evaluate your code"- Erde's Java teacher

A good script should be self explanitory and no amount of script documentation will make life easy when the code itself is not well thought out. If you seem to have a lot of commenting in your script, tkae a step back and think "have I built this script out in a logical manner, what alternative methods could I use?"
--
This really isn't about readability of your own script - but I feel it is so useful that I wanted to include it in this guide.

Consider storing all the games scripts in a document you can quickly search. This can allow you to home in on a specific command, event or function to see how it has beenm used in the base game scripts,

I store all the scripts in a OneNote Notebook. You can see below how I used it to search for a command that is not often used. "cm:disable_movement_for_character()"

2 Comments
[Myrm]Fable09 16 Jan, 2021 @ 7:31pm 
if I want to add starting settlements to a given faction in the beginning of campaign do you know what function should I used ?
emcdunna 10 Dec, 2017 @ 4:47pm 
I think just taking all raw files you use and using GIT to store them in a repo would work better, then you can get a Diff of all files, even before/after a patch and do a "merge". Should well with script files (too bad we cant do this for mod tables)