nxn-emergency: Új script – Sürgősségi kód rendszer (Code 1/2/3/4), frakciós státuszváltás, dispatch/sirencontrol/duty integráció

[firstvideosgrp]

📋 Összefoglalás

Az nxn-emergency a Nexon RP szerver sürgősségi reagálási kódrendszere. Kezeli a klasszikus RP "code" rendszert (Code 1–4), amellyel a frakciós tagok (rendőrök, EMS, tűzoltók) jelzik a jelenlegi reagálási státuszukat – ez befolyásolja a szirénhasználatot, a dispatch hívásokhoz rendelt prioritást, a HUD megjelenítést és az egységek láthatóságát a diszpécserpanelen.

⚠️ Fontos hatásköri lehatárolás:

• nxn-emergency → Code szint kezelés, reagálási státusz szinkronizálás, frakciós code policy
• nxn-sirencontrol → Szirén tónus/fény kezelés – az nxn-emergency code váltásakor automatikusan aktiválja/deaktiválja a szirént (ha Config.AutoSiren = true)
• nxn-dispatch → Hívás kezelés – a createCall metadata-ja tartalmazza a code szintet; code 1 esetén a dispatch priority értéke emelkedik
• nxn-duty → Duty állapot lekérés – csak duty-ban lévők válthatnak code-ot
• nxn-hud → Code badge megjelenítés a HUD-on
• nxn-notify → Értesítések code váltáskor

---

🔗 Hivatkozások a korábbi issue-kban

Issue	Hivatkozás
#158 – nxn-police	A rendőrök code szintje befolyásolja az MDT státuszt és a dispatch hívás prioritást; isOnDuty(src) export szükséges a code-váltás engedélyezéséhez
#167 – nxn-dispatch	A createCall metadata mezőjébe kerül a code szint; Code 1 hívás dispatch priority = 1, Code 2 → priority = 2, Code 3+ → priority = 3; getOnDutyUnits() export mutatja az egységek code státuszát
#173 – nxn-sirencontrol	Code 1/2 váltásakor az nxn-emergency opcionálisan hívja az nxn-sirencontrol setSirenTone() és setLightMode() exportjait; Code 3/4-re váltáskor toggleSiren() (ki); az isSirenActive() visszaolvasható

---

🔗 Kapcsolódó scriptek

Script	Kapcsolat
nxn-duty	Kötelező – isOnDuty(src, faction) export: csak duty-ban lévők válthatnak code-ot
nxn-sirencontrol	Opcionális – setSirenTone(toneId), setLightMode(modeId), toggleSiren(), isSirenActive() exportok; code váltáskor automatikus szirén vezérlés (ha Config.AutoSiren = true)
nxn-dispatch	Opcionális – createCall metadata code szint; getOnDutyUnits() exportban code státusz megjelenítés
nxn-hud	Opcionális – updateModuleData('emergency', { code, label, color }) – code badge a HUD-on
nxn-notify	Opcionális – code váltáskor toast értesítés
nxn-police	Opcionális – isOnDuty(src) export; rendőrségi code policy (pl. Code 1 csak officer+ rangnak)
nxn-ems	Opcionális – EMS code policy; EMS Code 1 = sürgős mentés, Code 3 = rendelkezésre áll
nxn-loading	updateModuleProgress('Emergency', 100) betöltéskor

---

🏗️ Fájlstruktúra

nxn-emergency/
├── fxmanifest.lua
├── config.lua
├── shared.lua
├── client.lua
├── server.lua
├── html/
│   ├── index.html      -- Code váltó panel NUI
│   ├── style.css
│   └── app.js
└── docs/index.html

Sablon: nxn-example boilerplate, dizájn: design-guide.html

---

📖 A Code rendszer értelmezése

Code	Elnevezés	Jelentés	Szirén	Dispatch prioritás
Code 1	Sürgős / Kód 1	Azonnali reagálás szükséges, szirén + kékfény	Aktív (wail/yelp)	Priority 1 – Kritikus
Code 2	Haladj el / Kód 2	Gyors reagálás, csak fény (hang nélkül)	Silent mód (csak fény)	Priority 2 – Magas
Code 3	Normál / Kód 3	Nem sürgős, rendes közlekedés	Ki	Priority 3 – Közepes
Code 4	Visszaáll / Kód 4	Incidens lezárult, egység szabad / visszaáll az állomásra	Ki	– (nem generál dispatch hívást)

