Programowanie w TypeScript w FiveM: nowoczesne skrypty z typami

Dlaczego TypeScript dla FiveM?

TypeScript wprowadza statyczne sprawdzanie typów, nowoczesne funkcje JavaScript i doskonałe wsparcie IDE do programowania w FiveM. Podczas gdy Lua pozostaje standardowym językiem skryptowym, TypeScript skompilowany do JavaScript działa natywnie w FiveM za pośrednictwem runtime JavaScript. Bezpieczeństwo typów wykrywa błędy na etapie kompilacji, które w przeciwnym razie spowodowałyby awarię serwera w czasie działania, autouzupełnianie znacząco przyspiesza development, a interfejsy sprawiają, że kod dokumentuje się sam. W przypadku złożonych projektów z wieloma programistami TypeScript zmniejsza narzut koordynacyjny i sprawia, że refaktoryzacja jest bezpieczniejsza.

Konfiguracja projektu z fivem-ts-boilerplate

Najszybszym sposobem na rozpoczęcie projektu TypeScript FiveM jest użycie społecznościowego fivem-ts-boilerplate. Sklonuj repozytorium szablonu, uruchom npm install aby skonfigurować zależności, i masz gotową do użycia strukturę projektu z osobnymi katalogami źródłowymi client, server oraz shared. Boilerplate zawiera konfigurację webpacka, która kompiluje TypeScript do paczek JavaScript kompatybilnych z FiveM, wraz z definicjami typów dla FiveM natives, funkcji citizen i popularnych API frameworków. Zbuduj swój projekt za pomocą npm run build a wynik trafia bezpośrednio do folderu zasobu.

Definicje typów i natives

Ten @citizenfx/client i @citizenfx/server pakiety typów zapewniają definicje TypeScript dla wszystkich natywnych funkcji FiveM i wywołań API. Definicje te umożliwiają autouzupełnianie dla funkcji takich jak GetEntityCoords, SetEntityHealth, oraz RegisterCommand, pokazując typy parametrów i zwracane wartości podczas pisania kodu. W przypadku API specyficznych dla frameworków, takich jak QBCore lub ESX, możesz utworzyć lub zainstalować dodatkowe pliki definicji typów, które pokrywają exporty i eventy frameworka. Zmienia to Twoje IDE w interaktywną przeglądarkę dokumentacji dla całego FiveM API.

Architektura klienta i serwera

Zorganizuj swój projekt TypeScript z wyraźnym podziałem na kod klienta i serwera. Użyj katalogu shared na interfejsy, enumy i funkcje pomocnicze potrzebne po obu stronach. Zdefiniuj interfejsy payloadu zdarzeń we wspólnych typach, aby kompilator weryfikował zgodność formatu danych między klientem a serwerem. Importuj wrappery frameworków z warstwy usług, która abstrahuje bazowy framework, dzięki czemu Twoja logika biznesowa jest przenośna pomiędzy konfiguracjami QBCore, ESX oraz standalone. Taka architektura sprawia, że baza kodu staje się modułowa i łatwa do testowania.

Debugowanie TypeScript w FiveM

Debugowanie skompilowanego kodu może być wyzwaniem, ponieważ wykonywany JavaScript różni się od twojego kodu źródłowego TypeScript. Włącz source maps w swojej konfiguracji webpack, aby ślady stosu błędów (stack traces) odwoływały się do twoich oryginalnych plików TypeScript. Użyj console.log instrukcji, które są przekazywane do konsoli serwera FiveM do debugowania po stronie serwera. W przypadku debugowania po stronie klienta narzędzia deweloperskie NUI dostępne pod F8 mogą badać wykonywanie JavaScript. Rozważ dodanie narzędzia do ustrukturyzowanego logowania, które uwzględnia znaczniki czasu, poziomy logów i odwołania do plików źródłowych, aby ułatwić śledzenie problemów w skompilowanym kodzie.

Migracja i współistnienie z Lua

Nie musisz od razu przepisywać całego serwera na TypeScript. Resources w TypeScript doskonale współistnieją ze skryptami w Lua, ponieważ komunikują się przez ten sam system eventów i exportów. Zacznij od tworzenia nowych funkcji w TypeScript, zachowując istniejące skrypty Lua. Wywołując exporty Lua z TypeScriptu, twórz deklaracje typów opisujące oczekiwane sygnatury funkcji. Stopniowo migruj kluczowe systemy, w miarę jak nabierasz wprawy w pracy z TypeScriptem. To stopniowe podejście pozwala Twojemu zespołowi uczyć się TypeScriptu, zachowując stabilność serwera i unikając ryzykownego przepisywania wszystkiego od zera.