This documentation covers everything you need to get your script set up and working as intended. Please make sure to read it carefully—most issues can be avoided by following the steps provided. If all dependencies are installed correctly and you follow the instructions, your script will work as expected.

🛠 Need Support?

If you've followed the documentation and are still having issues, head over to our Discord and open a support ticket. The link is in the sidebar (bottom left). We’ll help you out once you’ve confirmed you've run through the docs.

🧩 Custom Work & Services

Looking for something more tailored to your server? We offer:

• ⚙️ Script optimisations and performance tweaks

• ⚒️ Creation of scripts from idea to production.

• 🎨 UI creation, edits, and complete redesigns

• 🧱 Custom features or systems built to your spec

If you’re after something beyond what's available out-of-the-box, open a ticket in Discord to discuss your requirements.

lib.callback.await

Call and await for a response of a server callback

-- Client
lib.callback.await(event, ...)
-- Server
lib.callback.await(event, playerId, ...)

lib.callback.register

Register a client callback, this can be used to easily request data from a client from the server

lib.callback.register(event, cb)

lib.await

Used to add a timed delay to the defined callback

lib.await(func, timeout)

Usage

The cache is simple to access, once you've followed the steps, you will be able to access the following values:

Cache Types

Accessing

You can simple called cache.x with whichever type you wish anywhere in your code, so long as dirk_lib is imported.

lib.onCache

All of the above cache types can be used with lib.onCache, this is essentially a listener that will trigger upon change of the value and at initial set.

🔑 Get your asset from Keymaster

After purchasing one of our scripts, head over to — this is where all of your purchased assets are managed.

Once logged in, click on "Purchased Assets", then locate the script you just bought.

From there, hit Download to grab the latest version.

📂 Installation Guide

If this is your first time installing a DirkScripts resource, we recommend creating a folder named:

Place all DirkScripts scripts and their dependencies inside this folder. This keeps everything organised and ensures proper start order.

Example structure:

Add the following to your server.cfg:

The best location is somewhere after your framework and it's dependencies start.

This approach helps avoid loading issues and makes updates easier down the line.

lib.blip.register

Register a new blip to be shown on the map

lib.blip.register(id, data)

lib.blip.get

Get a blip's data via it's id

local blip = lib.blip.get(id)

lib.blip.delete

Remove a blip from the map and cache

lib.blip.delete(id)

Data Structure

This is the data structure of a blip and the valid options

{
    -- Required
    pos = vector2(150.0, 100.0),    -- Used as the location on the map
    name = "Example Blip",          -- Label displayed on the map key
    sprite = 1,                     -- Sprite to be displayed
    display = 4,                    -- Display options
    scale = 1.0,                    -- Size of the blip
    color = 1,                      -- Color of the blip
    -- Not Required
    shortRange = false,             -- Is the blip short range
    category = 1,                   -- Category of the blip
    alpha = 255,                    -- Alpha (opacity) of the blip
    rotation = 0,                   -- Rotation
    route = false,                  -- Should the blip be routed to
    canSee = function()             -- Should the blip render
        return true
    end,                  
}

Useful Links

FiveM Blip Sprites Reference: https://docs.fivem.net/docs/game-references/blips/#blips

FiveM Native SetBlipDisplay Reference: https://docs.fivem.net/natives/?_0x9029B2F3DA924928

Fivem Blip Colour Reference: https://docs.fivem.net/docs/game-references/blips/#blip-colors

FiveM Native SetBlipCategory Reference: https://docs.fivem.net/natives/?_0x234CDD44D996FD9A

🚀 Quick Start

To get started, simply ensure dirk_lib is started after your framework, inventory, and targeting resources. There’s no complex setup—dirk_lib will automatically detect supported resources and apply the correct bridging logic for your setup.

No extra config needed—just ensure the dependencies are started before dirk_lib.

⚙️ Server Variables (Convars)

