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

# Setup

> Install and configure the background select script - backgrounds, items, perks, and custom functions

## Installation

<Steps>
  <Step title="Download">
    Get the latest release from our [Tebex store](https://tebex.dietrich-development.com) and download it from your [Keymaster](https://portal.cfx.re/assets/granted-assets)
  </Step>

  <Step title="Extract">
    Extract the script folder to your server's `resources` directory
  </Step>

  <Step title="Configure">
    Add `ensure [script-name]` to your `server.cfg`
  </Step>

  <Step title="Customize">
    Configure the `config.lua` file to match your server's background options
  </Step>
</Steps>

## Configuration

The script is configured through the `config.lua` file. Here are the main configuration sections:

### Basic settings

```lua theme={null}
Config = {}

-- Debug mode
Config.debug = true

-- Event Handlers
Config.triggerEvent = "vorp:initNewCharacter" -- For RSG: "rsg-spawn:client:newplayer"
Config.afterSelectClientEvent = false -- Set to false if no event should be triggered after selection
```

### Background configuration

Each background is defined with UI settings, gameplay settings, and optional custom functions:

```lua theme={null}
-- Background configurations with UI data
Config.Backgrounds = {
    hunter = {
        -- UI Settings
        label = "Hunter",
        description = "A skilled character, experienced in the art of hunting and survival in the wilderness.",
        image = "images/hunter.jpg",
        
        -- Gameplay Settings
        job = "hunter",
        perks = {
            { name = "hunting", amount = 5000 },
            { name = "gunslinger", amount = 2000 }
        },
        items = {
            { name = "WEAPON_BOW", isWeapon = true },
            { name = "ammoarrownormal", amount = 2 }
        },

        custom = function(source, charid, background)
            -- Custom code here to call custom events or do custom things (server side)
        end
    }
}
```

### UI settings

Configure the user interface appearance and behavior:

```lua theme={null}
-- UI Settings
Config.UISettings = {
    -- Set to true to make the player invisible while the UI is open
    playerInvisible = true,
    
    -- UI Text (can be customized for different languages)
    text = {
        title = "Background Selection",
        description = "Select your background to define your character through his past and origin - a choice that significantly shapes your game start.",
        confirmationTitle = "Are you sure?",
        confirmationMessage = "This selection is final and cannot be changed.",
        confirmButton = "Confirm",
        cancelButton = "Cancel",
        selectButton = "Select"
    }
}
```

## Adding custom backgrounds

To add a new background, add a new entry to the `Config.Backgrounds` table:

```lua theme={null}
-- Example: Adding a new background
my_new_background = {
    -- UI Settings
    label = "My New Background",          -- Name shown in UI
    description = "Description here...",  -- Description shown in UI
    image = "images/my_image.png",        -- Image path relative to html folder
    
    -- Gameplay Settings
    job = "myjob",
    money = 100,  -- Optional: starting money (can be negative)
    
    -- Optional: starting perks (compatible with weapon progression systems)
    perks = {     
        { name = "some_perk", amount = 1000 }
    },
    
    -- Optional: starting items
    items = {     
        { name = "some_item", amount = 5 },
        { name = "WEAPON_SOMETHING", isWeapon = true }
    },
    
    -- Optional: custom code (server side)
    custom = function(source, charid, background)
        -- Custom code here to call custom events or do custom things (server side)
    end
}
```

## Background configuration options

### UI settings

```lua theme={null}
-- Required UI settings for each background
label = "Background Name",           -- Display name in the UI
description = "Background description...", -- Detailed description
image = "images/background.jpg",     -- Image file path
```

### Gameplay settings

```lua theme={null}
-- Core gameplay settings
job = "jobname",                     -- Starting job assignment
money = 100,                        -- Starting money (can be negative)

-- Optional perk configuration
perks = {
    { name = "perk_name", amount = 5000 }  -- Perk name and starting amount
},

-- Optional item configuration
items = {
    { name = "item_name", amount = 5 },                    -- Regular item
    { name = "WEAPON_NAME", isWeapon = true },             -- Weapon item
    { name = "item_name", amount = 1, metadata = {...} }   -- Item with metadata
}
```

### Custom functions

```lua theme={null}
-- Optional custom server-side function
custom = function(source, charid, background)
    -- source: player source ID
    -- charid: character ID
    -- background: background configuration table
    
    -- Example: Trigger custom events
    TriggerEvent('my_custom_event', source, charid)
    
    -- Example: Call external functions
    exports['my_script']:doSomething(source, charid)
end
```

## Item configuration

### Regular items

```lua theme={null}
items = {
    { name = "bandage", amount = 5 },
    { name = "compass", amount = 1 }
}
```

### Weapon items

```lua theme={null}
items = {
    { name = "WEAPON_BOW", isWeapon = true },
    { name = "WEAPON_REVOLVER_NAVY", isWeapon = true }
}
```

### Items with metadata

```lua theme={null}
items = {
    { 
        name = "horse_token", 
        amount = 1, 
        metadata = { 
            description = "American Paint Splashed White", 
            id = "A_C_Horse_AmericanPaint_SplashedWhite" 
        }
    }
}
```

## Perk integration

The script integrates with weapon progression systems:

```lua theme={null}
-- Perk configuration example
perks = {
    { name = "hunting", amount = 5000 },      -- Hunting skill
    { name = "gunslinger", amount = 2000 },   -- Weapon proficiency
    { name = "herbalism", amount = 7600 },    -- Herbalism skill
    { name = "mining", amount = 5000 },       -- Mining skill
    { name = "farming", amount = 5000 },      -- Farming skill
    { name = "medic", amount = 5000 },        -- Medical skill
    { name = "fishing", amount = 5000 },      -- Fishing skill
    { name = "cooking", amount = 5000 },      -- Cooking skill
    { name = "blacksmithing", amount = 5000 }, -- Blacksmithing skill
    { name = "lumber", amount = 5000 }        -- Lumberjacking skill
}
```

<Note>
  Perk names and amounts should match your weapon progression system configuration.
</Note>

## Usage examples

### Professional background example

```lua theme={null}
blacksmith = {
    label = "Blacksmith",
    description = "A skilled craftsman who forges weapons, tools, and horseshoes, essential to frontier life.",
    image = "images/blacksmith.jpg",

    job = "blacksmith",
    perks = {
        { name = "blacksmithing", amount = 5000 }
    },
    items = {
        { name = "hammer", amount = 1 },
        { name = "anvil", amount = 1 },
        { name = "iron_ore", amount = 10 }
    }
}
```

### Social background example

```lua theme={null}
outlaw = {
    label = "Outlaw",
    description = "A wanted criminal with a dark past, skilled in stealth and survival.",
    image = "images/outlaw.jpg",

    job = "outlaw",
    money = -50,  -- Negative starting money
    perks = {
        { name = "gunslinger", amount = 3000 },
        { name = "stealth", amount = 2000 }
    },
    items = {
        { name = "lockpick", amount = 10 },
        { name = "WEAPON_REVOLVER_NAVY", isWeapon = true },
        { name = "ammorevolvernormal", amount = 2 }
    },
    custom = function(source, charid, background)
        -- Set wanted level or trigger custom events
        TriggerEvent('outlaw:setWanted', source, 1)
    end
}
```

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  Config.triggerEvent = "vorp:initNewCharacter"
  -- No additional configuration required
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  Config.triggerEvent = "rsg-spawn:client:newplayer"
  -- No additional configuration required
  ```

  ```lua Custom Framework theme={null}
  -- Set custom events in config.lua
  Config.triggerEvent = "your_custom_event"
  Config.afterSelectClientEvent = "your_after_select_event"

  -- Requires additional configuration in frameworkBridge.lua
  -- See framework bridge documentation for details
  ```
</CodeGroup>

## Performance considerations

<Info>
  The script is optimized for performance with several key features:
</Info>

* **Efficient UI loading**: Background images and data are loaded efficiently
* **Minimal server impact**: Background selection is processed quickly
* **Configurable events**: Optional event triggering to reduce overhead
* **Debug mode**: Can be disabled in production for optimal performance

### Performance tips

* **Image optimization**: Use compressed images for background pictures
* **Background count**: Limit the number of backgrounds to essential options
* **Custom functions**: Keep custom functions lightweight and efficient
* **Debug mode**: Disable `Config.debug` in production

## Troubleshooting

<AccordionGroup>
  <Accordion title="Background not appearing">
    Verify the background is properly added to Config.Backgrounds, check that the image file exists in the correct path, and ensure the configuration syntax is correct.
  </Accordion>

  <Accordion title="Items not being given">
    Confirm item names match your inventory system, check that weapons are properly marked with isWeapon = true, and verify the framework integration is working correctly.
  </Accordion>

  <Accordion title="Perks not applying">
    Ensure perk names match your weapon progression system, verify perk amounts are valid, and check that the progression system is properly integrated.
  </Accordion>

  <Accordion title="UI not opening">
    Check that the trigger event is properly configured for your framework, verify the script is started in server.cfg, and ensure there are no console errors.
  </Accordion>

  <Accordion title="Custom functions not working">
    Verify the custom function syntax is correct, check that the function parameters are properly used, and ensure the function doesn't contain errors that prevent execution.
  </Accordion>
</AccordionGroup>

## Support

If you encounter issues or need assistance:

<Columns cols={2}>
  <Card title="Discord support" icon="discord" href="https://discord.gg/4jhQsPr6pe">
    Join our Discord community for support and updates.
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Docs home - installation basics and links to every script.
  </Card>
</Columns>