Developer Exports

This page serves to outline and explain the functions offered by Zea Developments' z_fire resource. These functions are designed for the purpose of collecting existing data or storing new data.

---

Client Exports

IsEntityOnFire

Description: Returns a boolean indicating whether the specified entity currently has an active fire attached to it.

Parameters: entity_handle (integer) – The entity handle to check for an active fire.

Returns: success (boolean) – true if the entity is on fire, false otherwise.

Example:

local success = exports['z_fire']:isEntityOnFire(entity_handle)

---

deleteFires

Description: Removes the specified fire(s) from the world using their unique identifiers.

Parameters: fire_ids (table) – A table containing one or more fire IDs to delete.

Returns: success (boolean) – true if the fires were successfully deleted, false otherwise.

Example:

local success = exports['z_fire']:deleteFires(fire_ids)

---

deleteFireById

Description: Removes a single fire instance from the world using its unique identifier.

Parameters: fire_id (string) – The unique ID of the fire to delete.

Returns: success (boolean) – true if the fire was successfully deleted, false otherwise.

Example:

local success = exports['z_fire']:deleteFireById(fire_id)

---

deleteSmokeById

Description: Deletes a smoke effect using its unique identifier. Returns true if the smoke was successfully removed, or false if the ID is invalid.

Parameters:

• smoke_id (string) – The unique ID of the smoke to delete.

Returns:

• success (boolean) – true if the smoke was successfully deleted, false otherwise.

Example:

local success = exports['z_fire']:deleteSmokeById(smoke_id)

---

getFiresInRange

Description: Returns a table of all active fires located within a specified distance from a given world position. If no fires are found, an empty table is returned.

Parameters:

• world_pos (vector3) – The world position to search from.

• range (number) – The radius (in meters) to search for fires around the world_pos.

Returns:

• found_fires (table) – A table containing fire IDs of all fires found within the specified range.

Example:

local found_fires = exports['z_fire']:getFiresInRange(world_pos, range)

---

getSmokeInRange

Description: Returns a table of all active smoke effects located within a specified distance from a given world position. If no smoke is found, an empty table is returned.

Parameters:

• world_pos (vector3) – The center world position to search from.

• range (number) – The radius (in meters) to search for smoke around the world_pos.

Returns:

• found_smoke (table) – A table containing smoke IDs of all smoke effects found within the specified range.

Example:

local found_smoke = exports['z_fire']:getSmokeInRange(world_pos, range)

---

getClosestFire

Description: Finds and returns the closest active fire to the specified world position. If a fire is found, the function returns its ID, associated data, and distance from the given position.

Parameters:

• world_pos (vector3) – The world position to search from.

Returns:

• fire_id (string or nil) – The ID of the closest fire, or nil if none found.

• fire_data (table or nil) – The fire’s associated data, or nil if none found.

• distance (number or nil) – The distance to the closest fire, or nil if none found.

Example:

local fire_id, fire_data, distance = exports['z_fire']:getClosestFire(world_pos)

---

getClosestSmoke

Description: Finds and returns the closest active smoke effect to the specified world position. If smoke is found, the function returns its ID, associated data, and distance from the given position.

Parameters:

• world_pos (vector3) – The world position to search from.

Returns:

• smoke_id (string or nil) – The ID of the closest smoke, or nil if none found.

• smoke_data (table or nil) – The smoke’s associated data, or nil if none found.

• distance (number or nil) – The distance to the closest smoke, or nil if none found.

Example:

local smoke_id, smoke_data, distance = exports['z_fire']:getClosestSmoke(world_pos)

---

setPlayerDuty

Description: Sets the player's duty status for a specified department. Validates input and triggers a server event if the data is correct.

Parameters:

• duty_status (boolean) – Whether the player should be set on duty (true) or off duty (false).

• department_abbr (string) – The abbreviated name of the department to set duty for (must match a configured department).

Returns:

• success (boolean) – Returns true if the request was valid and the duty change event was triggered, false otherwise.

Example:

local success = exports['z_fire']:setPlayerDuty(true, "LSFD")

---

createFire