You can customize the behaviour of dirk_lib by setting server variables (ConVars). These can be placed in your server.cfg or follow the tip below for a cleaner way.

Developers

To get started with lib, include the shared script within your resource's fxmanifest.lua

You are able to select modules to be loaded, however they will also dynamically import. This can be done via the dirk_libsmanifest option

Bridging

This is a list of all the resources that this lib will bridge for, add your own by making a PR or contacting me on discord.

lib.request.model

Load a model with timeout checks

local success = lib.request.model(model, timeout)

lib.request.streamedTextureDict

Request texture dictionary

local success = lib.request.streamedTextureDict(txd, timeout)

Server

Client

setCharacterState

This will set the character state to one of the ones you have defined within settings/extras/characterStates

lib.objects.register

Create a new object

lib.objects.get

Get information regarding an object

lib.objects.destroy

Completely remove an object

Data Structure

This is the data structure of an object and the valid options

lib.print

Print some information to the console

lib.addPrintType

Add a new of print to be used

Converting Data from Older Version

Please grab your old projectCars.json and place it in the root directory of dirk_projectCars. The script will auto-detect it on startup and convert any old vehicles to the new SQL table.

Inventory Instructions

📤 OX_INVENTORY/DIRK_INVENTORY

In order for this to work you will need to add all the data in INSTALLATION/itemsToAdd/ox_items.lua to ox_inventory/data/items.lua

❓QB-INVENTORY

For all QB based inventory systems you can find the items in the following folder

INSTALLATION/itemsToAdd/qb_items.lua should you wish to manually add them

lib.target.box

Create a simple box zone

lib.target.box(id, data)

lib.target.polyzone

Create a polrzone

lib.target.polyzone(id, data)

lib.target.removeZone

Remove a created zone

lib.target.removeZone(id)

lib.target.entity

Create an entity and allow targeting

lib.target.entity(entity, data)

lib.target.removeEntity

Remove an entity zone

lib.target.removeEntity(entity, net)

logout [QBX|QBCore ONLY]

This will make the player sit down and wait for logout, this can be adjusted under settings.basic

lib.interact.register

Create a new player interaction

lib.interact.register(name, data)

lib.interact.get

Get information regarding an interaction

local interaction = lib.interact.get(name)

lib.interact.destroy

Completely remove an interaction

lib.interact.destroy(name)

Data Structure

This is the data structure of an interaction and the valid options

There are multiple different interactions seen below:

Circle

{
    zone_type = "circle",
    pos = vector4(10, 10, 20, 10),
    radius = 10
}

Poly

{
    zone_type = "poly",
    polygon = {
        vector3(0, 0, 0),
        vector3(0, 0, 0),
        vector3(0, 0, 0),
    },
}

Box

{
    zone_type = "box",
    pos = vector4(10, 10, 20, 10),
    size = vector3(1, 1, 1)
}

Marker

{
    zone_type = "marker",
    pos = vector4(10, 10, 20, 10),
    color = vector4(255, 255, 255, 255),            -- RGBA
    scale = vector3(1, 1, 1),
    -- Not Required
    dir = vector3(0, 0, 0),
    rot = vector3(0, 0, 0),
    bob = false,
    face = false,
    txd = false,
    txn = false,
    drawEnts = false
}

Text

{
    zone_type = "text",
    text = "Hello World"
    pos = vector4(10, 10, 20, 10),
    size = vector3(1, 1, 1)
}

📄 Fields:

💡 Example

A free, simple, and flexible store system for FiveM, styled natively and designed to be themed easily to fit your server’s aesthetic.

Features

• Default Stores Has most if not all of the default stores configured with basic items from major inventories/frameworks but is fully adjustable.

• Categories Optionally have categories for your stores for easier navigation.

• Metadata Generators Supports adding unique metadata to specific items, even if your inventory system doesn’t handle it natively.

• Group/License Locking Lock the entire store or certain items to different groups or licenses within your city.

