FiveM Key Mapping API Rehberi (2026): Performanslı Tuş Atama ve Modern Kontrol Sistemleri

FiveM sunucu geliştirmede en sık yapılan mimari hatalardan biri, oyuncu girdilerini (keybinds) dinlemek için sürekli çalışan Citizen.CreateThread ve IsControlJustPressed döngüleri kullanmaktır. 2026 yılı standartlarında bu yaklaşım hem yüksek işlemci kullanımı (Resmon lag) oluşturur hem de oyuncuların tuş kombinasyonlarını GTA V ayarlarından değiştirmesine engel olur.

Bu rehberde, FiveM'in native Key Mapping API sistemini kullanarak sıfırdan nasıl performanslı, modern ve esnek bir tuş atama altyapısı kuracağınızı adım adım inceleyeceğiz.

1. Eski Yöntem vs. Modern Key Mapping API

Eski tarz scriptlerde tuş dinlemek için genellikle aşağıdaki gibi bir döngü kullanılır:

-- ❌ ÖNERİLMEYEN ESKİ YÖNTEM (Yüksek Resmon Tüketimi)
Citizen.CreateThread(function()
    while true do
        Citizen.Wait(0)
        if IsControlJustPressed(0, 38) then -- 'E' Tuşu
            -- Etkileşim kodları...
        end
    end
end)

Bu yöntem her karede (frame) çalışarak işlemciyi gereksiz yere yorar. RegisterKeyMapping API'si ise olay tabanlıdır (Event-Driven). Yani oyuncu tuşa basmadığı sürece arka planda hiçbir kod çalışmaz ve işlemci kullanımı 0.00ms kalır.

2. Adım Adım Entegrasyon Rehberi

Örnek bir etkileşim scripti üzerinden adım adım modern tuş atama yapısını oluşturalım.

Adım 1: Script Dosya Yapısını Hazırlama

resources/[scripts]/dexta_interaction/ klasörü oluşturun ve içine fxmanifest.lua ile client.lua dosyalarını ekleyin.

fxmanifest.lua içeriği:

fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'

Adım 2: Client Tarafında Komut ve Tuş Tanımlama

client.lua dosyanıza şu kod bloklarını ekleyin:

-- 1. Çalıştırılacak Konsol Komutunu Tanımlayın
RegisterCommand('dexta_interact', function()
    -- Oyucu kelepçeliyse veya baygınsa tuşun çalışmasını engelleyebilirsiniz
    if LocalPlayer.state.isCuffed or IsEntityDead(PlayerPedId()) then
        return
    end

    TriggerEvent('dexta_interaction:client:onInteract')
end, false)

-- 2. Komutu Bir Tuşa Bağlayın (RegisterKeyMapping)
-- Parametreler: (Komut Adı, Açıklama, Tuş Tipi, Varsayılan Tuş)
RegisterKeyMapping('dexta_interact', 'Çevre Etkileşimi Kullan', 'keyboard', 'E')

-- 3. Tetiklenecek Olay
RegisterNetEvent('dexta_interaction:client:onInteract', function()
    print('Etkileşim tuşuna basıldı!')
    -- Buraya envanter açma, araç kilitleme veya MLO etkileşim kodlarınızı ekleyebilirsiniz.
end)

3. Basma ve Bırakma (Hold/Release) Senaryoları

Bazı mekaniklerde (örneğin telsiz konuşması veya bir nesneyi taşırken) tuşa basılı tutma veya tuştan elini çekme durumlarını algılamanız gerekir. Key Mapping bunu + ve - ön ekleriyle kolayca çözer:

-- Tuşa BASILDIĞINDA çalışır (+)
RegisterCommand('+dexta_radio', function()
    print('Telsiz mandalına basıldı - Ses iletiliyor.')
end, false)

-- Tuş BIRAKILDIĞINDA çalışır (-)
RegisterCommand('-dexta_radio', function()
    print('Telsiz mandalı bırakıldı - İletim durdu.')
end, false)

-- Tuş Eşleme
RegisterKeyMapping('+dexta_radio', 'Telsiz Konuşma Mandalı', 'keyboard', 'CAPITAL')

4. Gelişmiş İpuçları ve Altyapı Çözümleri

• Tuş Değişikliklerini Sıfırlama: Oyuncu client tarafında tuşu değiştirdiğinde bu veri CitizenFX/fivem.cfg içinde saklanır. Scriptinizde varsayılan tuşu değiştirseniz bile eski oyuncularda otomatik güncellenmez. Yeni varsayılanı zorlamak için komut adını revize edebilirsiniz (Örn: dexta_interact_v2).
• Araç İçi ve Yaya Ayrımı: Komut içerisinde IsPedInAnyVehicle(PlayerPedId(), false) kontrolü ile tuşun sadece araçta veya sadece yadayken çalışmasını sağlayabilirsiniz.

Eğer bu tarz teknik geliştirmelerle, FPS optimizasyonlarıyla ve modern altyapılarla tek tek zaman kaybetmek istemiyorsanız; tam entegre, hazır ve güncel sistemlerin yer aldığı DxAV1 - Roleplay Paketi çözümümüzü inceleyebilirsiniz.

Sıkça Sorulan Sorular (SSS)

S: RegisterKeyMapping kullandığımda oyuncu tuşu değiştirebilir mi?

C: Evet. Bu yöntemin en büyük avantajı, oyuncunun ESC > Settings > Key Bindings > FiveM altından tuşu dilediği gibi özelleştirebilmesidir.

S: Neden IsControlJustPressed yerine bu sistemi kullanmalıyım?

C: IsControlJustPressed her salise (frame) çalışan döngülere ihtiyaç duyar ve Resmon değerini yükseltir. Key Mapping ise sadece tuşa basıldığında tetiklenen bir Event yapısı kullandığından 0.00ms performans sağlar.

S: Fare tıklamaları (Mouse Buttons) için Key Mapping kullanılabilir mi?

C: Evet. 3. parametre olarak 'keyboard' yerine 'mouse' yazıp varsayılan buton olarak MOUSE_BUTTON değerlerini tanımlayabilirsiniz.