OXP Scripted AI

Scriptable flight AI provides an intermediate level of control between moving a ship with a frame callback, and using stock AI routines such as performAttack

In the AI, use the command "performScriptedAI" or "performScriptedAttackAI" to put the ship into scriptable flight AI mode. It will then remain in this behaviour mode until you switch it to a different mode in the AI, or an error occurs in the script. While in this mode, the scriptedAI function in the ship script is called each frame to determine the behaviour.

this.scriptedAI = function(delta) 
{
   // delta = duration of frame. Often irrelevant unless you're doing
   // ultra-high-precision turns, or want a maneuvre to last a particular
   // length of time

   // calculations happen here
   return flightParameters;  
}

The function gets a virtual joystick to control the ship with, by returning an object with up to 5 properties. All properties are optional, though returning an object is not. The default is level flight, at zero speed, with the forward weapon selected. Numbers outside the allowed range will be corrected to the nearest allowed value.

• stickRoll: roll rate in radians per second. A number between -ship.maxRoll and ship.maxRoll
• stickRollFactor: number between -1 and +1 to set a proportion of ship.maxRoll. Overrules stickRoll if both are present.
• stickPitch: the same for ship.maxPitch
• stickPitchFactor: as stickRollFactor but for pitch
• stickYaw: the same for ship.maxYaw
• stickYawFactor: as stickRollFactor but for yaw
• desiredSpeed: number 0 or greater. If this is above ship.maxSpeed, and the ship has usable injectors, it will use them.
• desiredSpeedFactor: number 0 or greater. 1 represents ship.maxSpeed, but higher speeds are possible with injectors. Overrules desiredSpeed if both are present.
• chosenWeapon: "FORWARD", "AFT", "PORT" or "STARBOARD". Ignored outside the attack version of the AI.

The ship will then respond to the virtual joystick. If a large change is requested - say the ship is in level flight, and the virtual joystick is moved to maximum clockwise roll - then it will take some time for the ship to respond and accelerate to that roll rate: quite possibly more than one frame.

If the attack version of the AI is selected, and the ship's current target is in the sights of the selected weapon (and there is a weapon there, and it's ready to fire, etc.), the weapon will be fired.

For example:

this.scriptedAI = function(delta) 
{
  return { stickPitch: -0.2;
           desiredSpeed: this.ship.maxSpeed;
           chosenWeapon: "PORT"; };
}

will make the ship perform a fairly wide loop, and in attack mode, firing its port laser if the target crosses its sights. Might be a decent evasive attack if the target is the size of a small moon...

Since the function is called once per frame, it needs to be quick. Searching for entities and new targets, for instance, can take some time.

There is no direct support for missiles, ECM, and other ship equipment, but you can call ship.fireMissile() or ship.fireECM() from within the scriptedAI function.

---