Agency Phone Kurulum Kılavuzu: Eksiksiz FiveM Kurulumu ve Yapılandırması

Bu rehber, FiveM sunucunuza Agency Phone kurulumu ve yapılandırması sürecinin tamamında size yol gösterir. QBCore, ESX veya tamamen özel bir framework çalıştırıyor olun, ön koşullardan ilk başlatmaya ve yapılandırmada ince ayar yapmaya kadar ihtiyacınız olan her şeyi burada bulacaksınız. Eksiksiz teknik referans için şu adresteki resmi belgelere bakın: docs.agencyg.de/phone.

Ön Koşullar

Agency Phone kurulumunu yapmadan önce, sunucu ortamınızın aşağıdaki gereksinimleri karşıladığından emin olun:

• FiveM sunucu artifact'i: sürüm 6633 veya daha yenisi (önerilen: artifact sürümlerini daima güncel tutun)
• Veri Tabanı: MySQL 5.7+ veya MariaDB 10.3+, şununla: oxmysql (önerilen) veya mysql-async yüklendi ve yapılandırıldı
• CFX Keymaster: sunucunuzun lisans anahtarı şurada kayıtlı ve aktif olmalıdır: keymaster.fivem.net
• Framework (isteğe bağlı): Daha derin framework entegrasyonu istiyorsanız QBCore veya ESX. Standalone kullanım için gerekli değildir.
• Aktif Agency Phone satın alımı: resource, satın alma işleminden sonra CFX varlık portalı üzerinden teslim edilir

Adım 1: Satın Alın ve İndirin

Satın alma işleminizi şurada tamamladıktan sonra: Agency Scripts mağazası, lisansınız CFX hesabınıza otomatik olarak tanımlanır. İndirmek için:

1. Şuraya giriş yapın: keymaster.fivem.net satın alımınızla bağlantılı CFX hesabı ile.
2. Git Tanımlanan Varlıklar ve bulun: agency-phone.
3. Tıkla İndir en güncel sürüm zip dosyasını almak için.
4. QBCore veya ESX köprüsünü satın aldıysanız şunu da indirin: agency-phone-bridge-qb veya agency-phone-bridge-esx aynı listeden.

Adım 2: Klasör Yapısı

Zip dosyasını/dosyalarını çıkartın. Sizin resources dizini dışa aktarıldıktan sonra şu şekilde görünmelidir:

resources/
  [agency]/
    agency-phone/
      client/
      server/
      html/
      config.lua
      fxmanifest.lua
    agency-phone-bridge-qb/   (QBCore only)
      client/
      server/
      fxmanifest.lua

