Lephisto/scripts/ai/API

// ================
// CONSTANTS!
// ================

number player
  -- players pilot id.

// ================
// TASKS!
// ================

pushtask(number pos, string name, int/pointer targer)
  -- Pushes a task onto the queue.
    -- pos    : Place task at the beginning if 0, or end if 1.
    -- name   : Function name, this is to be defined in the lua file.
    -- target : int or pointer containing target info (for example, could be
                pilot id or a Vec2).
    -- return nil.

poptask()
  -- Pops the current task from the list.
    -- return nil

taskname()
  -- Returns the current task name.
    -- return string name of the current task.

// ================
// CONSULT!
// ================

gettarget()
  -- Gets the current target.
    -- return pointer to the target.

gettargerid()
  -- Gets the current targets id.
    -- return number of the current target id.

getdist(Vec2 vect)
  -- Gets the distance from the position of the Vec2 vect.
    -- Vect point to calculate the distance from.
    -- return nil.

getpos([number pilot])
  -- Get the pilots position of the current pilots position if no pilot
     is specified.
    -- pilot ID of the pilot to get the position of, if no params are called
       it uses the current pilot as target.
    -- return Vec2

minbrakedist()
  -- Returns the minimum required braking distance assuming all goes well.
    -- return number distance needed to brake.

armour([number pilot])
  -- Returns the total amount of armour left.

shield()
  -- Returns the total amount of shield left.

parmour()
  -- Returns the percentage of armour remaining.
    -- pilot - Optional pilot id, if not the current pilot is used.

pshield()
  -- Returns the percentage of shield remaining.
    -- pilot - Optional pilot id, if not the current pilot is used.

cargofree()
	-- Return amount of free space the pilot has.

// ================
// BOOLEAN!
// ================

exists(number id)
  -- Check to see if pilot id is valid.
    -- id -- Pilot to check.
    -- return true if the pilot is valid.

ismaxval()
  -- Check if velocity is maximum.
    -- return true if velocity is max, false otherwise.

isstopped()
  -- Check if we are stopped.
    -- return true if stopped, false otherwise.

isenemy(Pilot pilot)
  -- Check if p is an enemy of current pilot.
    -- p - Pilot to check if enemy.
    -- return true if p is enemy.

isally(Pilot p)
  -- Check if p is an ally of current pilot.
    -- p - Pilot to check if ally.
    -- return true if p is ally.

incombat([number id])
  -- Queries whether a pilot is in combat or not.
    -- id - Pilot to check if is in combat. -- Defaults to self.
    -- return if pilos is in combat or not.

// ================
// MOVEMENT!
// ================

accel(number mod)
  -- Accelerates the pilot.
    -- mod float that represents acceleration ratio between 0(stopped) and 1(max accel).
    -- return nil.

turn(number mod)
  -- Turns the pilot.
    -- mod float that represents the turning ratio between -1(max right) and 1(max left).
    -- return nil.

face(number/Vec2 target, number invert)
  -- Turn to face the current target.
    -- target pilot ID or Vec2 to face.
    -- invert face away if 1
    -- return number offset from target in grad

brake()
  -- Makes the pilot brake (backthrust).
    -- return nil.

getnearestplanet()
  -- Gets the nearest friendly planet's position.
    -- return position to the nearest friendly planet.

getrndplanet()
  -- Gets the position of a random friendly planet.
    -- return position to a random friendly planet.

// ================
// COMBAT!
// ================

combat([number b])
  -- Set pilot as either in combat or out (for comm etc.)
    -- b - if 0 set the pilot to be in combat, if 1 or ommitted sets it to be in combat.
    -- return nil

settarget(number target)
  -- Set the target for the pilot, should be called each frame.
    -- target - Pilot to be targeted.
    -- return nil.

secondary()
  -- Tries to set the best secondary weapon (defaults to launchers).
    -- return the type of secondary weapon set ("None", "Weapon", "Launcher")

shoot([number weapon])
  -- Make the pilot shoot weapons.
    -- weapon to shoot, 1 if primary, 2 if secondary, 3 if both. Defaults to 1.
    -- return nil.

getenemy()
  -- return the id of the nearest enemy or 0 if none is found.

// ================
// TIMERS!
// ================

settimer(number t, number delay)
  -- Set timer t to wait for delay ms.
    -- t      - Timer to set.
    -- delay  - Delay time in ms to wait.
    -- return nil.

timeup(number t)
  -- Return true if time is up for timer t.
    -- t - timer to check.
    -- return boolean true if timer t is up.

// ================
// MESSAGING!
// ================

comm(number id, string message)
  -- Make the pilot say something to the pilot of id.
    -- id - of the pilot to speak to.
    -- message - string to output.
    -- return nil

broadcast(string message)
  -- Make the pilot broadcast a message to everyone in the system.
    -- message - string to say to everyone in the system.
    -- return nil

// ================
// LOOT
// ================

setcredits(number creds)
	-- Set the pilot's credits. Only works during create.
		-- creds - Pilot's credits.
		-- return nil.

setcargo(string cargo, number quantity)
	-- Give the pilot quantity of cargo, only works during create.
		-- cargo - name of cargo to give the pilot.
		-- quantity - amount to give.
		-- return nil.

shipprice()
	-- Get the price of the pilot's ship.
		-- return the price of the ship.

// ================
// MISC
// ================

rng(number low, number high)
  -- Return a random number between low and high.
    -- low - minimum to return.
    -- high - maximum to return
    -- return random number between low and high.