Import Modules

dependencies { 'tLib' }

shared_scripts {
    '@tLib/imports.lua',
}

local kvp = tlib.kvp

Modules load on first access, so you declare nothing.

Declaring modules

tlib_modules { 'coords', 'kvp' } still works and makes a load eager, which fails at boot on a module that does not compile. Both spellings are accepted (tlib_module, tlib_modules).

occupancy and telemetry are in AUTOLOAD and load themselves in every consumer. telemetry defaults to studio-authored resources; declare it to opt in.

access

Decides who may use your resource, on the server, the way the owner configures — ACE, job, inventory item or their own function, all one shape.

Config.access = {
    mode = "item",          -- everyone | ace | job | item | custom; a list passes if EITHER does
    ace  = "tdetector.use",
    job  = { police = 0, sheriff = 2 },   -- job = MINIMUM grade
    item = "radar_detector",
    count = 1,                            -- how many of `item`; default 1
    custom = function(src) return false end,
}

local gate = tlib.access.gate(Config.access, { key = 'detector', label = 'the detector' })

RegisterNetEvent('tDetector:deploy', function()
    if not gate:allowed(source) then return end
end)

The client half draws UI only:

local gate = tlib.access.gate({ key = 'detector' })   -- same key as the server

if gate:allowed() then showButton() end
gate:onChange(function(allowed) toggleButton(allowed) end)
gate:refresh()   -- after going on duty, picking the item up

• It fails closed, always. An absent, unstarted or throwing framework denies; a custom that errors or returns a truthy non-boolean denies; an unset ACE denies; a gate with config errors denies everyone and says why.
• problems(block, label, env) with env = false catches file mistakes, which disable the gate. env = true catches mode = 'job' with no framework — never check that at startup, because an unstarted framework is indistinguishable from a missing one and the gate starts passing by itself when it appears.
• registerFramework takes { name, detect, jobs } and must be called from a server_script, not the shared config.lua. jobs returns a map of job → grade, so a player who is both police and sheriff is expressible. Under escrow, keep one server file in escrow_ignore for it.

• The axes are independent, so nat2k15 for jobs beside ox_inventory for items works, as does an item gate with no framework.
• Detection needs the resource started, not present, and reruns whenever any resource starts.
• Grades are normalised across qb, ESX and ND. A framework with no grade concept reports 0, so job = { LSPD = 3 } denies rather than ignoring the 3.
• vRP has no adapter. Load a script with vRP.loadScript, call registerFramework, and report grade 0.

config

Validates an owner-edited config.lua once at startup and refuses to run on a broken one.

local ok = tlib.config.check(Config, {
    file = 'shared/config.lua',
    keys = {
        detectionRangeMeters = { type = 'number', default = 500.0, min = 1, max = 2000 },
        speedUnit            = { type = 'string', default = 'kmh', oneOf = { 'kmh', 'mph' } },
    },
})
if not ok then return end

A key definition takes type (number, string, boolean, list, table), default, required, min, max, oneOf, and fix to override the suggested remedy.

• Every problem is reported at once, each naming file, key, expected, found and a fix.
• A default fills a key the owner omitted; a value the owner set is reported and left alone, never silently replaced.
• An unknown key warns with the key probably meant, including unit-less near-misses.
• A missing required key is fatal.

coords

Vehicle coordinate maths, local ↔ world.

local right, fwd, up, pos = GetEntityMatrix(GetVehiclePedIsIn(PlayerPedId(), false))
local wx, wy, wz = tlib.coords.localToWorld(right, fwd, up, pos, 0.5, 1.0, 0.0)

demo

Reports whether the server runs in demo mode — the tlib_demo convar, see Convars.

A resource on the normal primitives needs nothing. Your own writer that bypasses tlib.fs needs one line:

local function saveData(json)
    if tlib.demo.dropWrite('data.json') then return true end
    return tlib.fs.writeResourceFile('data.json', json)
end

Never let demo.active() decide something a player benefits from being wrong about on the client. The client value is pushed by tLib, so it is correct whether the owner wrote set or setr.

devgate

A gate for a feature that exists on your own servers and is absent from the shipped build. tlib.devgate(name) returns a predicate for the convar name, read on every call, on both sides.

local isInternal = tlib.devgate('my_resource_convar')

if isInternal() then
    RegisterCommand('my_internal_tool', runTool, false)
end

