“Sentient Entities”, that is bases and ships, evaluate lua code to decide their actions. You are the devine carbon unit on their homeworld, caring and providing for them, and feeding them with sourcecode. Yummy, delicious, horrible, fancy sourcecode.

But first, you have to learn their language!

Official Lua Documentation

The ships are programmed in lua. For your convenience, here is a direct link to:

The official lua reference

Quick overview pictures

Free-flying ships, docked ships and bases have different sets of actions they can perform (german only, sorry):

General Programming Environment

Your code is typically invoked through a callback mechanism, whenever something interesting happens (see below). You can then look at the world around you, decide what to do, invoke an action, and return from your function.

Note that there is a runtime limit on every callback that is being run. So if you try to solve the travelling salesman problem to move your ships around, you may run into problems. If the timeout is encountered, your ship computer wil be terminated with extreme prejudice.

Data Types

Apart from all the standard lua data types, entity pointers (describing ships, bases, planets, etc) are introduced into lua. From within lua, these are completely opaque “userdata” objects, with no operators or methods apart from assignment. Hence, entity ids are only valid for passing into external functions which manipulate them.

Detailled function description

The lua-callable functions come in three large categories: Actions (with which your entity interacts with it's environment), Queries (with which you can learn about your surroundings) and Helpers (which are mostly debugging cruft left by the lazy developers).

Actions

killself()

Raises a lua error, which cascades through your call stack, overloads your ship computer and sends your ship adrift. Needless to say, this is only seldomly a useful function to call by yourself.

Might be useful for other purposes though. (See send_data())

Return value: Are you kidding?

moveto(x,y)

Tells the dumb autopilot to fly your ship to the specified coordinates. This autopilot simply accelerates in a straight line, and comes to a halt at the specified location. Note that in the past, serious lithobreaking-related injuries have been reported when ignoring the presence of asteroids or planets in the way. Just so you've been warned. There is a more sophisticated autopilot, you know?

Return value: nil

Callbacks set up: When arriving at your destination, on_autopilot_arrived(self) is called.

set_autopilot_to(x,y)

Tells the more intelligent autopilot to fly your ship to the specified coordinates.

Using the latest in overengineered artificial intelligence (as if that meant much), this autopilot will do its best to avoid any asteroids or planets in the way, and arrive safely at the requested destination.

Flying with this autopilot is slower than using moveto(x,y), but it will certainly cause fewer headaches.

Return value: nil

Callbacks set up: When arriving at your destination, on_autopilot_arrived(self) is called.

autopilot_stop()

Teill the autopilot to come to a complete halt as quickly as possible.

Return value: nil

Callbacks set up: Calls on_autopilot_arrived(self) once stopped.

set_timer(ticks)

Tells your ship to look busy while doing absolutely nothing, for the specified number of ticks.

Return value: returns 1 if the timer was set up successfully, or nil if you were already genuinely busy.

Callbacks set up: Once the timer expired, on_timer_expired(self) is called.

dock(entity)

Dock with the given entity (which must be a ship, base or asteroid). The target will have to be within docking range and not currently docked to someone else.

Docking takes some time, during which you are busy. While docked, you can not move around.

Note that you can very well dock enemy ships, even as they are shooting at you. They might undock() you immediately, though.

Return value: on success, returns the entity you just docked, otherwise nil

Callbacks set up: docking_complete(other) is called with the docking partner's entity pointer as an argument, once docking is, well, complete. On the docking partner, being_docked(other) is invoked right away.

undock()

Detach from your docking partner. You are now free again!

Only works when you are not busy.

Return value: 1 if successful, otherwise nil

Callbacks set up: Upon completion of the undocking, on_undocking_complete(other) is called. On the docking partner, on_being_undocked(other) is invoked.

transfer_slot(local_slot, remote_slot)

When docked, transfer a slot from / to your docking partner. More precisely, swap the contents of your local slot with that of the remote slot.

Return value: 1 if successful, otherwise nil

Callbacks set up: Upon completion, on_transfer_complete(self) is called.

send_data(stuff)

Transfer lua_data to your docking partner. stuff can be either a string, or a lua function (which is automatically dumped as lua bytecode, and also sent as a string).

In the lua state of the partner, on_incoming_data(stuff) is invoked. This handler can then decide what to do with the string (such as evaluate it, or laugh about it and throw it away. If no on_incoming_data() handler is specified by the user, a default one is running in a lua state:

function on_incoming_data(d)
  local f = loadstring(d);
  f();
end

Which simply evaluates everything that's thrown at him. Hence, a newly built ship can be programmed by it's parent bae through this function.

Return Value: The on_incoming_data() handler on the other side can return a single number as return value, which is passed through to the invoking side. Otherwise, return value is nil.

Callbacks set up: On the sending side, no callbacks are being invoked. On the recieving side, on_incoming_data(stuff) is called to deal with the code.

build_ship(slot,slot,...) or build_ship(array)

Build a ship from a number of ore slots. You need to be a planetary base to do this, and not have another ship currently docked to you. Only certain sizes of ships are allowed: 3, 6, 12 and 24 slots in size, corresponding to the number of arguments supplied to this function.

The resulting new ship will be attached to you as your docking partner, and the resource blocks you specified will be consumed.

You typically want to transfer thrusters or weapons into this ship afterwards, and load some code into it using send_data()

Return value: The entity ID of the ship you are building, or nil if it failed for some reason.

Callbacks set up: once the ship is finished, on_build_complete() is called. The newly created ship will only be loaded with the BIOS code, so no callback is invoked there.

fire(entity)

Shoot a shot at the specified entity. This only works if you are not otherwise busy, the target is in range, and you actually have lasers on board.

A shot has a certain chance of turning a functional slot (such as a laser or thruster) into ore on the target ship, or vaporize a chunk of ore. Once everything in the target ship has been vaporized, the next shot can detonate the ship itself. Hooray for explosions!

After shooting, your weapons need some time to recharge (after which on_weapons_ready() will be called for you). The more weapons you have on board, the shorter this time becomes. A 24-slot-behemoth completely filled with lasers can fire every timestep, and is a fearsome beast indeed.

Return value: nil.

Callbacks set up: Once your weapons have cooled down, on_weapons_ready(self) will be called.

mine()

As a base, dig one chunk of ore from the planet. This is less efficient (much slower) than asteroid mining using spaceships, but the only way for a base to produce ore by itself.

You need an empty slot for the ore to be put into.

Return value: the slot number into which the ore was put, or nil if it failed.

Callbacks set up: Once complete, on_mining_complete(self) will be called.

manufacture(slot, type)

Build something useful out of a chunk of ore, like weapons or thrusters. Alternatively, if you have the luxury problem of having too much of those, you can turn them back into ore.

Valid arguments for type are DRIVE, WEAPON or ORE.

Return value: on success, the slot number is returned. Otherwise, nil.

Callbacks set up: Once done, on_manufacture_complete(self) will be called.

upgrade_base()

Double the size of your base, giving it twice the number of slots (3 → 6, 6 → 12, 12 → 24). This requires the appropriate number of slots to be filled with ore… which means: ALL of your slots must be filld with ore for this to work (and all of this will be consumed).

Return value: 1 on success, otherwise 0

Callbacks set up: Once done, on_upgrade_complete(self) will be called.

colonize(planet)

As a ship, give up your spatial freedom and turn yourself into a permanent settlement. Your ship will lose the ability to move, but gain the possibilities to mine, manufacture and build ships.

Return value: your new entity id will be returned, if successful. Otherwise, nil.

Callbacks set up: Once the colonization process is complete, on_colonize_complete(self) will be called.

Queries

Query functions don't set up callbacks, but return instantly.

get_player(entity) or get_player()

Returns the player id of the specified entity (or yourself).

For ships and bases, this is the player that created this ship/base. For planets, this is the player that currently owns a base on this planet. Uncolonized planets and asteroids have user id 0.

The entity needs to be within scanner range for this to work.

Return value: The player id number, or nil

get_entities(search_radius, filter) or get_entities(x, y, search_radius, filter)

Returns a list of entity pointers in the specified range around you (or the specified x,y position), which match the filter. Valid values for filter are PLANET, BASE, SHIP, ASTEROID or any bitwise or'ed combinations of these.

Of course, you can only see entities within your scanner range.

Return value: A list of entities.

find_closest(range, filter)

Find the closest entity matching the filter in your vicinity, up to a maximum range. Valid values for filter are PLANET, BASE, SHIP, ASTEROID or any bitwise or'ed combinations of these.

Return value: A single entity pointer, or nil.

get_position(entity)

Returns the x and y coordinate of the given entity.

The entity has to be within scanner range for this to work.

Return value: x, y of the target entity, or nil if it is out of range

get_distance(entity)

Returns the distance to the given entity.

The entity has to be within scanner range for this to work.

Return value: distance to the target enitty, or nil if it is dead/out of range.

get_docking_partner()

Gives you a entity pointer to your docking partner, or nil of you are not docked.

Return value: just that.

is_busy(entity) or is_busy()

Determine whether the given entity, or yourself, is currently busy doing something.

Being busy prevents you from performing most other actions (such as shooting, building, docking or transferring). Note that waiting for a timer also counts as being busy.

The given entity needs to be within scanner range for this to work.

Return value: nil if the entity is currently idle (or out of range), and one of the following constants if it is busy: DOCKING, UNDOCKING, TRANSFER, BUILD, TIMER, MINING, MANUFACTURE, COLONIZE UPGRADE, corresponding to the action the targeted entity is performing.

is_flying(entity) or is_flying()

Determine whether the given entity, or yourself, currently has an autopilot following a flight plan, or whether it is just sitting there.

The given entity needs to be within scanner range for this to work.

Return value: A boolean value. (or nil if out of range)

get_slots(entity) or get_slots()

Get a list of the slot contents of another entity, or yourself.

The given entity needs to be within scanner range for this to work.

Return value: A list of slot values (EMPTY, ORE, DRIVE or WEAPON). Or nil, if out of range.

get_type(entity)

Return value: Returns the type of the given entity pointer. Can be PLANET, SHIP, BASE or ASTEROID

get_world_size()

Return value: 4 numbers: xmin, xmax, ymin, ymax, which describe the extents of the game's world.

get_timestep()

Return value: One number, the total number of ticks this simulation has been running.

Helpers

entity_to_string(entity)

Gives a string representation of the given entity. Useful for debugging output.

Return value: a string, describing the entity, or nil if it is an invalid, out-of-range, or otherwise bad.

help() or help("command")

Gives interactive help on the lua console. Ideally this will be the same information you can find in this wiki here.

Return value: nil. Information will be printed on your lua console.

print(string)

Allows you to print debugging information into your lua log buffer, which you can access via the console.

Hooray for watching shit scroll by.

Return value: nil. The given string will be printed in the lua log buffer.

reset_lua_state()

Resets your bases lua state and initializes it newly. Has the same effect as kill_self for everything else.

Return value: this function never returns.

Callbacks

You can setup callback functions in your lua code, which will be triggered when certain interesting events happen. Each of these will be called with an entity argument that may be related to the event (in many cases, this will simply be your own id).

on_autopilot_arrived

Called when your autopilot arrives at it's destination.

entity argument: self

on_entity_approaching

Called when a ship or base enters your scanner radius

entity argument: the other entity

on_entity_in_range

Called when a ship or base enters your weapons range

entity argument: the other entity.

on_shot_at

Called when someone shoots at you.

entity argument: the shooter

on_weapons_ready

After firing weapons, this callback is invoked as soon as your weapons are ready to fire again

entity_argument: false

on_being_docked

Called when you are docked by another entity

entity argument: the new docking partner

on_docking_complete

Called when a docking operation you initiated has completed

entity argument: the new docking partner

on_being_undocked

Called when your docking partner initiated undocking.

entity argument: your former dockung partner

on_transfer_complete

Called when a slot-transfer between you and your docking partner completes.

entity argument: self

on_build_complete

Called when a ship has been successfully built, and is now attached to you.

entity argument: The new ship

on_timer_expired

Called when a timer, previously set by set_timer(), expires.

entity argument: self

on_mining_complete

By now you should really be able to infer the meaning from the name.

entity argument: self

on_manufacture_complete

Once a manufacture action completes, this is called.

entity argument: self

on_colonize_complete

called once the colonize process is complete. Congratulation, you are now a base.

entity argument: self

on_upgrade_complete

called upon completion of upgrade_base()

entity argument: self

on_homebase_killed

This callback is invoked in your homebase after it has been killed by an enemy. When you recieve this callback, you are already in your new base, with a fresh lua state from scratch.

entity argument: self

Global Variables

self

Entity pointer containing yourself. This should never be altered! (If you do, bad things will happen to your ship)

ORE, WEAPON, DRIVE, EMPTY

Global mnemonics for the possible slot contents

PLANET, SHIP, ASTEROID, BASE

Global mnemonics for the possible types of entity.

DOCKING, UNDOCKING, TRANSFER, BUILD, TIMER, MINING, MANUFACTURE, COLONIZE, UPGRADE

Global mnemonics for the possible return values of is_busy (denoting the actions that an entity may be waiting for).

luafunc_doc.txt · Last modified: 2011/06/25 14:31 by urs
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki