วิธีย้ายจาก QBCore ไป Qbox แบบปลอดภัย ไม่ให้ข้อมูลผู้เล่นหาย

August 23, 2026

การย้าย FiveM Server จาก QBCore ไป Qbox ไม่ควรทำด้วยการลบ qb-core แล้วใส่ qbx_core แทนทันที เพราะ Server RP มักมีข้อมูลและ Resources จำนวนมากเชื่อมโยงกับ Framework เดิม เช่น Character, Jobs, Gangs, Inventory, Vehicles, Housing, Phone และ Database

Qbox มีข้อได้เปรียบสำคัญคือมี QB Compatibility Bridge ทำให้ QBCore Scripts จำนวนมากสามารถทำงานต่อได้โดยไม่ต้อง Rewrite ทั้งหมดตั้งแต่วันแรก

แนวทาง Migration ที่ปลอดภัยจึงเป็น

QBCore Production
↓
Backup ทุกอย่าง
↓
สร้าง Test Server
↓
ติดตั้ง Qbox ผ่าน Official Recipe
↓
ย้าย/แปลง Database
↓
ย้าย Jobs และ Gangs
↓
Convert Inventory
↓
เปิด QB Compatibility Bridge
↓
นำ Scripts เดิมกลับทีละกลุ่ม
↓
แก้ Script ที่ไม่ Compatible
↓
ทดสอบ Player Data
↓
Load Test
↓
ค่อยย้าย Production

สิ่งสำคัญที่สุดคือ อย่าทดลอง Migration ครั้งแรกกับ Production Database ชุดเดียว

① ก่อนย้าย QBCore ไป Qbox ต้องเข้าใจก่อนว่าอะไรเปลี่ยน

QBCore ใช้ Core หลัก

qb-core

ขณะที่ Qbox ใช้

qbx_core

แต่ความแตกต่างไม่ได้มีแค่ชื่อ Resource

QBCore Scripts มักใช้

local QBCore = exports['qb-core']:GetCoreObject()

แล้วเรียก

QBCore.Functions
QBCore.Shared
QBCore.PlayerData

ส่วน Qbox Native Architecture เน้น

qbx_core exports
QBX modules
ox_lib
ox_inventory

ดังนั้น Migration มีทั้งระดับ

Framework
Database
Inventory
Scripts
Configuration

② Qbox รองรับ QBCore Scripts หรือไม่

รองรับส่วนใหญ่

Qbox มี Compatibility Layer สำหรับ Resource ที่ใช้ qb-core ตาม API ที่ QBCore รองรับอย่างถูกต้อง

ดังนั้น Migration ไม่ได้หมายความว่า Scripts หลายร้อยตัวต้องถูก Rewrite ก่อนเปิด Server

สามารถทำ

Qbox
↓
QB Bridge
↓
Existing QB Scripts

แล้วทยอย Convert เป็น Qbox Native ภายหลัง

นี่เป็นข้อได้เปรียบใหญ่ของ Qbox สำหรับ Server QBCore เดิม

③ Compatibility ไม่ได้หมายถึง 100% ทุก Script

Qbox ระบุ Compatibility กับ Existing QB Scripts สูงมาก แต่มีข้อยกเว้นสำคัญ

Resources ที่เสี่ยงมีปัญหา ได้แก่ Script ที่

เข้าถึง Database Tables ของ Core โดยตรง
อ่าน Internal Files ของ qb-core
ใช้ Undocumented APIs
ใช้ Functions ผิดรูปแบบ
แก้ qb-core โดยตรง

ดังนั้นก่อน Migration ควร Audit Scripts ก่อน

ไม่ควรคิดว่า

ใช้ QBCore
=
ใช้ Qbox ได้ทุกตัวแน่นอน

④ ขั้นแรก Backup Production Server

ก่อนแตะ Framework ให้ Backup อย่างน้อย

Database
resources/
server.cfg
Permissions
Voice Config
Custom Configs
Paid Script Configs

หากใช้ txAdmin ให้เก็บ Profile Configuration ด้วย

ตัวอย่าง Backup

qbcore-before-qbox-2026-08

เป้าหมายคือสามารถ Rollback กลับ QBCore เดิมได้ถ้า Migration มีปัญหา

⑤ Database Backup สำคัญที่สุด

ข้อมูลที่เสียแล้วบางอย่างสร้างใหม่ไม่ได้ เช่น

Characters
Money
Inventory
Vehicles
Businesses
Houses
Phone Data
Jobs
Gangs
Metadata

ดังนั้นก่อน Migration ควรทำ Database Dump เต็มชุด

และทดสอบด้วยว่า Backup นั้น Restore ได้จริง

Backup ที่ไม่เคยทดสอบ Restore ยังไม่ควรถูกถือว่าเชื่อถือได้ 100%

⑥ อย่า Migration บน Production โดยตรง

สร้าง

Qbox-Test

แยกจาก

QBCore-Production

