# Configuration

`Factions & Heist Scoreboard` uses a configuration file located in:

* `data/config.lua`

This file controls localization, branding, 3D player text, premium badges, admin groups, factions, and heist entries.

### Localization

```lua
Locale = 'en' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

To add a new language, copy `locales/en.json` and create your own language file.

***

### Branding

Controls the scoreboard header and image base path.

```lua
BrandName = 'MSK'
BrandAccent = 'SCRIPTS'
BrandTagline = 'SCOREBOARD'
UploadUrl = 'https://upload.domain.pl/static'
```

#### `BrandName`

Defines the first part of the header name.

```lua
BrandName = 'PEAK'
```

#### `BrandAccent`

Defines the accented part of the header name.

```lua
BrandAccent = 'RP'
```

#### `BrandTagline`

Defines the subtitle shown in the header.

```lua
BrandTagline = 'SCOREBOARD'
```

#### `UploadUrl`

Defines the base path used for images.

```lua
UploadUrl = 'https://upload.domain.pl/static'
```

This is also used for heist images.

You can also use a local NUI path if needed.

***

### 3D Text Above Heads

Controls the 3D text drawn above players and nearby vehicles.

```lua
ColorRgb = { r = 255, g = 0, b = 0 }
AdminRange = 100.0
PlayerRange = 40.0
ShowVehicleInfo = true
VehicleInfoRange = 19.9
```

#### `ColorRgb`

Defines the RGB color of the server ID text.

```lua
ColorRgb = { r = 255, g = 0, b = 0 }
```

#### `AdminRange`

Defines the draw range for admins in meters.

```lua
AdminRange = 100.0
```

#### `PlayerRange`

Defines the draw range for regular players in meters.

```lua
PlayerRange = 40.0
```

#### `ShowVehicleInfo`

Enables vehicle information above vehicles.

```lua
ShowVehicleInfo = true
```

#### `VehicleInfoRange`

Defines the draw range for vehicle information.

```lua
VehicleInfoRange = 19.9
```

***

### Premium Rank Badges

Premium badges are shown above player heads when the player has a matching `vip` state bag value.

```lua
PremiumRanks = {
    ['VIP']   = { label = 'VIP',   color = '#0ccbe8' },
    ['SVIP']  = { label = 'SVIP',  color = '#ff00c8' },
    ['ELITE'] = { label = 'ELITE', color = '#edcc0e' },
}
```

#### Example

```lua
Player(source).state:set('vip', 'ELITE', true)
```

To add a custom premium rank, add a new entry to `PremiumRanks` and set the same value in the player state bag.

***

### Admin Groups

Defines which groups are treated as admins by the scoreboard.

```lua
AdminGroups = {
    ['admin'] = true,
    ['developer'] = true,
}
```

Admins can see more player information and use extended draw ranges.

***

### Factions

Factions are configured manually in `data/config.lua`.

Example:

```lua
Factions = {
    {
        id = 'police',
        name = 'Los Santos Police Department',
        shortName = 'LSPD',
        color = '#4F8EF7',
        isLSPD = true,
    },
    {
        id = 'ambulance',
        name = 'Emergency Medical Services',
        shortName = 'EMS',
        color = '#FF4757',
    },
}
```

#### `id`

Framework job name used to identify faction members.

#### `name`

Full faction name shown in the scoreboard.

#### `shortName`

Short version of the faction name.

#### `color`

Hex color used for the faction in the UI.

#### Police Counting

If a faction should count toward police requirements for heists, add one of the following flags:

* `isLSPD = true`
* `isBCSO = true`
* `isSASPR = true`

All factions marked with one of these flags are counted together as police for heist requirements.

***

### Heists

Each heist is configured manually in `data/config.lua`.

Example:

```lua
{
    name = 'furgonetka',
    title = 'Van Robbery',
    description = 'Rob the GRUPPE-6 van.',

    crime = { min = 1, max = 2 },
    cops  = { min = 2, max = 4 },

    getCooldown = function()
        return exports['prp_truckrobbery']:TabletCd()
    end,

    items = {
        { name = 'ladunekwybuchowy', label = 'Explosive Charge', amount = 1, blur = false },
    },
}
```

#### `name`

Unique internal heist ID.

This is also used as the image name:

```javascript
{UploadUrl}/{name}.png
```

#### `title`

Display name shown in the heist tablet.

#### `description`

Short heist description.

#### `crime`

Defines the required number of criminals online.

```lua
crime = { min = 1, max = 2 }
```

#### `cops`

Defines the required number of police online.

```lua
cops = { min = 2, max = 4 }
```

If you do not want a police requirement, use:

```lua
cops = { min = 0, max = 0 }
```

#### `getCooldown`

Server-side function that returns the heist cooldown.

```lua
getCooldown = function()
    return exports['prp_truckrobbery']:TabletCd()
end
```

Return values:

* `false` — heist is ready
* number greater than `0` — cooldown remaining in seconds

#### `items`

Defines the items required for the heist.

Example:

```lua
items = {
    { name = 'ladunekwybuchowy', label = 'Explosive Charge', amount = 1, blur = false },
}
```

**Fields**

* `name` — internal item name
* `label` — displayed item label
* `amount` — required quantity
* `blur` — hides the item icon in the UI

Use `blur = true` for secret or sensitive items.

***

### Heist Images

Each heist should have a matching image uploaded to `UploadUrl`.

Format:

```javascript
{UploadUrl}/{name}.png
```

Example:

```lua
https://upload.domain.pl/static/furgonetka.png
```

If the image is missing, the heist entry may appear without a preview image.

***

### Notes

* The UI is built with Vue, so `ui/dist/` must be compiled before deployment
* `getCooldown` runs server-side
* Any resource referenced inside `getCooldown` must start before this resource
* Factions flagged as `isLSPD`, `isBCSO`, or `isSASPR` count toward police requirements
* `blur = true` hides the item icon in the UI


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mskscripts.gitbook.io/mskscripts/scripts/factions-and-heist-scoreboard/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.