ox_lib मार्गदर्शिका: डेवलपर्स के लिए आवश्यक FiveM लाइब्रेरी

ox_lib क्या है और आपको इसे क्यों उपयोग करना चाहिए?

ox_lib FiveM के लिए एक ओपन-सोर्स उपयोगिता लाइब्रेरी है जो आधुनिक स्क्रिप्ट विकास के लिए डि फैक्टो मानक बन गई है। यह पूर्व-निर्मित UI घटकों, उपयोगिता कार्यों, और प्रदर्शन उपकरणों का एक विशाल संग्रह प्रदान करता है जो हर स्क्रिप्ट के लिए पहिया फिर से बनाने की आवश्यकता को समाप्त करता है। ox_lib के अस्तित्व से पहले, डेवलपर्स को अपनी खुद की नोटिफिकेशन सिस्टम, इनपुट डायलॉग, प्रोग्रेस बार, और संदर्भ मेनू स्क्रैच से बनाना पड़ता था, जिससे अक्सर एक ही सर्वर पर विभिन्न स्क्रिप्टों में UI असंगत होता था। ox_lib इसे एकीकृत, परिष्कृत घटकों का सेट प्रदान करके हल करता है जो पेशेवर दिखते हैं और बॉक्स से बाहर विश्वसनीय रूप से काम करते हैं। यह Lua और JavaScript दोनों का समर्थन करता है, किसी भी फ्रेमवर्क (QBCore, ESX, या standalone) के साथ काम करता है, और Overextended टीम द्वारा सक्रिय रूप से बनाए रखा जाता है। यदि आप 2026 में FiveM स्क्रिप्ट लिख रहे हैं और ox_lib का उपयोग नहीं कर रहे हैं, तो आप अनावश्यक समय बर्बाद कर रहे हैं उन चीजों को बनाने में जो पहले से मौजूद हैं।

अपने रिसोर्स में ox_lib सेट अप करना

ox_lib को अपने रिसोर्स में शामिल करने के लिए केवल दो चरण आवश्यक हैं: निर्भरता को अपने fxmanifest.lua और अपनी स्क्रिप्ट्स में लाइब्रेरी को कॉल करना। @ox_lib/init.lua import आपको सभी साझा उपयोगिताओं तक पहुंच देता है, जबकि मॉड्यूल सिस्टम आपको केवल उन फीचर्स को चयनात्मक रूप से लोड करने देता है जिनकी आपको आवश्यकता है। इससे आपका संसाधन हल्का रहता है क्योंकि अप्रयुक्त मॉड्यूल कभी लोड नहीं होते। सुनिश्चित करें कि ox_lib आपके संसाधन से पहले आपके server.cfg में शुरू हो रहा है, इसे रखकर ensure ox_lib अपने कस्टम संसाधनों के ऊपर। यहाँ ox_lib का उपयोग करने वाले नए संसाधन के लिए न्यूनतम सेटअप है:

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

name 'my-awesome-script'
version '1.0.0'

-- Required: import ox_lib
shared_scripts {
    '@ox_lib/init.lua',
    'config.lua',
}

client_scripts {
    'client/*.lua',
}

server_scripts {
    'server/*.lua',
}

-- Declare ox_lib as a dependency
dependencies {
    'ox_lib',
}

-- Enable ox_lib locale system (optional)
lua54 'yes'

सूचनाएं: साफ, सुसंगत अलर्ट

ox_lib सूचनाएं बदसूरत डिफ़ॉल्ट चैट संदेशों और अधिकांश स्क्रिप्टों द्वारा उपयोग किए जाने वाले कस्टम NUI पॉपअप्स को बदलती हैं। वे आइकन, रंग, और स्वचालित खारिजी के साथ चिकनी टोस्ट संदेश के रूप में प्रकट होती हैं। आप स्थिति, अवधि, प्रकार (सफलता, त्रुटि, चेतावनी, सूचना) सेट कर सकते हैं, और शीर्षक के नीचे एक विवरण भी जोड़ सकते हैं। नोटिफिकेशन सिस्टम केवल क्लाइंट-साइड है और बेहद हल्का है, जो आपके स्क्रिप्ट में लगभग कोई अतिरिक्त भार नहीं जोड़ता। सूचनाएं ox_lib की सबसे अधिक उपयोग की जाने वाली विशेषता हैं और किसी भी स्क्रिप्ट में खिलाड़ियों को प्रतिक्रिया संप्रेषित करने का आपका डिफ़ॉल्ट तरीका होना चाहिए।

