Poradnik konfiguracji Agency Phone: Kompletna instalacja i konfiguracja FiveM

Ten poradnik przeprowadzi Cię przez cały proces instalacji i konfiguracji Agency Phone na Twoim serwerze FiveM. Niezależnie od tego, czy używasz QBCore, ESX, czy w pełni własnego frameworka, znajdziesz tutaj wszystko, czego potrzebujesz: od wymagań wstępnych, przez pierwsze uruchomienie, aż po dostrojenie konfiguracji. Pełną dokumentację techniczną znajdziesz w oficjalnej dokumentacji pod adresem docs.agencyg.de/phone.

Wymagania wstępne

Przed instalacją Agency Phone upewnij się, że środowisko Twojego serwera spełnia następujące wymagania:

• Artefakt serwera FiveM: wersja 6633 lub nowsza (zalecane: zawsze utrzymuj artefakty aktualne)
• Baza danych: MySQL 5.7+ lub MariaDB 10.3+, z oxmysql (zalecane) lub mysql-async zainstalowany i skonfigurowany
• CFX Keymaster: klucz licencyjny twojego serwera musi być zarejestrowany i aktywny na keymaster.fivem.net
• Framework (opcjonalnie): QBCore lub ESX, jeśli zależy Ci na głębszej integracji z frameworkiem. Niewymagane przy działaniu w trybie standalone.
• Aktywny zakup Agency Phone: resource jest dostarczany przez portal assetów CFX po zakupie

Krok 1: Kup i pobierz

Po sfinalizowaniu zakupu w Sklep Agency Scripts, twoja licencja jest automatycznie rejestrowana na twoim koncie CFX. Aby pobrać:

1. Zaloguj się do keymaster.fivem.net z kontem CFX powiązanym z twoim zakupem.
2. Przejdź do Przyznane zasoby i zlokalizuj agency-phone.
3. Kliknij Pobierz aby pobrać archiwum zip najnowszego wydania.
4. Jeśli zakupiłeś bridge dla QBCore lub ESX, pobierz także agency-phone-bridge-qb lub agency-phone-bridge-esx z tej samej listy.

Krok 2: Struktura folderów

Rozpakuj plik(i) zip. Twój resources katalog po rozpakowaniu powinien wyglądać następująco:

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

Ten [agency] folder to folder kategorii (nawiasy kwadratowe informują FiveM, że to grupa resource). Nie jest to bezwzględnie wymagane, możesz umieścić agency-phone bezpośrednio w resources/, ale używanie folderów kategorii pozwala zachować porządek.

Krok 3: Konfiguracja bazy danych

Agency Phone tworzy własne tabele bazy danych przy pierwszym uruchomieniu, korzystając z systemu automatycznej migracji wbudowanego w oxmysql. Nie musisz ręcznie importować żadnych plików SQL. Po prostu upewnij się, że połączenie z bazą danych jest skonfigurowane w server.cfg:

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

Przy pierwszym uruchomieniu serwera Agency Phone utworzy następujące tabele: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts, oraz phone_settings. Jeśli korzystasz ze świeżej bazy danych, tabele zostaną utworzone automatycznie. Jeśli migrujesz z innego skryptu telefonu, upewnij się, że w Twoim istniejącym schemacie nie występują konflikty nazw.

Krok 4: Wpisy w server.cfg

Dodaj następujące linijki ensure do swojego server.cfg. Kolejność ma znaczenie, oxmysql musi ładować się przed Agency Phone:

# 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

Jeśli korzystasz z QBCore lub ESX, upewnij się, że sam framework ładuje się przed resource bridge, jak pokazano w komentarzach powyżej. Rdzeń standalone (agency-phone) powinien być zawsze uruchamiany przed jakimkolwiek zasobem bridge.

Krok 5: Konfiguracja (config.lua)

Otwórz agency-phone/config.lua w edytorze tekstu. Jest to główny plik konfiguracyjny, który kontroluje niemal każdy aspekt działania telefonu. Oto szczegółowy przegląd najważniejszych ustawień:

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"

Uwagi dotyczące QBCore

W przypadku korzystania z bridge QBCore (Config.Framework = "qbcore"), aplikacja bankowa automatycznie pobiera stan konta i dane transakcji z ekonomii QBCore. Uprawnienia aplikacji oparte na pracach (takie jak dostęp do MDT) korzystają z natywnego systemu prac QBCore, więc nie jest wymagana żadna dodatkowa konfiguracja poza dodaniem nazw prac do Config.MDTJobs. Numery telefonów są zapisywane dla każdej postaci i powiązane z identyfikatorem postaci QBCore.

Uwagi dotyczące ESX

Z bridge ESX (Config.Framework = "esx"), aplikacja bankowa łączy się z kontami ESX (domyślnie: bank). Jeśli Twoja konfiguracja ESX używa niestandardowych nazw kont, skonfiguruj je we własnym config.lua. Stopnie prac w ESX są uwzględniane przy dostępie do MDT, wystarczy podać tylko nazwy prac; wszystkie rangi w ramach danej pracy otrzymują dostęp automatycznie, chyba że skonfigurujesz ograniczenia rang w konfiguracji bridge.