แล้ว Clone Database มาใช้

Architecture ที่เหมาะคือ

Production QBCore
│
├── Backup
│
└── Clone Database
       ↓
    Qbox Test

ผู้เล่นจริงจึงไม่ได้รับผลกระทบระหว่างทดลอง Conversion

⑦ จด QBCore Stack เดิมก่อน

สร้าง Inventory ของ Resources ก่อน Migration

ตัวอย่าง

Framework: qb-core
Inventory: qb-inventory
Target: qb-target
Voice: pma-voice
Phone: ...
Housing: ...
Garage: ...
Banking: ...
Multijob: ...

และแยก Custom Scripts ออกเป็นหมวด

จะช่วยให้รู้ว่าต้อง Migration อะไรบ้าง

⑧ แบ่ง Scripts เป็น 3 กลุ่ม

แนะนำให้แบ่งเป็น

กลุ่ม A — Qbox Native

Resource รองรับ

Qbox
qbx_core

โดยตรง

กลุ่ม B — QB Bridge Compatible

Resource รองรับ QBCore และทำงานผ่าน Qbox Compatibility Layer

กลุ่ม C — ต้องแก้

Resource ใช้

Direct SQL
qb-core internals
Old Inventory APIs
Custom Core modifications

กลุ่ม C คือส่วนที่ต้องใช้เวลามากที่สุด

⑨ อย่าเริ่มจากการทับ qbx_core ลงใน Server เดิม

Qbox Documentation แนะนำให้ติดตั้ง Qbox ผ่าน Recipe

แนวทางที่สะอาดกว่าคือ

สร้าง Qbox Base ใหม่
↓
ให้ Base เปิดได้
↓
ค่อย Migration ข้อมูลและ Scripts

แทน

QBCore เดิม
↓
ลบ qb-core
↓
ใส่ qbx_core
↓
หวังว่าทุกอย่างจะทำงาน

วิธีหลัง Debug ยากมาก

⑩ ติดตั้ง Qbox Base ด้วย txAdmin

สร้าง Test Server ใหม่

จากนั้นใน txAdmin เลือก

Popular Recipes
↓
QBox Framework

Recipe จะให้ Configuration พื้นฐานที่ Qbox ปัจจุบันต้องใช้ เช่น

server.cfg
ox.cfg
permissions.cfg
voice.cfg

หากติดตั้ง Manual ต้องตรวจไฟล์เหล่านี้กับ Current Qbox Recipe เอง

⑪ Database ของ Qbox ต้องเตรียมให้ถูก

Qbox ปัจจุบัน Target

MariaDB

และกำหนด Version ขั้นต่ำตาม Current Documentation

ดังนั้นถ้า QBCore Server เก่าอยู่บน Database Stack ที่ไม่ตรง Requirement ของ Qbox ควรแก้ Infrastructure ก่อน Migration

อย่ารอจน qbx_core Start แล้ว SQL Error จึงค่อยตรวจ Version

⑫ ติดตั้ง Qbox Clean Base ให้ผ่านก่อน

ก่อนนำ Database/QB Scripts เดิมเข้ามา ต้องทดสอบว่า Clean Qbox Server

เปิดได้
Database Connect
qbx_core Start
Character สร้างได้
Inventory เปิด
Job ทำงาน
Reconnect ได้

ถ้า Clean Base ยัง Error อย่าเริ่ม Migration

ไม่เช่นนั้นจะไม่รู้ว่า Error มาจาก Qbox Base หรือข้อมูล QBCore เดิม

⑬ Update Server Configuration

Official Conversion Guide ระบุให้ Update Configuration Files ให้เป็น Qbox Version

ไฟล์สำคัญ ได้แก่

server.cfg
ox.cfg
permissions.cfg
voice.cfg

ถ้าติดตั้งผ่าน Qbox Recipe ไฟล์เหล่านี้จะถูกเตรียมให้อยู่แล้ว

ไม่ควรเอา server.cfg จาก QBCore เดิมมาทับ Qbox ทั้งไฟล์ทันที

⑭ Merge Config ไม่ใช่ Replace

สิ่งที่ควรทำคือ

Qbox Current Config
↓
นำค่าที่จำเป็นจาก QBCore เดิมมา Merge

เช่น

Server Name
Endpoint
Max Clients
ACE
Custom Resources
Server Tags
Game Build

ไม่ใช่

ลบ Qbox server.cfg
↓
Copy QBCore server.cfg เดิมมาใช้

เพราะ Qbox มี Convars และ Resource Stack ของตัวเอง

⑮ ตรวจ qbx:enableBridge

Qbox มี QB Compatibility Bridge

โดยใช้ Convar

setr qbx:enableBridge "true"

สำหรับ Migration Server QBCore ควรเปิด Compatibility Layer ในช่วงแรกตาม Configuration ที่รองรับ

แนวคิดคือ

QBCore Scripts
↓
QB Bridge
↓
qbx_core

