Server: CreateOilSpill(payload, creator, options)

All exports

Call these exports from a server script in your own resource, with sky_firejob started. They create or remove an incident when called. Automatic oil leaks after collisions or from wear need Sky Mechanic or another resource that detects the condition and calls Firejob.

The return formats and IDs differ between fire and oil exports:

creator, where accepted, is a player's current server ID (source). Use 0 or omit it for server-created incidents. It is separate from the vehicle network ID, fire ID, and oil spill ID.

Server Exports

CreateOilSpill(payload, creator, options)

Creates an active oil spill and synchronizes it to clients. Firejob assigns the spill ID; you do not generate or supply it.

This export returns two values. On success, the second value is a table containing the new ID at spill.id. On failure, the second value is an error string.

Create, keep the ID, and remove the spill later

This complete server-side example creates a spill, saves its ID, and removes that same spill after one minute. Replace the coordinates with your incident location. In a real incident system, keep the ID in your own incident state and remove it when that incident ends.

-- server.lua
local ok, spill_or_error = exports["sky_firejob"]:CreateOilSpill({
    coords = { x = 215.0, y = -810.0, z = 30.0 },
    source = "my_incident_resource",
    radius = 1.5,
    intensity = 0.9
}, 0)

if not ok then
    print(("Could not create oil spill: %s"):format(spill_or_error))
    return
end

local spill_id = spill_or_error.id -- e.g. "17"; this is the ID to save.
print(("Created oil spill %s"):format(spill_id))

SetTimeout(60000, function()
    local removed = exports["sky_firejob"]:RemoveOilSpill(spill_id, "incident_finished")
    if removed then
        print(("Removed oil spill %s"):format(spill_id))
    else
        print(("Oil spill %s could not be removed; it may already be gone."):format(spill_id))
    end
end)

For example, a successful call returns true followed by a table with these fields:

A failed call returns false, error:

Only read .id after checking ok. local spill = CreateOilSpill(...) would capture the first return value, a boolean, instead of the spill table.

Source grouping and limits

By default, calls from the same calling resource and the same payload.source share a cooldown and minimum-distance record. When payload.source is omitted, the export uses "external" for this grouping. Changing creator or sourceVehicleNetId alone does not create a separate source group.

For independent vehicle trails, set options.sourceKey to a stable key unique to your resource and that vehicle, such as "my_incident_resource:vehicle:123" for vehicle network ID 123. sourceKey groups creation limits; it is not a spill ID and is not included in GetOilSpills() results.

The shipped defaults are a 5-second cooldown, 6-metre spacing, 12 active spills per vehicle, and 80 active spills overall. Exceeding the overall limit removes the oldest spill to make room. The effective configuration can change these limits. Removing a spill does not clear its source group's last creation time or position, so immediately repeating the example may return cooldown or too_close.

Use overrides deliberately for scripted scenes that need them. These server exports do not run cleanup job, duty, or item checks for the calling resource.

Lifetime and saved IDs

Spills can disappear through cleanup, expiry, spreading, capacity limits, or explicit removal. The shipped lifetime is 90 minutes. Firejob attempts to save spills to its database; a successful creation return confirms an active synchronized spill, not a database-write acknowledgement. Database failures are logged separately.

Delete on restart is enabled by default. Disable it to restore unexpired saved spills after a resource restart. An explicit ID reset renumbers active spills, and cleared IDs may be reused later. Treat saved IDs as references to the current incident, not permanent identifiers. Use GetOilSpills() and your origin metadata when rebuilding an integration's state.