Krok 6: Weryfikacja pierwszego uruchomienia

Uruchom serwer i obserwuj wyjście w konsoli. Poprawne załadowanie Agency Phone wygląda tak:

[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

Jeśli na tym etapie widzisz błędy, sprawdź sekcję rozwiązywania problemów poniżej. Gdy serwer już działa, połącz się klientem i naciśnij F1 (lub skonfigurowany klawisz telefonu), aby otworzyć telefon. Przy pierwszym użyciu telefon poprosi gracza o ustawienie numeru, jeśli nie ma jeszcze żadnego przypisanego.

Typowe błędy i rozwiązania

Błąd: "oxmysql is not started"

Oznacza to, że oxmysql nie jest uruchomione przed agency-phone w Twoim server.cfg. Przenieś ensure oxmysql wiersz powyżej ensure agency-phone i zrestartuj serwer.

Błąd: "Failed to create table phone_contacts: Table already exists"

To ostrzeżenie, a nie błąd krytyczny. Oznacza to, że instalujesz zasób na istniejącej bazie danych. Istniejące dane zostają zachowane. Możesz bezpiecznie zignorować to ostrzeżenie. Jeśli chcesz wykonać czystą instalację, usuń ręcznie phone_* najpierw tabele w twojej bazie danych.

UI telefonu nie otwiera się po naciśnięciu klawisza

Najpierw sprawdź, czy zasób uruchomił się bez błędów w konsoli serwera. Po drugie, upewnij się, że żaden inny zasób nie korzysta z tego samego przypisania klawisza (domyślnie: F1). Możesz zmienić przypisanie klawisza w config.lua poniżej Config.PhoneKey. Po trzecie, sprawdź konflikty fokusu NUI: jeśli inny zasób przechwytuje fokus NUI w tym samym czasie, telefon może nieprawidłowo odbierać naciśnięcia klawiszy.

Aplikacja bankowa pokazuje $0 / puste saldo

Jeśli korzystasz z trybu standalone, aplikacja bankowa domyślnie używa wewnętrznego portfela. Aby połączyć ją z ekonomią QBCore lub ESX, musisz użyć odpowiedniego zasobu bridge i ustawić Config.Framework poprawnie. Jeśli bridge jest uruchomiony (ensured), ale saldo nadal wynosi zero, sprawdź, czy postać gracza jest w pełni załadowana w frameworku przed inicjalizacją telefonu (kolejność ładowania frameworka w server.cfg).

Aplikacja MDT niewidoczna dla policjantów

Potwierdź, że Config.EnableMDT = true w config.lua oraz czy aktualna nazwa pracy gracza dokładnie odpowiada jednemu z wpisów w Config.MDTJobs. Dopasowanie nazwy pracy uwzględnia wielkość liter. Użyj dokładnie takiego ciągu nazwy pracy, jak zdefiniowano w konfiguracji prac Twojego frameworka.

Dodatkowe opcje konfiguracji

Agency Phone oferuje znacznie więcej opcji konfiguracji niż te omówione w tym poradniku. Do najbardziej przydatnych ustawień zaawansowanych należą:

• Config.MaxContactsPerPlayer, ogranicz liczbę kontaktów, które gracz może zapisać (domyślnie: bez limitu)
• Config.GPSUpdateInterval, jak często blip lokalizacji gracza aktualizuje się na wspólnym GPS (w milisekundach)
• Config.SocialPostCooldown, minimalny czas między postami w mediach społecznościowych w celu zapobiegania spamowi (w sekundach)
• Config.AllowAnonCalls, czy gracze mogą wykonywać połączenia ukrywające ich numer przed odbiorcą
• Config.CameraPhotoQuality, Poziom jakości zrzutów ekranu NUI (1-10, wpływa na rozmiar obrazu w galerii w grze)

Pełny, opatrzony komentarzami plik konfiguracyjny ze wszystkimi opcjami jest dostępny w oficjalnej dokumentacji pod adresem docs.agencyg.de/phone. Dokumentacja jest aktualizowana przy każdym wydaniu i zawiera uwagi dotyczące migracji dla konkretnych wersji w przypadku zmiany ustawień.

Aktualizowanie Agency Phone

Gdy pojawi się nowa wersja, otrzymasz powiadomienie na swoim koncie CFX Keymaster. Aby zaktualizować, pobierz nowy plik zip ze strony Granted Assets, rozpakuj go i zastąp istniejący agency-phone folder na swoim serwerze. Zawsze czytaj changelog aktualizacji przed aktualizacją na aktywnym serwerze, zawiera on listę wszelkich zmian w kluczach config.lua wymagających twojej uwagi. Twoja baza danych i istniejące dane graczy nigdy nie są usuwane przez aktualizację.