ช่วยลดจำนวน Resource ที่ต้อง Rewrite ทันที

⑯ ไม่ต้องติดตั้ง qb-core คู่กับ qbx_core

จุดนี้สำคัญมาก

อย่าทำ

ensure qb-core
ensure qbx_core

เพียงเพราะ Custom Script เรียก

exports['qb-core']:GetCoreObject()

Qbox QB Bridge ถูกสร้างขึ้นเพื่อรองรับ API ลักษณะนี้

ดังนั้นใน Qbox Server

qbx_core
↓
QB Bridge
↓
exports['qb-core']

สามารถเป็น Compatibility Path ได้

⑰ No such export GetCoreObject in qbx_core แปลว่าอะไร

ถ้า Script เขียน

exports['qbx_core']:GetCoreObject()

นี่ไม่ใช่ Native Qbox API

Qbox ไม่มี Core Object แบบ QBCore

Resource QBCore ที่ยังต้องใช้ Core Object ควรเรียกผ่าน Compatibility Interface ตามรูปแบบที่ Qbox รองรับ เช่น

exports['qb-core']:GetCoreObject()

เมื่อ QB Bridge เปิดอยู่

⑱ Job Grades ต้องแก้

Official Qbox Conversion Guide ระบุความแตกต่างสำคัญว่า Qbox ใช้ Job Grade Keys เป็น

number

ไม่ใช่ String

QBCore เดิมอาจมี

grades = {
    ['0'] = {
        name = 'recruit'
    },
    ['1'] = {
        name = 'officer'
    }
}

Qbox ต้องเป็นลักษณะ

grades = {
    [0] = {
        name = 'recruit'
    },
    [1] = {
        name = 'officer'
    }
}

จุดเล็กนี้ห้ามมองข้าม

⑲ Gang Grades ต้องแก้เหมือนกัน

เช่นเดียวกับ Jobs

จาก

grades = {
    ['0'] = {...},
    ['1'] = {...}
}

ควรเป็น

grades = {
    [0] = {...},
    [1] = {...}
}

ตาม Qbox Structure

หากย้าย Jobs/Gangs จำนวนมาก ควรตรวจทุก Definition ก่อนเปิด Server

⑳ ย้าย Jobs เข้า qbx_core

นำ Job Definitions จาก QBCore เดิมมาปรับตาม Qbox

ตรวจอย่างน้อย

Job Name
Label
Default Duty
Off Duty Pay
Grades
Payment
Boss Status

อย่าเปลี่ยน Internal Job Names หาก Scripts และ Player Data เดิมอ้างชื่อเหล่านั้นอยู่

ตัวอย่าง

police
ambulance
mechanic

ควรรักษา Name เดิมถ้าไม่มีเหตุผลต้อง Migration ชื่อด้วย

㉑ ย้าย Gangs แบบเดียวกัน

ตรวจ

Gang Name
Label
Grades
Boss Grades

ให้ตรงกับ Data เดิม

ถ้า Player เดิมมี

gang = ballas

แต่ Qbox Config เปลี่ยนเป็น

ballasgang

โดยไม่ได้ Migration Player Data ระบบจะไม่ตรงกัน

หลีกเลี่ยงการ Rename Entity ระหว่าง Framework Migration ถ้าไม่จำเป็น

㉒ ตรวจ players.citizenid Collation

Qbox Conversion Guide ระบุให้ตรวจ Column

players.citizenid

ว่าใช้

utf8mb4_unicode_ci

อย่างถูกต้อง

นี่สำคัญต่อ Foreign Keys และ Tables ใหม่ของ Qbox

Collation ไม่ตรงสามารถทำให้ SQL Migration ล้มเหลวได้

㉓ Foreign Key Constraint Error มาจากอะไร

หากพบ Error ประเภท

Foreign Key Constraint is incorrectly formed

ระหว่าง Conversion ให้ตรวจ Collation ของ Columns ที่เชื่อมกัน

ตัวอย่าง

players.citizenid

และ

other_table.citizenid

ควรใช้ Collation ที่ Compatible กัน

อย่าลบ Foreign Key เพียงเพื่อให้ SQL ผ่านก่อนตรวจ Root Cause

㉔ รัน qbx_core SQL

Official Conversion Guide กำหนดให้รัน SQL ที่มากับ qbx_core

Migration ปัจจุบันมีการเปลี่ยน players Table เช่น

เพิ่ม last_logged_out
ปรับ players.citizenid collation

และสร้าง Structure ที่ Qbox ต้องใช้

ควรใช้ SQL จาก Qbox Version ที่กำลังติดตั้งจริง

ไม่ควรใช้ไฟล์ SQL จาก Tutorial รุ่นเก่า

㉕ player_groups คืออะไร

Qbox ใช้

player_groups

สำหรับระบบ Groups/Jobs/Gangs ใน Architecture ปัจจุบัน