Description: Creates a new fire instance in the world using the provided fire data. Supports multiple fire behavior types including structure, grass, prop, and vehicle fires. When targeting an entity (e.g., vehicle or prop), the fallbackPos field is required.

Parameters:

• fire_data (table) – A table defining the fire's particle data, behavior, and additional options. • ptfxData (table) – Particle effect data - type (string) – The particle effect type (e.g., "normal2") - pos (vector3) – The position or offset for the fire - scale (number) – The scale of the fire effect - fallbackPos (vector3) – Required for props and vehicles; world coordinates fallback • behaviourType (string) – Type of fire ("interior", "grass", "prop", or "vehicle") • canSpread (boolean) – Whether the fire can spread • spreadSize (number) – The radius the fire can spread to • burnoutTime (number) – Time (in seconds) before the fire burns out • roomHash (integer) – (Only for interior fires) Room hash for spreading logic • networkEntity (integer) – (Only for prop/vehicle fires) Entity to attach the fire to • origin (table) – Origin metadata - is (boolean) – Whether this is the origin fire - id (string or nil) – The ID of the origin fire, if any

Returns:

• uuid (string or nil) – A unique identifier for the created fire, or nil if creation failed.

Examples:

Interior Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {type = 'normal2', pos = vector3(1988.87, 3048.00, 47.21), scale = 1.0},
    behaviourType = 'interior',
    canSpread = true,
    spreadSize = 100,
    roomHash = -576181983,
    burnoutTime = 999,
    origin = {is = true, id = nil}
})

Grass Fire

 local uuid = exports['z_fire']:createFire({
    ptfxData = {type = 'normal2', pos = vector3(1988.87, 3048.00, 47.21), scale = 1.0},
    behaviourType = 'grass',
    canSpread = true,
    spreadSize = 100,
    burnoutTime = 999,
    origin = {is = true, id = nil}
})

Prop Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(0.1, 1.0, 0.1),
        scale = 1.0,
        fallbackPos = vector3(0.0, 0.0, 0.0)
    },
    behaviourType = 'prop',
    canSpread = true,
    spreadSize = 100,
    networkEntity = 123,
    burnoutTime = 999,
    origin = {is = true, id = nil}
})

Vehicle Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(0.1, 1.0, 0.1),
        scale = 1.0,
        fallbackPos = vector3(0.0, 0.0, 0.0)
    },
    behaviourType = 'vehicle',
    canSpread = true,
    spreadSize = 100,
    networkEntity = 123,
    burnoutTime = 999,
    origin = {is = true, id = nil}
})

---

createSmoke

Description: Creates a smoke effect in the world using the provided data. Can optionally attach the smoke to a networked entity and configure dispersal behavior.

Parameters:

• smoke_data (table) – A table defining the smoke’s particle data and behavior: • ptfxData (table) – Particle effect data - type (string) – The particle effect type (e.g., "linger1") - pos (vector3) – The position where the smoke should spawn - scale (number) – The scale of the smoke effect • networkEntity (integer or nil) – Optional networked entity ID to attach the smoke to • canDisperse (boolean) – Whether the smoke is allowed to disperse over time

Returns:

• uuid (string or nil) – A unique identifier for the smoke effect, or nil if creation failed.

Example Usage:

local uuid = exports['z_fire']:createSmoke({
    ptfxData = {
        type = 'linger1',
        pos = vector3(1883.354, 2681.788, 45.671),
        scale = 1.0
    },
    networkEntity = nil,
    canDisperse = true
})

---

Server Exports

isPlayerOnDuty

Description: Checks whether a specified user (by source ID) is currently marked as on duty in any registered department.

Parameters:

• source_user (integer) – The server ID of the player to check.

Returns:

• is_on_duty (boolean) – Returns true if the player is currently on duty, false otherwise.

Example:

local is_on_duty = exports['z_fire']:isPlayerOnDuty(source_user)

---

setPlayerDuty

Description: Sets or removes a player's duty status for a given department. Returns a boolean indicating success or failure, and an optional status code describing the result.

Parameters:

• source_id (string) – The server ID of the player.

• department_abbr (string) – The abbreviated name of the department.