💡 A code rendszer RP-alapú konvenció. A számok szerver szinten konfigurálhatóak (Config.Codes), így a nevek, színek és viselkedések testreszabhatók.

---

⚙️ config.lua

Config = {}

Config.ResourceName = GetCurrentResourceName()
Config.Debug        = false

-- Code váltás billentyűje (NUI-on kívüli gyorsváltás)
Config.KeyOpenPanel = 'U'    -- Code panel megnyitása

-- Automatikus szirén vezérlés code váltáskor (nxn-sirencontrol integrációhoz)
-- Ha true: code 1/2 váltáskor a sirencontrol exportjai automatikusan hívódnak
Config.AutoSiren = true

-- Csak duty-ban lévők válthatnak code-ot
Config.RequireDuty = true

-- Code definíciók
Config.Codes = {
    {
        id              = 'code1',
        label           = 'Code 1',
        description     = 'Sürgős reagálás – szirén + kékfény',
        shortLabel      = 'C1',
        color           = '#e74c3c',       -- piros
        icon            = 'hgi-siren',
        sirenTone       = 'wail',          -- nxn-sirencontrol tone ID (ha AutoSiren = true)
        lightMode       = 'full',          -- nxn-sirencontrol light mode ID
        dispatchPriority = 1,             -- nxn-dispatch createCall priority override
    },
    {
        id              = 'code2',
        label           = 'Code 2',
        description     = 'Gyors reagálás – csak fény, hang nélkül',
        shortLabel      = 'C2',
        color           = '#e67e22',       -- narancs
        icon            = 'hgi-alarm-clock',
        sirenTone       = 'off',           -- hang nélkül
        lightMode       = 'silent',        -- csak fény mód (nxn-sirencontrol)
        dispatchPriority = 2,
    },
    {
        id              = 'code3',
        label           = 'Code 3',
        description     = 'Normál – nem sürgős, rendes közlekedés',
        shortLabel      = 'C3',
        color           = '#27ae60',       -- zöld
        icon            = 'hgi-checkmark-circle-02',
        sirenTone       = 'off',
        lightMode       = 'off',
        dispatchPriority = 3,
    },
    {
        id              = 'code4',
        label           = 'Code 4',
        description     = 'Visszaáll – incidens lezárult, szabad egység',
        shortLabel      = 'C4',
        color           = '#95a5a6',       -- szürke
        icon            = 'hgi-home-wifi',
        sirenTone       = 'off',
        lightMode       = 'off',
        dispatchPriority = nil,            -- nem generál dispatch hívást
    },
}

-- Frakciónkénti code policy
-- allowedCodes: csak ezek a code-ok elérhetőek az adott frakciónak
-- defaultCode: duty on-kor ez lesz az alapértelmezett
Config.FactionPolicies = {
    police = {
        allowedCodes = { 'code1', 'code2', 'code3', 'code4' },
        defaultCode  = 'code3',
    },
    sheriff = {
        allowedCodes = { 'code1', 'code2', 'code3', 'code4' },
        defaultCode  = 'code3',
    },
    ems = {
        allowedCodes = { 'code1', 'code2', 'code3', 'code4' },
        defaultCode  = 'code3',
    },
    fire = {
        allowedCodes = { 'code1', 'code2', 'code3', 'code4' },
        defaultCode  = 'code3',
    },
}

-- Duty off-kor automatikusan törlődik-e a code
Config.ClearCodeOnDutyOff = true

-- Dispatch automatikus hívás code 1/2 váltáskor
-- Ha true: code 1 vagy 2-re váltáskor automatikusan létrehoz egy 'general_police' / 'general_ems' típusú hívást
-- (csak ha Config.AutoDispatch = true ÉS van aktív dispatch)
Config.AutoDispatch = false
Config.AutoDispatchType = 'general_police'  -- override: nil = frakció alapján auto
Config.AutoDispatchCooldown = 120           -- mp: ennyi időn belül ne hozzon létre újat