Conversion Guide ระบุให้สร้าง Table นี้ผ่าน qbx_core.sql

จากนั้นจึง Convert Job/Gang Data ของ Player เดิมเข้ามา

นี่เป็นส่วนสำคัญของ Multi-job/Multi-gang Architecture

㉖ ใช้ convertjobs หลัง Server เปิด

หลัง

qbx_core.sql

ถูกติดตั้ง และ Qbox Server Start แล้ว

Official Conversion Guide ให้รัน

convertjobs

ใน txAdmin Console

เพื่อ Populate

player_groups

จากข้อมูล Jobs/Gangs เดิม

อย่ารัน Command โดยไม่ Backup Database ก่อน

㉗ ตรวจผล convertjobs

หลัง Conversion ควรสุ่มตรวจ Player หลายประเภท

เช่น

ตำรวจ Grade สูง
ตำรวจ Grade ต่ำ
EMS
Mechanic
Unemployed
Gang Member
Gang Boss

แล้วดูว่า

Job
Grade
Gang
Grade

ถูกต้อง

อย่าเช็ก Player เพียง Account เดียวแล้วถือว่า Migration สมบูรณ์

㉘ ระวัง External Multijob

Qbox เตือนชัดว่าอย่าใช้ Multijob/Multigang Resources ที่ไม่รับประกัน Compatibility

โดยเฉพาะ Script ที่

แก้ Qbox Database Tables โดยตรง

หรือ

เก็บ Core Job Data ซ้ำใน Table ของตัวเอง

อาจทำให้ข้อมูลเสียหรือไม่ Sync กับ player_groups

㉙ Qbox มี Multijob ใน Core อยู่แล้ว

ก่อนนำ

qb-multijob
custom-multijob

กลับเข้ามา ให้ตรวจว่าจำเป็นหรือไม่

Qbox มี Configuration เช่น

set qbx:max_jobs_per_player 1

และ

set qbx:max_gangs_per_player 1

สามารถกำหนดจำนวน Groups ที่ Player ถือได้

จึงอาจไม่จำเป็นต้องใช้ External Multijob Resource เดิม

㉚ Migration Inventory เป็นหนึ่งในส่วนใหญ่ที่สุด

ถ้า QBCore เดิมใช้

qb-inventory

แต่ Qbox Base ใช้

ox_inventory

ต้องทำ Inventory Conversion

ข้อมูลที่ต้องระวัง ได้แก่

Player Items
Metadata
Weapons
Stashes
Trunks
Gloveboxes
Shops
Crafting
Job Storage

อย่าเริ่ม Server จริงจน Inventory ของ Player ทดสอบผ่าน

㉛ Backup Database ก่อน Inventory Conversion

Official Qbox Conversion Guide เน้นให้ Backup ก่อนขั้นตอนนี้โดยตรง

เพราะ Inventory Conversion สามารถเปลี่ยน Player Item Data จำนวนมาก

Workflow ที่ควรเป็น

Database Clone
↓
Inventory Convert
↓
ตรวจผล
↓
ผิด?
→ Restore Clone

ไม่ควรรัน Conversion ซ้ำหลายครั้งบน Database เดิมโดยไม่รู้ว่า Script Idempotent หรือไม่

㉜ Items จาก QBCore ต้องตรวจใหม่

QBCore เดิมอาจเก็บ Definitions ใน

QBCore.Shared.Items

แต่ Qbox Native Architecture ใช้ ox_inventory อย่างใกล้ชิด

Conversion Guide แนะนำแนวคิด

QBCore.Shared.Items

เปลี่ยนเป็น

exports.ox_inventory:Items()

สำหรับ Native Code

ดังนั้น Custom Items ต้องตรวจทั้ง

Name
Label
Weight
Stack
Metadata
Client/Server Behavior

หลัง Migration

㉝ อย่าเพิ่ม Item ซ้ำสองระบบโดยไม่เข้าใจ Bridge

Qbox FAQ ระบุว่าไม่จำเป็นต้องเพิ่ม Item ทั้ง

qbx_core/shared/items.lua

และ

ox_inventory

ในทุกกรณี

Shared Items ฝั่ง QB Compatibility มีไว้ช่วย Resources ที่ยังเข้าถึง Items ผ่าน Bridge

Resource Native ox_inventory ควรใช้ระบบ Item ของ Inventory ตามที่ออกแบบมา

อย่าสร้าง Item Definitions ซ้ำจนไม่รู้ว่าระบบไหนเป็น Source of Truth

㉞ ทดสอบ Inventory ทุกประเภท

หลัง Conversion ทดสอบ

Player Inventory
Stash
Vehicle Trunk
Glovebox
Job Storage
Shop
Crafting
Weapons
Metadata Items

โดยเฉพาะ Items ที่มี Metadata เช่น

Serial
Durability
Custom Labels
Attachments

อย่าทดสอบแค่ว่า Water หนึ่งขวดเปิด Inventory แล้วมองเห็น

