Exports

Call every export as exports['tLib']:FunctionName(...). Each section says which side it is registered on.

Menu System

Client and server. One NUI menu shared by every resource. tLib owns the screen, the keyboard and the permission check; you declare pages and handle rows.

Pages register on the server, and every open is answered with that player's ACE-filtered tree. Handlers, presenters and hooks register on the client. Menu IDs are namespaced owner:name. Every export takes an optional trailing declaredOwner, used only where the platform cannot identify the caller.

Menu Consumers builds one end to end.

Server — declaring the tree

definition is { ace, actions = { [itemId] = { ace, run?, clientAction?, cooldown?, fixedValue?, domain? } }, theme?, rootVisible? }. rootVisible = false omits the shared-root link only; it changes no permission.

Server — changing what is registered

Client — behaviour

Client — the screen

Unscoped: the screen belongs to the player.

SubmitFeedback

For a resource whose settings live in a tLib dialog. A menu already grows a "Send feedback" row on its owner's root page.

local sent = exports['tLib']:SubmitFeedback(message, function(result)
    if result.ok then return end
    -- result.error == 'rate-limited' | 'invalid' | 'unreachable'
end)

A page

{ id = 'myres:tools', title = 'Tools', subtitle = ..., description = ..., parent = ..., items = { ... } }

A row

kind is action, toggle, select, slider, submenu or status.

Every kind on one page, in that order:

A namespace or page theme reskins the same definition:

Dialog System

Client. Modal form dialogs. Results arrive as local events and as optional inline callbacks — additive, not alternatives.

A default md dialog, with a required text, a two-option select as a segmented control and a checkbox:

ShowDialog options

A dialog reopens where the player left it — selected tab, scroll position, dragged panel position — per dialog id. Values and validation state are never kept, and a tLib restart or a reconnect forgets the rest. resetState = true opts out.

Field types

All share id (required), type, label, description, required, disabled. An unknown type logs a warning and falls back to text.

maxLength is enforced by the page, so a server-side cap is visible while typing rather than on submit.

display

Text, not a control: the label renders at full opacity with no input beside it, carries no value and is never submitted. Use it for a readout, a section heading or help text.

{ id = 'note', type = 'display', label = 'Patterns are saved per vehicle model.' }

Confirming a dialog button

A button fires onButtonClick on press. Give it a confirm string and the press asks that question first; only an explicit Confirm fires the callback. Escape and Cancel answer it without firing, and the dialog stays open either way. variant = 'destructive' is colour only, so a button that cannot be undone wants both:

{
    id = 'wipe',
    type = 'button',
    label = 'Clear all patterns',
    variant = 'destructive',
    confirm = 'Every pattern on this vehicle is deleted. This cannot be undone.',
}

One of each type in an lg dialog. A select with two options renders as a segmented control:

Events

tLib:dialog:opened (dialogId) · tLib:dialog:submitted (dialogId, values), keyed by field id · tLib:dialog:cancelled (dialogId)

local dialogId = exports['tLib']:ShowDialog('my_dialog', {
    title = 'Player Info',
    fields = {
        { id = 'name', type = 'text', label = 'Name', required = true },
        { id = 'age', type = 'number', label = 'Age', min = 1, max = 120 },
        { id = 'role', type = 'select', label = 'Role', options = {
            { value = 'civ', label = 'Civilian' },
            { value = 'leo', label = 'Law Enforcement' },
        }},
    },
})

AddEventHandler('tLib:dialog:submitted', function(id, values)
    if id == dialogId then print(values.name, values.age, values.role) end
end)

Toast / Notification System

Client. Non-interactable notifications stacked in a screen corner.

IDs are local to the producing resource, and stopping a producer removes its persistent cards. A type change or duration = 0 restarts the type default; text- or theme-only updates keep the deadline. Limits: 32 active per producer, 256 total.

Each type carries its own icon and colour. Newest sits at the bottom:

Events: tLib:toast:shown (id, toastType, title, owner) · tLib:toast:updated (id, patch, owner) · tLib:toast:dismissed (id, owner) · tLib:toast:dismissedAll (owner)

exports['tLib']:ShowToast(nil, 'success', 'Saved', 'Your settings have been saved.')

local toastId = exports['tLib']:ShowToast(nil, 'loading', 'Saving...', 'Please wait.')
exports['tLib']:UpdateToast(toastId, { type = 'success', title = 'Done', description = 'Save complete.' })

Theme System

Client. CSS-variable themes, global or scoped to one dialog, toast or menu. One id themes all three surfaces.

Events: tLib:theme:added, tLib:theme:removed, tLib:theme:set — each (id).

HUD Layout

Client. Puts your on-screen element in the shared HUD editor, so a player moves, scales and hides it alongside every other resource's HUD.

options is { label, width, height, canHide?, canScale?, minScale?, maxScale?, persist?, minVisiblePixels?, minVisibleFraction?, defaults = { x, y, scale, visible, anchor }, layout? }. Layouts persist per server endpoint; without one they are session-only and tLib says so at startup. For a persist component the record is written before fn runs, so true means the position survived.

One editor, not one per resource:

defaults and layout are different things

defaults is the factory placement, where "Reset this" goes. layout is where the widget is now. Pass both, always:

exports['tLib']:RegisterHudComponent('radio', {
    label = 'Radio', width = 300, height = 440, persist = false,
    defaults = factoryPlacement,   -- where Reset puts it
    layout   = savedPlacement,     -- where it is
}, onLayout)

With persist = false you own the storage, and passing the saved position as defaults makes Reset restore the placement the player is escaping. Pin tlib_min_version '1.0', the first release carrying layout.