-- nxn-hud badge szín téma
Config.HUDBadgeColors = {
    code1 = '#e74c3c',
    code2 = '#e67e22',
    code3 = '#27ae60',
    code4 = '#95a5a6',
    none  = '#7f8c8d',
}

-- ACE jog admin force-code-hoz
Config.AdminAce = 'nxn.emergency.admin'

---

📡 Kliens exportok

Export	Visszatérés	Leírás
getCurrentCode()	table|nil	Aktuális code adatai ({ id, label, color, ... }) vagy nil
getCurrentCodeId()	string|nil	Aktuális code ID ('code1', 'code3', stb.)
isInCode(codeId)	boolean	Az adott code-ban van-e a játékos
setCode(codeId)	boolean	Programatikusan beállít egy code-ot
clearCode()	boolean	Code törlése (duty off esetén)
getAllowedCodes()	table[]	Frakció alapján elérhető code-ok listája

📡 Szerver exportok

Export	Paraméterek	Visszatérés	Leírás
getPlayerCode(src)	number	table|nil	Játékos aktuális code-ja (szerver cache)
getPlayerCodeId(src)	number	string|nil	Játékos code ID-ja
isInCode(src, codeId)	number, string	boolean	Az adott code-ban van-e a játékos
setCode(src, codeId, adminSrc?)	number, string, number?	boolean	Szerver oldalon code beállítás
clearCode(src)	number	boolean	Code törlés
getUnitsByCode(codeId)	string	table[]	Az adott code-ban lévő összes egység listája
getAllUnitCodes()	–	table	Az összes duty-ban lévő egység code státusza { [src] = codeData }

---

📡 Net eventek

Kliens → Szerver

nxn-emergency:server:setCode    -- { codeId }
nxn-emergency:server:clearCode  -- {} (duty off, vagy manuális törlés)

Szerver → Kliens

nxn-emergency:client:codeChanged   -- { src, codeId, codeData } (broadcast – más egységek látják)
nxn-emergency:client:forceCode     -- { codeId } (admin kényszer)
nxn-emergency:client:syncCodes     -- { codes: {[src]=codeId} } (duty belépéskor szinkron)

Szerver lokál (más scriptek figyelik)

nxn-emergency:server:codeChanged   -- src, oldCodeId, newCodeId, faction
nxn-emergency:server:codeCleared   -- src, oldCodeId, faction

---

🔄 Működési folyamat

Code váltás (kliens)

Játékos [U] gomb → NUI panel megnyílik
    ↓
GetAllowedCodes() → frakció policy alapján szűrt code lista
SendNUIMessage({ action = 'open', codes = allowedCodes, current = currentCode })
    ↓
Játékos rákattint egy code gombra → NUI 'setCode' callback
    ↓
Config.RequireDuty? → nxn-duty:isOnDuty() check
    ↓ OK
TriggerServerEvent('nxn-emergency:server:setCode', { codeId = codeId })
    ↓
Szerver validál → cache frissít → broadcast → exportok hívása
    ↓
nxn-emergency:client:codeChanged event visszajön → NUI frissítés, HUD badge
    ↓
Config.AutoSiren? → nxn-sirencontrol exportok hívása

Szerver: code beállítás és broadcast

-- nxn-emergency/server.lua:
local unitCodes = {}  -- [src] = { codeId, faction, changedAt }

