# Configuration

### Prerequisites

Before setting up the force-appearance, ensure that you have the following dependency installed:

* **ox\_lib**: This library is required for the resource to function correctly.
  * **GitHub Repository**: [ox\_lib](https://github.com/overextended/ox_lib)
  * **Documentation**: [ox\_lib Documentation](https://overextended.dev/ox_lib)

## Configuration

This page covers all configuration options available in Force Appearance. All configuration files are located in the `config/` folder.

### Installation

#### 1. Database Setup

Run the SQL file to create necessary tables and columns:

```sql
-- The install.sql will automatically:
-- 1. Add skin and tattoos columns to your framework's character table
-- 2. Create the outfits table

-- For ESX:
ALTER TABLE `users` ADD COLUMN IF NOT EXISTS `skin` longtext NULL;
ALTER TABLE `users` ADD COLUMN IF NOT EXISTS `tattoos` LONGTEXT NULL DEFAULT '[]';

-- For QBCore/QBox:
ALTER TABLE `players` ADD COLUMN IF NOT EXISTS `skin` longtext NULL;
ALTER TABLE `players` ADD COLUMN IF NOT EXISTS `tattoos` LONGTEXT NULL DEFAULT '[]';

-- Outfits table (created automatically):
CREATE TABLE IF NOT EXISTS `outfits` (...)
```

#### 2. Resource Installation

1. Extract `force-appearance` to your resources folder
2. Add to your `server.cfg`:

```cfg
ensure oxmysql
ensure ox_lib
ensure force-appearance
```

3. Restart your server

#### 3. Framework Configuration

The system will auto-detect your framework, but you can manually configure it in `config/config.lua`.

### Core Configuration (`config/config.lua`)

#### Basic Settings

```lua
Config.Debug = false -- Enable debug prints (use only for development)
Config.Locale = 'en' -- Language: "ar", "en", "es", "fr", "pt", "de", "nl", "pl", "ru", "sv" or "auto"
Config.RunFetchPedOnStart = false -- Fetch all FiveM peds from documentation (only when new peds are added)
```

#### Framework Setup

```lua
Config.Framework = {
  name = "auto",    -- Options: "auto", "esx", "qbcore", "qbox", "custom"
  resource = "auto" -- Auto-detect or specify resource name: "es_extended", "qb-core", etc.
}
```

**Framework Options:**

* `"auto"` - Automatically detects ESX, QBCore, or QBox
* `"esx"` - Force ESX framework
* `"qbcore"` - Force QBCore framework
* `"qbox"` - Force QBox framework
* `"custom"` - Use custom framework (edit `client/custom/frameworks/custom.lua` and `server/custom/frameworks/custom.lua`)

#### Progress Bar System

```lua
Config.Progressbar = {
  system = "ox_lib" -- Options: "auto", "none", "esx_progressbar", "qb-progress", "ox_lib", "custom"
}
```

**Progress Bar Options:**

* `"auto"` - Auto-detect available progress bar
* `"none"` - Use built-in 3D text progress display
* `"ox_lib"` - Use ox\_lib progress bar
* `"esx_progressbar"` - ESX progress bar
* `"qb-progress"` - QBCore progress bar
* `"custom"` - Use custom progress bar (edit `client/custom/progressbar.lua`)

#### Admin Command

```lua
Config.SkinCommand = {
  enabled = true,
  command = "skin",
  Allowconsole = true,
  permission = { "admin" }, -- Framework-specific permission check
  suggestion = {
    help = "Open Skin Appearance Menu",
    arguments = {
      { name = 'playerId', help = "Player ID (optional)", type = 'number' }
    }
  }
}
```

Usage:

* `/skin` - Opens appearance menu for yourself
* `/skin [playerId]` - Opens appearance menu for target player (admin only)

#### Interaction System

Configure how players interact with shops:

```lua
Config.Interaction = {
  Target = {
    enabled = true,
    system = 'ox_target', -- Options: 'ox_target', 'qb-target'
    distance = 2.0
  },
  Marker = {
    enabled = true,
    id = 20, -- Marker type (https://docs.fivem.net/docs/game-references/markers/)
    distance = 7.0
  },
  Text3D = {
    enabled = true,
    distance = 5.0,
    key = 'E'
  },
  HelpNotification = {
    enabled = true,
    distance = 3.0,
    key = 'E'
  },
  keyCode = 38 -- E key (https://docs.fivem.net/docs/game-references/controls/)
}
```

**Interaction Modes:**

* **Target** - Use ox\_target or qb-target for interactions
* **Marker** - Display floating markers at shop locations
* **Text3D** - Show 3D text prompts
* **HelpNotification** - Native GTA help notification

You can enable multiple modes simultaneously.

#### UI Settings

```lua
Config.KeepFocus = true -- Keep NUI focused when menu is open
Config.ColorTheme = "green" -- Theme: "orange", "blue", "green", "purple", "red", "yellow", "default"
Config.Alignment = "start" -- Alignment: "start", "end"
Config.GrainEffect = true -- Cinematic grain overlay effect
```

#### Custom Color Themes

You can customize themes or create new ones:

```lua
Config.Colors = {
  green = {
    bg = "bg-emerald-900/98",          -- Main background
    secondary = "bg-emerald-600/95",   -- Secondary elements
    text = "text-emerald-50",          -- Text color
    border = "border-emerald-500/50",  -- Border color
    hover = "hover:bg-emerald-500/95", -- Hover state
    shadow = "shadow-emerald-900/40",  -- Shadow color
  },
  -- Add your custom theme here
  custom = {
    bg = "bg-your-color",
    secondary = "bg-your-color",
    text = "text-your-color",
    border = "border-your-color",
    hover = "hover:bg-your-color",
    shadow = "shadow-your-color",
  }
}
```

#### Character Animations

Configure the idle animations used in shops:

```lua
Config.Animations = {
  { dict = 'amb@world_human_hang_out_street@female_arms_crossed@base', anim = 'base' },
  { dict = 'amb@world_human_cop_idles@male@idle_b', anim = 'idle_d' },
  { dict = 'oddjobs@bailbond_surf_farm', anim = 'base' },
  { dict = 'amb@world_human_stand_guard@male@idle_a', anim = 'idle_a' },
  { dict = 'anim@miss@low@fin@vagos@', anim = 'idle_ped06' }
}
```

### Barber Shop Configuration (`config/barbershop.lua`)

#### Pricing

```lua
Barbershop.Config = {
  Prices = {
    ['hair'] = 100,
    ['beard'] = 50,
    ['eyebrows'] = 40,
    ['chest'] = 50,
    ['makeup'] = 80,
    ['lipstick'] = 60,
    ['blush'] = 50,
  }
}
```

#### Blip Settings

```lua
Blip = {
  enabled = true,
  sprite = 71,  -- Barber scissors icon
  color = 2,    -- Green
  scale = 0.8,
  label = "Barber Shop"
}
```

#### Shop Locations

Add or modify barber shop locations:

```lua
Locations = {
  {
    coords = vector3(-30.85, -151.73, 57.07), -- NPC interaction point
    entity = `s_f_m_fembarber`, -- NPC ped model
    heading = 328.10,
    chair = {
      coords = vector3(-35.41, -153.12, 57.92), -- Where player sits
      heading = 67.85,
      state = false
    },
    ped = {
      coords = vector3(-34.74, -153.97, 57.08), -- NPC spawn location
      heading = 65.85
    }
  },
  -- Add more locations...
}
```

#### Animations

```lua
Animations = {
  idle = {
    dict = 'amb@world_human_hang_out_street@female_arms_crossed@base',
    anim = 'base'
  },
  sitting = {
    dict = 'anim@heists@prison_heiststation@cop_reactions',
    anim = 'cop_b_idle'
  }
}
```

### Clothing Store Configuration (`config/clothingstore.lua`)

#### Shared Components

Define which categories are available in clothing stores:

```lua
Clothingstore.SharedComponents = {
  categories = {
    "clothes",      -- Clothing items
    "accessories",  -- Accessories
  }
}
```

#### Pricing

```lua
Prices = {
  ['tshirt'] = 100,
  ['torso'] = 150,
  ['arms'] = 100,
  ['pants'] = 120,
  ['shoes'] = 80,
  ['chain'] = 150,
  ['helmet'] = 100,
  ['glasses'] = 50,
  ['watches'] = 120,
  ['bracelets'] = 80,
  ['bproof'] = 200
}
```

#### Interior Offsets

Camera offsets for different clothing store interiors:

```lua
Interiors = {
  [140801] = vector3(0.6, 0.3, 0.6),
  [176129] = vector3(0.6, 0.3, 0.6),
  -- Interior hash = camera offset
}
```

#### Blip Settings

```lua
Blip = {
  enabled = true,
  sprite = 73,  -- T-shirt icon
  color = 47,   -- Purple
  scale = 0.8,
  label = "Clothing Store"
}
```

### Tattoo Shop Configuration (`config/tattoo.lua`)

Configure tattoo shop locations, pricing, and blips. Structure is similar to barber shops.

### Outfit System Configuration (`config/outfits.lua`)

```lua
Outfits.Config = {
  MaxOutfits = -1, -- -1 for unlimited, or set a number
  SavePrice = 100, -- Cost to save an outfit

  Components = {
    -- Which components are saved in outfits
    'tshirt_1', 'tshirt_2',
    'torso_1', 'torso_2',
    'arms', 'arms_2',
    'pants_1', 'pants_2',
    'shoes_1', 'shoes_2',
    'mask_1', 'mask_2',
    'chain_1', 'chain_2',
    'helmet_1', 'helmet_2',
    'glasses_1', 'glasses_2',
    'watches_1', 'watches_2',
    'bracelets_1', 'bracelets_2'
  },

  Dialog = {
    delete = {
      title = 'Delete Outfit',
      description = 'Are you sure you want to delete this outfit?'
    }
  }
}
```

### Performance Tuning

#### For Large Servers (100+ players)

```lua
-- In config/config.lua
Config.UpdateDelay = 100 -- Increase NUI update delay

-- In client/functions.lua (if needed)
Appearance.cacheExpiry = {
  peds = 600000,     -- 10 minutes
  tattoos = 600000,  -- 10 minutes
  appearance = 120000 -- 2 minutes
}
```

#### For Small Servers (<50 players)

```lua
Config.UpdateDelay = 30 -- Decrease for snappier feel

Appearance.cacheExpiry = {
  peds = 180000,    -- 3 minutes
  tattoos = 180000, -- 3 minutes
  appearance = 30000 -- 30 seconds
}
```

### Localization

#### Changing Language

Set the locale in `config/config.lua`:

```lua
Config.Locale = 'en' -- or 'es', 'fr', 'de', etc.
```

Or use auto-detection based on server locale:

```lua
Config.Locale = 'auto'
```

#### Available Languages

* Arabic (`ar`)
* German (`de`)
* English (`en`)
* Spanish (`es`)
* French (`fr`)
* Dutch (`nl`)
* Polish (`pl`)
* Portuguese (`pt`)
* Russian (`ru`)
* Swedish (`sv`)

#### Adding Custom Translations

1. Copy `locales/en.json` to `locales/your_lang.json`
2. Translate all strings
3. Set `Config.Locale = 'your_lang'`

### Custom Framework Integration

#### Setting Up Custom Framework

1. Set framework to custom:

```lua
Config.Framework = {
  name = "custom",
  resource = "your_framework"
}
```

2. Edit `client/custom/frameworks/custom.lua`:

```lua
if Config.Framework.name ~= "custom" then return end

-- Your framework client-side functions
Framework = {}

function Framework:GetPlayerData()
  -- Return player data
end

-- Implement all required functions
```

3. Edit `server/custom/frameworks/custom.lua`:

```lua
if Config.Framework.name ~= "custom" then return end

-- Your framework server-side functions
Framework = {}

-- Set your database table and column names
Framework.CharactersTable = "your_characters_table"
Framework.CharactersSkinColumn = "skin"
Framework.CharactersTattoosColumn = "tattoos"
Framework.CharactersIdentifierColumn = "identifier"

-- Implement required functions
```

### Next Steps

Now that your configuration is complete, check out the Usage & Integration guide to learn how to use the events, exports, and integrate with your scripts.


---

# 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://docs.forcedevelopments.com/resources/force-appearance/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.