• set_status (boolean) – true to place the player on duty, false to remove them from duty.

Returns:

• success (boolean or nil) – true if the operation was successful, nil otherwise.

• code (integer) – A status code providing context about the result.

Status Codes:

Code	Meaning
0	Operation successful
1	Department not found
2	Player was not on duty when trying to remove
3	Player is already on duty in another dept

local success, code = exports['z_fire']:setPlayerDuty(source_id, "LSFD", true)

if success then
    print("Player successfully put on duty.")
else
    print("Failed to set duty status. Code:", code)
end

---

createFire

Description: Creates a fire instance in the world using the provided configuration. If a valid source (player ID) is not provided, the system will select a random valid player to associate with the fire. This function supports all behavior types, including interior, grass, prop, and vehicle fires.

Parameters:

• fire_data (table) – A structured table defining the fire's appearance and behavior.

• source (integer) – (Optional) The source player ID. If nil or -1, the system automatically assigns a random valid player with a working ping.

Returns:

• uuid (string or nil) – The unique identifier for the created fire, or nil if creation failed.

fire_data Table Structure:

Field	Type	Description
ptfxData	table	Particle effect data:
- type (string) – Particle type, e.g., "normal2"
- pos (vector3) – Position or offset for the fire
- scale (number) – Scale of the particle effect
- fallbackPos (vector3) – Required for prop and vehicle types; world position fallback
behaviourType	string	One of: "interior", "grass", "prop", or "vehicle"
canSpread	boolean	Whether the fire can spread
spreadSize	number	The radius for potential spread
burnoutTime	number	Time in seconds until the fire auto-extinguishes
roomHash	integer	(For interior fires only) GTA room hash
networkEntity	integer	(For prop/vehicle fires) The network entity ID
origin	table	Origin info:
- is (boolean) – Whether this is an origin fire
- id (string or nil) – Parent fire ID if applicable

Examples:

Interior Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(1988.87, 3048.00, 47.21),
        scale = 1.0
    },
    behaviourType = 'interior',
    canSpread = true,
    spreadSize = 100,
    roomHash = -576181983,
    burnoutTime = 999,
    origin = {is = true, id = nil}
}, source)

Grass Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(1988.87, 3048.00, 47.21),
        scale = 1.0
    },
    behaviourType = 'grass',
    canSpread = true,
    spreadSize = 100,
    burnoutTime = 999,
    origin = {is = true, id = nil}
}, source)

Prop Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(0.1, 1.0, 0.1),
        scale = 1.0,
        fallbackPos = vector3(0.0, 0.0, 0.0)
    },
    behaviourType = 'prop',
    canSpread = true,
    spreadSize = 100,
    networkEntity = 123,
    burnoutTime = 999,
    origin = {is = true, id = nil}
}, source)

Vehicle Fire

local uuid = exports['z_fire']:createFire({
    ptfxData = {
        type = 'normal2',
        pos = vector3(0.1, 1.0, 0.1),
        scale = 1.0,
        fallbackPos = vector3(0.0, 0.0, 0.0)
    },
    behaviourType = 'vehicle',
    canSpread = true,
    spreadSize = 100,
    networkEntity = 123,
    burnoutTime = 999,
    origin = {is = true, id = nil}
}, source)

---

createSmoke

Description: Creates a smoke effect in the world using the provided configuration. Can optionally be attached to a networked entity and supports automatic dispersal over time.

Parameters:

• smoke_data (table) – Configuration table for the smoke instance. • ptfxData (table) – Particle effect data: - type (string) – The particle effect type (e.g., "linger1") - pos (vector3) – World position to spawn the smoke - scale (number) – Scale of the smoke effect • networkEntity (integer or nil) – Optional networked entity ID to attach the smoke to • canDisperse (boolean) – Whether the smoke is allowed to disperse over time

Returns:

• uuid (string or nil) – A unique identifier for the created smoke effect, or nil if creation failed.

Example:

local uuid = exports['z_fire']:createSmoke({
    ptfxData = {
        type = 'linger1',
        pos = vector3(1883.354, 2681.788, 45.672),
        scale = 1.0
    },
    networkEntity = nil,
    canDisperse = true
})

