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.

🔑 Get your asset from Keymaster

After purchasing one of our scripts, head over to keymaster.fivem.net — 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:

[dirk]

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

Example structure:

resources/
└── [dirk]/
    ├── dirk_inventory
    ├── dirk_traphouse
    └── dirk_dependencies

Add the following to your server.cfg:

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

ensure [dirk]

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

🚀 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.await

Used to add a timed delay to the defined callback

lib.await(func, timeout)

Server

Client

logout [QBX|QBCore ONLY]

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

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.

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

lib.table.deepClone

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

local copiedTable = lib.table.deepClone(table)

lib.table.findKeyInTable

Check through a table for a set key

local foundData = lib.table.findKeyInTable(tbls, key)

lib.table.includes

Check if a value is present in a table

local found = lib.table.includes(table, value, recursive)

lib.table.convert

Convert data to different formats

local data = lib.table.convert(_type, data)

lib.table.count

Count a table and sub tables

local count = lib.table.count(table)

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

['windscreen'] = {
  ['weight'] = 1000,
  ['label'] = 'Windscreen',
},

❓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

['windscreen'] = {
  ['description'] = 'Vehicle Part',
  ['useable'] = true,
  ['weight'] = 1000,
  ['shouldClose'] = false,
  ['type'] = 'item',
  ['label'] = 'Windscreen',
  ['unique'] = false,
  ['name'] = 'windscreen',

},

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)

setCharacterState

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

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

Usage

The cache is simple to access, once you've followed the Getting Started 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.

  -- We can replace 'cuffed' with any of the values from above.
  lib.onCache('cuffed', function(isCuffed, oldValue)
    print(('Player is now cuffed: %s\nPlayer was cuffed before: %s'):format(isCuffed, oldValue))
  end)
  -- OR IF YOU REALLY WANTED--
  AddEventHandler("dirk_lib:cache:cuffed", function(isCuffed, oldValue)
    print(('Player is now cuffed: %s\nPlayer was cuffed before: %s'):format(isCuffed, oldValue))
  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

📄 Fields:

💡 Example

tools = {
    wrench = {
        label         = "Wrench",
        weight        = 1000,
        description   = "A sturdy wrench for basic repairs.",
        chanceOfBreak = 25, -- 25% chance of breaking
        holdRotation  = vector3(90.0, 0.0, 0.0),
        holdOffset    = vector3(0.0, -0.15, -0.02),
        model         = "prop_tool_wrench",
        strength      = 2000,
        useable       = function(src)
            -- custom usage logic here
        end
    }
}

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)

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 dirk_lib convars

lib.player.get

Get the player's information

lib.player.identifier

Returns the identifier (CitizenID) of the player

lib.player.name

Returns the name of the character

lib.player.phone_number

Return the phone number of the character

lib.player.gender

Return the gender of the character

lib.player.checkOnline

Check if a player is online by their CitizenID

lib.player.jail

Send a player to jail

lib.player.addMoney

Add money to a player

lib.player.removeMoney

Remove money to a player

lib.player.addItem

Add item to a player

lib.player.removeItem

Remove an item for a player

lib.player.editItem

Edit the metadata of an item

lib.player.getInventory

Returns the inventory of the player

Example Return:

lib.zones.register

Create a new zone

Zone Examples

lib.zones.get

Get zone information

lib.zones.delete

Remove a created zone

lib.zones.isInsideZone

Check whether a position lies inside a zone(s)

Data Structure

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

Some zones have different requirements, see below:

📄 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
    }
}

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

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
}

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 StoreProps.

Example

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

local storeData = {
    id = 'myNewTestStore', 
    type = 'buy', 
    name = 'My Test Store', 
    description = 'My Short Test Description', 
    icon        = 'fas fa-store', 
    modelType   = 'ped', 
    models      = {'mp_m_shopkeep_01'}, 
    locations   = {
        vector4(0,0,0,0),
    },
    paymentMethods = {'cash', 'bank'}, 
    stock = {
        {
          name = 'bread',  
          price = 100, 
        }
    },
}

exports.dirk_stores:registerStore(storeData)

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"

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)