㉟ Target ต้อง Migration หรือไม่

ถ้า Server เดิมใช้

qb-target

และ Qbox ใหม่ใช้

ox_target

Custom Scripts อาจต้องปรับ

แต่ไม่จำเป็นต้อง Convert Target ทุก Script ในวันแรกหาก Resource และ Bridge รองรับ Stack เดิมได้

ควรเลือก Strategy ว่า

Migration Phase 1
→ Compatibility ก่อน

Migration Phase 2
→ Native OX Target

จะปลอดภัยกว่าการเปลี่ยนทุก Subsystem พร้อมกัน

㊱ Phone เป็น Resource ที่ต้อง Audit หนัก

Phone มักเชื่อมกับ

Character
Phone Number
Banking
Jobs
Vehicles
Housing
Voice
Database

ก่อนย้ายต้องตรวจว่า Phone รองรับ

Qbox Native

หรือ

QBCore ผ่าน QB Bridge

แบบไหน

และมี Database Migration ของตัวเองหรือไม่

อย่าเปลี่ยน Phone พร้อม Framework โดยไม่มี Test Data

㊲ Housing ต้องตรวจ Citizen ID

Housing มักเชื่อมกับ

citizenid

ดังนั้นถ้ารักษา Citizen ID เดิมได้ ข้อมูล Ownership มีโอกาส Migration ง่ายขึ้น

แต่ต้องตรวจ

Keys
Garages
Furniture
Stashes
Database Foreign Keys

แยกด้วย

Housing Script บางตัว Query players โดยตรง จึงต้อง Audit เป็นพิเศษ

㊳ Garage และ Vehicles ต้องทดสอบ

ตรวจ

Owned Vehicles
Plate
Citizen ID
Garage State
Impound
Vehicle Properties
Keys

หลัง Migration

อย่าพิสูจน์เพียงว่า Player Spawn รถใหม่ได้

ต้องทดสอบรถเดิมที่มีอยู่ใน Production Database ด้วย

㊴ Banking และ Money ต้องตรวจทุก Account

ตรวจ

Cash
Bank
Custom Accounts
Society Money
Business Accounts

ถ้ามี Banking Resource Third-party

Resource อาจ Query QBCore Tables โดยตรง

จึงควรตรวจ Source/Documentation ว่ารองรับ Qbox หรือไม่

Money เป็นระบบสำคัญมาก ห้าม Migration โดยดูยอด Player คนเดียว

㊵ Custom QBCore Scripts เริ่มจาก QB Bridge ก่อน

สำหรับ Resource จำนวนมาก วิธีที่ปลอดภัยคือ

ยังไม่ Rewrite
↓
เปิด QB Bridge
↓
ทดสอบ Resource เดิม

ถ้า Resource ทำงานครบก็สามารถเปิดใช้งานผ่าน Compatibility ก่อน

จากนั้นค่อย Convert Native เมื่อมีเวลา

ช่วยลด Scope Migration ครั้งแรกอย่างมาก

㊶ QBCore GetCoreObject ใช้ต่อได้ไหม

สำหรับ Resource ที่ใช้ QBCore Compatibility ผ่าน Qbox Bridge สามารถใช้รูปแบบ

local QBCore = exports['qb-core']:GetCoreObject()

ต่อได้ในกรณีที่ API นั้นอยู่ใน Compatibility Layer

อย่าเปลี่ยนเป็น

exports['qbx_core']:GetCoreObject()

เพราะ qbx_core ไม่มี QBCore Core Object แบบ Native

㊷ Convert Script เป็น Qbox Native เมื่อไร

ควรพิจารณาเมื่อ

ทีมเป็นเจ้าของ Source
Resource สำคัญ
มีการพัฒนาต่อ
ต้องการลด Bridge Dependency
ต้องการใช้ Qbox APIs ใหม่

ไม่จำเป็นต้อง Convert Paid Resource ที่ทำงานสมบูรณ์ผ่าน Bridgeเพียงเพื่อความสวยงาม

Migration ควรลดความเสี่ยง ไม่ใช่เพิ่ม Scope โดยไม่จำเป็น

㊸ แทน QBCore.Functions อย่างไร

Qbox Conversion Guide ให้แนวคิด

QBCore.Functions.*

เปลี่ยนไปใช้

exports.qbx_core:*

ตาม Function ที่ Qbox เปิดให้

แต่ไม่ควร Search/Replace

QBCore.Functions.
→ exports.qbx_core:

ทั้ง Project โดยอัตโนมัติ

เพราะ Function Signatures ไม่ได้เหมือนกันทุกตัว

ต้อง Convert API ทีละจุด

㊹ GetPlayerData เปลี่ยนอย่างไร

QBCore Client Code อาจใช้

QBCore.Functions.GetPlayerData()

Qbox Native Conversion สามารถใช้

QBX.PlayerData

ผ่าน PlayerData Module ตาม Current Guide

