Skip to main content

​
Resource fails to start - name assertion error

The folder must be named exactly awoken_multicharacter (underscore) for all frameworks. No version numbers, no suffixes, no extra characters. The resource checks its own name on startup and refuses to load if it doesn’t match.

​
Players spawn into the world instead of hitting the selector

  1. The old multichar is still running. Search every .cfg file on your server, not just server.cfg. A resource ensured in a category file will still load even if you commented it out in the main config.
  2. QBX’s built-in flag isn’t disabled. In qbx_core/config/client.lua, confirm multicharacter = false is set.

​
Character creation fails

Check the server console for the exact error. The most common cause is a qbx_core version that is too old or a missing players table column. Make sure you are on a recent release of qbx_core and that your DB schema is up to date.

​
Clothing editor doesn’t open for new characters

The clothing editor is opened by firing Config.FirstCharacterEvent on the client. If it isn’t showing:
  • Make sure the event name matches what your appearance resource expects. See the Configuration page for the correct event per resource.
  • Confirm the appearance resource is actually running (GetResourceState in F8 console).
  • This only fires when Config.StartingApartment = false. If apartments is enabled, the apartment resource is responsible for opening the editor.

​
Preview ped shows default appearance (saved skin not loading)

The preview ped in the selector should show the character’s last saved appearance. If it shows a blank freemode model instead:
  • Skin was never saved. If the player closed the clothing editor without saving, there is nothing to load. Once they save an appearance it will display correctly.
  • Appearance resource not running. Without it the skin application path won’t execute.
Skins are read from the playerskins table (citizenid, model, skin columns). Check that this table exists and that your appearance resource is actually writing to it when players save their look.

​
Two apartment / skin screens overlap on new characters (or the ped is invisible)

This means two resources are both running a new-player spawn flow - awoken and your framework/housing script. They fire at the same time and fight for focus, so you get the character selector or clothing editor stacked over the apartment selector, and the ped can end up invisible during customisation. Fix it by making one resource own the flow:
Using qbx_properties (or any qbx apartment script):
  1. In qbx_core/config/client.lua set startingApartment = false so qbx stops running its own starter apartment.
  2. In awoken config.lua set Config.StartingApartment = true.
Also confirm useExternalCharacters = true is set in qbx_core/config/client.lua.
See the Starting apartment section for the full single-owner rule.

​
Apartment selector doesn’t open for new characters

Check the server console when a new character is created. The resource logs which apartment resources it detected so you can see exactly what it found.
Supported: ps-housing, qbx_properties, qbx_apartments, qb-apartments, bcs_housing, 0r-apartment, okokSpawnSelector, vms_spawnselectorIf yours isn’t listed, set Config.StartingApartment = false and use Config.NewPlayerNoApartmentStartCoords as the fallback spawn point.

​
Discord role slots aren’t working

  • Bot token wrong or expired. Regenerate it in the Discord Developer Portal.
  • Server Members Intent disabled. Go to the Developer Portal, open your app, go to Bot, then Privileged Gateway Intents, and enable Server Members Intent. Without it role fetches silently fail and everyone gets Config.DefaultSlots.
  • Wrong IDs. guildId is your Discord server ID, not a channel or role ID. Right-click your server icon and copy the Server ID (requires Developer Mode in Discord settings). For role IDs, right-click the role and copy the Role ID.
Role data is cached when the player connects. A reconnect is needed for updated slots to take effect.

​
Framework preload times out (character loads but some systems don’t initialise)

The resource waits up to 10 seconds for the framework’s player loaded event after character selection. If it times out the character still spawns, but ESX or QBX dependent resources may not have their player object ready in time.
The gate listens for QBCore:Server:PlayerLoaded. If that event isn’t firing, check that nothing is blocking qbx_core or qb-core’s player load sequence.