RegisterNetEvent('nxn-emergency:server:setCode', function(data)
    local src = source

    -- Duty check
    if Config.RequireDuty and GetResourceState('nxn-duty') == 'started' then
        local faction = GetPlayerFaction(src)  -- nxn-duty alapján
        if not faction then return end
    end

    local codeData = GetCodeById(data.codeId)
    if not codeData then return end

    local oldCode = unitCodes[src] and unitCodes[src].codeId or nil
    local faction = GetPlayerFaction(src)

    unitCodes[src] = {
        codeId    = data.codeId,
        faction   = faction,
        changedAt = os.time(),
    }

    -- Broadcast: duty-ban lévők ugyanabból a frakcióból látják egymás code-ját
    TriggerClientEvent('nxn-emergency:client:codeChanged', -1, {
        src      = src,
        codeId   = data.codeId,
        codeData = codeData,
        faction  = faction,
    })

    -- Szerver event más scripteknek
    TriggerEvent('nxn-emergency:server:codeChanged', src, oldCode, data.codeId, faction)

    -- Auto dispatch (config alapján)
    if Config.AutoDispatch and codeData.dispatchPriority and codeData.dispatchPriority <= 2 then
        AutoDispatchOnCode(src, codeData, faction)
    end
end)

AddEventHandler('playerDropped', function()
    unitCodes[source] = nil
end)

nxn-sirencontrol integráció (auto szirén)

-- nxn-emergency/client.lua:
AddEventHandler('nxn-emergency:client:codeChanged', function(data)
    -- Csak a saját code változásra reagálunk szirén vezérléssel
    if data.src ~= GetPlayerServerId(PlayerId()) then return end
    if not Config.AutoSiren then return end
    if GetResourceState('nxn-sirencontrol') ~= 'started' then return end

    local code = data.codeData
    -- Szirén tónus beállítás
    if code.sirenTone and code.sirenTone ~= 'off' then
        exports['nxn-sirencontrol']:setSirenTone(code.sirenTone)
    else
        -- Code 3/4: szirén kikapcsolás
        if exports['nxn-sirencontrol']:isSirenActive() then
            exports['nxn-sirencontrol']:toggleSiren()  -- ki
        end
    end
    -- Fény mód beállítás
    if code.lightMode then
        exports['nxn-sirencontrol']:setLightMode(code.lightMode)
    end
end)

nxn-dispatch integráció (code metadata)

-- nxn-emergency: más scriptek (pl. nxn-police) hívják a dispatch-t
-- és a code szintet metadata-ként adják át:

-- nxn-police/server.lua példa:
local codeId = nil
if GetResourceState('nxn-emergency') == 'started' then
    codeId = exports['nxn-emergency']:getPlayerCodeId(src)
end
exports['nxn-dispatch']:createCall({
    type     = 'pursuit',
    title    = 'Rendőrségi üldözés',
    coords   = coords,
    factions = { 'police', 'sheriff' },
    priority = codeId == 'code1' and 1 or codeId == 'code2' and 2 or 3,
    metadata = { code = codeId, officerName = GetPlayerName(src) },
})

nxn-hud badge

-- nxn-emergency/client.lua:
AddEventHandler('nxn-emergency:client:codeChanged', function(data)
    if data.src ~= GetPlayerServerId(PlayerId()) then return end
    if GetResourceState('nxn-hud') ~= 'started' then return end
    exports['nxn-hud']:updateModuleData('emergency', {
        code  = data.codeData.shortLabel,
        color = data.codeData.color,
        icon  = data.codeData.icon,
    })
end)

nxn-duty integráció (duty off → code törlés)

-- nxn-emergency/client.lua:
AddEventHandler('nxn-duty:client:dutyChanged', function(faction, onDuty)
    if not onDuty and Config.ClearCodeOnDutyOff then
        TriggerServerEvent('nxn-emergency:server:clearCode', {})
        if GetResourceState('nxn-hud') == 'started' then
            exports['nxn-hud']:updateModuleData('emergency', nil)
        end
    elseif onDuty then
        -- Duty on: alapértelmezett code beállítása
        local policy = Config.FactionPolicies[faction]
        if policy and policy.defaultCode then
            exports['nxn-emergency']:setCode(policy.defaultCode)
        end
    end
end)

---

📡 NUI Panel

A code panel egy kompakt floating panel, U gombbal nyitható:

┌──────────────────────────────────────┐
│  🚨 REAGÁLÁSI KÓD              [X]  │
├──────────────────────────────────────┤
│                                      │
│  [ 🔴 CODE 1 ]  [ 🟠 CODE 2 ]       │
│    Sürgős          Gyors             │
│                                      │
│  [ 🟢 CODE 3 ✓]  [ ⬜ CODE 4 ]       │
│    Normál          Visszaáll         │
│                                      │
├──────────────────────────────────────┤
│  Aktuális: CODE 3 – Normál           │
└──────────────────────────────────────┘

