Lua Script Callbacks

Callbacks are Lua functions that the server calls automatically when specific game events occur. Define only the ones your script needs — missing callbacks are silently ignored.

Scripts run at the fleet level. A solo ship is a fleet of one, so the same callbacks fire either way. Callbacks that pass a source_id or member ship ID should be filtered with fleet.contains(id) rather than comparing to a single ship ID.

All parameters passed to callbacks are integer IDs unless noted otherwise.

Lifecycle

on_init()

Called once when the script is loaded and attached to a fleet.

function on_init()
    print("Script started for fleet " .. fleet.id)
    set_timer("tick", 10)
end

on_timer(timer_name)

Called when a timer set by set_timer() expires.

function on_timer(timer_name)
    if timer_name == "tick" then
        -- do work
        set_timer("tick", 10)
    end
end

Note: The built-in "tick" timer fires every 10 seconds and is automatically restarted. You can also create your own named timers.

Solar System Events

on_solar_system_change()

Called when the fleet's flagship enters a new solar system. Also called once on script load if the flagship is already in a solar system.

function on_solar_system_change()
    print("Entered solar system: " .. solar_system.name)
end

Sector Events

These callbacks fire for events in the flagship's sector. The fleet maintains a sector invariant: every member is expected to be there.

on_sector_add(space_object_id)

Called when a ship enters the sector (warp arrival or undock).

function on_sector_add(space_object_id)
    if fleet.contains(space_object_id) then return end
    print("Outside ship " .. space_object_id .. " entered the sector")
end

on_sector_remove(space_object_id)

Called when a ship leaves the sector.

function on_sector_remove(space_object_id)
    print("Ship " .. space_object_id .. " left the sector")
end

on_sector_target_locking(source_id, target_id)

Any ship in the sector starts locking a target. Use fleet.contains(source_id) to detect locks initiated by your own fleet.

function on_sector_target_locking(source_id, target_id)
    if target_id == fleet.flagship_id then
        print("Flagship is being locked by " .. source_id)
    end
end

on_sector_target_locked(source_id, target_id)

A lock completes anywhere in the sector.

function on_sector_target_locked(source_id, target_id)
    if fleet.contains(source_id) then
        fleet.activate_all_modules(target_id)
    end
end

on_sector_target_unlocked(source_id, target_id)

A lock is released anywhere in the sector.

function on_sector_target_unlocked(source_id, target_id)
    if fleet.contains(source_id) then
        print("We lost our lock on " .. target_id)
    end
end

Fleet Events

These callbacks fire for events affecting the fleet itself.

on_fleet_change_sector()

Called when the fleet (flagship) arrives in a new sector.

function on_fleet_change_sector()
    print("Arrived in sector: " .. sector.name)
end

on_fleet_travel_finish()

Called when an individual warp/jump/dock leg of the fleet completes. Fires for every leg — see on_travel_finished for end-to-end arrival of fleet.travel_to.

function on_fleet_travel_finish()
    if fleet.is_docked then
        for _, item in ipairs(fleet.get_inventory()) do
            fleet.unload_to_station(item.item_id)
        end
    end
end

on_travel_finished(sector_id)

Called when an autonomous trip started with fleet.travel_to(sector_id) reaches its destination.

function on_travel_finished(sector_id)
    print("Arrived in sector " .. sector_id)
    fleet.set_status("Arrived")
end

on_travel_failed(reason)

Called when an autonomous fleet.travel_to(...) cannot complete — the target sector does not exist, or no jumpgate route connects the current solar system to the target.

function on_travel_failed(reason)
    print("Travel failed: " .. reason)
end

on_fleet_member_attacked(ship_id, attacker_id)

A weapon hit lands on one of the fleet's ships.

function on_fleet_member_attacked(ship_id, attacker_id)
    print("Member " .. ship_id .. " hit by " .. attacker_id)
    fleet.activate_all_modules(attacker_id)
end

on_fleet_member_destroyed(ship_id)

A fleet member has been destroyed. Fires before any flagship promotion.

function on_fleet_member_destroyed(ship_id)
    print("Lost member " .. ship_id)
end

on_flagship_changed(old_id, new_id)

The previous flagship was destroyed and command transferred to the next member (in fleet.Members order).

function on_flagship_changed(old_id, new_id)
    fleet.set_status("Command transferred")
end

on_low_shield(ship_id)

A fleet member's shield dropped below 25% of maximum after a hit.

function on_low_shield(ship_id)
    print("Low shield on " .. ship_id)
end

on_low_energy(ship_id)

A fleet member's energy dropped below 25% of maximum after a hit.

function on_low_energy(ship_id)
    print("Low energy on " .. ship_id)
end

on_ship_module_deactivated(ship_id)

A module on a fleet member stopped running. Reasons include: asteroid mined out, cargo full, no energy, manual deactivation, target lost.

function on_ship_module_deactivated(ship_id)
    if fleet.is_cargo_full then
        fleet.dock(sector.get_closest_station_id())
    end
end

on_ship_docked(ship_id, station_id)

A fleet member docked at a station.

function on_ship_docked(ship_id, station_id)
    print("Member " .. ship_id .. " docked at " .. station_id)
end

on_ship_undocked(ship_id)

A fleet member undocked.

function on_ship_undocked(ship_id)
    print("Member " .. ship_id .. " is in space")
end

on_target_in_module_range(target_id)

A locked target entered module range.

function on_target_in_module_range(target_id)
    fleet.activate_all_modules(target_id)
end

on_target_destroyed(target_id, wreck_id)

A target one of the fleet's ships destroyed has been turned into a wreck.

function on_target_destroyed(target_id, wreck_id)
    print("Killed " .. target_id .. ", wreck " .. wreck_id)
end

Player Events

on_broadcast_received(source_id, message)

A ship owned by the same player called fleet.broadcast(message). Fires once per receiving fleet (deduped). Use fleet.contains(source_id) to skip your own fleet's broadcasts.

function on_broadcast_received(source_id, message)
    if fleet.contains(source_id) then return end
    if message == "sos" and not fleet.is_docked then
        local sender = player.get_ship_by_id(source_id)
        if sender then
            fleet.set_status("Responding to SOS")
            fleet.warp_to(sender.sector_id)
        end
    end
end

Not yet implemented