Interact system

1. 01

   ضع السكربت

   حمّل السكربت من حسابك على Tebex، ثم انسخ مجلد avenida_interact/ إلى resources/[avenida]/ على سيرفرك.

2. 02

   فعّله في server.cfg

   أضف ensure avenida_interact. لا شيء يحتاج إلى أن يُحمَّل قبله: منذ 1.1.0 لا اعتمادية للسكربت، فلا يهم ترتيب التحميل.

3. 03

   اضبط قيمك الافتراضية

   افتح config/config.lua واضبط ما ينطبق على كل النقاط: النص، والمفتاح، ومسافتي showIcon وcanInteract، والأيقونة، واللون، والألوان المسماة، ومسافة ظهور الشخصيات، وConfig.Hud لاختيار أي HUD يُخفى أثناء الحوار.

4. 04

   أزل الأمثلة

   تبقى الأمثلة في config/entities/ وconfig/peds/ وconfig/positions/ فعّالة ما دامت ملفاتها موجودة. احذف ما لا تريده، فالـ manifest يلتقط هذه المجلدات بنمط عام، ولا شيء آخر تعدله.

5. 05

   جرّب إعادة التحميل الساخنة

   شغّل السيرفر ثم اكتب /restart avenida_interact داخل اللعبة. تختفي الأيقونات وتعود نظيفة، وتبقى النقاط التي سجّلتها ريسورساتك، دون إعادة تشغيل جلستك.

أول نقطة تفاعل لديك في 30 ثانية

أنشئ ملف `myscript/client.lua` في ريسورسك والصق هذا. تظهر علامة سماوية على بعد 30 مترًا، وتنفتح نافذة "E - Hello" على بعد مترين. الشيء الوحيد الذي يجب أن يعمل هو avenida_interact نفسه.

-- myscript/client.lua
exports.avenida_interact:positionRegister({
    coords      = vec3(-265.0, -963.6, 31.2),
    showIcon    = 30.0,           -- marker fades in at 30m
    canInteract = 2.0,            -- label unrolls at 2m
    hintIcon    = 'interact',     -- see the icon list below
    hintColor   = '#22d3ee',      -- hex, or an alias from Config.Colors
    message     = 'Hello',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('chat:addMessage', { args = { 'Hello, world!' } })
    end,
})

exports عامة مرتّبة حسب المجال. كل صف يعرض توقيع الاستدعاء وما يفعله، لا كيف يفعله.

Interact Points

• positionRegister

  exports.avenida_interact:positionRegister(cfg) --> id نسخ

  يسجل نقطة على إحداثيات ثابتة. يقبل كل الحقول البصرية (hintIcon، hintColor، showIcon، canInteract، offsetZ، blips) إضافة إلى choices[] لعدة مفاتيح على النقطة نفسها. ويقبل canInteract رقمًا أو دالةً، فتستطيع ربط ظهور النافذة بوظيفة أو غرض أو مهلة. يعيد id.

• pedRegister

  exports.avenida_interact:pedRegister(cfg) --> id نسخ

  يستدعي شخصية مضبوطة (نموذج، animDict وanimName أو scenario، وblip)، ويربط بها نقطة ويعيد رقمها. الشخصية لا تُقتل ولا تهرب ولا تسقط أرضًا. تظهر وتختفي عند حدّ Config.PedSpawnRange، أي 50 مترًا افتراضيًا. اضبط randomComponents = false على بائع له اسم معروف، وإلا رأى كل لاعب ملابس مختلفة.

• pedRemove

  exports.avenida_interact:pedRemove(idx) نسخ

  أُضيف في 1.1.0. يزيل شخصية مسجّلة بـ pedRegister ويحذف تسجيلها، كي ينصرف صاحب المهمة المؤقّت عند انتهاء مهمته.

• entityRegister

  exports.avenida_interact:entityRegister(cfg) --> id نسخ

  يربط نقطة بـ entity موجودة، تُمرَّر في cfg.entity. ويدعم cfg.bone لتعليق النافذة على عظمة بدلًا من مركز الـ entity. استعمله مع ما يستدعيه سكربت آخر: مركبة، وprop موضوع، وغرض ملقى.