-- client.lua: Notification examples

-- Simple notification
lib.notify({
    title = 'Vehicle Stored',
    description = 'Your vehicle has been stored in the garage.',
    type = 'success',         -- 'success' | 'error' | 'warning' | 'info'
    duration = 5000,          -- milliseconds
    position = 'top-right',   -- 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
})

-- Error notification with icon
lib.notify({
    title = 'Access Denied',
    description = 'You do not have the required key.',
    type = 'error',
    icon = 'lock',
    iconColor = '#ff4444',
})

-- Notification from server side
-- server.lua
RegisterNetEvent('garage:store', function()
    local src = source
    TriggerClientEvent('ox_lib:notify', src, {
        title = 'Garage',
        description = 'Vehicle stored successfully.',
        type = 'success',
    })
end)

संदर्भ मेनू: इंटरैक्टिव विकल्प सूची

संदर्भ मेनू विकल्पों की स्क्रॉल करने योग्य सूचियाँ होती हैं जिन पर खिलाड़ी क्लिक करके क्रियाएँ ट्रिगर कर सकते हैं। ये जॉब मेनू, दुकान इंटरफेस, वाहन विकल्प, और किसी भी परिदृश्य के लिए उपयुक्त हैं जहाँ खिलाड़ी को कई क्रियाओं में से चुनना होता है। प्रत्येक मेनू आइटम में एक आइकन, विवरण, दाईं ओर मेटाडेटा, और जटिल विकल्प वृक्षों को व्यवस्थित करने के लिए नेस्टेड सबमेनू हो सकते हैं। मेनू तब तक खुला रहता है जब तक खिलाड़ी इसे स्पष्ट रूप से बंद न करे या कोई गैर-सबमेनू विकल्प न चुने, जो इसे आइटम श्रेणियों के माध्यम से ब्राउज़ करने के लिए आदर्श बनाता है। संदर्भ मेनू सर्वर डेटा के आधार पर गतिशील रूप से भी उत्पन्न किए जा सकते हैं, इसलिए आप अपनी डेटाबेस से वास्तविक समय की इन्वेंटरी को दर्शाने वाले दुकान मेनू बना सकते हैं।

-- client.lua: Context menu examples

-- Simple shop menu
lib.registerContext({
    id = 'weapons_shop',
    title = 'Ammu-Nation',
    options = {
        {
            title = 'Pistol',
            description = 'Standard 9mm handgun',
            icon = 'gun',
            metadata = {
                {label = 'Price', value = '$2,500'},
                {label = 'Ammo', value = '12 rounds'},
            },
            onSelect = function()
                TriggerServerEvent('shop:buy', 'weapon_pistol')
            end,
        },
        {
            title = 'Body Armor',
            description = 'Standard kevlar vest',
            icon = 'shield',
            metadata = {
                {label = 'Price', value = '$5,000'},
                {label = 'Protection', value = '50%'},
            },
            onSelect = function()
                TriggerServerEvent('shop:buy', 'armor')
            end,
        },
        {
            title = 'Attachments',
            description = 'Browse weapon modifications',
            icon = 'wrench',
            arrow = true,  -- Shows arrow indicating submenu
            menu = 'attachments_submenu',
        },
    },
})

lib.showContext('weapons_shop')

प्रोग्रेस बार और प्रोग्रेस सर्कल

प्रोग्रेस बार टाइम किए गए क्रियाओं के दौरान दृश्य प्रतिक्रिया देते हैं जैसे लॉकपिकिंग, क्राफ्टिंग, वाहन मरम्मत, या खाना पकाना। ox_lib दोनों लाइनियर बार और सर्कुलर इंडिकेटर प्रदान करता है। प्रोग्रेस एनीमेशन के दौरान, आप खिलाड़ी नियंत्रण जैसे मूवमेंट, कॉम्बैट, और कार एंट्री को अक्षम कर सकते हैं ताकि एक्सप्लॉइट्स रोके जा सकें। आप खिलाड़ी को एक एनीमेशन और प्रॉप भी संलग्न कर सकते हैं ताकि वे बार भरते समय क्रिया को स्पष्ट रूप से प्रदर्शन करें। यह फंक्शन लौटाता है true यदि खिलाड़ी ने क्रिया रद्द कर दी (जैसे कि हिलने से) और false यदि यह सफलतापूर्वक पूरा हुआ। हमेशा इस रिटर्न वैल्यू की जांच करें ताकि खिलाड़ी द्वारा रुकाए गए आइटम देने या क्रियाओं को पूरा करने से बचा जा सके।