• Payment Methods Easily add new payment methods to use in any store via the settings/paymentMethods.lua. Here you can define an add and a remove function to implement any sort of currency you wish.

• Dynamic Store Creation Register new stores at runtime from the server, giving you complete control over when and where stores appear.

• Theming Change the color scheme globally or per store. Don't like green? Pick something that matches your vibe. To set a new global theme for all dirk_scripts see

lib.table.deepClone

Used to quickly copy a table, useful for global state values

lib.table.findKeyInTable

Check through a table for a set key

lib.table.includes

Check if a value is present in a table

lib.table.convert

Convert data to different formats

lib.table.count

Count a table and sub tables

Server

registerStore

Dynamically creates a store at runtime, syncing to all clients for use straight away, when the resource that creates it is stopped the store will be deleted and unregistered from all clients. The storeData parameter is based upon the .

Example

This will spawn a very basic shop with a store clerk at the coordinates listed.

You can allow players to purchase labs via tebex instead of in-game for some labs should you wish players can join the server after purchase and use the Config.RedeemCommand (/ClaimLab) in order to claim their new lab this will give them keys into their inventory and ownership.

First you will need to ensure you have linked your tebex to your FiveM server there are many guides for this on Google. You will then need to make a new package with the deliverable product being a Game Server command setup like so: The name of this package you create must be the name of the index of the lab in the config. So in the example below it would have to be "Downtown Cocaine Lab"

    ['Downtown Cocaine Lab'] = { --## Private Owned
      Door  = vector4(184.57171630859,-1514.0261230469,29.318643569946,225.4059753418), 
      Shell = "Cocaine High End Shell", -- Can be false or can be model name of a shell


      TebexPackage = 'https://www.dirkscripts.com/category/resources', --## This will not be useable until claimed. Please read the documentation provided on how to setup tebex packages. --- Access.Ownable must be a number but it doesnt matter which number it is if this is a tebex package you can set this to the link to the package see docs

      TeamWorkMode = false, --## If this is true required items will come from the shared stockpile and reward items will also go here
      KeyItem      = nil, --## This could be a name of an item if you wanted a different item to be the key for this lab :thinking: It'll still need metadata attached via the script
      
      Access = {
        Ownable = 50000, --## Will make this buyable and have key access -- Probably leave Gangs, Jobs and Public as false. Can be false also
        KeyCode = false, --## Do you want a keycode to access this? -- This will overwrite everything else
        Public  = false, 
        Gangs   = false, --## Gangs can access this lab
        Jobs    = false, --## Gangs can access this lab
      },


      IngOrders = {
        Price        = 5000, 
        DropPoint    = vector4(171.79383850098,-1517.9276123047,29.141628265381,135.28630065918), 
        Items = {
          rawcocaine   = 50, 
          bakingsoda   = 50, 
          actionfigure = 25,  
        },
      },

      Blip = { --## Delete this blip table if you don't want a blip
        Scale   = 0.75, 
        Sprite  = 497, 
        Color   = 45,
        Display = 4,
        Close  = true, --## Will only show this on the minimap when you are close to the lab forcing players to drive around and try find it. 
      },

      Stages = {
        [1] = {
          Position      = vector4(4.825562, -3.003174, -2.673802, 179.7306060791),
          Label         = "Cut Cocaine",
          Icon          = "fa-solid fa-scissors",
          
          FancyScene    = "Cut Cocaine", --# This can be one of the scenes from Config.Scenes or it can be false and you can use a regular animation
          NormalAnim    = false, --## Can be false or can be a table like so {anim = "anim_b", dict = "dict_a", time = 15000}
          RequiredItems = {
            rawcocaine = 3, 
            bakingsoda = 2, 
          },
          RewardItems   = {
            cutcocaine = 2, 
          },
        },
        [2] = {
          Position      = vector4(3.890869, -0.5727539, -2.673793,359.83615112305),
          Label         = "Cut Cocaine",
          Icon          = "fa-solid fa-scissors",
          
          FancyScene    = "Cut Cocaine", --# This can be one of the scenes from Config.Scenes or it can be false and you can use a regular animation
          NormalAnim    = false, --## Can be false or can be a table like so {anim = "anim_b", dict = "dict_a", time = 15000}
          RequiredItems = {
            rawcocaine = 3, 
            bakingsoda = 2, 
          },
          RewardItems   = {
            cutcocaine = 2, 
          },
        },
        [3] = {
          Position      = vector4(4.125854, 3.231079, -2.673817,0.0),
          Label         = "Package Cocaine",
          Icon          = "fa-solid fa-box-archive",
          
          FancyScene    = "Package Cocaine", --# This can be one of the scenes from Config.Scenes or it can be false and you can use a regular animation
          NormalAnim    = false, --## Can be false or can be a table like so {anim = "anim_b", dict = "dict_a", time = 15000}
          RequiredItems = {
            cutcocaine   = 1, 
            actionfigure = 1, 
          },
          RewardItems   = {
            cocainepackage = 1, 
          },
        },
      },
    },

