MultiCharacter

MultiCharacter provides character selection, framework identity management, and spawn selection for QBCore, Qbox (qbx_core), and ESX Legacy. Players can create multiple characters, preview their appearances, and choose who to play. Each account has three character slots by default.

The resource requires a supported framework, MySQL provider, OneSync, BigDaddy-Appearance, and the version of BigDaddy-CharacterManager that includes the MultiCharacter editor integration. It is not a standalone appearance preset manager.

{:links-list}

INSTALLATION

  1. Open the downloaded ZIP and place the BigDaddy-MultiCharacter resource folder in your server's resources folder. If using the source project, deploy the nested folder with that name, not the solution folder. Include the compiled client/server assemblies and dependencies, plus the supplied bridge, html, manifest, configuration, and licensing files.
  2. Install BigDaddy-Appearance and the compatible BigDaddy-CharacterManager release with the MultiCharacter editor integration. Keep Character Manager's room/map assets. Follow the Character Manager PRO installation instructions, including its separate database setup.
  3. Add your product key (get it here) to settings.ini. Configure the required licenses for the appearance/editor resources as well.
  4. Configure your MySQL connection and start one supported provider: oxmysql, mysql-async, or ghmattimysql. MultiCharacter automatically creates its own bd_characters table; no separate SQL import is needed for that table. The database user must be able to create it.
  5. Enable OneSync and configure your framework using the table below. Stop competing character selectors and resources that independently log in or spawn characters during selection.
  6. Edit config.json, then start resources in dependency order. For example, with oxmysql:
ensure oxmysql

# Start your framework and its required dependencies here.

ensure BigDaddy-Appearance
ensure BigDaddy-CharacterManager
ensure BigDaddy-MultiCharacter
  1. Reconnect to open character selection. Test creation, editing, logout, and login with a test character before opening the server to players.

DO NOT RENAME THE FOLDER.

Keep the resource folder named BigDaddy-MultiCharacter.

{:is-danger}

FRAMEWORK SETUP

FRAMEWORK CONFIGURATION
QBCore Start qb-core and stop qb-multicharacter.
Qbox Start qbx_core. Set characters.useExternalCharacters = true in qbx_core/config/client.lua so its built-in character flow does not compete with MultiCharacter.
ESX Legacy Start es_extended, set Config.Multichar = true, and stop esx_multicharacter. Keep EsxCharacterPrefix aligned with existing character identifiers.

Framework auto-detection checks Qbox, then QBCore, then ESX. Database auto-detection checks oxmysql, then mysql-async, then ghmattimysql. Only a running provider can be selected.

Support is implemented in the supplied source for these frameworks and providers. Actual login, database persistence, spawning, and appearance behavior must be checked with your server's framework versions and other resources.

CONFIGURATION

Restart BigDaddy-MultiCharacter after changing configuration. Keep JSON property names and capitalization as supplied.

SETTINGS.INI

SECTION SETTING DESCRIPTION
licensing key1 Your product key. Licensing must complete before character selection starts.
settings debug Supplied as false. Enables diagnostic logging when set to true.
settings DesyncKey Internal licensing synchronization value. Leave the supplied value unchanged.

Character slots and editing availability are configured in config.json below.

CONFIG.JSON

config.json is read on the server. Account slot overrides are not distributed as a downloadable client configuration file.

These values match the checked project's supplied configuration. AllowOtherLocations is supplied as false, although omitting that property defaults it to true.

SETTING SUPPLIED VALUE DESCRIPTION
Framework auto auto, qbcore, qbx, or esx.
Database auto auto, oxmysql, mysql-async, or ghmattimysql.
MaxCharacters 3 Account slot limit, from 1 to 100. Lowering it does not remove existing characters or make them unselectable.
SlotOverrides {} Per-account limits keyed by a full license:... identifier. Each limit must be between 1 and 100.
CharacterManagerResource BigDaddy-CharacterManager Integrated appearance editor resource. Keep this aligned with the installed editor and manifest dependency.
EsxCharacterPrefix char ESX character identifier prefix. Letters only; match existing identifiers.
BucketStart 60000 Beginning of the private selection bucket range. Valid range: 1000 to 1000000000. Reserve this range from other bucket systems.
SessionTimeoutSeconds 1800 Abandoned selection/editor session timeout in seconds, from 120 to 7200. Expired selection sessions disconnect the player.
AllowCharacterEditing true Allows existing-character edits from selection and /skin. Setting this to false still allows new-character creation and deletion.
AllowLastLocation true Offers the framework's last saved position. Forced to true when AllowOtherLocations is false.
AllowOtherLocations false Allows named spawn choices when true. When false, only Last location is offered; new characters or missing/invalid saved positions still use the first configured spawn.
Spawns Legion Square, Sandy Shores Ordered spawn definitions. At least one is required, even in last-location-only mode.

ACCOUNT SLOT OVERRIDES

Replace the empty SlotOverrides object with accounts that need a different limit:

"SlotOverrides": {
  "license:REPLACE_WITH_THE_PLAYERS_IDENTIFIER": 5
}

Use the full account license identifier, not a character ID, Discord ID, or temporary server ID.

SELECTION SCENE

The scene controls the preview location independently of gameplay spawns. Each player selects characters in a private routing bucket.

SETTING SUPPLIED VALUE DESCRIPTION
Scene.Position X: 54.7156, Y: 7221.8982, Z: 3.5, Heading: 42.4638 Player preview position and facing direction.
Scene.Camera X: 52.6891, Y: 7223.8104, Z: 3.85 Camera world position.
Scene.LookAt X: 54.7156, Y: 7221.8982, Z: 3.5 World position the camera points toward.
Scene.FieldOfView 42.0 Camera field of view, from 20 to 90 degrees.
Scene.Hour 18 Selection scene hour, from 0 to 23.
Scene.Weather EXTRASUNNY Selection weather. Use a supported uppercase name below.
Scene.AnimationDictionary Empty Optional preview animation dictionary. Leave both animation fields empty for neutral standing idle.
Scene.AnimationName Empty Animation name within the dictionary.

