DATA MIGRATION#

Zero-Touch Migration - onex-creation automatically migrates player data from other clothing scripts when players join. No manual commands or scripts required!

How It Works#

Migration in onex-creation is completely seamless and automatic:

Setup - Configure onex-creation with your existing player skin data source
Player Joins - When a player connects, the script detects their legacy appearance format
Auto-Convert - Data is automatically converted to Schema v2
Transparent - Players see their existing appearance without any interruption

No manual migration commands needed. No batch scripts to run. No server downtime. Everything happens seamlessly in the background when players join your server.

Supported Formats#

onex-creation can automatically migrate from these clothing scripts:

Source Script	Format	Auto-Detect
esx_skin	`esx_skin`	✅ Yes
skinchanger	`esx_skin`	✅ Yes
qb-clothing	`qb-clothing`	✅ Yes
fivem-appearance	`fivem-appearance`	✅ Yes
illenium-appearance	`illenium-appearance`	✅ Yes
Old onex-creation	`onex-legacy`	✅ Yes

Easy Extensibility#

Need to migrate from a different clothing script? onex-creation's migration system is designed to be easily extensible.

Adding New Format Support#

The format detection system uses pattern matching to identify data structures. Adding support for a new clothing script is straightforward:

Example: Adding Custom Format
-- Format detection checks for unique keys in the data structure
-- Each clothing script has distinctive patterns:

-- esx_skin uses: sex, face, skin, hair_1, tshirt_1, torso_1, etc.
-- qb-clothing uses: model, pants.item, arms.item, t-shirt.item, etc.
-- fivem-appearance uses: model, components[].component_id, props[].prop_id, etc.

If you're using a clothing script not listed above, contact support. New format converters can be added quickly based on your script's data structure.

Setup Requirements#

To enable automatic migration, ensure your configuration points to your existing player skin data:

ESX Framework#

config.lua
Config.Framework = 'esx'
Config.SkinTable = 'users'           -- Table containing skin data
Config.SkinColumn = 'skin'           -- Column with JSON skin data
Config.IdentifierColumn = 'identifier'

QBCore Framework#

config.lua
Config.Framework = 'qbcore'
Config.SkinTable = 'players'         -- Table containing skin data
Config.SkinColumn = 'skin'           -- Column with JSON skin data
Config.IdentifierColumn = 'citizenid'

That's it! Once configured, migration happens automatically.

What Gets Migrated#

The automatic migration converts all player appearance data:

Data Type	Migrated
Character model	✅
Face shape & features	✅
Skin tone	✅
Hair style & color	✅
Clothing components	✅
Props (hats, glasses, etc.)	✅
Tattoos	✅
Overlays (makeup, blemishes)	✅

Migration Process Flow#

┌─────────────────────────────────────────────────────────────┐
│                    PLAYER JOINS SERVER                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              CHECK FOR EXISTING ONEX DATA                    │
│         Does player have Schema v2 appearance?               │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              │                               │
           YES │                           NO │
              ▼                               ▼
┌─────────────────────────┐   ┌─────────────────────────────┐
│   LOAD EXISTING DATA    │   │   FETCH LEGACY SKIN DATA    │
│   Apply Schema v2       │   │   From configured table     │
└─────────────────────────┘   └─────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────┐
                              │    AUTO-DETECT FORMAT       │
                              │ esx_skin? qb-clothing? etc. │
                              └─────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────┐
                              │    CONVERT TO SCHEMA V2     │
                              │   Automatic transformation  │
                              └─────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────┐
                              │    SAVE & APPLY            │
                              │   Store new format & load   │
                              └─────────────────────────────┘

Benefits of Automatic Migration#

Feature	Benefit
Zero Downtime	No server restart or maintenance window needed
No Player Action	Players don't need to do anything
Gradual Migration	Data converts as players join naturally
Rollback Safe	Original data remains untouched
Error Handling	Failed conversions don't break player spawning

Verification (Optional)#

While migration is automatic, you can verify it's working:

Server Console
-- Check migration stats
/onex_migration_stats

This shows:

Total players migrated
Formats detected
Any conversion errors

Troubleshooting#

Player Appears with Default Skin#

Check database connection to legacy skin table
Verify column names in configuration
Check server console for migration errors

Specific Player Not Migrating#

Ensure legacy data exists for that identifier
Check if data is valid JSON
Look for format detection logs

Want to Force Re-Migration#

Server Script
-- Force re-migration for specific player
exports['onex-creation']:ForceRemigrate(identifier)

Next Steps#

Customization

Troubleshooting