Agency-ProgressBar: Detal UI, który po cichu wynosi każdy skrypt na wyższy poziom

Niewielki skrypt, potężny efekt

Paski postępu pojawiają się w FiveM na każdym kroku: wytrychowanie, naprawianie, pranie brudnych pieniędzy, górnictwo, pomoc medyczna. Domyślne implementacje są funkcjonalne, ale nijakie. Agency-ProgressBar to nasza wizja tego, jak powinno wyglądać to narzędzie, gdy ktoś dba o detale.

Anatomia dobrego progress bara

Dobry pasek postępu komunikuje jednocześnie cztery rzeczy: jaka akcja się odbywa, na jakim jesteś etapie, ile czasu pozostało i czy możesz ją anulować. Większość implementacji obsługuje tylko dwie pierwsze. Agency-ProgressBar pokazuje wszystkie cztery, z subtelnymi animacjami, dzięki którym pasek porusza się płynnie, a nie skokowo.

Anulowanie, które działa

Anulowanie zainicjowane przez gracza wyzwala krótką animację zanikania, która przywraca przezroczystość paska do zera w 300 ms. Bez gwałtownego zniknięcia. Deweloperzy mogą zarejestrować callback anulowania, dzięki czemu skrypty czyszczą stan prawidłowo, gdy gracz odejdzie w trakcie akcji.

Pozycjonowanie kontekstowe

Pasek pojawia się w pobliżu odpowiedniego elementu na ekranie: nad twoją głową przy akcjach na sobie, nad docelowym NPC przy akcjach interaktywnych. Koniec z odczytywaniem statusu akcji na dole ekranu, gdy coś dzieje się na górze. To kontekstowe pozycjonowanie to subtelne ulepszenie UX, które gracze odczuwają, nawet nie potrafiąc go nazwać.

Wzorzec exportów

Podobnie jak wszystkie nasze skrypty narzędziowe, Agency-ProgressBar oferuje proste API exports: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). Wdróż to do dowolnego skryptu w kilka minut. Współpracuje z Agency-Notify, Agency-Hud i resztą naszego ekosystemu bez żadnej specjalnej konfiguracji.

Instalacja & konfiguracja

Agency-ProgressBar to narzędzie drop-in bez żadnych zależności bazodanowych. Pobierz z Tebex, wrzuć folder do katalogu resources, dodaj ensure agency-progressbar do server.cfg. To wszystko. Resource zaczyna działać natychmiast, a każdy skrypt może wywołać exports API przy następnym restarcie.

Jeśli zastępujesz istniejący pasek postępu (progressBar z ox_lib, qb-progressbar itp.), funkcja znajdź i zamień w nazwie wywołania exportu pozwala przeprowadzić większość migracji w kilka minut. Struktura parametrów została celowo dopasowana do popularnych wzorców społeczności.

Opcje konfiguracji

Otwórz config.lua aby dostosować wartości domyślne:

• Domyślna pozycja, nad głową gracza (domyślnie) lub na stałe na dole pośrodku.
• Schemat kolorów, gradient koloru wypełnienia. Obsługuje pojedynczy kolor, gradient dwupunktowy lub mapowanie według ważności (zielony dla normalnego, pomarańczowy dla wolnego, czerwony dla krytycznego).
• Klawisz anulowania, który klawisz anuluje pasek postępu z możliwością anulowania. Domyślnie: backspace.
• Anuluj animację, fade-out (domyślnie), slide-out lub natychmiastowe zniknięcie.
• Wyświetlanie czasu, pokazuj pozostałe sekundy (domyślnie), procent lub nic.
• Minimalny czas trwania, akcje krótsze niż ten próg całkowicie pomijają pasek. Domyślnie: 500ms.

Kompatybilność z frameworkami

Agency-ProgressBar jest w pełni standalone i nie ma żadnych zależności od frameworka. Działa identycznie na QBCore, ESX oraz na niestandardowych konfiguracjach serwera. API exportów jest jedyną płaszczyzną integracji: brak wspólnych zmiennych globalnych, brak eventów frameworka, brak sprawdzania uprawnień. Zainstaluj go i wywołuj z dowolnego skryptu, niezależnie od jego pochodzenia.

Dlaczego ma to znaczenie dla roleplay

Paski postępu to podstawowy element UX, który pojawia się w dziesiątkach sytuacji w rozgrywce: wytrychowanie, zakuwanie w kajdanki, crafting, leczenie, zbieranie dowodów, hakowanie. Kiedy paski te wyglądają niespójnie lub zachowują się inaczej w różnych skryptach, powstaje subtelny szum wizualny, który zaburza spójność serwera.