• Put the call in a script not in escrow_ignore, or there is a convar name a customer can read.
• Gate registration, not behaviour. No command, keybind, menu row, panel or export should exist at all — one that exists and refuses advertises the feature in cmdlist.
• Read per call, so a replicated convar flipped mid-session applies at once. Where registration happens at load, off → on needs a restart.
• A client VM only sees setr. A client gate on a set convar is permanently off.
• 1, true, yes, on enable it; anything else, including unset, is off.

diag

Console blocks for the things an operator must go and fix. You write the prose; diag does the wrapping, dashed rules, ^colour codes and the [resource] prefix.

tlib.diag.fatal('Config does not exist. tRadio cannot start.', {
    cause = 'config/config.lua failed to load. Almost always a Lua syntax error.',
    fix   = 'Scroll UP: FiveM printed the exact file and line just before this message.',
    once  = 'no-config',
})

opts is { cause, fix, detail, scope, once }, all optional. A fix list renders as "Fix it one of these ways". It prints and never logs.

kvp

Typed KVP wrapper, prefixed per community server via tlib_community_id (needs setr) or sv_projectName — see Convars.

settings

Typed settings store backed by KVP, with defaults, user-set tracking and server-pushed defaults.

local store = tlib.settings.create({
    { key = 'volume', type = 'float', default = 0.8 },
    { key = 'darkMode', type = 'bool', default = false },
})

modules

Server-side content discovery. A module is a folder plus a module.json declaring what it is, as in layouts/QRX-720/module.json.

schema, kind, id, name, version are required; author, license, description, slug optional. A marketplace sound module adds sound.file and may add sound.durationSeconds, sound.toneKeys, sound.peaks.

• id must equal the folder name, byte for byte, which catches a rename on copy.
• kind is declared, never inferred from location. A mismatch is refused at start rather than 404ing on ui.html on a player's machine.
• sounds and themes are reserved and cannot be module ids.
• Content comes from a live scan, so a folder dropped in at runtime is found without a restart — clearCache() makes it visible to a scan already run.

logger

Levelled console logging with one format everywhere: [scope][LEVEL] message.

permission

Admin and permission checks matching tLib's own rules.

• isAdmin is answered inside your resource, so it works while tLib is still starting. has must ask tLib and returns false if tLib cannot answer, since a resolver may deny what ACE would grant.
• Use onChange, not a single read of exports['tLib']:IsAdmin() at start — that export is cached when tLib starts, so a revoked ace leaves a panel drawing its admin section until the player reconnects.

net

A net event with its guard built into the registration.

net.fromServer (client). Runs the handler only for an event that really came from the server (source == 65535), not a local TriggerEvent from another resource or a cheat menu. A rejection is reported once per event name, never per call.

tlib.net.fromServer('myres:serverDefaults', function(defaults)
    applyServerDefaults(defaults)
end)

net.fromClient (server). The source guard, a rate limit and an optional permission gate, applied once. The handler is called as fn(src, ...).

tlib.net.fromClient('myres:saveLayout', {
    allow    = function(src) return gate:allowed(src) end,
    onDenied = function(src) TriggerClientEvent('myres:denied', src) end,
}, function(src, layout)
    saveLayout(src, layout)
end)

A rate-limited call is dropped silently, so a feature that must reopen a panel it just closed uses panel:reopen() from opengate, not the request path.

opengate

The "may I open my panel?" handshake: the client asks, the server decides fresh on every open, and the answer is one of three things.

tlib.opengate.serve({
    key      = 'settings',
    allow    = function(src) return gate:allowed(src) end,
    configOk = function() return myresConfigOk() end,
    payload  = function(src) return { isAdmin = tlib.permission.isAdmin(src) } end,
})

Checks run in order: rate limit, configOk, then allow. A panel open to everyone writes allow = function() return true end.

local panel = tlib.opengate.panel({
    key      = 'settings',
    onOpen   = function(data) openSettingsDialog(data) end,
    onDenied = function() toast("You don't have permission to use this.") end,
    onBroken = function() toast("This server's config has errors — ask an admin.") end,
})

All three replies register through net.fromServer, so a local TriggerEvent can neither open the panel nor fake a denial. reopen() replays a grant and cannot create one.

platform

The FiveM native adapter, inside your VM.

getMyVehicle() answers nil or { handle, type, displayType, modelHash, isDriver, isEmergency, isEngineOn }, where type is heli | plane | boat | car and displayType is Air | Boat | Vehicle.

tlib.platform.bindKey({
    id      = 'toggle',
    product = 'tRadar',
    action  = 'Toggle the radar',
    default = 'F5',
    press   = function() toggle() end,
})

Defaults: group keyboard, pair true, default '', which appends "(unbound)" to the label. The positional form bindKey(key, cb, eventType, bindingId, label) also works. Each bind is reported to the keybind registry.