นี่เป็นตัวอย่างที่แสดงว่า Migration ไม่ใช่ Rename Function เพียงอย่างเดียว

Architecture การโหลดข้อมูลเปลี่ยนด้วย

㊺ Jobs จาก QBCore.Shared เปลี่ยนอย่างไร

จาก

QBCore.Shared.Jobs

Qbox Native สามารถใช้

exports.qbx_core:GetJobs()

หลักคือใช้ Public API

ไม่เข้าถึง Core Internal Table โดยตรง

㊻ Gangs เปลี่ยนอย่างไร

จาก

QBCore.Shared.Gangs

เป็นแนวคิด

exports.qbx_core:GetGangs()

เมื่อ Convert Native

และสำหรับการตรวจ Group ของ Player ปัจจุบัน Qbox ยังมี APIs อย่าง

HasGroup
HasPrimaryGroup
GetGroups

ตาม Use Case

㊼ Vehicles เปลี่ยนอย่างไร

จากแนวคิด

QBCore.Shared.Vehicles

Qbox มี Exports เช่น

exports.qbx_core:GetVehiclesByName()

และ APIs อื่นสำหรับ Vehicle Definitions

Resource ใหม่ควรใช้ API ที่ Framework เปิดให้แทนการอ่าน Internal Data Files

㊽ Weapons เปลี่ยนอย่างไร

Qbox Conversion Guide มีแนวทางแทน

QBCore.Shared.Weapons

ด้วย

exports.qbx_core:GetWeapons()

แต่ถ้า Server ใช้ Weapon-as-item ผ่าน ox_inventory ต้องตรวจ Inventory Architecture ของ Resource ด้วย

อย่า Convertเฉพาะ Shared Table แล้วมองข้าม Weapon Inventory Logic

㊾ Text UI เปลี่ยนได้

QBCore Scripts บางตัวใช้

DrawText
HideText
ChangeText

ผ่าน qb-core

Qbox Conversion Guide แนะนำ ox_lib Text UI เช่น

lib.showTextUI(...)

และ

lib.hideTextUI()

ใน Qbox Native Conversion

นี่เป็นตัวอย่างการพึ่ง OX ecosystem มากขึ้นหลัง Migration

㊿ Direct SQL Resource ต้องตรวจเป็นพิเศษ

สมมติ Resource ทำ

SELECT *
FROM players
WHERE citizenid = ?

อาจยังทำงานบางกรณี

แต่ Qbox Developer Guide แนะนำไม่ให้ Resource เข้าถึง Tables ที่ Core เป็นเจ้าของโดยตรง

เพราะ Schema สามารถเปลี่ยนได้

ถ้ามี Public Export เช่น

exports.qbx_core:GetOfflinePlayer(citizenid)

ควรพิจารณาใช้ API แทนตาม Use Case

51. อย่าแก้ qbx_core เพื่อให้ Script เก่ารอด

ถ้า Resource เก่าต้องการ Function ที่ Qbox ไม่มี

ไม่ควรเริ่มด้วย

แก้ qbx_core
↓
เพิ่ม Function เก่า
↓
แก้ Database

เพราะต่อไป Update Framework ยากมาก

ทางเลือกที่ดีกว่า

Bridge
Adapter Resource
Update Script
Replace Script

ตามความเหมาะสม

52. ใช้ Adapter Resource ช่วย Migration ได้

สมมติ Custom Scripts 20 ตัวเรียก API ภายในของคุณเอง

สามารถสร้าง

my-framework-bridge

ให้เป็นชั้นกลาง

Custom Scripts
↓
my-framework-bridge
↓
qbx_core

แทนการแก้ Scripts ทั้ง 20 ตัวพร้อมกัน

นี่ช่วยควบคุม Migration และทำให้ Framework-specific Code อยู่จุดเดียว

53. ทดสอบ Character หลัง Migration

ทดสอบอย่างน้อย

Character เดิมเข้าได้
Character ใหม่สร้างได้
Character Switching
Logout
Reconnect
Position
Identity
Metadata

อย่าเริ่มจาก Character ใหม่อย่างเดียว

ต้องทดสอบ ข้อมูลผู้เล่นเดิมจาก Production Clone ด้วย เพราะนั่นคือเป้าหมายหลักของ Migration

54. ทดสอบ Job และ Gang

ใช้ Accounts หลายแบบ

Unemployed
Police Recruit
Police Boss
EMS
Mechanic
Gang Member
Gang Boss

ตรวจ

Job
Grade
Duty
Boss Permissions
Gang
Group

และ Reconnect อีกครั้ง

นี่ช่วยจับ Conversion Error ของ player_groups

55. ทดสอบ Economy

ตรวจ

Cash
Bank
Shop Purchase
Salary
Billing
Society
Business

แล้ว Restart Server

ดูว่าข้อมูล Save/Load ถูกต้อง