• entityRegisterByHash

  exports.avenida_interact:entityRegisterByHash(hash, cfg) نسخ

  watcher سلبي: ينطبق الإعداد على كل entity من هذا النموذج، الموجودة الآن والتي ستظهر لاحقًا. ويغطي خيط واحد كل الـ hash المسجلة، ويجسّها كل 5 ثوانٍ. هذا ما تريده لأجهزة الصراف وآلات البيع والأبواب، بدلًا من قائمة إحداثيات تصونها بنفسك.

• entityRemove

  exports.avenida_interact:entityRemove(idx) نسخ

  يفك النقطة التي أعادها entityRegister. أما الـ entity نفسها فلا تُمس.

• interactCreate

  exports.avenida_interact:interactCreate(cfg) --> id نسخ

  نقطة تُنشأ وتُزال عند الطلب. استعملها حين لا تعيش النقطة إلا وقتًا قصيرًا: هدف مهمة، وحقيبة على الأرض، وجثة تُفتَّش.

• interactRemove

  exports.avenida_interact:interactRemove(id) نسخ

  يزيل نقطة أنشأها interactCreate، وعلامتها على الخريطة إن كانت أعلنت واحدة.

• unlockLastInteract

  exports.avenida_interact:unlockLastInteract() نسخ

  تقفل النقطة نفسها بعد استعمالها، كي لا يشغّلها مرتين مفتاحٌ يبقى مضغوطًا. استدعِ هذا في نهاية إجرائك لإعادة تفعيلها. فإن بقي اللاعب في المدى عادت النافذة فورًا، وإلا انتظرت دخوله من جديد.

Prompt API

• HandleTextUI

  exports.avenida_interact:HandleTextUI(id, data) --> duiHandler نسخ

  ينشئ أو يحدّث فقاعة ثلاثية الأبعاد مستقلة، بلا نقطة تفاعل خلفها. استعمله حين تريد التحكم في الظهور من خيطك أنت. يعيد الـ handler الذي تمرره إلى Draw3DSprite.

• Draw3DSprite

  exports.avenida_interact:Draw3DSprite({ duiHandler, coords, maxDistance, hintOnly? }) نسخ

  يرسم الفقاعة في فضاء العالم من خيط رسم، مصحَّحةً حسب نسبة الشاشة. ومع hintOnly = true تُرسم العلامة وحدها، وهي حالة النقطة العادية على المسافات البعيدة.

• CloseTextUI

  exports.avenida_interact:CloseTextUI(id) نسخ

  يخفي الفقاعة لكنه يبقي الـ DUI في الذاكرة، فتكون إعادة الفتح فورية.

• RemoveTextUI

  exports.avenida_interact:RemoveTextUI(id) نسخ

  يزيل فقاعة نهائيًا ويحرر الـ DUI. استعمله حين تعلم أنها لن تعود.

• RemoveTextUIs

  exports.avenida_interact:RemoveTextUIs() نسخ

  يزيل كل الفقاعات النشطة. ويُستدعى تلقائيًا عند إيقاف الريسورس.

• IsDuiVisible

  exports.avenida_interact:IsDuiVisible() --> boolean نسخ

  يعيد true ما دامت نافذة معروضة على الشاشة. اقرأه كي لا تتكدس نوافذك فوق تفاعل جارٍ.

Key handler

• HandleHoldTextUI

  exports.avenida_interact:HandleHoldTextUI(id, data) --> duiHandler نسخ

  الطبقة التي بُنيت عليها النقاط: ترسم نافذة على Coords وتراقب مفتاحها من خيط إدارة كل 50ms. ويأخذ data الحقول BindToHold (رقم التحكم)، DistanceHold، Coords، وChoicesUI وChoicesCtrl لنافذة بعدة مفاتيح، وonCallback(id) وcanInteract(id, dist). وتنطلق النافذة عند الضغط بفاصل 500ms، وينفَّذ الـ callback داخل pcall، فخطأ من جهتك لا يكسر النافذة.