-- client.lua: Progress bar examples

-- Linear progress bar with animation
local cancelled = lib.progressBar({
    duration = 8000,
    label = 'Lockpicking door...',
    useWhileDead = false,
    canCancel = true,
    disable = {
        car = true,
        move = true,
        combat = true,
    },
    anim = {
        dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
        clip = 'machinic_loop_mechandler',
    },
    prop = {
        model = 'prop_lockpick_01',
        bone = 57005,
        pos = vec3(0.14, 0.0, -0.01),
        rot = vec3(0.0, 0.0, 0.0),
    },
})

if cancelled then
    lib.notify({ title = 'Cancelled', type = 'error' })
else
    lib.notify({ title = 'Door Unlocked', type = 'success' })
    TriggerServerEvent('lockpick:success', doorId)
end

-- Circular progress (useful for quick actions)
if lib.progressCircle({
    duration = 2000,
    label = 'Searching...',
    position = 'bottom',
    useWhileDead = false,
    canCancel = true,
    disable = { move = true },
}) then
    lib.notify({ title = 'Search cancelled', type = 'error' })
else
    TriggerServerEvent('search:complete')
end

इनपुट संवाद: खिलाड़ी डेटा एकत्र करना

इनपुट संवाद आपको खिलाड़ियों से टाइप किया हुआ टेक्स्ट, नंबर, ड्रॉपडाउन चयन, चेकबॉक्स, रंग चयनकर्ता, तिथियां, और स्लाइडर मान एक साफ़ मोडल इंटरफ़ेस के माध्यम से एकत्र करने देते हैं। यह उन स्क्रिप्ट्स के लिए आवश्यक है जिन्हें खिलाड़ी इनपुट की जरूरत होती है जैसे घर की कीमत सेट करना, लाइसेंस प्लेट दर्ज करना, गैंग का नाम रखना, या नौकरी सेटिंग्स कॉन्फ़िगर करना। प्रत्येक इनपुट फ़ील्ड में एक लेबल, वैकल्पिक विवरण, आवश्यक फ़्लैग, और प्रकार-विशिष्ट विकल्प होते हैं जैसे नंबरों के लिए न्यूनतम/अधिकतम मान या ड्रॉपडाउन के लिए पूर्व-निर्धारित विकल्प। फ़ंक्शन लौटाता है nil यदि खिलाड़ी संवाद रद्द करता है और सबमिट करने पर फ़ील्ड क्रम में मानों की एक सरणी। हमेशा क्लाइंट और सर्वर दोनों पर लौटाए गए डेटा को मान्य करें ताकि शोषण से बचा जा सके।

-- client.lua: Input dialog examples

-- Vehicle listing form
local input = lib.inputDialog('List Vehicle for Sale', {
    { type = 'input', label = 'Title', description = 'Name for the listing', required = true, max = 50 },
    { type = 'number', label = 'Price ($)', description = 'Asking price', required = true, min = 1000, max = 10000000 },
    { type = 'select', label = 'Condition', options = {
        { value = 'new', label = 'Brand New' },
        { value = 'used', label = 'Used - Good' },
        { value = 'damaged', label = 'Damaged' },
    }},
    { type = 'textarea', label = 'Description', description = 'Describe your vehicle', max = 500 },
    { type = 'checkbox', label = 'I agree to the marketplace terms' },
})

if not input then return end -- Player cancelled

local title, price, condition, description, agreedTerms = table.unpack(input)

if not agreedTerms then
    lib.notify({ title = 'You must agree to the terms', type = 'error' })
    return
end

TriggerServerEvent('marketplace:list', {
    title = title,
    price = price,
    condition = condition,
    description = description,
})

ज़ोन: कुशल क्षेत्र पहचान