lib.player.get

Get the player's information

local player = lib.player.get(source)

lib.player.identifier

Returns the identifier (CitizenID) of the player

local citizenid = lib.player.identifier(src)

lib.player.name

Returns the name of the character

local firstName, lastName = lib.player.name(src)

lib.player.phone_number

Return the phone number of the character

local phoneNumber = lib.player.phone_number(src)

lib.player.gender

Return the gender of the character

local gender = lib.player.gender(src)

lib.player.checkOnline

Check if a player is online by their CitizenID

local isOnline = lib.player.checkOnline(identifier)

lib.player.jail

Send a player to jail

lib.player.jail(trg, data)

lib.player.addMoney

Add money to a player

lib.player.addMoney(src, acc, amount, reason)

lib.player.removeMoney

Remove money to a player

lib.player.removeMoney(src, acc, amount, reason)

lib.player.addItem

Add item to a player

lib.player.addItem(src, item, amount, md, slot)

lib.player.removeItem

Remove an item for a player

lib.player.removeItem(src, item, amount, md, slot)

lib.player.editItem

Edit the metadata of an item

lib.player.editItem(src, slot, new_data)

lib.player.getInventory

Returns the inventory of the player

local inventory = lib.player.getInventory(src)

Example Return:

{
    {
        name = "example",
        label = "Example Item",
        count = 10,
        info = {
            metadata = true,
        },
        slot = 1
    }
}

📄 Fields:

💡 Example

luaCopyEditparts = {
    oil_filter = {
        label        = "Oil Filter",
        searchChance = 15,
        weight       = 250,
        tools        = { wrench = 1 },
        consumables  = { oil = 1 },
        anim         = {
            dict  = "anim@amb@clubhouse@tutorial@bkr_tut_ig3@",
            clip  = "machinic_loop_mechandplayer",
            flag  = 16,
            time  = 5
        },
        reqParts     = { "engine_cover" },
        model        = "prop_oilcan_01a",
        applyRange   = 2.0,
        applyAtBone  = "engine",
        canStart     = function(installed, part)
            return installed, installed and "" or "Engine won't start without oil filter."
        end,
        removePart   = function(self, entity, part)
            -- custom logic to clean up or detach
        end,
        addPart      = function(self, entity, part)
            -- apply tuning or set vars
        end
    }
}

Dependencies

• dirk_lib (REQUIRED)

Items

There is a folder within the script called 'install' within that is another folder called 'itemsToAdd' please choose the format you require for your framework/inventory

lib.zones.register

Create a new zone

lib.zones.register(id, data)

Zone Examples

lib.zone.register("exampleZone", {
    type = "circle",
    pos = vector3(0, 0, 0),
    radius = 5.0,
    onEnter = function(data)
        lib.print("debug", "Entered Zone")
    end,
    onExit = function(data)
        lib.print("debug", "Exited Zone")
    end,
})

