# 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 provides a comprehensive guide to configuring **force-characters** for your server. ### Basic Configuration #### Debug Mode Enable or disable debug logging for troubleshooting: ```lua Config.Debug = true -- Set to false in production ``` #### Language Set the default language for the UI. Supports automatic language detection or manual selection: ```lua Config.Locale = 'en' -- Options: "ar", "de", "en", "es", "fr", "nl", "pl", "pt", "ru", "sv", or "auto" ``` ### Framework Configuration #### Framework Selection Configure which framework your server uses: ```lua Config.Framework = { name = "auto", -- Options: "esx", "qbcore", "qbx", "custom" or "auto" resource = "auto" -- Resource name for ESX or QBCore } ``` **Auto-detection** will automatically detect: * `es_extended` or `bablo_base` (ESX) * `qbx_core` (QBox) * `qb-core` (QBCore) If no framework is detected, it will default to `custom`. ### Character Settings #### Maximum Characters Set the maximum number of character slots per player: ```lua Config.MaxCharacters = 5 ``` > ⚠️ **Important**: Ensure `Config.Interior.peds` has at least the same number of entries as `Config.MaxCharacters`. #### Character Features ```lua Config.DisableCharDeletion = false -- Set to true to prevent players from deleting characters Config.DisableCharCreator = false -- Set to true to disable built-in character creator Config.CharactersImage = true -- Enable/disable character images ``` ### Interior Configuration Configure the character selection interior location and ped positions: ```lua Config.Interior = { coords = vector3(-802.37, 175.28, 72.84), -- Interior coordinates hideCoords = vector4(-797.21, 178.22, 72.83, 23.03), -- Hidden player position Camera = { coords = vector4(-802.54, 177.30, 72.84, 181.89), -- Camera position and rotation }, peds = { -- Each entry represents a character slot position { coords = vector4(-803.67, 171.43, 71.44, 291.90), scenario = false, -- Can be scenario name or false grounded = false, -- Should ped be on ground dict = "missheist_jewelleadinout", -- Animation dictionary anim = "jh_int_outro_loop_a" -- Animation name }, -- Add more ped positions (must have at least Config.MaxCharacters entries) } } ``` #### Ped Configuration Options * **coords**: Position and heading of the character ped * **scenario**: GTA scenario name (e.g., `"WORLD_HUMAN_GUARD_STAND"`) or `false` for animation * **grounded**: Whether the ped should be on the ground * **dict**: Animation dictionary (used when scenario is false) * **anim**: Animation name (used when scenario is false) ### Appearance System Configure which appearance system to use: ```lua Config.Appearance = "auto" -- Options: "auto", "esx_skin", "qb-clothing", "illenium-appearance", -- "rcore_clothing", "force-appearance" or "custom" ``` **Auto-detection** will check for these resources in order: 1. `force-appearance` 2. `skinchanger` or `esx_skin` 3. `qb-clothing` 4. `illenium-appearance` 5. `rcore_clothing` If none are found, it defaults to `custom`. ### Spawn Configuration #### Default Spawn Location Set the default spawn location when no other spawn is available: ```lua Config.DefaultSpawnLocation = vector4(402.90, -996.81, -100.00, 175.0) ``` #### Spawn Selector Enable or disable the spawn selector: ```lua Config.UseSpawnSelector = true ``` #### Spawn Points Configure available spawn locations: ```lua Config.SpawnPoints = { { name = "lastlocation", -- Internal identifier label = "Last Location", -- Display name description = "Last Location", -- Description shown to player }, { name = "legion", label = "Legion Square", description = "Legion Square", coords = { x = 223.16, y = -888.62, z = 30.69 }, -- Spawn coordinates ui = { left = 71.5, top = 52.5 }, -- UI position on map (percentage) }, { name = "policestation", label = "Police Station", description = "Police Station", job = "police", -- Only available for this job coords = { x = 396.3, y = -1636.77, z = 29.29 }, ui = { left = 73.75, top = 50 }, }, } ``` #### Spawn Point Properties * **name**: Unique identifier * **label**: Display name in UI * **description**: Description text * **coords**: Spawn coordinates `{x, y, z}` (optional for `lastlocation`) * **job**: Job requirement (optional) * **ui**: Position on map in UI `{left, top}` in percentage ### Character Information Configure which character information fields to display: ```lua Config.charInfo = { firstname = true, -- Show first name lastname = true, -- Show last name dateofbirth = true, -- Show date of birth phone = true, -- Show phone number money = true, -- Show cash amount bank = true, -- Show bank balance height = true, -- Show height job = true, -- Show job grade = true, -- Show job grade gender = true, -- Show gender nationality = true, -- Show nationality image = true, -- Show character image } ``` ### Start Data Configure default values for new characters: ```lua Config.StartData = { dateformat = "yyyy-mm-dd", -- Date format for birth date money = 1000, -- Starting cash bank = 5000, -- Starting bank balance job = "unemployed", -- Starting job grade = 0 -- Starting job grade } ``` > 📝 **Note**: If using QBCore, change money start data in `qb-core/config.lua` #### Starter Items Define items given to new characters: ```lua Config.StarterItems = { { item = "iphone", amount = 1 }, { item = "water", amount = 5 }, -- Add more items as needed } ``` ### Height Configuration Set minimum and maximum height values (in centimeters): ```lua Config.height = { min = 100, -- Minimum height max = 210, -- Maximum height } ``` ### Interface Configuration #### Color Theme Choose from multiple color themes: ```lua Config.Interface = { ColorTheme = "green", -- Options: "orange", "blue", "green", "purple", "red", "yellow", "default" GrayScale = false, -- Enable grayscale mode } ``` #### Animations Configure UI animations: ```lua Config.Interface.Animations = { enabled = true, -- Enable/disable animations duration = 300, -- Animation duration in milliseconds type = "fade", -- Animation type } ``` #### UI Positions Customize UI component positions using Tailwind CSS classes: ```lua Config.Interface.Positions = { characters = "absolute bottom-4 p-8 px-14", creator = "flex justify-end items-start h-screen w-screen pr-12 pt-4", } ``` #### Music Player Configure the built-in music player: ```lua Config.Interface.MusicPlayer = { enabled = false, -- Enable/disable music player volume = 0.01, -- Default volume (0.0 to 1.0) autoplay = false, -- Start playing automatically shuffle = false, -- Enable shuffle mode repeats = "none", -- Options: "none", "one", "all" visualizer = true, -- Show audio visualizer playlist = { { title = "Song Title", artist = "Artist Name", cover = "nui://force-characters/web/public/default-cover.png", src = "nui://force-characters/web/public/default-song.mp3", }, -- Add more songs }, } ``` **Music Player Properties** * **enabled**: Turn music player on/off * **volume**: Default volume level (0.0 = mute, 1.0 = max) * **autoplay**: Automatically start playing on load * **shuffle**: Randomize song order * **repeats**: Repeat mode ("none", "one", "all") * **visualizer**: Display audio visualization * **playlist**: Array of song objects with title, artist, cover image, and source ### Character Creator Set the location for character creation: ```lua Config.CharCreator = { coords = vector4(402.90, -996.81, -100.00, 175.0), } ``` ### Spawn Menu Command Configure the spawn menu command that allows players to reopen the spawn selector: ```lua Config.SpawnMenuCommand = { enabled = true, -- Enable/disable the command command = "spawnmenu", -- Command name protections = { combatDelay = true, -- Prevent use during combat deathCheck = true, -- Prevent use when dead }, -- Custom restriction function restricted = function() -- Return true to allow, false to deny -- Add your custom logic here return true end } ``` #### Protection Options * **combatDelay**: Blocks command usage during combat * **deathCheck**: Blocks command usage when player is dead * **restricted**: Custom function for additional restrictions ### Example Configuration Here's a complete example configuration for a typical server: ```lua Config = {} Config.Debug = false Config.Locale = 'en' Config.Framework = { name = "esx", resource = "es_extended" } Config.MaxCharacters = 4 Config.Appearance = "force-appearance" Config.UseSpawnSelector = true Config.DisableCharDeletion = false Config.CharactersImage = true Config.StartData = { dateformat = "yyyy-mm-dd", money = 2500, bank = 10000, job = "unemployed", grade = 0 } Config.StarterItems = { { item = "phone", amount = 1 }, { item = "id_card", amount = 1 }, { item = "water", amount = 3 }, } Config.Interface = { ColorTheme = "blue", GrayScale = false, MusicPlayer = { enabled = true, volume = 0.05, autoplay = true, }, } ``` ### Tips & Best Practices 1. **Always test** configuration changes in a development environment first 2. **Set Debug to false** in production for better performance 3. **Match ped positions** with MaxCharacters count 4. **Use job-specific spawns** for better roleplay immersion 5. **Choose appropriate starter items** based on your server economy 6. **Customize UI theme** to match your server branding 7. **Test appearance system** compatibility before going live ### Next Steps Now that you've configured force-characters, head over to Usage / Integration to learn how to integrate it with your other resources. --- # 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-characters/configuration.md?ask= ``` 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.