Gdy każdy progress bar na twoim serwerze korzysta z Agency-ProgressBar, język wizualny staje się spójny. Gracze rozwijają intuicję co do tego, co pasek oznacza i jak się zachowuje. Zachowanie przy anulowaniu jest jednolite. Typografia pasuje do reszty twojego UI. To drobiazgi, ale razem tworzą zauważalnie bardziej dopracowane doświadczenie dla graczy.

Pozycjonowanie kontekstowe ma większe znaczenie, niż mogłoby się wydawać. Pasek postępu przypięty do głowy twojej postaci podczas otwierania zamka wytrychem pozwala skupić się na akcji, a nie na rogu ekranu. W napiętych momentach, na przykład podczas ucieczki w trakcie otwierania zamka, pozwala to graczom zachować orientację przestrzenną przy widocznym pasku.

Często zadawane pytania

Czy mogę uruchomić wiele pasków postępu jednocześnie?

Tak. Każdy Play() wywołanie zwraca ID i zarządza własnym stanem. Wiele pasków układa się pionowo nad graczem z zachowaniem odpowiednich odstępów. Jest to przydatne przy działaniach wieloetapowych, gdzie postęp równoległych zadań musi być widoczny jednocześnie, chociaż większość scenariuszy RP korzysta z jednego paska na raz.

Jak przypiąć pasek postępu do propa lub NPC zamiast gracza?

Przekaż target = {type = 'entity', id = entityNetId} pole w tabeli options. Pasek unosi się nad określonym entity, a nie nad graczem. Używaj tego do akcji naprawy, czynności medycznych na powalonych graczach lub w każdym przypadku, gdy uwaga akcji skupia się na zewnątrz.

Czy pasek może być wymuszony po stronie serwera jako niemożliwy do anulowania?

Tak. Ustaw canCancel = false podczas wywoływania Play(). Klawisz anulowania nie działa i nie jest odtwarzana żadna animacja anulowania. Jest to odpowiednie dla akcji wymuszanych przez serwer (animacje aresztowania, oskryptowane scenki przerywnikowe), w których przerwanie przez gracza zaburzyłoby płynność rozgrywki.

Czy to działa z animacjami ox_lib?

Tak. Agency-ProgressBar jest niezależny od animacji, animacje obsługujesz we własnym skrypcie równolegle z wywołaniem paska postępu. Pasek jest wyłącznie elementem UI. Możesz go łączyć z dowolną biblioteką animacji lub bezpośrednimi wywołaniami animacji FiveM.

Wymagania

• Serwer FiveM (dowolny framework lub standalone)
• konto cfx.re z ważną licencją Agency-ProgressBar
• Brak zależności od bazy danych
• Brak zależności od zewnętrznych zasobów

Praktyczne przykłady integracji

Oto typowe wzorce integracji Agency-ProgressBar z istniejącymi skryptami:

Otwieranie wytrychem: Zadzwoń Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) na początku próby użycia wytrychu. Połącz z równolegle uruchomioną minigrą lockpick. Jeśli minigra zakończy się niepowodzeniem, wywołaj Dismiss() ze zwróconym ID. Jeśli się powiedzie, pozwól paskowi zakończyć się naturalnie.

Leczenie medyczne: Użyj target = {type = 'entity', id = patientNetId} aby zakotwiczyć pasek nad pacjentem, a nie nad medykiem. Gracze obserwujący scenę widzą postęp w miejscu leczenia, a nie unoszący się nad głową medyka.

Zbieranie dowodów: Ustaw canCancel = false do oskryptowanego zbierania dowodów, którego nie powinno dać się przerwać (aby uniemożliwić graczom anulowanie w celu uniknięcia pozostawienia odcisków palców na miejscu zdarzenia). Pasek bez możliwości anulowania informuje gracza, że ta czynność jest obowiązkowa, a nie opcjonalna.

Akcje po stronie serwera: Uruchom pasek postępu u klienta, podczas gdy akcja po stronie serwera wykonuje się asynchronicznie. Gdy nadejdzie odpowiedź serwera, pozwól paskowi dokończyć działanie lub zamknij go wcześniej w zależności od wyniku po stronie serwera. Wizualny czas trwania powinien w przybliżeniu odpowiadać oczekiwanemu czasowi przetwarzania na serwerze.