MAX_SEAT_INDEX is 16.

occupancy

One shared answer to who is aboard a vehicle, in which tier, and which of them may act on it. The controller is the driver if one is seated, otherwise the front passenger. In AUTOLOAD.

• seat, vehicle, netId, partner and isController are front-seat-only and nil for a rear passenger, so state.seat ~= nil reads as "may I operate this". A rear passenger appears only in tier and the cabin* fields, and only onCabinChange fires for them.
• tlib:occupancy:moved is one event name for every resource; its payload is a hint, since the seat is re-read from the host.
• Neither sweep runs until you start it.

jsonstore

The single memoised writer for one resource's JSON data file, with per-owner schema seeding, versioning and forward migration.

local store = tlib.jsonstore.open({ log = tlib.logger.create('tDetector') })
store:write({ props = placements })

• Migrations must be idempotent. A write can report success without the bytes landing, so the next start migrates again.
• A migration dropping a top-level key not listed in allowRemove is refused and nothing is written. Write a rename as a copy plus an allowRemove.
• A malformed schema raises rather than locking.
• __schema is keyed by owner. Never stamp a version when applying defaults, or your migrations will skip it.

fs

One function. fs.writeResourceFile(relPath, contents, resource, log) returns true, or false, err with err never empty. resource defaults to GetCurrentResourceName(); log only controls the one-time warning.

local ok, err = tlib.fs.writeResourceFile('data.json', encoded)
if not ok then log('could not write data.json — ' .. err, tlib.logger.ERROR) end

SaveResourceFile is tried first, falling back to the calling resource's own Node bridge, which exists only if that resource calls registerWriteResourceFile() from tLib/shared/ts/fs/server.ts and rebuilds its bundle; otherwise err says so by name. No server.cfg line changes this.

assets

Reconciles a stored list of operator-dropped files against what is in the folder.

local list, changed, reason = tlib.assets.sync(installedSounds, 'layouts/sounds',
                                               { extensions = tlib.assets.AUDIO })

changed reports membership, not length, so a one-in-one-out swap reports true. Retained records come back byte-identical. scan needs tLib's Node bundle (ScanResourceFiles); a missing export reads back as "unavailable" rather than throwing.

audio3d

Positional device audio: the server decides who is near enough to hear a vehicle-mounted device, and the client pushes one batched frame per tick into the consumer's own NUI.

local bus = tlib.audio3d.createBus({
    event  = 'tradar:worldSound',
    range  = Config.audioRange,
    fields = { kind = { type = 'string', max = 16 } },
})
RegisterNetEvent('tradar:emitWorldSound', function(payload) bus:emit(source, payload) end)

createBus asserts event and range. Defaults: maxReceivers 24 (1–128), minIntervalMs 100 (0–10000), maxPerSecond 20 (1–120). The emitter is the vehicle, so a sender on foot emits nothing.

Mark your own unit with setLocal, or the player hears two copies of the tone and they comb-filter.

framerelay

Publishes the device picture computed by the occupant who owns it onto the vehicle's statebag, for every other client in scope to read.

local relay = tlib.framerelay.create({
    key       = 'tdetScreenFrame',
    frame     = function() return localFrame end,
    hasScreen = function(vehicle) return tdetGetAttachedProp(vehicle) ~= nil end,
    sanitise  = tdetScreenSanitiseFrame,
    differs   = tdetScreenFrameDiffers,
})

Defaults: absent hasScreen means yes, heartbeatMs 1000, staleMs 3000.

seq and netId are written by the relay and powered is read by it, so those names are reserved; powered = false publishes nothing. staleMs clears a crashed driver's last frame. publishTick reads occupancy.isController() live, so the occupancy sweep must be running.

drivenprop

Drives an unattached, frozen prop's world matrix from its parent vehicle's, each frame. Use it when a prop needs a non-unit scale: scale lives in the basis-vector lengths of SetEntityMatrix, which AttachEntityToEntity does not carry.

• add detaches, freezes and disables collision, then writes the matrix. Undo any of the three and it breaks: attached loses the scale, unfrozen falls through the world, collision-enabled bounces off the vehicle.
• remove and clear neither delete the prop nor re-attach it; re-attaching discards the scale.
• transform raises on a left-handed basis, and returns the native's (forward, right, up, at) ordering, not the (right, forward, up) the rest of the module takes.
• create starts a per-frame thread and an onResourceStop handler; importing does not. Share one driver per resource.

lifecycle