Every layout tLib is handed — saved record, layout, defaults — is validated independently and falls through to the next when unusable, then clamped against the live resolution so at least minVisiblePixels (96) or minVisibleFraction (0.4) stays on screen. That runs on registration.

Units

x and y are a ratio of a 1080px-tall reference screen on both axes, the same unit the widget's size scales by. Centre-anchored x is the exception and stays proportional to width.

If a player loses their HUD, /tlibhud reset restores every component to its factory placement and clears the saved layout — editor open or shut, whichever resource opened it.

Keybind registry

Client. The only place two different resources' bindings are visible at once — a resource's own tlib.platform.keybindConflicts() sees only its own VM.

Only token is required; resource defaults to ?, label to the token, group to keyboard. A malformed entry is dropped silently rather than raised, so a typo shows up as a bind missing from GetKeybinds(). An entry with no default never counts as a collision, and a conflict needs more than one resource.

tLib prints its report ten seconds after start, once; a bind reported later is recorded but misses it, so call GetKeybindConflicts() yourself after that. Nothing here reassigns a key — act on a conflict by changing a default and shipping it.

Marketplace

Client and server. The in-game panel for browsing and installing published content.

For ProvideMarketplaceData, give your dialog a tab with view = "marketplace" and call it when the server answers with what is installed. Use OpenMarketplace where there is no host dialog to embed in.

Logger

Client and server. Levels are 1 DEBUG, 2 INFO, 3 WARN, 4 ERROR. A trailing number in the arguments is the level; everything else is tostring'd and space-joined.

local log = exports['tLib']:CreateLogger('myresource', print)
log('Server started')           -- INFO
log('Something went wrong', 4)  -- ERROR

-- Log() returns the line and leaves printing to you:
local line = exports['tLib']:Log('myresource', { 'Something went wrong', 4 })
if line then print(line) end

HTTP Helper

Server. Non-blocking requests through FiveM's PerformHttpRequest. Not related to tLib's public HTTP routing hub.

Redirects are followed. There are no timeout or TLS-verification options. callback is function(statusCode, body, headers, errorData). An HTTP error status is still a delivered response, so check the status.

exports['tLib']:Fetch({ url = 'https://example.com/api', method = 'GET' },
    function(status, body, headers, err)
        if status ~= 200 then return print('Request failed:', status, err) end
        print('Body:', body)
    end)

Permissions

Client and server. Levels: 0 none, 1 admin (tlib.admin), 2 superadmin (tlib.superadmin).

Diagnostics consent

Server. Both exports cross as a JSON string. See tlib_telemetry in Convars for what is collected.

local c = json.decode(exports['tLib']:GetTelemetryConsent())

• There is no provisioned field; never render a "cannot transmit" state.
• It is not permission-gated. Gate it at your own call site.
• Never put it on an unauthenticated surface. tLib's hub binds 0.0.0.0 with no auth on its index, so it calls neither export.

tlib_telemetry_status in the server console prints the same answer plus the queue depth and whether the transport has given up.

Local inference

Server. For resources shipping their own model runtime. Everything crosses as a JSON string; an empty string is the universal "no".

Starting those engines is a separate, gated surface — see Child processes.

Child processes

Server. One line covers a whole box, however many resources on it ship a local engine:

add_unsafe_child_process_permission tLib

tLib makes the call, so no other resource needs its own grant.

cwd is resource-relative and must be one the catalog declares for that program; omitted, it is the binary's own directory. env names must be on the program's allowlist, so LD_PRELOAD cannot be set. mode is lines (default) or bytes, which returns stdout base64 with nothing dropped and keeps stdin open.

The caller names a program, never a path. tLib's catalog declares which resources may spawn, which programs each may run, where those live and what their arguments may look like. It resolves the executable inside the calling resource, rebuilds the argv from a declared shape, and execs with no shell. The catalog declares a binary per platform, so the caller never says which it wants and nothing shells out to PowerShell.

Lifecycle

A child belongs to tLib's runtime, not its owner's. tLib reaps it when the owning resource stops (including the stop half of a restart), when the owner calls SpawnUnserve, and when tLib stops. A caller restarting is kill-and-respawn, not reuse.

Binary integrity

These binaries are verified where they are fetched, not where they are run. This gate adds containment and argument shape, not integrity.

Utilities

CreateDiscovery needs resourceName = GetCurrentResourceName() when called at module init time: GetInvokingResource() is nil during top-level execution, and without the name the file I/O targets tLib instead of you.

Exporting a config into another resource

Discovery can move a config out of your data.json and into the resource that owns the model — a vehicle pack ships tels.json beside its .yft, declares it in its own fxmanifest.lua, and the config travels with the vehicle.

So the destination performs the write: tLib calls the target's own WriteResourceFile export. Nothing is reported as exported unless the file landed.

The target decides which path you get:

• It runs its own code. Any resource whose server bundle calls registerWriteResourceFile() from tLib/shared/ts/fs/server.ts accepts the export directly. tLib writes the JSON in and adds the metadata line to its fxmanifest.lua.
• It is a plain asset pack. No scripts, no bundle, no runtime to write with. tLib writes the finished file into its own directory and prints these steps to the player in chat and to the server console:

1. Copy tLib/export-staging/<target-resource>/<file>.json  ->  <target-resource>/<file>.json
2. Add this line to <target-resource>/fxmanifest.lua:  tels_config 'tels.json'
3. Restart <target-resource> (or the server).

The staged file is the target's existing config with your model merged in. Until you copy it the config is still local and still served to clients.

The metadata key is whatever the consuming resource declares — tels_config for tELS, tradio_config for tRadio — and the value is the file name relative to the resource root. Without that line the file is never read.