Cipher MultiCharacter

Requirements

Required

• oxmysql
• qbx_core or qb-core

Recommended

• illenium-appearance, fivem-appearance or qb-clothing
• qbx_apartments or qb-apartments when new characters choose a starting apartment

Current release is v2.1.2.

Installation

1. Drop Cipher-MultiCharacter into your resources directory.
2. Start it after the framework, oxmysql, appearance and apartment resources.
3. Disable the multicharacter resource that came with your framework.
4. Review all three files under config/.
5. Restart and test both an existing character and the complete new-character flow.

ensure Cipher-MultiCharacter

QBox

Set this in qbx_core/config/client.lua:

useExternalCharacters = true

QBCore

Stop or remove qb-multicharacter. Do not run two character selectors together.

Cipher creates its two small tables automatically by default. If automatic table creation is disabled, import sql/cipher_multichar.sql.

Configuration

• config/shared.lua — character rules, first-time setup and spawn locations
• config/client.lua — scene, cameras, animations, integrations and UI style
• config/server.lua — slots, appearance storage, dossier fields and cooldowns
• locales/en.lua — every player-facing line
• integrations/ — focused adapters for custom or renamed resources

The resource validates framework names, duplicate spawn IDs, coordinates, appearance table names and slot settings during startup. Fix every CONFIG ERROR before opening the server.

Saved appearances

The default query expects the common playerskins layout with id, citizenid, model, skin and active columns. Change Config.Server.Appearance if your resource renamed the table or fields.

The client adapter is selected automatically. Force one in Config.Client.Integrations.appearance when more than one compatible clothing resource is installed.

Spawn locations

Locations support categories, descriptions, districts, map cameras and server-side permissions. Empty categories hide automatically. Last location has its own category, and uncategorized entries use defaultCategory.

{
    id = 'pillbox',
    category = 'city',
    label = 'Pillbox Medical',
    coords = vec4(298.52, -584.61, 43.26, 70.0),
    camera = vec3(314.0, -594.0, 54.0),
    lookAt = vec3(298.52, -584.61, 43.26),
    permission = {
        jobs = { police = 0, ambulance = 2 },
        ace = 'cipher.spawn.pillbox'
    }
}

Available permission checks are jobs, gangs, citizen IDs and ACE. The server checks access again when a spawn is selected; hiding a button is not treated as security.

Dossiers and activity

The standard dossier can show identity, occupation, position, affiliation, phone, nationality, account, money and activity. Metadata fields can be declared in config, while other resources can calculate their own fields:

exports['Cipher-MultiCharacter']:RegisterDossierProvider(function(source, citizenid, playerRow, dossier)
    return {
        { label = 'Reputation', value = 'Trusted' },
        { label = 'Crew', value = 'Southside Customs' }
    }
end)

Activity tracks previous selection, total session playtime, first tracked date and the last saved district. Playtime writes when the player unloads, disconnects or the resource stops rather than on a repeating query.

Character slots

Slots can come from the default config, ACE permissions, per-license overrides or another resource. Every result is clamped to the configured maximum.

add_ace group.supporter cipher.slots.6 allow
add_ace group.vip cipher.slots.8 allow
add_ace group.admin cipher.multichar.admin allow

Staff with the admin ACE can use /charslots for the manager, or the direct form:

/charslots 12 8
/charslots 12 reset

Changes apply the next time the target's character list loads. The command does not force a logout.

Integration API

Server exports expose allowed slots, the selected character, spawn permission checks, provider registration and persistent slot overrides. Client exports expose the selected character and whether selection is active.

Local lifecycle events fire when a character is previewed, selected, created, deleted and spawned. Use these to pair another script with Cipher MultiCharacter without making it a required dependency.

The first-character flow defaults to Identity → Apartment → Clothing. Standard QBox and QBCore apartment resources hand off to clothing themselves. For a custom apartment event that does not, set opensClothingAfterSelection to false.

Troubleshooting

Two selectors open

The old framework selector is still running. Disable it and keep only Cipher MultiCharacter.

A saved appearance is wrong

Confirm the adapter, table and column names match the exact appearance resource version on your server.

A spawn is missing

Check its category contains at least one location and the character passes its job, gang, citizen ID or ACE rules.

The camera is inside a wall

Test the configured camera and lookAt coordinates with all of your map assets and interiors loaded.

Updating

1. Back up the resource configuration and database.
2. Read the release notes for adapter or schema changes.
3. Replace the whole resource folder.
4. Merge your settings and restart.
5. Retest existing characters, new-character setup, appearance loading and every spawn category.

Support

Include your framework, appearance and apartment resources, the full console error, whether the character is new or existing, and the steps that caused the problem.