Keeps a registration against a dependency alive across that dependency's restarts. The worked example is in Menu Consumers.

• Watch a dependency, never yourself — your own resource name asserts.
• ctx.once requires fn to return exactly true; a truthy non-true fails the step. Completed steps are remembered across retries within one generation.
• Retries stop after 300 attempts 100 ms apart and print the last real error. Only another start event or your own retry() re-arms it.

menuhost

Lets one resource expose navigation slots that other resources register links into. See Menu Consumers.

Per slot, enabled defaults to on, an absent resources allowlist admits any resource, and an unranked entry sorts at 1000. A slot's menu must be one of the host's own pages and a plugin's menu one of the plugin's. The caller comes from GetInvokingResource(), so the host cannot register on its own behalf. install fires tlib:menu:hostReady before returning — wait on that, not on the host resource starting.

menu

Loads tLib's menu validators into your VM: tlib.menu.schema is MenuSchema, tlib.menu.catalog is MenuCatalog.

Loading it also defines the bare globals MenuSchema and MenuCatalog. If your shared files read those globals, declare tlib_module { 'menu' }, or the lazy load has not run and they are nil.

healthcheck

Ordered HTTP GET probes against a base URL, with retries, delivering one aggregate result. tlib.healthcheck(opts) and .check(opts) are the same call and return nothing. Everything arrives at opts.callback as { success, steps, attempts, failedStep, message, url }, each step being { name, passed, status, error }.

• Defaults: one step (reachable, path /), retries 2 (three attempts), retryDelay 1000, timeout 8000, delay 500. With no expect, a step passes on any status 200–599.
• Give it opts.url or opts.waitEvent; waitEvent wins and takes the URL from the event payload. With neither it does nothing.
• The sequence short-circuits, so result.steps is shorter than opts.steps on a failure and a retry restarts at step 1. A timeout is status = 0, not an error.
• %port% in a step's errorMsg becomes the port parsed from the URL — 443, 80, or a literal ?.

marketplace

The consumer's half of the in-game marketplace: the payload that opens the browser, and the server-side installed-sound registry.

opts carries initialTab (uis or sounds), previewFn, previewState and panelPreviewUrl, which lets a theme be shown on a real dispatch panel instead of as a swatch strip. Only tRadio publishes one.

tlib.marketplace.standardTypes(GetCurrentResourceName(), {
    note = note, warn = warn,
    layouts = { installed = onLayoutInstalled, uninstalled = onLayoutRemoved },
    sounds  = { warnEvent = 'tdet:soundOverwriteWarning',
                installed = onSoundInstalled, uninstalled = onSoundRemoved },
})

Paths default to layouts and layouts/sounds; layouts = false or sounds = false skips a type. note and warn take one argument, a message — not a logger plus a level. meta.src is nil when the installing admin disconnected mid-install.

hud

A transport bridge for a consumer with its own NUI that wants its widget in tLib's shared HUD editor.

• Updates arrive as SendNUIMessage({ tlibHud = data }) — one wrapper key, not an action string — queued until your NUI calls __tlib_hud_ready.
• Definitions survive a tLib restart. Register once; never re-register on onClientResourceStart. A registration made while tLib is stopped, or refused because the HUD editor is open, is cached and retried for a minute.
• When tLib stops you receive the last committed geometry with phase = 'rollback' and editing = false. Handle that phase, or a stop mid-edit leaves a preview the player cannot cancel.

ratelimit

A per-player minimum interval on a net event, as a closure you call at the top of the handler.

local gate = tlib.ratelimit.bucket('requestVehicleProps', 1000)

RegisterNetEvent('tdet:requestVehicleProps', function()
    local src = source
    if not src or src <= 0 then return end
    if gate(src) then return end
end)

gate(nil) answers false. Names are scoped to your own VM; the same name twice hands back two closures over one timestamp table and the last intervalMs wins. Disconnected players are swept for you. net.fromClient already applies a rate limit, so use this directly only for something that is not a net event, or to put several events on one budget.

realtime

Rooms, typed events and the upstream control socket, over tLib's WebSocket router. tlib_module { 'realtime' } is required, or the rt* exports are never registered.

tlib.realtime:setRooms(playerId, { 'radio:freq:154.125' })
tlib.realtime:onEvent('ptt', function(playerId, sessionId, payload) end)

Handler lists are per consumer VM, so two resources can subscribe to one event. A handler that throws is caught and printed, not propagated. Audio frames do not come through here.

inference

Announce a model runtime this resource started, and find one another resource already has up for the same weights. Colon-called, like realtime. The exports underneath are in Exports; to start the engine, see Child processes.