Panel elemek:

• 4 (vagy config-ban meghatározott számú) code gomb
• Aktív code kiemelés (szín + checkmark)
• Code leírás az aktív gomb alatt
• Csak az engedélyezett code-ok jelennek meg (FactionPolicies alapján)
• Nexon dizájn sablon, Huge Icons
• Nem backdrop-filter!

---

🔌 Integrációs példák más scriptekből

nxn-dispatch (egység code státusz a webes panelen)

-- nxn-dispatch/server.lua:
-- A getOnDutyUnits() export kiegészíthető code státusszal:
local function GetAllDutyUnitsWithCode(faction)
    local units = GetAllDutyUnits(faction)  -- meglévő függvény
    for _, unit in ipairs(units) do
        if GetResourceState('nxn-emergency') == 'started' then
            unit.code = exports['nxn-emergency']:getPlayerCodeId(unit.src)
        end
    end
    return units
end
-- A webes dispatch panel így mutathatja: "Kovács R. | Rendőrség | Code 1 🔴"

nxn-sirencontrol (code váltás visszaolvasása szirénből)

-- Ha a játékos manuálisan kapcsolja be a szirént (nxn-sirencontrol),
-- az nxn-emergency automatikusan Code 1-re állhat (opcionális, config-gal):
-- nxn-emergency/client.lua:
AddEventHandler('nxn-sirencontrol:client:stateChanged', function(data)
    if not Config.AutoCodeFromSiren then return end
    if data.tone ~= 'off' and exports['nxn-emergency']:getCurrentCodeId() == 'code3' then
        -- Szirén bekapcsolt → auto Code 1
        exports['nxn-emergency']:setCode('code1')
    elseif data.tone == 'off' then
        -- Szirén leállt → auto Code 3
        exports['nxn-emergency']:setCode('code3')
    end
end)

nxn-police (code alapú jogosultság ellenőrzés)

-- nxn-police/server.lua:
-- Csak Code 1-ben lévő rendőr kezdeményezhet prioritásos üldözést:
local function CanStartPriorityPursuit(src)
    if GetResourceState('nxn-emergency') ~= 'started' then return true end
    local codeId = exports['nxn-emergency']:getPlayerCodeId(src)
    return codeId == 'code1'
end

---

✅ Implementációs checklist

Alap

• fxmanifest.lua – dependencies: nxn-loading; opcionális: nxn-duty, nxn-sirencontrol, nxn-dispatch, nxn-hud, nxn-notify
• config.lua – code definíciók, frakciós policy, auto szirén, auto dispatch, billentyű
• shared.lua – NXN.Emergency namespace, Log/Info/Warn/Error logger
• client.lua – NUI panel, code kezelés, szirén/hud integráció, exportok
• server.lua – cache, szerver eventek, exportok, broadcast
• html/ – Code panel NUI

Kliens logika

• U billentyű: NUI panel toggle
• getAllowedCodes() belső függvény: frakció policy alapján szűrt code lista
• NUI 'setCode' callback → TriggerServerEvent('nxn-emergency:server:setCode', { codeId })
• NUI 'closePanel' callback → panel zárása
• nxn-emergency:client:codeChanged event figyelése:
  • Saját code: NUI frissítés, nxn-hud:updateModuleData('emergency', ...) hívás
  • Saját code: Config.AutoSiren esetén nxn-sirencontrol exportok hívása
  • Saját code: nxn-notify:send toast (ha config engedélyezi)
• nxn-emergency:client:syncCodes event: duty belépéskor szinkron
• nxn-emergency:client:forceCode event: admin kényszer code
• nxn-duty:client:dutyChanged event figyelése:
  • Duty off → TriggerServerEvent('nxn-emergency:server:clearCode') + HUD törlés
  • Duty on → setCode(policy.defaultCode)