Migration ที่ดูปกติขณะ Online แต่อัปเดต Database ไม่ถูกอาจเห็นปัญหาหลัง Restart เท่านั้น

56. ทดสอบ Inventory

ใช้ Character ที่มี Inventory ซับซ้อน

เช่น

Weapons
Metadata Items
Stacked Items
Unique Items
Stash
Vehicle Storage

ไม่ควรใช้ Character ใหม่ที่มีเพียง Starter Items สำหรับ Validation ทั้งระบบ

Player เก่าที่เล่นมานานคือ Test Case ที่สำคัญกว่า

57. ทดสอบ Paid Scripts

สร้าง Checklist ทีละ Resource

Phone
Housing
Garage
Banking
Police
EMS
Mechanic
Businesses
Crafting
Dealership

สำหรับแต่ละ Script จด

Qbox Native
QB Bridge
Needs Fix
Replace

จะเห็น Migration Status ทั้ง Server ชัดเจน

58. ตรวจ Console และ F8

ทุกครั้งที่เปิด Feature ให้ดู

Server Console
+
Client F8

Error สำคัญ เช่น

No such export
nil value
SQL error
missing dependency
callback error

ควรถูกบันทึกพร้อมชื่อ Resource

อย่าใช้คำว่า “Script พัง” รวม ๆ เพราะแก้ยาก

59. ใช้ Resmon/Profiler หลัง Functional Test

หลังระบบทำงานครบแล้วจึงทดสอบ Performance

เปรียบเทียบ

QBCore เดิม
vs
Qbox Migration

ภายใต้ Load ใกล้เคียงกัน

ดู

Client Resmon
Server Profiler
Database Load
Hitch Warnings
Memory

อย่าตัดสิน Performance จากการเข้า Server คนเดียว 5 นาที

60. Migration Checklist ก่อนเปิด Production

Backup

Database Backup
Resources Backup
Config Backup
Rollback Plan

Qbox Base

MariaDB ถูก Version
Qbox Recipe ติดตั้งสำเร็จ
qbx_core Start
OX Dependencies ทำงาน

Database

players.citizenid Collation ถูก
qbx_core.sql รันแล้ว
player_groups มี
convertjobs ทำแล้ว
Foreign Keys ไม่มี Error

Framework

Jobs แปลง Grade เป็น Number
Gangs แปลง Grade เป็น Number
QB Bridge เปิดตามแผน
ไม่ติดตั้ง qb-core ซ้ำ

Inventory

Conversion สำเร็จ
Items ครบ
Metadata ครบ
Stashes ครบ
Vehicle Storage ครบ

Scripts

Phone
Housing
Garage
Banking
Police
EMS
Jobs
Businesses

ผ่านการทดสอบ

Player

Character เดิมเข้าได้
Character ใหม่สร้างได้
Money ถูก
Job/Gang ถูก
Inventory ถูก
Vehicles ถูก
Reconnect ผ่าน

Production

Backup ล่าสุด
Maintenance Window
Rollback Tested
Test Server ผ่านทั้งหมด

วิธี Migration ที่ปลอดภัยที่สุดแบบย่อ

ถ้าต้องการเพียงลำดับหลัก ให้ใช้

① Backup QBCore Server และ Database

② Clone Database ไป Test Server

③ Audit Resources

④ แบ่ง Qbox Native / QB Compatible / ต้องแก้

⑤ ติดตั้ง Clean Qbox ผ่าน txAdmin Recipe

⑥ ใช้ Current Qbox Config

⑦ ตรวจ MariaDB

⑧ ปรับ Job/Gang Grades จาก String เป็น Number

⑨ ตรวจ players.citizenid Collation

⑩ Run qbx_core SQL

⑪ Start Qbox

⑫ Run convertjobs

⑬ Convert qb-inventory → ox_inventory

⑭ เปิด QB Compatibility Bridge

⑮ นำ QB Scripts กลับทีละกลุ่ม

⑯ Convert Custom Scripts ที่จำเป็นเป็น Qbox Native

⑰ ทดสอบ Character เดิม

⑱ ทดสอบ Job/Gang/Money

⑲ ทดสอบ Inventory

⑳ ทดสอบ Vehicles/Phone/Housing

㉑ ตรวจ Console/F8

㉒ Load Test

㉓ Backup Production อีกรอบ

㉔ กำหนด Maintenance Window

㉕ Migration Production

㉖ ตรวจข้อมูลหลังเปิดจริง

㉗ Rollback ทันทีหากพบ Data Integrity Problem

ควร Convert ทุก Script ก่อน Migration ไหม

ไม่จำเป็น

Qbox Documentation ระบุว่าการ Convert Resource เป็น Qbox Native เป็น Optional เพราะ QB Bridge รองรับ Existing QB Scripts จำนวนมาก

แนวทางที่ลดความเสี่ยงกว่า คือ

Phase 1
Qbox + QB Bridge
↓
ทำให้ Server ใช้งานได้ครบ