local shared = tlib.inference:lookup('text', 'qwen3-1.7b-q4_k_m')
if not shared then
    local handle = tlib.inference:advertise({
        capability = 'text',
        workload   = 'qwen3-1.7b-q4_k_m',
        url        = 'http://127.0.0.1:18291/v1',
        model      = 'local',
    })
end

Give url as the full URL including the route; nothing is appended. Only 127.0.0.1, [::1] and localhost are accepted. Re-advertising replaces every entry for the same resource and capability, so moving an engine to a new port needs no withdraw.

soundstore

The tone-key to .wav registry behind a resource's sound settings, with a boot reconciliation against what is on disk.

Defaults: resource to GetCurrentResourceName(), dir to layouts/sounds, file to data.json, keys to {}.

An empty directory scan counts as a failed scan. The store shares your resource's jsonstore object.

secrets

Overlays a gitignored config.local.lua and then matching convars onto Config in place, so the tracked config file ships blank. Server-only.

Precedence is convar, then config.local.lua, then config.lua. A convar is named <prefix>_<dotted_path_with_underscores>. opts.convarPrefix defaults to the resource name lowercased, opts.resource to GetCurrentResourceName(), and opts.quiet is falsy, so it prints what it applied. The sidecar loads into an empty environment: it must return a plain table and can call nothing, not even print. A list in the sidecar replaces the one in config.lua rather than appending.

spatial

A throttled index of player positions: the cached counterpart to tlib.platform.getNearbyPlayers.

The two halves are separate indexes with separate clocks. setRefreshRate applies to the whole VM.

telemetry

The diagnostics pipeline: scrubbing, fingerprinting, operation timing and the batched send.

While consent is off, events are dropped rather than queued, so turning diagnostics on sends no backlog. With it on, the queue caps at 32 and discards oldest first. A fault is deduped for 120 seconds per fingerprint.

screentarget

Picks the one vehicle whose device screen this client renders — AddReplaceTexture is keyed on the texture name, so there can only be one. Your own vehicle always wins, otherwise the nearest in range, with hysteresis.

Defaults: range 8.0 m, switchMargin 2.0 m (absolute metres, not a fraction), dwellMs 1500. source is own or nearest.

onChange fires only on a vehicle or source change, never on distance, so it is safe to rebuild a browser inside it. Treat update() returning nil as the signal to tear that browser down, or it paints stale pixels onto a vehicle the player has left. dwellMs delays displacement only. Create one arbiter per device kind.

runtimetxd

Calls CREATE_RUNTIME_TXD at most once per resource load, and mints names a restart cannot collide with.

local txds = tlib.runtimetxd.create('tdet_scr_txd')
local name = txds.textureName('tdet_screen', serial)

Budget one permanently pinned streaming slot per resource load: the engine frees neither a runtime txd nor a runtime texture, so repeated restarts accumulate them. Reusing a name across a restart instead makes AddReplaceTexture resolve against the previous load's dictionary and silently do nothing.

soundfields

Builds the Sounds tab of a settings dialog and keeps it live, remembering which keys the open dialog drew.

The remembered list is module-level, so keep one dialog open at a time per resource. refresh patches what was drawn, not the current config, so a sound key added server-side after the dialog opened appears only at the next open.

propeditor and vehicleprop

The in-vehicle prop stack. vehicleprop owns the model registry, the placement store and the attach/detach lifecycle; propeditor owns the orbit camera and the editing UI. Create vehicleprop and reach the editor through instance.editor.

local prop = tlib.vehicleprop.create({
    prefix = 'tdet', model = 'prop_cs_police_torch', decor = 'tdet_prop',
    saveEvent = 'tdet:savePlacement', removeEvent = 'tdet:removePlacement',
})

create asserts prefix, model, decor, saveEvent and removeEvent.

• Scale decides the attach mechanism. A unit scale uses AttachEntityToEntity; anything else is driven per frame through drivenprop. Never test "is this attached" to decide whether a prop is live — ask the tracking table.
• CreateObject signals failure with 0, which Lua treats as true. if not prop then never catches it, and the prop simply never appears.
• The placement, attached and model tables are emptied in place, never replaced.
• A record the editor did not change round-trips byte-identical. receiveEvent accepts server-triggered events only (source == 65535).

versioncheck

tlib.versioncheck(opts) — the startup banner, version comparison and changelog. It is both callable and a table, so tlib.versioncheck(opts) and .check(opts) are the same call, alongside .github(repo), .studios(product, current) and .lean(...). It has its own page: Version Check.