iShip.InstallAIPilot

I have spent about 6 hours trying to understand this function. I thought I would post what I have learned in hopes of saving someone else that time.

There is a nice debug screen for looking into the AI of ships. You can open it up using CTRL-ALT-z but only if you have NOT used the UniGUI which removes the screen when it closes. (I just modified the Torn Stars version of UniGUI to put the screen back up).

On this screen is displayed the "Attacked" flag as well as all the functions that are installed with the iShip.InstallAIPilot function. And the ratios of threat and hit points. Which means you can use this function to understand how the PS scripts set up the pilots.

The Install function takes a "self preservation ratio" value as one of its arguments. This value is between 0.0 and 1.0 (meaning 100% of hit points). A value of 0.5 means 50% of ships hit points. When ship damage reaches this % of hit points, the ship will turn red on the players hud. At this same moment ONE of the four functions will be called.

This calling of a function will only happen once. The threat ratios determine which of the first three functions are called. Ignore, Fight, or Flee.

The ratios are calculated as attacker threat/ship threat. So if the ship has a threat of 80 and the attacker has a threat of 160 then the ratio would be 160/80= 2.0

If you set the fight-ignore ratio above 2.0 in this case, the ship will call the ignore function (the attacker is not worthy of notice).
If you set the fight-flee ratio to be below 2.0 in this case, the flee function will get called (the attacker is too dangerous to fight)
If the ratio falls between these two then the fight function is called.
Normal values are 0.1 for the ignore-fight (attacker must be less than 10% threat to be ignored). And 4.0 for the fight-flee (attacker must be more than 4 times as deadly to make a ship run). Coward pilots have a 1.0 value for fight-flee. They will run when the odds are 1 to 1.

If the function that should be called is not installed, then the self preserve function will be called. This caught me up for the longest time. When a ship hit the self preserve value of 20% of hit points, I expected it to call the self preserve function. But it did not. Instead it examined the threat levels and called the fight function.

Once any of the functions are called, that ship will not call the functions again. That one function is the only notice that the script writer gets that his ship is getting attacked. One solution is to set the self preserve value very high, like 90%. The ship will call one of its functions very soon after being attacked and the script writer can take action. During that function call, launch a task that watches the ships hit points. When they finally reach that low 20% level, give the ship flee orders.

This explains why most PS ships fight to the death. At the first attack, they call an fight function, and the self preserve function is never called.

As complex as this sounds, the real behavior is more complex yet. First, the threat levels change with hit points of damage. So if a ship has taken 50% damage (the level of the self preserve ratio) then the threat value of the ship will only be 50% of starting. This needs to be taken into account when planning threat levels.

Another complication is that transports normally have a threat level of zero and they have a different behavior. A ships threat value is set in the ships INI file. If the ship has a zero threat, then TWO of the functions can be called.

The Ignore function is called first. And this happens when the ship is first attacked, long before the self preserve ratio is reached.

Once the self preserve ratio is reached, the "real" function is called. You can notice this behavior in standard EoC. When you attack a freighter, it will first tell you "Hey, leave me alone" but if you keep shooting it, it says "I surrender, take the cargo pods".

I knew both of these messages were sent by the Install functions. And it really set me down the wrong path, since I thought every kind of ship would get two function calls. One when first attacked, and one later when badly damaged. Not true. And now everyone knows.

I wish I found this post a bit earlier. However, I was on the same track. Now I have to figure out a way to make ships 'reset', as in Unstable Space they tend to stay alive for a long time.

Well, I may have found a solution already. I simply tried removing the aipilot, then reinstalling a new one with the same settings. As long as I do this while the ships is nursing its wounds somewhere, it should be invisible to the player.