• nxn-sirencontrol:client:stateChanged figyelése (ha Config.AutoCodeFromSiren = true)
• Kliens exportok: getCurrentCode(), getCurrentCodeId(), isInCode(codeId), setCode(codeId), clearCode(), getAllowedCodes()
• nxn-loading:updateModuleProgress('Emergency', 100) betöltéskor
• GetResourceState ellenőrzés minden opcionális export hívás előtt

Szerver logika

• unitCodes cache tábla: [src] = { codeId, faction, changedAt }
• nxn-emergency:server:setCode net event handler
• nxn-emergency:server:clearCode net event handler
• playerDropped → cache cleanup
• Duty check: nxn-duty:isOnDuty(src, faction) ha Config.RequireDuty = true
• Frakció meghatározás: GetPlayerFaction(src) belső segédfüggvény
• TriggerClientEvent('nxn-emergency:client:codeChanged', -1, ...) broadcast
• nxn-emergency:server:codeChanged lokális event triggerelése
• nxn-emergency:server:codeCleared lokális event triggerelése
• Auto dispatch: AutoDispatchOnCode(src, codeData, faction) belső függvény
• Duty belépéskor sync: syncCodes küldése az adott játékosnak
• Szerver exportok: getPlayerCode(src), getPlayerCodeId(src), isInCode(src, codeId), setCode(src, codeId, adminSrc?), clearCode(src), getUnitsByCode(codeId), getAllUnitCodes()
• Admin parancs: /setcode [playerId] [codeId] ACE védelemmel

NUI (html/)

• Code gombok: csak engedélyezett code-ok (NUI-ba küldve)
• Aktív code kiemelés: szín + active CSS class
• Code leírás az aktív gomb alatt
• setCode NUI callback
• closePanel NUI callback (ESC + X gomb)
• updateState NUI message: code lista + aktuális code szinkron
• Nexon dizájn sablon
• Nem backdrop-filter!
• Huge Icons: hgi-siren, hgi-alarm-clock, hgi-checkmark-circle-02, hgi-home-wifi

Biztonság

• Szerver-oldali codeId whitelist: csak Config.Codes-ban szereplő ID fogadható el
• Frakció policy ellenőrzés szerveren: csak az engedélyezett code-ok fogadhatók el az adott frakciónak
• Rate limit: max 1 code váltás / 2 másodperc per játékos

Minőség

• docs/index.html dokumentáció (nxn-example sablon alapján, Nexon dizájnnal)
• fxmanifest.lua – docs/index.html NEM kerül a files szekcióba
• Debug mód: /emergencydebug parancs – aktuális code státuszok kiírása

---

🗓️ Szükséges módosítások más issue-kban

nxn-police (#158) – kiegészítés

• nxn-emergency:server:codeChanged szerver event figyelése → ha Code 1-re vált egy rendőr, opcionálisan createCall('general_police', ...) hívás
• getPlayerCodeId(src) export használata dispatch hívás priority és metadata.code mezőjéhez
• MDT-ben az aktív egységek code státuszának megjelenítése

nxn-dispatch (#167) – kiegészítés

• getOnDutyUnits(faction?) szerver export kiegészítése code mezővel (ha nxn-emergency fut)
• Webes dispatch panel: egységek listájánál Code 1 🔴 / Code 3 🟢 badge megjelenítés
• metadata.code mező megjelenítése a híváslistában (webes panel + játékon belüli HUD)

nxn-sirencontrol (#173) – kiegészítés

• nxn-emergency:client:codeChanged event figyelése: ha az nxn-emergency auto szirén vezérlést kér, az nxn-sirencontrol fogadja és alkalmazza (ha még nincs manuálisan felülírva)
• isSirenActive() export dokumentálása az nxn-emergency számára

---

📎 Referenciák

• #158 – nxn-police: duty rendszer, rang alapú jogosultságok, MDT
• #167 – nxn-dispatch: createCall export, getOnDutyUnits, webes panel
• #173 – nxn-sirencontrol: setSirenTone, setLightMode, toggleSiren, isSirenActive exportok
• nxn-example boilerplate
• Nexon dizájn guide