Phase 2
Convert Custom Scripts สำคัญ
↓
Qbox Native

Phase 3
ลด Compatibility Debt

วิธีนี้เหมาะกับ Server ใหญ่กว่าการ Rewrite ทุกอย่างก่อน Cutover

Script แบบไหนควร Convert ก่อน

ให้ Priority กับ Resource ที่

แก้ Core โดยตรง
Direct SQL
Performance Critical
Security Critical
ทีมพัฒนาเอง
มีการแก้บ่อย

เช่น

Economy
Jobs
Businesses
Vehicle Ownership
Permissions

ส่วน Resource ที่ทำงานดีผ่าน QB Bridge และไม่มีปัญหาไม่จำเป็นต้องรีบ Rewrite

Script แบบไหนควรเปลี่ยนแทนการแก้

ถ้า Resource

เก่ามาก
ไม่มี Developer ดูแล
ใช้ Deprecated APIs
Direct SQL หนัก
แก้ qb-core internals
มี Bugs จำนวนมาก

การหา Qbox Native Resource ใหม่อาจคุ้มกว่าการ Migration Code เก่าทีละจุด

อย่ารักษา Technical Debt เพียงเพราะ Script เดิมเคยใช้งานมานาน

Production Cutover ควรทำอย่างไร

ก่อน Cutover จริง

หยุด Production
↓
Backup Database ล่าสุด
↓
Copy Data ล่าสุดไป Migration Environment
↓
Run Conversion ที่ผ่านการซ้อมมาแล้ว
↓
Start Qbox
↓
Smoke Test
↓
เปิดให้ผู้เล่น

อย่าปล่อยให้ผู้เล่นเขียนข้อมูลใหม่ลง QBCore Database ระหว่างกำลังทำ Final Conversion

ไม่เช่นนั้นข้อมูลช่วงนั้นอาจตกหล่น

หลังเปิด Qbox ต้องตรวจอะไรทันที

สุ่ม Accounts หลายประเภทและตรวจ

Character
Cash
Bank
Job
Gang
Inventory
Cars
House
Phone
Business

จากนั้นดู

Server Console
Database Errors
F8
Hitch Warnings

อย่างใกล้ชิด

ปัญหาเกี่ยวกับ Data Integrity ควรมี Priority สูงกว่า UI Bug เล็ก ๆ

สรุปวิธีย้ายจาก QBCore ไป Qbox

การย้าย QBCore ไป Qbox ไม่ใช่เพียง

ลบ qb-core
↓
ใส่ qbx_core

แต่เป็น Migration ของ

Framework
Database
Jobs
Gangs
Inventory
Resources
APIs
Configuration

Qbox ทำให้กระบวนการง่ายขึ้นด้วย QB Compatibility Bridge ซึ่งช่วยให้ QBCore Scripts จำนวนมากยังทำงานต่อได้ และ Official Conversion Guide ระบุว่าการ Convert Scripts เป็น Qbox Native ไม่จำเป็นต้องทำทั้งหมดทันที

ขั้นตอนที่สำคัญมาก ได้แก่

Backup Database
↓
ติดตั้ง Qbox Base ด้วย Recipe
↓
Update Config
↓
ปรับ Job/Gang Grade Keys
↓
ตรวจ citizenid Collation
↓
Run qbx_core SQL
↓
Run convertjobs
↓
Convert Inventory
↓
เปิด QB Bridge
↓
ทดสอบ Scripts

โดยเฉพาะ Job/Gang Migration ต้องระวัง player_groups และไม่ควรใช้ External Multijob Resources ที่แก้ Core Tables โดยตรง เพราะ Qbox เตือนว่าอาจนำไปสู่ Data Corruption ได้

สำหรับ Custom Code ควรทยอยเปลี่ยนจากแนวคิด

QBCore.Functions
QBCore.Shared

ไปสู่

qbx_core exports
QBX modules
ox_inventory
ox_lib

เมื่อมีเหตุผล ไม่จำเป็นต้อง Rewrite ทุก Resource ในวันแรก

แนวทางของ comsiam คือ Migration QBCore → Qbox ควรทำเป็น Project แยกบน Test Server และใช้ Production Database Clone จริงในการทดสอบ เพราะข้อมูล Character ที่สะอาดจาก Server ใหม่ไม่สามารถจำลองปัญหาที่ Player เก่ามี Inventory, Vehicles, Houses และ Jobs สะสมมาหลายเดือนได้

ก่อน Cutover จริง comsiam แนะนำให้มี Rollback Plan ที่ทดสอบแล้ว และหยุดการเขียนข้อมูลลง Production QBCore ชั่วคราวระหว่าง Final Database Conversion เพราะเป้าหมายอันดับหนึ่งของ Migration ไม่ใช่แค่ให้ Qbox เปิดติด แต่ต้องรักษาข้อมูลผู้เล่นเดิมให้ครบและถูกต้อง