> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunder-studio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Practical reference for TS-Lib utilities and bridges.

This page gives you a **practical overview** of what TS-Lib exposes at runtime once you include `@ts-lib/import.lua` in your resource.

***

## Core utilities

TS-Lib attaches a few helpers to a global `TS` table that are reused across Thunder Scripts.

### Logging

* `Utils.Print(message, resourceName?)`
* `Utils.DebugPrint(message, resourceName?)`
* `Utils.ErrorPrint(message, resourceName?)`
* `Utils.SuccessPrint(message, resourceName?)`

```lua theme={null}
Utils.DebugPrint('My script has started', GetCurrentResourceName())
```

### Generic utils

Common helpers include:

* `Utils.IsRessourceLoaded(resourceName): boolean`
* `Utils.IsTableEmpty(tbl): boolean`

```lua theme={null}
if not Utils.IsRessourceLoaded('qb-core') then
    Utils.ErrorPrint('qb-core is missing, TS-Lib bridges will not work correctly')
end
```

### Intervals

TS-Lib embeds an interval helper to simplify repeating callbacks:

* `TS.Intervals.Set(callback, ms, ...): id`
* `TS.Intervals.Clear(id)`

```lua theme={null}
local id = TS.Intervals.Set(function()
    Utils.DebugPrint('Still alive')
end, 5000)

-- later
TS.Intervals.Clear(id)
```

***

## UI helpers

TS-Lib exposes small, framework-agnostic UI helpers through `TS.Lib.*`.\
These are rendered via the bundled NUI (`ui/build`).

### Subtitle

* `TS.Lib.Subtitle.Show(text: string)`
* `TS.Lib.Subtitle.Hide()`

From a client script that has included `@ts-lib/import.lua`:

```lua theme={null}
TS.Lib.Subtitle.Show('Press E to interact')

-- later
TS.Lib.Subtitle.Hide()
```

From another resource using exports only:

```lua theme={null}
exports['ts-lib']:SendSubtitle('Press E to interact')

-- later
exports['ts-lib']:HideSubtitle()
```

### Text UI (help text)

* `TS.Lib.TextUI.Show(text: string, position?: string)`
* `TS.Lib.TextUI.Hide()`

`position` defaults to `'top-left'`. Common positions used by the UI are:

* `top-left`
* `top-center`

Example from a client script:

```lua theme={null}
TS.Lib.TextUI.Show('Press E to open garage', 'top-center')

-- later
TS.Lib.TextUI.Hide()
```

Or via exports:

```lua theme={null}
exports['ts-lib']:SendTextUI('Press E to open garage', 'top-center')

-- later
exports['ts-lib']:HideTextUI()
```

### Text Input

* `TS.Lib.TextInput(data: table): table`

Opens a NUI-based text input dialog and returns the user's input.

```lua theme={null}
local result = TS.Lib.TextInput({
    title = "Enter Vehicle Plate",
    placeholder = "ABC 123",
    type = "text",  -- "text", "number", or "password"
    value = ""
})

if result.receivedData then
    if result.hasCanceled then
        print("User canceled")
    else
        print("Entered:", result.data)
    end
end
```

Or via exports:

```lua theme={null}
local result = exports['ts-lib']:TextInput({
    title = "Enter Vehicle Plate",
    placeholder = "ABC 123",
    type = "text"
})
```

***

## Command System

TS-Lib provides a unified command registration system with built-in type validation and permission support.

* `TS.Lib.Command.add(commandName, properties, callback)`

```lua theme={null}
TS.Lib.Command.add('givecar', {
    help = 'Give a car to a player',
    params = {
        { name = 'playerId', help = 'Target player ID', type = 'playerId' },
        { name = 'model', help = 'Vehicle model name', type = 'string' },
    },
    restricted = 'admin'  -- Can be boolean, string, or table of groups
}, function(source, args, raw)
    print(('Admin %d gave %s to player %d'):format(source, args.model, args.playerId))
end)
```

### Parameter Types

| Type         | Description                                             |
| ------------ | ------------------------------------------------------- |
| `number`     | Converts argument to a number                           |
| `playerId`   | Accepts 'me' or player ID; validates player exists      |
| `string`     | Ensures argument is not a number                        |
| `longString` | Captures all remaining text (must be last parameter)    |
| `boolean`    | Accepts `true`/`false`, `yes`/`no`, `1`/`0`, `on`/`off` |

***

## Server Utilities

### Update Checker

* `TS.CheckUpdate(versionUrl, changelogUrl?)`

Checks for updates by fetching a version JSON from a remote URL. Shows a formatted console box if outdated.

