Installation Guide

This installation guide covers the required resources, database setup, server.cfg ordering, optional housing and appearance setup, and Tebex slot package configuration for ARS Multicharacter.

Prerequisites

• ox_lib — required for locale loading, commands, callbacks, and NUI notifications
• oxmysql — required for character queries, slot overrides, and redeem codes
• One framework resource: qbx_core, qb-core, or es_extended
• One supported appearance resource for first-time character creation
• Optional: ps-housing, qb-houses, or qb-apartments for housing-aware spawn selection
• Optional: Tebex account and connected FiveM game server for selling character slots

Installation Steps

1. Download and Place Resource

Place the resource in your server’s resources folder:

server-data/resources/[folder]/ars_multicharacter/

The built NUI files are already included in html/, so the production resource does not need a frontend build step.

2. Import the Database Tables

Run ars_multicharacter.sql in your database:

CREATE TABLE IF NOT EXISTS `ars_multicharacter_slots` (
  `license` VARCHAR(60) NOT NULL,
  `slots` INT NOT NULL DEFAULT 4,
  PRIMARY KEY (`license`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

CREATE TABLE IF NOT EXISTS `ars_multicharacter_auth_codes` (
  `code` VARCHAR(64) NOT NULL,
  `slots` INT NOT NULL DEFAULT 1,
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `redeemed_by` VARCHAR(60) NULL DEFAULT NULL,
  `redeemed_at` TIMESTAMP NULL DEFAULT NULL,
  PRIMARY KEY (`code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

3. Configure Framework Mode

Open config.lua and confirm the framework mode:

Config.Framework = 'auto'

auto detects qbx_core, then qb-core, then es_extended. If your server starts resources in an unusual order, use an explicit value:

Config.Framework = 'qb'
Config.Framework = 'qbx'
Config.Framework = 'esx'

4. Configure Appearance

Install and start one supported appearance resource before ars_multicharacter:

Priority	Resource	Notes
1	bl_appearance	Uses InitialCreation and SetPedAppearance
2	illenium-appearance	Works with compatible resources such as murderface-appearance and juddlie_appearance
3	qs-appearance	ILLENIUM-compatible API
4	fivem-appearance	ILLENIUM-compatible API
5	qb-clothing	Legacy QBCore clothing flow
6	skinchanger	Legacy ESX skinchanger flow

To force a specific appearance resource:

Config.FrameworkSettings = {
    qb = {
        starterItems = true,
        skinResource = 'illenium-appearance',
    },
    qbx = {
        starterItems = true,
        skinResource = 'illenium-appearance',
    },
    esx = {
        starterItems = true,
        prefix = 'char',
        skinResource = 'skinchanger',
    },
}

5. Configure Housing

Housing is optional. The default auto mode detects ps-housing first, then qb-houses.

Config.Housing = {
    resource = 'auto',
    useApartmentForNewChar = false,
}

Setting	Values	Purpose
resource	'auto', 'ps-housing', 'qb-housing', 'none'	Selects the housing integration
useApartmentForNewChar	true or false	Sends new characters to qb-apartments when using qb-houses

6. Add to Server Config

Ensure dependencies and your framework start before ars_multicharacter:

ensure ox_lib
ensure oxmysql
ensure [your-framework-resource]
ensure [your-appearance-resource]
ensure [your-housing-resource]
ensure ars_multicharacter

Example for a QBCore server using illenium-appearance:

ensure ox_lib
ensure oxmysql
ensure qb-core
ensure illenium-appearance
ensure ars_multicharacter

7. Configure Tebex Slot Packages

Tebex packages create redeemable slot codes from the Tebex transaction ID. Players redeem that transaction ID in the UI or with /redeemcharslot <code>.

Connect Tebex to Your FiveM Server

1. In Tebex, open Settings > Game Servers.
2. Copy your FiveM server secret key.
3. Add it to server.cfg:

sv_tebexSecret "YOUR_TEBEX_SECRET_KEY_HERE"

Warning: Keep your Tebex secret private. Anyone with access to it can send commands to your server as Tebex.

Create a Character Slot Package

1. In Tebex, create or edit a package.
2. Add a game server command for your FiveM server.
3. Use this command format:

tebex_charslot {transaction} 5

Replace 5 with the number of character slots the package should grant.

4. Enable Execute the command even if the player is offline.

Store Link

If you want the selector to show a purchase button, set your store URL:

Config.SlotOverrides = {
    enabled = true,
    storeUrl = 'https://your-store.tebex.io',
}

Verification

1. Start the server and join as a normal player.
2. Confirm the character selector opens with portrait peds and the configured UI layout.
3. Create a new character and verify the configured appearance resource opens.
4. Save the character and choose a spawn location.
5. Use /logout to return to the selector.
6. As an admin, run /setcharslots <license> 3 and rejoin to confirm the slot count changes.
7. Generate a code with /generatecharcode 2, redeem it with /redeemcharslot <code>, and confirm the slot count increases.

Updating

1. Back up config.lua and server/utils.lua.
2. Replace the resource files with the new version.
3. Compare your backup against the new defaults.
4. Restore your custom values and restart the resource or server.

Troubleshooting

Character Selector Does Not Open

• Confirm ox_lib, oxmysql, and your framework start before ars_multicharacter.
• Check the server console for Framework not found or bridge errors.
• Confirm ui_page 'html/index.html' is active in fxmanifest.lua.

Appearance Creator Does Not Open

• Start a supported appearance resource before ars_multicharacter.
• Set Config.FrameworkSettings.<framework>.skinResource explicitly if auto-detection picks the wrong resource.
• Check the debug log line Skin resource detected: <resource>.

Housing Does Not Appear in Spawn Selection

• Confirm ps-housing, qb-houses, or qb-apartments is started before ars_multicharacter.
• Set Config.Housing.resource to 'ps-housing', 'qb-housing', or 'none' if auto-detection is wrong.
• For new-character apartments, use qb-houses with qb-apartments and set useApartmentForNewChar = true.

Tebex Codes Are Not Redeemable

• Verify the Tebex command is exactly tebex_charslot {transaction} <slots>.
• Confirm Execute the command even if the player is offline is enabled.
• Check ars_multicharacter_auth_codes for the transaction ID.
• Make sure players paste the Tebex transaction ID, not the package name.

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.