# Client

This section covers the client-side functions located in `integration/client/`. These functions unify interactions with third-party resources like Target systems, Inventory (client actions), Fuel, Keys, and UI elements.

### Target System

The lib standardizes all target interactions using the `qb-target` data structure. If `ox_target` is used, the lib automatically converts the syntax (mapping `action` to `onSelect`, `job` to `groups`, etc.).

#### `Lib47.AddBoxZone`

Creates a box zone for targeting.

```lua
--- @param name string Unique name for the zone
--- @param center vector3 Central coordinates
--- @param length number Length of the box
--- @param width number Width of the box
--- @param options table Zone options (minZ, maxZ, debugPoly, heading, useZ)
--- @param targetoptions table List of options using qb-target structure
Lib47.AddBoxZone("my_zone", vector3(100.0, 200.0, 30.0), 2.0, 2.0, {
    minZ = 29.0,
    maxZ = 31.0,
    debugPoly = false,
    heading = 90.0
}, {
    options = {
        {
            type = "client", -- or "server", "command"
            event = "myscript:client:action",
            icon = "fas fa-user",
            label = "Interact",
            job = "police", -- qb-target standard
            gang = "ballas", -- qb-target standard
            item = "handcuffs", -- qb-target standard
            action = function() -- Optional function support if not using event
                print("Clicked")
            end
        }
    },
    distance = 2.5
})
```

#### `Lib47.AddPolyZone`

Creates a complex polygon zone.

```lua
--- @param name string
--- @param points table List of vector3 points
--- @param options table (minZ, maxZ, debugPoly)
--- @param targetoptions table
Lib47.AddPolyZone("my_poly", {
    vector3(100.0, 100.0, 30.0),
    vector3(105.0, 100.0, 30.0),
    vector3(105.0, 105.0, 30.0)
}, {
    minZ = 29.0,
    maxZ = 31.0
}, { --[[ targetoptions ]] })
```

#### `Lib47.AddCircleZone`

Creates a spherical/circular zone.

```lua
--- @param name string
--- @param center vector3
--- @param radius number
--- @param options table
--- @param targetoptions table
Lib47.AddCircleZone("my_circle", vector3(100.0, 200.0, 30.0), 1.5, {
    debugPoly = true
}, { --[[ targetoptions ]] })
```

#### `Lib47.AddTargetEntity`

Adds target options to specific entities (NetID or Local).

```lua
--- @param entities table|number Single entity or list of entities
--- @param options table qb-target standard options
Lib47.AddTargetEntity(entity, {
    options = {
        {
            icon = "fas fa-car",
            label = "Check Vehicle",
            action = function(entity)
                print("Checking " .. entity)
            end
        }
    },
    distance = 2.0
})
```

#### `Lib47.AddTargetModel`

Adds target options to specific models.

```lua
--- @param models string|number|table Model name/hash or list
--- @param options table
Lib47.AddTargetModel('prop_atm_01', {
    options = {
        {
            event = "bank:open",
            icon = "fas fa-money-bill",
            label = "Use ATM"
        }
    },
    distance = 1.5
})
```

#### `Lib47.RemoveZone`

Removes a registered zone by name.

```lua
Lib47.RemoveZone("my_zone")
```

***

### UI & Progress

The lib standardizes progress bars using the `ox_lib` data structure.

#### `Lib47.ShowProgress`

Displays a progress bar (Circle in Ox, standard bar in QB/ESX).

```lua
--- @param data table ox_lib progress structure
--- @param successCb function (optional)
--- @param cancelCb function (optional)
--- @return boolean true if completed, false if cancelled
local success = Lib47.ShowProgress({
    label = 'Repairing Vehicle...',
    duration = 5000,
    position = 'bottom',
    useWhileDead = false,
    canCancel = true,
    disable = {
        move = true,
        car = true,
        combat = true
    },
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_ped',
        flag = 49
    },
    prop = {
        model = 'prop_tool_wrench',
        bone = 57005,
        pos = vec3(0.1, 0.0, 0.0),
        rot = vec3(0.0, 0.0, 0.0)
    }
}, function()
    print("Done!")
end, function()
    print("Cancelled!")
end)
```

#### `Lib47.Notify`

Sends a notification to the player.

```lua
--- @param msg string Message content
--- @param type string 'success', 'error', 'info'
--- @param duration number Duration in ms
Lib47.Notify("Vehicle Repaired", "success", 5000)
```

***

### Inventory (Client)

#### `Lib47.OpenStash`

Opens a stash inventory for the player.

```lua
--- @param identifier string Unique stash ID
--- @param name string Display label
--- @param weight number Max weight (in kg or grams depending on inv)
--- @param slots number Max slots
Lib47.OpenStash("shop_stash_1", "Shop Storage", 100000, 50)
```

#### `Lib47.OpenSearchInventory`

Opens another player's inventory (e.g., searching/robbing).

```lua
--- @param targetServerId number
Lib47.OpenSearchInventory(targetServerId)
```

#### `Lib47.CloseInventory`

Forces the inventory to close.

```lua
Lib47.CloseInventory()
```

#### `Lib47.SetInventoryBusy`

Sets the player's inventory state to busy (prevents opening).

```lua
--- @param state boolean
Lib47.SetInventoryBusy(true)
```

***

### Vehicles & Keys

#### `Lib47.GiveVehicleKey`

Gives keys for a specific vehicle to the player.

```lua
--- @param plate string
--- @param vehicle entity
--- @param virtual boolean (optional) For temporary keys if supported
Lib47.GiveVehicleKey("ABC 123", vehicleEntity)
```

#### `Lib47.RemoveVehicleKey`

Removes keys from the player.

```lua
--- @param plate string
--- @param vehicle entity
Lib47.RemoveVehicleKey("ABC 123", vehicleEntity)
```

#### `Lib47.SetVehicleFuel`

Sets the fuel level of a vehicle.

```lua
--- @param vehicle entity
--- @param amount number (0-100)
Lib47.SetVehicleFuel(vehicleEntity, 100.0)
```

#### `Lib47.StoreVehicleHousing`

Stores a vehicle in a housing garage (Supporting CD, OkOk, JG, Loaf, Ak47).

```lua
--- @param garageId string
--- @param vehicle entity
Lib47.StoreVehicleHousing("my_house_1", vehicleEntity)
```

#### `Lib47.OpenGarageHousing`

Opens the garage menu for a specific housing property.

```lua
--- @param garageId string
Lib47.OpenGarageHousing("my_house_1")
```

***

### Status

#### `Lib47.IsDead`

Checks if a player (or self) is dead. Supports Metadata checks and Animation checks.

```lua
--- @param target number|nil Target Server ID or nil for self
--- @return boolean
local dead = Lib47.IsDead() -- checks self
```

#### `Lib47.IsLastStand`

Checks if a player is in the "last stand" / downed state.

```lua
--- @param target number|nil
--- @return boolean
local downed = Lib47.IsLastStand()
```

#### `Lib47.IsIncapacitated`

Checks if the player is either dead OR in last stand.

```lua
--- @param target number|nil
--- @return boolean
if Lib47.IsIncapacitated() then
    print("Player is down or dead")
end
```