Features Overview

Table of Contents

• Character Selection
• Character Creation
• Scene System
• Preview Peds
• Announcements
• Logout System
• Validation System
• Integration Points
• Technical Architecture

---

Character Selection

Overview

The character selection screen displays all characters for the current player with full visual preview.

Character Display

Each character card shows:

• First and last name
• State ID (CitizenID)
• Last played timestamp
• Character slot number

Character Actions

Action	Description
Select	Click a character card to select and spawn
Delete	Remove a character (if enabled in config)
Create	Create a new character (if slots available)

Multi-Character Support

• Default 5 character slots per player
• Configurable per-player slot limits
• Characters sorted by creation order (CID)

---

Character Creation

Creation Wizard

Character creation follows a simple step-by-step process:

Step 1: Personal Information

• First name
• Last name

Step 2: Details

• Date of birth (date picker)
• Gender selection (Male/Female)
• Nationality (dropdown or freeform)

Input Validation

All inputs are validated on both client and server:

Field	Validation
First Name	2-20 characters, letters/spaces/hyphens/apostrophes only
Last Name	2-20 characters, letters/spaces/hyphens/apostrophes only
Date of Birth	Valid date, age between 18-80 (configurable)
Gender	Must be 0 (male) or 1 (female)
Nationality	2-50 characters

Name Formatting

Names are automatically formatted:

• john → John
• MARY → Mary
• van der berg → Van Der Berg
• o'brien → O'Brien

Post-Creation Flow

After character creation:

1. Character is saved to database
2. QBCore player data is initialized
3. Starter items are given (from QBCore.Shared.StarterItems)
4. Spawn flow begins:
   • With qb-apartments: Opens apartment selection
   • Without qb-apartments: Spawns at default location

---

Scene System

Overview

Scenes provide cinematic backgrounds for character selection, making each login a visual experience.

Included Scenes

Scene	Description	Features
Apartment	Luxury high-rise interior	4 ped positions, evening setting
Garage	Underground car garage	3 ped positions, vehicle preview
Pier	Del Perro Pier	3 ped positions, daytime
Sinner Street	Street corner	1 ped position, motorcycle

Scene Features

Camera System:

• Custom camera angles per scene
• Per-ped camera overrides
• Smooth camera transitions
• Configurable FOV

Environment Control:

• Weather override (per scene)
• Time of day override (per scene)
• No interference with server weather/time

Vehicles:

• Optional preview vehicles
• Static display only
• Configurable model and position

Scene Persistence

• Player's scene preference is saved locally
• Persists across sessions via KVP storage
• Falls back to configured default scene

Scene Selector

The UI includes a scene selector that allows players to:

• Browse available scenes
• Preview scene names
• Switch scenes instantly
• Preference auto-saves

---

Preview Peds

Overview

Preview peds display each character's full appearance on the selection screen.

Appearance Data

Preview peds include:

• Character model (gender-based)
• Face features (from oxide-clothing)
• Hair style and color
• Full clothing outfit
• Accessories and props

Ped Positions

Each scene can have multiple ped positions:

• ped - Primary position (first character)
• ped_2 - Second position
• ped_3 - Third position
• ped_4 - Fourth position (and so on)

Characters are displayed at their respective positions based on slot order.

Animations

Each ped position has a configured animation:

• Animations play continuously
• Different animations per scene/position
• Configurable animation dict and name

Camera Transitions

When selecting a character:

1. Camera smoothly transitions to that character's position
2. Uses position-specific camera settings if defined
3. Falls back to scene's default camera

---

Announcements

Overview

Display important server information on the character selection screen.

Announcement Types

Type	Icon	Use Case
info	Info icon	General information, welcome messages
update	Update icon	Patch notes, new features
warning	Warning icon	Important notices, maintenance

Display

Announcements appear in a dedicated panel showing:

• Announcement title
• Full message body
• Date posted
• Type indicator (color-coded)

Management

Announcements are configured in config.lua:

• Add new announcements to the array
• Remove old announcements as needed
• Order determines display order

---

Logout System

Overview

The logout system allows players to return to character selection without reconnecting.

Logout Flow

1. Player triggers logout (command or UI button)
2. Screen fades to black
3. Character data is saved
4. Player is logged out from QBCore
5. Character selection screen appears
6. Screen fades back in

Logout Methods

Method	Description
Command	Type /logout in chat
UI Button	Click logout button in character selection

Timing

The logout transition has configurable timing:

• Fade out duration (default: 500ms)
• Hold black screen (default: 1500ms)
• Fade in duration (default: 500ms)

---

Validation System

Shared Validation

Oxide Multichar uses a shared validation system accessible to both client and server.

Available Functions

-- Validate a name
local valid, error = OxideMultichar.ValidateName('John')
-- Returns: true or false, error message

-- Validate date of birth
local valid, error = OxideMultichar.ValidateDOB('1990-01-15')
-- Returns: true or false, error message

-- Validate nationality
local valid, error = OxideMultichar.ValidateNationality('American')
-- Returns: true or false, error message

-- Format a name
local formatted = OxideMultichar.FormatName('john doe')
-- Returns: 'John Doe'

Validation Rules

Name Validation:

• Not empty
• Length within configured min/max
• Starts with a letter
• Only letters, spaces, hyphens, apostrophes

DOB Validation:

• Valid YYYY-MM-DD format
• Valid month (1-12)
• Valid day for the month
• Leap year handling for February
• Age within configured range

Nationality Validation:

• Not empty
• Length 2-50 characters

Security

• Client-side validation for immediate feedback
• Server-side validation enforced before database operations
• All character data re-validated on server before creation

---

Integration Points

QBCore Framework

Full integration with QBCore:

• QBCore.Player.Login() for character selection/creation
• QBCore.Player.Logout() for logout
• QBCore.Player.DeleteCharacter() for character deletion
• QBCore.Commands for admin commands
• QBCore.Shared.StarterItems for new character items

oxide-clothing

Character appearance integration:

• Fetches face, hair, and clothing data
• Applies full appearance to preview peds
• Uses ApplyFullCharacter export

qb-apartments

New character spawn integration:

• Detects if qb-apartments is started
• Opens apartment selection for new characters
• Sets routing bucket for apartment selection

qb-spawn

Existing character spawn integration:

• Opens spawn selection UI
• Player chooses spawn location
• Respects last saved position option

ox_lib

Utility library integration:

• lib.callback for client-server communication
• lib.print for debug logging
• Model loading utilities

Routing Buckets

• Players placed in isolated buckets during selection
• Prevents interaction with other players
• Restored to bucket 0 after spawning

Database

Character data queries:

• Single optimized query with JOINs
• Fetches player, appearance, and clothing data
• No N+1 query problems

---

Technical Architecture

Client Modules

Module	File	Responsibility
Camera	camera.lua	Camera creation, transitions, idle animation
Scene	scene.lua	Scene loading, weather, time, vehicles
NUI	nui.lua	NUI communication, callbacks
Selection	selection.lua	Character selection, preview peds
Creator	creator.lua	Character creation wizard

Communication Flow

[NUI (Vue)] <-> [nui.lua] <-> [server/main.lua]
     |              |
     └── fetchNui/SendNUIMessage

Module Loading Order

Modules are loaded via fxmanifest in dependency order:

1. camera.lua
2. scene.lua
3. nui.lua
4. selection.lua
5. creator.lua
6. main.lua