REQUEST_NAMED_PTFX_ASSET — How to load Particle Dictionary

Before using any Particle Effect in FiveM always load the dictionary first — this is why the effect disappears or does not appear.

Why must you download?

GTA V stores particle assets in streaming pools — not all of them are loaded in memory all the time. If you run the effect without loading the dictionary first, the game will be silent and not display anything.

Native Functions

-- Load dictionary
RequestNamedPtfxAsset(assetName) -- string

-- Check if it has been downloaded or not.
HasNamedPtfxAssetLoaded(assetName) -- returns bool

-- delete from memory
RemoveNamedPtfxAsset(assetName)

-- Set assets for next call
UseParticleFxAssetNextCall(assetName)

Standard Pattern

local function SafeRequestPtfx(assetName, timeout)
  timeout = timeout or 5000 -- default 5 seconds

  -- Check if it has been loaded or not.
  if HasNamedPtfxAssetLoaded(assetName) then
    return true
  end

  RequestNamedPtfxAsset(assetName)

  local startTime = GetGameTimer()
  while not HasNamedPtfxAssetLoaded(assetName) do
    if GetGameTimer() - startTime > timeout then
      print("[PTFX] Timeout loading: " .. assetName)
      return false
    end
    Citizen.Wait(0)
  end

  return true
end

Usage

local function PlayEffect(effectName, dictName, coords, scale)
  -- Load dictionary with safe pattern.
  if not SafeRequestPtfx(dictName) then
    return -- Unable to load — skip
  end

  -- Important: You must call before starting effect every time.
  UseParticleFxAssetNextCall(dictName)

  StartParticleFxNonLoopedAtCoord(
    effectName,
    coords.x, coords.y, coords.z,
    0.0, 0.0, 0.0,
    scale or 1.0,
    false, false, false
  )
end

Preload vs On-Demand

On-Demand (load when used)

-- suitable for effects that are used infrequently
local function PlayExplosion(coords)
  RequestNamedPtfxAsset("scr_rcbarry2")
  while not HasNamedPtfxAssetLoaded("scr_rcbarry2") do
    Citizen.Wait(0)
  end
  UseParticleFxAssetNextCall("scr_rcbarry2")
  StartParticleFxNonLoopedAtCoord("scr_exp_clown_explode", ...)
  RemoveNamedPtfxAsset("scr_rcbarry2")
end

Preload

-- suitable for frequently used effects
local loadedAssets = {}

local function PreloadAssets()
  local assets = {"core", "scr_powerplay"}
  for _, assets in ipairs(assets) do
    RequestNamedPtfxAsset(asset)
    loadedAssets[asset] = true
  end
end

-- called resource start
Citizen.CreateThread(function()
  PreloadAssets()
  -- Wait for the download to finish.
  Citizen.Wait(1000)
end)

Memory Management

-- View the currently loaded dictionary (debug)
local function ListLoadedAssets(assetList)
  for _, name in ipairs(assetList) do
    print(name .. ": " .. tostring(HasNamedPtfxAssetLoaded(name)))
  end
end

-- Cleanup when resource stops
AddEventHandler("onResourceStop", function(resourceName)
  if resourceName == GetCurrentResourceName() then
    RemoveNamedPtfxAsset("core")
    RemoveNamedPtfxAsset("scr_powerplay")
  end
end)

Summary