Supported weather names: EXTRASUNNY, CLEAR, CLOUDS, OVERCAST, SMOG, FOGGY, RAIN, THUNDER, CLEARING, NEUTRAL, SNOW, BLIZZARD, SNOWLIGHT, XMAS, and HALLOWEEN.

Check scene height, collision, and camera framing in game with your installed maps. If using an MLO or shell, install and load it first; MultiCharacter does not create an interior shell.

SPAWN LOCATIONS

Each entry has a unique Id, display Label, optional Description, and a Position containing X, Y, Z, and Heading. The ID last is reserved for the saved-location option.

"Spawns": [
  {
    "Id": "legion",
    "Label": "Legion Square",
    "Description": "Start in the heart of Los Santos.",
    "Position": { "X": 195.17, "Y": -933.77, "Z": 30.69, "Heading": 144.0 }
  }
]

Set AllowOtherLocations to true to offer named locations. The first entry also supplies the fallback for new characters and characters without a valid saved location.

COMMANDS

COMMAND / KEY DESCRIPTION
/logout Saves and unloads the active framework character, then returns to selection without disconnecting. Finish or cancel any open editor first.
/skin Edits the active framework-linked character at the current location. Exit vehicles first. Requires AllowCharacterEditing: true and the integrated in-place editor. Cancel restores the previous appearance.
ESC Pauses the selection menu and releases mouse focus.
Enter Returns to selection after pausing.

HOW TO PLAY

  1. Join the server to open selection, or use /logout after playing.
  2. Select a character to preview it, or choose Create Character if a slot is available.
  3. For a new character, enter first and last name, date of birth, sex, nationality, and height in centimeters. Choose Create Appearance to open Character Manager's editor.
  4. Save the appearance to retain the new character as a draft. Canceling creation returns to selection without saving a new character.
  5. Choose Edit Appearance to change a selected character's look, when editing is enabled. Save or cancel to return to selection.
  6. Choose a spawn and select Play Character. The framework loads that character's identity and data. A draft's native framework record is created on its first successful login.

Disconnect leaves the server. Pausing selection does not log a character into the framework.

DELETING A CHARACTER

Select the character, choose Delete Character, check the name in the confirmation, and choose Permanently Delete. Choose Keep Character to cancel. Deletion is available only from selection while the character is offline.

CHARACTER DELETION IS PERMANENT.

Deletion removes the saved appearance, framework character, and linked character data. Back up your database and test with disposable characters before using this on a live server.

{:is-danger}

QBCore and Qbox use their framework deletion API, including its configured related tables. Additional cleanup searches the current database for string columns named citizenid, identifier, or owner and deletes rows whose value exactly matches the character's framework identifier. ESX uses this character-key cleanup and deletes its users row last in the transaction.

Custom tables with other keys or references embedded in JSON need their own integration. If cleanup fails, the character stays marked as deleting, cannot be played or edited, and occupies its slot. Check framework/database logs and select Delete again to retry; reconnect first if a timeout message instructs you to do so.

EXISTING CHARACTERS AND SAVED DATA

Existing framework characters are imported automatically with unchanged citizen IDs or ESX character identifiers. Disabled ESX characters remain unavailable.

Legacy skins and standalone Character Manager presets are not automatically converted or assigned. Imported characters without a managed appearance must set one before playing. Keep editing enabled while preparing those characters.

MultiCharacter stores its registry, identity links, slots, and managed appearances in bd_characters. Character Manager's standalone presets use the separate bd_character table. The framework owns money, inventory, jobs, health, armor, and other gameplay state. Starter money/default state follows normal framework creation logic; MultiCharacter does not grant starter items or charge for clothing.

Housing/apartment spawn selection and arbitrary third-party spawn-selector handoff are not included. Restarting MultiCharacter does not force already-loaded players back into selection.

DEVELOPER EXPORTS

These server-side exports accept a player's server ID:

EXPORT RETURNS
GetActiveCharacterId(source) Active Big Daddy registry character ID, or null if none is loaded. This is not the framework citizen ID or ESX identifier.
GetActiveCharacterName(source) Active character's first and last name, or null if none is loaded.

TROUBLESHOOTING

ISSUE WHAT TO CHECK
Selection does not start Check licensing, OneSync, resource names, dependency order, and server console errors.
Waiting for dependencies/database Confirm the selected framework and database provider are running and usable. Stop competing selectors. Initialization retries while waiting for dependencies.
Invalid configuration Check the named setting in the log, JSON syntax, supported ranges, scene coordinates, and required spawn list. Invalid configuration prevents initialization.
Appearance editor unavailable Install the compatible Character Manager integration, including EditExternalCharacter and EditExternalCharacterInPlace. Confirm BigDaddy-Appearance is ready. An older standalone-only release is insufficient.
Only Last location appears The supplied configuration has AllowOtherLocations: false. Set it to true to offer named spawns.
Edit button unavailable or /skin denied Check AllowCharacterEditing, the managed appearance, and whether another editor or selection operation is active.
Imported character cannot play Set its appearance first. Check whether the framework character is disabled, missing, or awaiting deletion cleanup.
Player or camera appears in the wrong place Check scene position, camera, look-at target, map loading, and collision independently from Spawns.
Operation reports an uncertain result Follow the error's reconnect instruction before retrying. Check framework/database logs for partially completed operations.
Selector/editor stops during use Active selection sessions are disconnected for cleanup. Reconnect if an interrupted editor leaves the session unusable.