Installation Guide

Table of Contents

• Prerequisites
• Download and Placement
• Server Configuration
• Building the Web UI
• Migration from qb-multicharacter
• First Launch Verification
• Next Steps

---

Prerequisites

Before installing Oxide Multichar, ensure you have:

Requirement	Description
qb-core	QBCore framework (required)
ox_lib	Overextended library for callbacks and utilities (required)
oxmysql	MySQL database resource (required)
oxide-clothing	Character appearance system - provides qb-clothing (required)
qb-apartments	For new character spawn flow (optional)
qb-spawn	For existing character spawn selection (optional)
Node.js 18+	For building the web UI (only if not pre-built)

---

Download and Placement

1. Download the oxide-multichar resource from your purchase location.

2. Extract the folder to your server's resources directory:

resources/
└── [your-folder]/
    └── oxide-multichar/
        ├── client/
        │   └── modules/
        ├── server/
        ├── shared/
        ├── web/
        │   └── dist/      # Pre-built UI (or build yourself)
        ├── config.lua
        └── fxmanifest.lua

3. Ensure the folder is named exactly oxide-multichar.

---

Server Configuration

Step 1: Remove or Disable qb-multicharacter

Oxide Multichar replaces qb-multicharacter. You must remove or disable the original:

Option A - Remove from server.cfg:

# Remove or comment out this line:
# ensure qb-multicharacter

Option B - Delete the resource:

Delete the qb-multicharacter folder from your resources directory.

Important: Do NOT run both resources at the same time.

Step 2: Add oxide-multichar to server.cfg

Add the following to your server.cfg:

# Oxide Multichar - Must start AFTER dependencies
ensure oxide-multichar

Step 3: Ensure Correct Start Order

Your resource start order should look like this:

ensure oxmysql
ensure ox_lib
ensure qb-core

# Appearance system
ensure oxide-clothing

# Other QBCore resources...
ensure qb-inventory
ensure qb-apartments    # Optional
ensure qb-spawn         # Optional

# Multichar - ensure it starts after dependencies
ensure oxide-multichar

---

Building the Web UI

If your download includes a pre-built web/dist/ folder, you can skip this section.

Building Locally

1. Ensure you have Node.js 18+ installed

2. Navigate to the web directory:

cd resources/[your-folder]/oxide-multichar/web

3. Install dependencies:

npm install

4. Build for production:

npm run build

5. Verify that web/dist/ was created with:
   • index.html
   • assets/*.js
   • assets/*.css

Development Mode

For UI development with hot reload:

cd web
npm run dev

This starts a local dev server. Changes will auto-refresh in the browser.

---

Migration from qb-multicharacter

If you have an existing qb-multicharacter installation:

Step 1: Backup Your Server

Create a backup of your resources folder before making changes.

Step 2: Stop Your Server

Shut down your FiveM server completely.

Step 3: Update server.cfg

Replace qb-multicharacter with oxide-multichar:

# Remove this:
# ensure qb-multicharacter

# Add this:
ensure oxide-multichar

Step 4: Configure oxide-multichar

Review config.lua and adjust settings to match your server's needs:

• Character slot limits
• Age range requirements
• Scene preferences
• Logout configuration

Step 5: Start Your Server

Start your server and verify the migration was successful.

What Works Automatically

Feature	Status
Existing characters	Fully compatible
Character appearance	Works with oxide-clothing
QBCore player data	No migration needed
Spawn locations	Uses qb-spawn/qb-apartments

---

First Launch Verification

After starting your server, verify the installation:

1. Check Server Console

Look for this startup message:

[ox_lib] Oxide Multichar (QBCore) initialized

2. Test In-Game

1. Connect to your server
2. The character selection screen should appear automatically
3. Verify you can see existing characters (if any)
4. Test creating a new character
5. Test selecting an existing character
6. Test the logout command: /logout

3. Verify Scene System

1. Check that scenes load properly
2. Use the scene selector to switch between scenes
3. Verify your scene preference persists after reconnecting

---

Next Steps

• Configure the resource - Customize slots, scenes, and behavior
• Explore features - Discover all capabilities
• Troubleshooting - Common issues and solutions