ox_lib ज़ोन पुराने, अप्रभावी तरीके को बदलते हैं जो हर फ्रेम में खिलाड़ी की स्थिति की जांच करता था GetEntityCoords और दूरी गणित। ज़ोन सिस्टम एक अनुकूलित स्थानिक पहचान एल्गोरिदम का उपयोग करता है जो केवल विन्यास योग्य अंतराल पर निर्देशांक जांचता है और जब खिलाड़ी ज़ोन सीमाओं को पार करते हैं तो enter/exit कॉलबैक ट्रिगर करता है। आप ज़ोन को गोले, बॉक्स, या बहुभुज के रूप में परिभाषित कर सकते हैं, जिससे वे छोटे इंटरैक्शन पॉइंट से लेकर बड़े पड़ोस की सीमाओं तक के लिए पर्याप्त लचीले होते हैं। ज़ोन घुमाव, विकास के लिए डिबग ड्राइंग, और कॉलबैक को पास किए जाने वाले मनमाने डेटा का समर्थन करते हैं। किसी भी स्क्रिप्ट के लिए जिसे यह पता लगाना है कि खिलाड़ी किसी विशिष्ट क्षेत्र में है, ox_lib ज़ोन सबसे प्रदर्शनकारी समाधान हैं।

-- client.lua: Zone examples

-- Sphere zone for a shop entrance
local shopZone = lib.zones.sphere({
    coords = vec3(25.7, -1347.3, 29.5),
    radius = 3.0,
    debug = true,  -- Set false in production
    onEnter = function(self)
        lib.notify({ title = 'Press [E] to open shop', type = 'info' })
        lib.showTextUI('[E] Open Shop', { position = 'right-center' })
    end,
    onExit = function(self)
        lib.hideTextUI()
    end,
})

-- Box zone with rotation for a parking spot
local parkingZone = lib.zones.box({
    coords = vec3(215.3, -810.0, 30.7),
    size = vec3(6.0, 3.0, 2.0),
    rotation = 70.0,
    debug = true,
    onEnter = function(self)
        lib.showTextUI('[E] Store Vehicle')
    end,
    onExit = function(self)
        lib.hideTextUI()
    end,
})

-- Clean up zones when resource stops
AddEventHandler('onResourceStop', function(resource)
    if resource == GetCurrentResourceName() then
        shopZone:remove()
        parkingZone:remove()
    end
end)

कैश: स्मार्ट डेटा एक्सेस

यह lib.cache मॉड्यूल बिना हर फ्रेम में नेटिव कॉल किए बार-बार आवश्यक खिलाड़ी डेटा तक त्वरित पहुंच प्रदान करता है। मान जैसे cache.ped, cache.vehicle, cache.seat, cache.weapon, और cache.playerId स्वचालित रूप से ox_lib द्वारा इवेंट लिसनर्स के माध्यम से अपडेट किए जाते हैं, पोलिंग के बजाय। इसका मतलब है कि आप सुरक्षित रूप से पढ़ सकते हैं cache.vehicle अपने कोड में कहीं भी प्रदर्शन की चिंता किए बिना। कैश मान बदलने पर घटनाएं भी चलाता है, इसलिए आप के लिए हैंडलर पंजीकृत कर सकते हैं ox_lib:cache:vehicle जब कोई खिलाड़ी वाहन में प्रवेश करता है या बाहर निकलता है तो प्रतिक्रिया देने के लिए। ज़ोन और ox_lib के बाकी हिस्सों के साथ मिलकर, कैश सिस्टम आपको साफ, इवेंट-चालित कोड लिखने देता है बजाय फ्रेम-आधारित पोलिंग लूप्स के जो CPU चक्रों को बर्बाद करते हैं जो शायद ही कभी बदलते हैं।

-- client.lua: Cache examples

-- Access cached values (no native calls needed)
local myPed = cache.ped
local myVehicle = cache.vehicle  -- nil if not in a vehicle
local mySeat = cache.seat        -- -1 = driver, 0 = front passenger, etc.
local myWeapon = cache.weapon

-- React to vehicle changes
lib.onCache('vehicle', function(vehicle)
    if vehicle then
        -- Player entered a vehicle
        local plate = GetVehicleNumberPlateText(vehicle)
        lib.notify({
            title = 'Vehicle',
            description = 'Plate: ' .. plate,
            type = 'info',
        })
    else
        -- Player exited a vehicle
        lib.notify({ title = 'On foot', type = 'info' })
    end
end)

-- React to weapon changes
lib.onCache('weapon', function(weapon)
    if weapon then
        print('Player equipped weapon:', weapon)
    end
end)