• CloseHoldTextUI

  exports.avenida_interact:CloseHoldTextUI(id) نسخ

  يخفي النافذة دون تدمير النسخة، لخروج نظيف حين يغادر اللاعب المنطقة.

• RemoveHoldTextUI

  exports.avenida_interact:RemoveHoldTextUI(id) نسخ

  يدمر نسخة واحدة ويحرر الـ DUI الخاص بها.

• RemoveHoldTextUIs

  exports.avenida_interact:RemoveHoldTextUIs() نسخ

  يدمر كل النسخ النشطة.

أمثلة جاهزة للنسخ واللصق للحالات الشائعة. ضعها في موردك، وعدّل القيم، وانشرها.

exports.avenida_interact:positionRegister({
    coords      = vec3(149.5, -1040.4, 29.4),
    showIcon    = 30.0,
    canInteract = 2.0,
    hintIcon    = 'bank',
    hintColor   = 'blue',
    message     = 'Use the ATM',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('myserver-banking:openATM')
    end,
    blips = {
        sprite  = 277,
        color   = 2,
        scale   = 0.8,
        text    = 'ATM',
        display = 4,
    },
})

local ATM_PROPS = {
    'prop_atm_01', 'prop_atm_02', 'prop_atm_03', 'prop_fleeca_atm',
}

for _, prop in ipairs(ATM_PROPS) do
    exports.avenida_interact:entityRegisterByHash(prop, {
        canInteract = 1.2,
        offsetZ     = 1.0,
        hintIcon    = 'bank',
        hintColor   = 'blue',
        choices = {
            {
                bind       = 'E',
                message    = 'Use the ATM',
                onInteract = function()
                    TriggerEvent('myserver-banking:atmUse')
                end,
            },
            {
                bind      = 'G',
                message   = 'Rob the ATM',
                hintColor = 'red',
                condition = function()
                    return exports['myserver-police']:hasEnoughCops(2)
                end,
                onInteract = function(entity)
                    TriggerServerEvent('myserver-robbery:startATM', NetworkGetNetworkIdFromEntity(entity))
                end,
            },
        },
    })
end

exports.avenida_interact:pedRegister({
    coords           = vec4(-1393.81, -1064.09, 3.17, 266.09),
    model            = 'a_f_y_vinewood_04',
    animDict         = 'anim@amb@waving@male',
    animName         = 'ground_wave',
    randomComponents = false,
    message          = 'Talk with Maria',
    showIcon         = 10.0,
    canInteract      = 3.0,
    hintIcon         = 'talk',
    hintColor        = 'gold',
    blips = { sprite = 119, color = 50, text = 'Lumberjack', scale = 0.8 },
    dialogue = {
        name     = 'Maria',
        startMsg = 'Hello, are you ready to start your shift?',
        elements = {
            {
                label  = 'Yes, where do I start?',
                action = function(changeDialog, close)
                    SetNewWaypoint(-584.01, 5491.59)
                    changeDialog('The forest is on your GPS now.', {
                        { label = 'Got it!', action = function(_, close) close() end },
                    })
                end,
            },
            {
                label  = 'I\'ll come back later',
                action = function(_, close) close() end,
            },
        },
    },
})

• هل فعلًا لا أحتاج إلى ox_lib؟
  لا تحتاج إليه. منذ 1.1.0 ينفذ `bridges/compat.lua` إنشاء الـ DUI ونقاط القرب وأدوات الانتظار بـ natives خالصة، وسطر `@ox_lib/init.lua` معلَّق في الـ manifest. وإن فضلت المرور عبر ox_lib، اضبط `Config.UseOxLib = true` وأزل التعليق عن ذلك السطر. المساران مدعومان، ومسار الـ natives هو الافتراضي.
• لا تظهر علامتي، فأين أبحث؟
• يُتجاهل شرط الخيار عندي
• ما الألوان التي أستطيع استعمالها؟
• كانت النافذة ممطوطة على شاشتي العريضة
• تبقى نقاطي ظاهرة بعد إيقاف ريسورسي
• كيف أربطه بـ ESX أو QBCore أو Qbox أو ox أو vRP؟
• كم نقطة أستطيع تسجيلها؟