Lua Bindings

Bindings are global tables available in every Lua script. They provide read access to game state and action methods that queue server commands for execution on the next tick.

Scripts run at the fleet level. A solo ship is a fleet of one — same API, same callbacks. Action methods on fleet iterate every member of the fleet and queue per-ship commands; aggregate properties combine ship-level values (sums for pools, mins for weakest link stats).

Properties vs. methods. Properties are plain fields and must be accessed without parentheses (e.g., fleet.is_docked, sector.name, fleet.member_count). The runtime snapshots their values into the binding table before each callback. Methods — actions that queue commands and array/object queries — are called normally (e.g., fleet.activate_all_modules(), sector.get_enemy_ids()).

fleet — The Script's Fleet

The primary binding. Every script controls a fleet; solo ships are wrapped in a singleton fleet automatically.

Properties

Methods

Action methods iterate the fleet and queue per-ship commands automatically.

sector — Current Sector

Read-only information about the sector the ship is currently in.

Properties

Methods

solar_system — Current Solar System

Read-only information about the solar system the ship is in.

Properties

Methods

player — Owning Player

Read-only information about the player that owns this ship, plus lookups into the player's other ships. Used most often inside on_broadcast_received to resolve the broadcasting ship's location.

Properties

Methods

Each ship table from get_ships() / get_ship_by_id() has these fields: id, name, shield, shield_max, hull, hull_max, energy, energy_max, speed, max_speed, sector_id, solar_system_id, is_docked, docked_at_id, traveling, blueprint_id, status_message, faction_id, script_running, scale.

Formation types

Read fleet.formation_type to inspect; formation control is engine-driven.

market — Market Operations

Queue buy/sell commands and read live order data for any station.

Action methods

Query methods

market.get_sell_orders(station_id, item_id)

Returns a 1-based array of sell order tables at the given station, sorted by ascending price.

Each entry:

market.get_buy_orders(station_id, item_id)

Returns a 1-based array of buy order tables at the given station (same fields as above).

Example

function on_timer(timer_name)
    if timer_name ~= "tick" then return end

    local station_id = ship.docked_at_id
    if station_id == 0 then return end

    -- Find cheapest sell order for hull blocks
    local orders = market.get_sell_orders(station_id, "hull")
    if #orders > 0 then
        local best = orders[1]  -- already sorted lowest first
        local item = items.get_item("hull")
        if best.price < item.base_price * 0.95 then
            market.buy(station_id, "hull", best.remaining_quantity, best.price)
        end
    end

    set_timer("tick", 10)
end

items — Item & Group Data

Read-only access to the game's item catalogue and item groups.

Methods

items.get_item(item_id)

Returns a table of item fields, or nil if the item does not exist.

items.get_all_items()

Returns a 1-based array of all items (same table structure as get_item).

items.get_items_by_group(group_id)

Returns a 1-based array of items belonging to the given group.

items.get_all_groups()

Returns a 1-based array of all item group tables.

Each group entry:

items.get_group(group_id)

Returns a single group table, or nil if not found.

Example

function init()
    -- Print all weapons with damage > 100
    local all = items.get_all_items()
    for i = 1, #all do
        local item = all[i]
        if item.damage > 100 then
            print(item.name .. " dmg=" .. item.damage .. " range=" .. item.range)
        end
    end

    -- Find cheapest ore group item on the market
    local ore_items = items.get_items_by_group("ore")
    local best_price = math.huge
    local best_id = nil
    for i = 1, #ore_items do
        local orders = market.get_sell_orders(params.station_id, ore_items[i].id)
        if #orders > 0 and orders[1].price < best_price then
            best_price = orders[1].price
            best_id = ore_items[i].id
        end
    end
    if best_id then
        market.buy(params.station_id, best_id, 10, best_price)
    end
end

stats — Statistics Tracking

Register and track custom statistics with automatic time-series consolidation.

Methods