The [agency] klasörü bir kategori klasörüdür (köşeli parantezler FiveM'e bunun bir resource grubu olduğunu belirtir). Kesinlikle zorunlu değildir, şunu yerleştirebilirsiniz: agency-phone doğrudan şunun içinde: resources/, ancak kategori klasörlerini kullanmak düzeni korur.

Adım 3: Veritabanı Kurulumu

Agency Phone, ilk başlatmada oxmysql içindeki yerleşik auto-migration sistemini kullanarak kendi veritabanı tablolarını oluşturur. Herhangi bir SQL dosyasını manuel olarak içe aktarmanız gerekmez. Veritabanı bağlantınızın şurada yapılandırıldığından emin olmanız yeterlidir: server.cfg:

# server.cfg, database connection string (oxmysql example)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

İlk sunucu başlangıcında Agency Phone şu tabloları oluşturacaktır: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts, ve phone_settings. Yeni bir veritabanı kullanıyorsanız tablolar otomatik olarak oluşturulacaktır. Başka bir telefon script'inden geçiş yapıyorsanız mevcut şemanızda ad çakışması olmadığından emin olun.

Adım 4: server.cfg Girdileri

Aşağıdaki ensure satırlarını şuraya ekleyin: server.cfg. Sıralama önemlidir, oxmysql Agency Phone uygulamasından önce yüklenmelidir:

# Dependencies
ensure oxmysql

# Agency Phone (standalone or with framework bridge)
ensure agency-phone

# Only add if using QBCore bridge:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Only add if using ESX bridge:
# ensure es_extended
# ensure agency-phone-bridge-esx

QBCore veya ESX kullanıyorsanız, framework'ün kendisinin yüklendiğinden emin olun önce yukarıdaki yorumlarda gösterildiği gibi bridge resource. standalone çekirdek (agency-phone) her zaman herhangi bir bridge kaynağından önce ensure edilmelidir.

Adım 5: Yapılandırma (config.lua)

Aç agency-phone/config.lua bir metin düzenleyicide. Bu birincil yapılandırma dosyasıdır ve telefonun neredeyse tüm davranışlarını denetler. İşte en önemli ayarların ayrıntılı bir incelemesi:

Config = {}

-- ============================================================
-- FRAMEWORK
-- "standalone" | "qbcore" | "esx"
-- ============================================================
Config.Framework = "standalone"

-- ============================================================
-- PHONE NUMBERS
-- ============================================================
-- Format string for auto-generated numbers. X = random digit.
Config.PhoneNumberFormat = "555-XXXX"

-- Allow players to pay in-game currency to change their number
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- default currency (adjust per framework)

-- ============================================================
-- APPS: enable/disable individual apps
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- set true only for LEO servers
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (only relevant when Config.EnableMDT = true)
-- ============================================================
-- Jobs that can access the MDT app
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- SOCIAL MEDIA
-- ============================================================
-- Rename the social app to match your server's lore
Config.SocialAppName = "Chirper"
-- Max post length in characters
Config.SocialPostMaxLength = 280

-- ============================================================
-- ENCRYPTED MESSAGING
-- Requires players to hold a specific inventory item
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- UI
-- ============================================================
-- Default theme: "dark" or "light"
Config.DefaultTheme = "dark"
-- Notification display duration in milliseconds
Config.NotificationDuration = 5000
-- Phone open keybind (FiveM key name)
Config.PhoneKey = "F1"

QBCore'a Özel Notlar

QBCore bridge kullanılırken (Config.Framework = "qbcore"), bankacılık uygulaması bakiye ve işlem verilerini QBCore ekonomisinden otomatik olarak çeker. Meslek tabanlı uygulama izinleri (MDT erişimi gibi) QBCore'un yerel meslek sistemini kullanır, meslek adlarını şuraya eklemek dışında ek bir yapılandırma gerekmez: Config.MDTJobs. Telefon numaraları karakter başına saklanır ve QBCore karakter tanımlayıcısına bağlanır.

ESX'e Özel Notlar

ESX bridge ile (Config.Framework = "esx"), bankacılık uygulaması ESX hesaplarına bağlanır (varsayılan: bank). ESX kurulumunuz özel hesap adları kullanıyorsa, bunları bridge'in kendi config.lua. MDT erişimi için ESX meslek rütbeleri dikkate alınır, yalnızca meslek adlarının listelenmesi yeterlidir; bridge config içinde rütbe kısıtlamaları yapılandırmadığınız sürece o meslekteki tüm grade'ler otomatik olarak erişim kazanır.

Adım 6: İlk Başlatma Doğrulaması

Sunucunuzu başlatın ve konsol çıktısını izleyin. Başarılı bir Agency Phone yüklemesi şöyle görünür:

[agency-phone] Database tables verified/created, OK
[agency-phone] Framework: standalone
[agency-phone] Loaded 0 contacts, 0 messages (fresh install)
[agency-phone] Resource started successfully, v2.x.x

Bu aşamada hatalarla karşılaşırsanız aşağıdaki sorun giderme bölümünü inceleyin. Sunucu çalıştıktan sonra bir istemciyle bağlanın ve şu tuşa basın: F1 (veya yapılandırdığınız telefon tuşu) ile telefonu açabilirsiniz. İlk kullanımda telefon, henüz atanmış bir numarası yoksa oyuncudan numarasını belirlemesini isteyecektir.

Sık Karşılaşılan Hatalar ve Çözümleri

Hata: "oxmysql is not started"

Bu, şuradaki dosyanızda oxmysql kaynağının agency-phone kaynağından önce ensure edilmediği anlamına gelir: server.cfg. Şunu taşıyın: ensure oxmysql üstteki satır ensure agency-phone ve sunucuyu yeniden başlatın.

Hata: "Failed to create table phone_contacts: Table already exists"

Bu ölümcül bir hata değil bir uyarıdır, mevcut bir veritabanının üzerine yeniden kurulum yaptığınız anlamına gelir. Mevcut veriler korunur. Bu uyarıyı güvenle yok sayabilirsiniz. Temiz bir kurulum istiyorsanız, şunları manuel olarak silin: phone_* önce veritabanınızdaki tabloları.

Tuşa basıldığında telefon UI açılmıyor

İlk olarak, resource'un sunucu konsolunda hata vermeden başladığını kontrol edin. İkinci olarak, başka hiçbir resource'un aynı tuş atamasını (varsayılan: F1) kullanmadığını doğrulayın. Tuş atamasını şuradan değiştirebilirsiniz: config.lua altında Config.PhoneKey. Üçüncüsü, NUI odak çakışmalarını kontrol edin: Başka bir resource aynı anda NUI odağını alıyorsa telefon tuş basımını doğru şekilde algılayamayabilir.

Banka uygulaması $0 / boş bakiye gösteriyor

standalone modunda çalışıyorsanız, bankacılık uygulaması varsayılan olarak dahili bir cüzdan kullanır. Bunu QBCore veya ESX ekonomisine bağlamak için ilgili bridge kaynağını kullanmalı ve şunu ayarlamalısınız: Config.Framework düzgün şekilde. Bridge ensure edilmiş olmasına rağmen bakiye hâlâ sıfır görünüyorsa, telefon başlatılmadan önce oyuncunun karakterinin framework içinde tamamen yüklendiğini doğrulayın (server.cfg içindeki framework yükleme sırası).

MDT uygulaması polis memurları için görünmüyor

Şunu onaylayın: Config.EnableMDT = true config.lua içinde ve oyuncunun mevcut meslek adının şuradaki girdilerden biriyle tam olarak eşleştiğini: Config.MDTJobs. Meslek adı eşleştirmesi büyük/küçük harfe duyarlıdır. Framework'ünüzün meslek yapılandırmasında tanımlanan tam meslek adı dizesini kullanın.

Ek Yapılandırma Seçenekleri

Agency Phone, bu kılavuzda ele alınanların ötesinde çok daha fazla yapılandırma seçeneğine sahiptir. En kullanışlı gelişmiş ayarlardan bazıları şunlardır:

• Config.MaxContactsPerPlayer, bir oyuncunun kaydedebileceği kişi sayısını sınırlayın (varsayılan: sınırsız)
• Config.GPSUpdateInterval, paylaşılan GPS üzerinde oyuncunun konum işaretçisinin ne sıklıkla güncelleneceği (milisaniye cinsinden)
• Config.SocialPostCooldown, spam'i önlemek için sosyal medya gönderileri arasındaki minimum süre (saniye)
• Config.AllowAnonCalls, oyuncuların alıcıdan numaralarını gizleyen aramalar yapıp yapamayacağı
• Config.CameraPhotoQuality, NUI ekran görüntüsü kalite seviyesi (1-10, oyun içi galeri görsel boyutunu etkiler)

Tüm seçenekleri içeren ayrıntılı açıklamalı config dosyasının tamamına şu adresteki resmi dokümantasyondan ulaşabilirsiniz: docs.agencyg.de/phone. Belgeler her sürümle birlikte güncellenir ve ayarlar değiştiğinde sürüme özel geçiş notları içerir.

Agency Phone'u Güncel Tutma

Yeni bir sürüm yayınlandığında, CFX Keymaster hesabınızda bir bildirim alırsınız. Güncellemek için Granted Assets sayfasından yeni zip dosyasını indirin, arşivden çıkarın ve mevcut olanla değiştirin: agency-phone klasörüdür. Canlı bir sunucuda güncelleme yapmadan önce her zaman güncelleme changelog'unu okuyun: config.lua anahtarlarında dikkatinizi gerektiren tüm değişiklikleri listeler. Veritabanınız ve mevcut oyuncu verileriniz bir güncelleme ile asla silinmez.