Integracja CXG-GTFAT z innymi zasobami

Pliki bridge/*.lua są edytowalnymi punktami adaptacji uprawnień, trwałości, powiadomień, stanowisk i formatów wyglądu. Poprawki menu to ręczne zmiany przeznaczone dla konkretnych wersji; zasób nie modyfikuje innych zasobów podczas instalacji.

Menu wyglądu

Poprawki przygotowano dla tych repozytoriów i rewizji:

Folder integrations pakietu zawiera pliki illenium-appearance.patch, fivem-appearance.patch, qb-clothing.patch i skinchanger.patch. Nie są stosowane automatycznie. W deweloperskim checkoutcie menu sprawdź właściwą poprawkę przed jej zastosowaniem:

git apply --check /ruta/al/parche-correcto.patch
git apply /ruta/al/parche-correcto.patch

Jeśli sprawdzenie się nie powiedzie, przerwij i dostosuj zmianę do zainstalowanej wersji; nie wymuszaj poprawki. Forki i nowsze rewizje mogą się różnić. Poprawka fivem-appearance wymaga przebudowania pakietu komendą build:game zgodnie z instrukcją menu. Poprawki nie poświadczają wszystkich wersji ani nie zastępują testów na serwerze.

Podczas zapisu techniczny decal jest oczyszczany, aby menu nie zapisało go jako zwykłego wyboru gracza. Menu z własną tabelą wyglądu musi wywołać oczyszczanie w miejscu zapisu. Waga jest przechowywana oddzielnie od strojów.

Zapis własnego wyglądu

Kliencki export SanitizeAppearance zwraca kopię wyglądu. Obsługiwane formaty to components, qb i esx:

local appearanceCopy = exports['CXG_GTFAT']:SanitizeAppearance(
    ped,
    appearance,
    'components'
)

GuardarApariencia(appearanceCopy)

GuardarApariencia to przykładowe wywołanie; zastąp je funkcją zapisu menu. components akceptuje tablicę komponentów albo obiekt z właściwością components; każdy komponent używa component_id, drawable, texture i opcjonalnie palette. Format qb używa pola decals z item i texture, a esx używa decals_1 i decals_2. Export zwraca głęboką kopię, zachowuje pozostałe pola i nie zmienia tymczasowo peda. Jeśli adapter formatu zawiedzie albo format jest nieznany, zwraca niezmienioną kopię i zapisuje diagnostykę.

Rejestracja peda podglądu

Jeśli menu używa peda podglądu oddzielnego od postaci, zarejestruj podgląd aktywnej postaci. Wyrejestruj go przed usunięciem encji:

local previewPed = ObtenerPreviewActual()

if previewPed and DoesEntityExist(previewPed) then
    exports['CXG_GTFAT']:RegisterPreviewPed(previewPed)
end

-- Al cerrar o cancelar el menú, antes de eliminar el ped:
exports['CXG_GTFAT']:UnregisterPreviewPed(previewPed)
EliminarPreview(previewPed)

ObtenerPreviewActual i EliminarPreview to przykładowe wywołania; zastąp je funkcjami menu. Rejestruj tylko podgląd aktywnej postaci, nie pedy świata ani podglądy innych postaci. Alternatywnie ustaw Config.GetPreviewPed, aby zwracał bieżącego peda lub nil. RefreshAppearance(previewPed) żąda ponownej oceny już zarządzanego peda i samo nie włącza Fat.

Exporty zasobów serwerowych

Exporty serwerowe to uprzywilejowane API dla innych zasobów serwera. Nie przekazuj ich bezpośrednio z eventu wywoływalnego przez klienta.

local playerSource = source -- ID del jugador en el servidor
local kg, err = exports['CXG_GTFAT']:GetWeight(playerSource)
if kg == nil then
    print('No hay un peso confirmado:', err)
end

local appliedKg, setError = exports['CXG_GTFAT']:SetWeight(playerSource, 92.5)
if appliedKg == nil then
    print('No se pudo fijar el peso:', setError)
end

local addedKg, addError = exports['CXG_GTFAT']:AddWeight(playerSource, -2.0)
if addedKg == nil then
    print('No se pudo sumar peso:', addError)
end

local resetKg, resetError = exports['CXG_GTFAT']:ResetWeight(playerSource)
if resetKg == nil then
    print('No se pudo restablecer el peso:', resetError)
end

Argument source to ID gracza po stronie serwera, a nie wartość wysłana przez klienta. Wszystkie wartości są w kg. GetWeight zwraca wagę albo nil, error. SetWeight i AddWeight zwracają znormalizowaną zastosowaną wagę w kg albo nil, error; SetWeight odrzuca wartości poza zakresem i zaokrągla do najbliższego kroku, a remisy w górę. AddWeight dopuszcza ujemne przyrosty. ResetWeight zapisuje defaultKg i zwraca zastosowaną wagę w kg; nie usuwa zapisanej wartości.

Aby otworzyć UI gracza z innego zasobu serwerowego:

local playerSource = source -- ID del jugador en el servidor
local opened, err = exports['CXG_GTFAT']:OpenWeightUI(playerSource)
if not opened then
    print('No se pudo abrir la báscula:', err)
end

Jako drugi argument można opcjonalnie przekazać ID stanowiska: OpenWeightUI(source, 'gimnasio'). Bez stanowiska obowiązuje polityka dostępu komend, nawet jeśli rejestracja komend jest wyłączona. Wynik true potwierdza autoryzację i wysłanie żądania otwarcia, ale nie potwierdza, że klient wyrenderował interfejs.

Exporty serwera

RefreshCharacter jest opcjonalny dla integracji wielopostaciowych; wywołaj go, gdy framework udostępni właściwą tożsamość. Zasób nie łączy się automatycznie z Qbox.

Błędy mogą obejmować not_ready, invalid_source, player_unavailable, character_unavailable, invalid_weight, out_of_range, permission_denied, context_denied, busy, storage_failed, storage_timeout, storage_unknown lub not_synced. Nie traktuj błędu zapisu jako potwierdzonej wagi i nie ponawiaj automatycznie zapisu z wynikiem storage_timeout lub storage_unknown.

Exporty klienta

local kg, err = exports['CXG_GTFAT']:GetWeight()
local settings = exports['CXG_GTFAT']:GetWeightSettings()
local isOpen = exports['CXG_GTFAT']:IsWeightUIOpen()
local closed = exports['CXG_GTFAT']:CloseWeightUI()
local status, statusError = exports['CXG_GTFAT']:GetFatStatus()
local reserved, reservedError = exports['CXG_GTFAT']:GetReservedDecals(PlayerPedId())

GetWeight zwraca nil, 'not_synced' do czasu otrzymania wartości potwierdzonej przez serwer. GetFatStatus(ped?) i GetReservedDecals(ped) udostępniają tylko informacje do odczytu; nie potwierdzają wyrenderowania geometrii. GetReservedDecals może służyć do ukrycia zarezerwowanych decalów w menu. RefreshAppearance(previewPed?) odświeża wyłącznie zarządzany wygląd gracza lub zarejestrowany podgląd.

RegisterPreviewPed(ped) i UnregisterPreviewPed(ped) pozwalają przekazać selektorowi encję podglądu. Peda może wyrejestrować tylko zasób, który go zarejestrował. Zarejestrowane podglądy są czyszczone po zatrzymaniu zasobu właściciela.

SanitizeAppearance(ped, appearance, format) zwraca kopię wyglądu; nil, error nie jest wskaźnikiem błędu. RegisterPreviewPed i UnregisterPreviewPed zwracają true po powodzeniu i false, jeśli nie można zarejestrować lub usunąć peda.

Edytowalne bridge

Domyślnie CanAccess rozpoznaje tylko ace i everyone. Dla jobs, groups lub custom zaimplementuj sprawdzanie przez właściwe API serwera i zwracaj dokładnie true po przyznaniu dostępu. Wyjątki i pozostałe wartości odmawiają dostępu. Pola polityki job, group i custom są interpretowane przez adapter.

Niestandardowy dostawca zapisu implementuje sygnatury LoadWeight(characterId, context, done), SaveWeight(characterId, kg, context, done) oraz, jeśli trzeba uzgadniać niepewne zapisy, ReconcileWeight(characterId, context, done). Odczyt wywołuje done(true, kg) (użyj kg = nil, gdy nie ma zapisanej wartości) albo done(false, 'storage_failed'). Zapis wywołuje done(true) dopiero po potwierdzeniu albo done(false, 'storage_failed'). Uzgodnienie wywołuje done(true, true) tylko wtedy, gdy wcześniejszy zapis nie może zakończyć się później; w przeciwnym razie done(false, 'storage_unknown'). Dla rzeczywiście asynchronicznych zapisów ustaw AsyncStorage = true; callback musi zakończyć się w kontekście FiveM obsługującym oczekiwanie. API czeka do 10 sekund przed zgłoszeniem limitu czasu. Po storage_timeout nie ponawiaj automatycznie; najpierw uzgodnij zapis przez dostawcę gwarantującego, że wcześniejszy zapis nie zostanie później zastosowany. Nie deklaruj trybu asynchronicznego, jeśli dostawca zwraca sterowanie przed rozpoczęciem lub zakolejkowaniem zapisu.

Hooki OnWeightChanged, OnCharacterChanged, OnUIOpened, OnUIClosed i Log służą do obserwacji lub rejestrowania zmian. Hooki nie przyznają dostępu ani nie cofają potwierdzonych operacji.

Kontrola przed włączeniem

Poprawki i adaptery należy zweryfikować z rzeczywistymi wersjami i zasobami serwera. Przed udostępnieniem integracji graczom:

1. Powtórz zmianę Normal/Fat na męskiej i żeńskiej postaci freemode.
2. Przy aktywnym Fat zapisz i ponownie wczytaj wygląd oraz strój. Potwierdź, że techniczny decal nie zapisuje się jako zwykły wybór, a waga pozostaje niezależna od stroju.
3. Przy włączonej trwałości postaci uruchom ponownie zasób i połącz się ponownie. Potwierdź, że ta sama postać odzyskuje wagę, a inna jej nie dziedziczy.
4. Otwórz menu wyglądu z zarejestrowanym podglądem i sprawdź, czy pokazuje bieżącą postać. Przy anulowaniu lub zamykaniu menu wyrejestruj go przed usunięciem encji.

Wykonanie tych kroków na serwerze jest konieczne do sprawdzenia konkretnego zestawu menu, frameworka i ubrań. Sama obecność poprawki nie potwierdza tych wyników.