[TUTORIAL] Simple Custom Code

(Taiidan Republic Mod) #1

I have been meaning to do a custom code tutorial for a while. Here is a simple one, based on my advice to @Captain_Freedom here Messing around with shields


Custom code is a script that runs for a specific ship type. It can be used to manage abilities or handle slightly unusual functionalities that you might want to give your ships. It is a powerful tool once you get the hang of it - the possibilities are endless (you could make a ship change its paint scheme when it gets below a certain health value, or turn off the nav lights when it is being attacked, or decrease its speed when it is carrying salvage, or trigger a MAD animation while the ship is in a dust cloud…)

In this example we will make the hgn_defensefieldfrigate field ability inactive unless the player has researched the scout ping ability.

Custom Code file

First, we need to create the following file as hgn_defensefieldfrigate.lua in data/ship/hgn_defensefieldfrigate/:

function Update_DefFieldFrigate(CustomGroup, playerIndex, shipID)
	if (Player_HasResearch(playerIndex, "ScoutPingAbility")==1) then
		SobGroup_AbilityActivate(CustomGroup, AB_DefenseField, 1)
		SobGroup_AbilityActivate(CustomGroup, AB_DefenseFieldShield, 1)
		SobGroup_AbilityActivate(CustomGroup, AB_DefenseField, 0)
		SobGroup_AbilityActivate(CustomGroup, AB_DefenseFieldShield, 0)

This is the custom code. What it does is to check if the player owning the frigate has the scout ping ability research and if so, activates the field ability. If not, the ability is disabled. Custom code functions always take three arguments:

  • the sob group of the ship in question (in our case used to activate/disactivate the ability)
  • The player ID (in our case used to check if the player has the research)
  • The ship ID (not used in our example) - this is a unique number given to this particular ship

Ship file

Firstly, we need to comment out the following line in hgn_defensefieldfrigate.ship :


This is because that line would prevent us from managing the ability by scripting, which is what we want to do.

Secondly, we need to add the following line to hgn_defensefieldfrigate.ship before the LoadModel bit:


The arguments of addCustomCode() are:

  • NewShipType
  • string, path to the script (the script we created above)
  • string, function called on loading the ship files (not needed in our case)
  • string, function called on ship creation (not needed in our case)
  • string, function called on ship update (we use this, the arguments automatically passed to the function are player ID, sobgroup, ship ID)
  • string, function called on ship death (not needed in our case)
  • string, name of the group(?), I have never used this… I usually set it to the ship name
  • float, update frequency

That’s it! Launch the game with the appropriate command line to override the big file and you should see your field frigates without the shield button until you have the scout ping research. Hopefully that helps in getting started with custom code, but obviously much more complicated things can be achieved. If you have questions on your specific implementation of custom code, ask here and someone will try to help you!

Modding tutorials Master Thread