lib.zone.register("exampleZone", {
    type = "circle2D",
    pos = vector2(0, 0),
    radius = 5.0,
    onEnter = function(data)
        lib.print("debug", "Entered Zone")
    end,
    onExit = function(data)
        lib.print("debug", "Exited Zone")
    end,
})

local polyPoints = {
    vector2(0, 0),
    vector2(10, 10),
    vector2(20, 20),
    vector2(0, 30),
    vector2(-10, 15),
}

lib.zone.register("exampleZone", {
    type = "poly",
    pos = polyPoints,
    onEnter = function(data)
        lib.print("debug", "Entered Zone")
    end,
    onExit = function(data)
        lib.print("debug", "Exited Zone")
    end,
})

lib.zone.register("exampleZone", {
    type = "box",
    pos = vector4(0, 0, 0, 0),
    size = vector3(0, 0, 0),
    onEnter = function(data)
        lib.print("debug", "Entered Zone")
    end,
    onExit = function(data)
        lib.print("debug", "Exited Zone")
    end,
})

lib.zone.register("exampleZone", {
    type = "game_zone",
    gameZone = "ALTA"
    onEnter = function(data)
        lib.print("debug", "Entered Zone")
    end,
    onExit = function(data)
        lib.print("debug", "Exited Zone")
    end,
})

lib.zones.get

Get zone information

local zone = lib.zones.get(name)

lib.zones.delete

Remove a created zone

lib.zones.delete(name)

lib.zones.isInsideZone

Check whether a position lies inside a zone(s)

local isInside, zoneName = lib.zones.isInsideZone(name, pos)

Data Structure

This is the data structure of a blip and the valid options

{
    -- Required
    type = "circle",            -- Type of zone: circle, circle2D, poly, box, game_zone                 
    -- Not Required
    onEnter = function(data)
        -- Callback for entering the zone
    end,
    onExit = function(data)
        -- Callback for exiting the zone
    end,
}

Some zones have different requirements, see below:

{
    pos = vector3(0, 0, 0),   -- Position of the zone
    radius = 5.0,             -- Size of the zone radially from the point
}

{
    pos = vector2(0, 0),      -- Position of the zone
    radius = 5.0,             -- Size of the zone radially from the point
}

{
    points = {                -- Boundy marks for the polyzone
        vector2(0, 0),
        vector2(2, 1),
        vector2(3, 3),
    }
}

{
    pos = vector4(0,0,0,0),      -- Position of the zone, x, y, z, heading
    size = vector3(0,0,0)        -- Size of the zone from the center point
}

{
    gameZone = "ALTA"
}

Server

Client

📄 Fields:

💡 Example

BaseStores = BaseStores or {}
BaseStore.gunshop = {
    id          = "gunshop",
    type        = "buy",
    name        = "Ammu-Nation",
    description = "Everything you need to stay protected.",
    icon        = "fa-solid fa-gun",
    modelType   = "ped",
    models      = { "s_m_m_ammucountry" },
    locations   = {
        vec4(17.8, -1108.6, 29.8, 160.0)
    },
    paymentMethods = { "cash", "bank" },
    categories  = { 
        {
            
        }
    },
    stock       = {
        { item = "pistol", price = 2500 },
        { item = "pistol_ammo", price = 100 }
    },
    openingHours = { 9, 21 },
    groups       = { police = 0, sheriff = 0 },
    licenses     = { "weapon_license" },
    canOpen      = function(src)
        return true
    end,
    onExchange   = function(src, items, price)
        if price > 10000 then
            return false, "Transaction limit exceeded"
        end
        return true
    end
}

projectCar:deleteNearest

Will delete the nearest projectCar entirely from the database and the world.

projectCar:completeNearest

Will complete the nearest projectCar requiring the player to just get in and start it

projectCar:giveEngine

This will give you an engine with the correct metadata dependant on the class you supply.

projectCar:allItems

Will give you all the items you need to complete a car.