---

extinguishFire

Description: Extinguishes the specified fires by their unique IDs. Triggers the internal extinguishment logic and removes the fire effects from the world.

Parameters:

• fires_to_extinguish (table) – A table containing one or more fire IDs to extinguish.

Returns:

• (none) – This export does not return a value.

Example:

local fires_to_extinguish = {
    "fire_a8f73b2",
    "fire_b29e3d9",
    "fire_c1c8e72"
}

exports['z_fire']:extinguishFire(fires_to_extinguish)

---

getAllFires

Description: Returns a table containing all currently active fires tracked by the system.

Returns:

• fires (table) – A table of all active fire instances. Each entry typically includes metadata such as ID, position, behavior type, and more.

Example:

local all_fires = exports['z_fire']:getAllFires()

for id, fire in pairs(all_fires) do
    print(("Fire ID: %s at position: %s"):format(id, tostring(fire.ptfxData.pos)))
end

---

getAllFires

Description: Returns a table containing all currently active fires tracked by the system.

Returns:

• fires (table) – A table of all active fire instances. Each entry typically includes metadata such as ID, position, behavior type, and more.

Example:

local all_fires = exports['z_fire']:getAllFires()

for id, fire in pairs(all_fires) do
    print(("Fire ID: %s at position: %s"):format(id, tostring(fire.ptfxData.pos)))
end

---

GetFiresInRange

Description: Returns a list of all active fires located within a specified range of a world position. Fires attached to entities will use their fallbackPos for distance calculation.

Parameters:

• world_position (vector3) – The central position from which to search for nearby fires.

• range (number) – The radius (in meters) to search within. Defaults to 5.0 if not specified.

Returns:

• detected_fires (table or nil) – A table of fires within range. Each entry includes: - id (string) – The unique ID of the fire - data (table) – The full fire data table associated with that fire

Example:

local firesNearby = exports['z_fire']:getFiresInRange(vector3(200.0, 300.0, 45.0), 10.0)

for _, fire in pairs(firesNearby) do
    print(("Found fire ID %s at pos %s"):format(fire.id, tostring(fire.data.ptfxData.pos)))
end

---

deleteFires

Description: Deletes multiple fires from the world using a table of fire entries. Accepts a table where each item contains a fire id field.

Parameters:

• fire_table (table) – A table of fire entries to delete. Each entry must include an id field (usually returned by getFiresInRange, etc.).

Returns:

• success (boolean) – true if the input was valid and the delete event was triggered, false otherwise.

Example:

local firesNearby = exports['z_fire']:getFiresInRange(vector3(200.0, 300.0, 45.0), 10.0)
local success = exports['z_fire']:deleteFires(firesNearby)

if success then
    print("All nearby fires deleted.")
else
    print("Failed to delete fires. Invalid input.")
end

---

getAllSmoke

Description: Returns a table containing all currently active smoke effects tracked by the system.

Returns:

• smoke_table (table) – A table of all active smoke instances. Each entry typically includes the smoke's ID, particle data, attachment info, and behavior settings.

Example:

local all_smoke = exports['z_fire']:getAllSmoke()

for id, smoke in pairs(all_smoke) do
    print(("Smoke ID: %s at position: %s"):format(id, tostring(smoke.ptfxData.pos)))
end

---

getSmokeInRange

Description: Searches for and returns all smoke effects located within a specified range of a world position.

Parameters:

• world_position (vector3) – The center point of the search area.

• range (number) – The radius (in meters) to search. Defaults to 5.0 if nil.

Returns:

• detected_smoke (table or nil) – A table of smoke entries found within the given range. Each entry contains: - id (string) – The unique ID of the smoke - data (table) – The full data structure for that smoke effect

Example Usage:

local nearbySmoke = exports['z_fire']:getSmokeInRange(vector3(100.0, 200.0, 30.0), 10.0)

for _, smoke in pairs(nearbySmoke) do
    print(("Smoke ID: %s, scale: %.1f"):format(smoke.id, smoke.data.ptfxData.scale))
end

---