```lua theme={null}
-- In your script after including ts-lib
TS.CheckUpdate(
    'https://raw.githubusercontent.com/yourname/yourscript/main/version.json',
    'https://docs.thunder-studio.net/scripts/your-script/changelog'
)
```

The version JSON should look like:

```json theme={null}
{ "version": "1.0.7" }
```

### Bridge Helpers

* `TS.Bridge.GetPlayers(): table` - Returns a list of player sources
* `TS.Bridge.HasPermission(source, permission): boolean` - Checks if player has a permission (uses framework bridge or ACE as fallback)

```lua theme={null}
-- Get all players
local players = TS.Bridge.GetPlayers()

-- Check permission
local canSpawn = TS.Bridge.HasPermission(source, 'admin')
```

***

## Bridges overview

The main reason to use TS-Lib is its **bridge** modules. They expose normalized APIs that hide framework-specific or script-specific details.

* `Bridge.Framework.*` → talks to your **framework** (QBCore / ESX / QBox / standalone)
* `Bridge.Garages.*` → talks to your **garage** script
* `Bridge.VehicleKeys.*` → talks to your **vehicle keys** script
* `Bridge.Notify.*` → unified **notification** system

Each bridge has its own dedicated page with full details:

* [Framework Bridge](/scripts/ts-lib/bridges-framework)
* [Garage Bridges](/scripts/ts-lib/bridges-garages)
* [Vehicle Keys Bridges](/scripts/ts-lib/bridges-vehiclekeys)
* [Notify Bridge](/scripts/ts-lib/bridges-notify)

Below are the patterns you will most often use from a script that depends on TS-Lib.

***

## Framework bridge (quick reference)

### Client

* `Bridge.Framework.Client.PlayerData`\
  Unified player data, automatically updated when the player loads / unloads / changes job.

* `Bridge.Framework.Client.Functions.GetPlayerJob() -> ok, jobOrError`

```lua theme={null}
local ok, job = Bridge.Framework.Client.Functions.GetPlayerJob()
if ok then
    print(('Job: %s (%s)'):format(job.name, job.label))
end
```

* `Bridge.Framework.Client.Functions.Notify(message, type?)`

```lua theme={null}
Bridge.Framework.Client.Functions.Notify('Saved vehicle successfully', 'success')
```

### Server

* `Bridge.Framework.Server.Functions.GetPlayerJob(source)`
* `Bridge.Framework.Server.Functions.GetPlayersByJobName(jobName, checkOnDuty?)`
* `Bridge.Framework.Server.Functions.GetPlayers()`
* `Bridge.Framework.Server.Functions.GetVehicleType(model)`
* `Bridge.Framework.Server.Functions.HasPermission(source, permission)`

See [Framework Bridge](/scripts/ts-lib/bridges-framework) for framework-specific notes and event names.

***

## Garage bridge (quick reference)

### Server

* `Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId?) -> boolean`
* `Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, state)`

```lua theme={null}
local owned = Bridge.Garages.Server.Functions.IsVehicleOwned(plate, netId)
if not owned then return end

-- mark the vehicle as outside
Bridge.Garages.Server.Functions.SetVehicleOutsideState(plate, true)
```

See [Garage Bridges](/scripts/ts-lib/bridges-garages) for the exact behavior per system.

***

## Vehicle keys bridge (quick reference)

The keys bridge focuses on **locking / unlocking** vehicles from a unified entrypoint.

### Client

* `Bridge.VehicleKeys.Client.Functions.SetDoorStatus(entity, lockStatus)`

```lua theme={null}
-- Example: lock a vehicle from another script
Bridge.VehicleKeys.Client.Functions.SetDoorStatus(vehicle, 2) -- 2 = locked
```

Lock states follow GTA's native semantics (`1` = unlocked, `2` = locked, `4` = locked for all players, etc.).

See [Vehicle Keys Bridges](/scripts/ts-lib/bridges-vehiclekeys) for system-specific behavior (`qb-vehiclekeys`, `qs-vehiclekeys`, `standalone`).

***

## Notify bridge (quick reference)

The notify bridge provides a unified way to send notifications across different frameworks.

### Client

* `Bridge.Notify.Client.Functions.Notify(message, type?)`

```lua theme={null}
-- Show a success notification
Bridge.Notify.Client.Functions.Notify('Vehicle saved successfully', 'success')

-- Show an error notification
Bridge.Notify.Client.Functions.Notify('Vehicle not found', 'error')
```

Supported types vary by framework:

* **QBCore**: `success`, `error`, `warning`, `info` (or any custom type)
* **ESX**: Uses ESX notification system

See [Notify Bridge](/scripts/ts-lib/bridges-notify) for more details.