Docs / Scripts & MLOs / Character Selection

Character Selection

A cinematic, camera-driven replacement for the default character menu: curated showcase locations, friend and partner previews standing beside your character, adjustable weather and pose, and an optional backstory field per character slot.

Currently QBox-only, built directly on qbx_core.

Dependencies

  • qbx_core
  • ox_lib
  • oxmysql: characters, relationships (friends/partner) and playtime are all persisted to the database

Optional: if you run scully_emotemenu alongside this, a small compatibility hook suppresses its hands-up/point gestures while the select screen owns the player, so the two don't fight for input. It isn't required. The select screen works fine without it.

What's in the config

shared/config.lua covers most of what you'll actually touch:

  • Locations: the showcase carousel. Each entry sets a ped spawn point, a curated camera angle, and optionally a locked pose or a friend-preview layout for that specific spot.
  • SpawnLocations: separate from the carousel; these populate the Spawn Selector screen once a player is past character select.
  • Poses: the emote list cycled by the in-menu "Change Pose" keybind.
  • WeatherOptions: the weather picker shown in Settings.
  • Characters: toggles the backstory field and its max length.
  • Partner: timing for the partner preview scene.
  • Camera: blend duration between showcase locations.
  • StoreUrl: the link opened by the menu's Store button. Point this at your own storefront.

shared/theme.lua controls the menu's visual theme separately from gameplay config.

How it's structured

The camera system is split into its own modules (client/camera/camera.lua, ped.lua, vehicle.lua, scene.lua, keybinds.lua) rather than one monolithic file, so each concern (framing, ped handling, ambient vehicles, scene composition, input) can be tuned independently. Friends and partners are tracked server-side (server/database/relationships.lua) and rendered client-side as preview peds at select. The UI itself is NUI-driven (web/dist), talking back to Lua through client/nui/callbacks.lua.

Installation notes

Follow the general Installation steps, then run the included database migrations before first start, since character relationships and playtime tracking both need their tables to exist. Update Config.StoreUrl and the showcase Locations coordinates to match your own server before going live; the defaults are tuned to a specific map layout and won't necessarily suit yours.

Common issues

  • Friend preview never shows: check friendPreviewCitizenIds / the friend-request flow completed on both accounts, and that the current showcase location actually defines friendSeats: some locations intentionally suppress it.
  • New characters spawn in the wrong place: that's controlled separately by Config.NewCharacterSpawn, not the showcase Locations list.
  • Store button does nothing: it opens Config.StoreUrl in the system browser. Confirm that's set to a real URL, not left as a placeholder.