Integrate CXG-GTFAT with other resources

The bridge/*.lua files are editable adaptation points for permissions, persistence, notifications, stations, and appearance formats. Menu patches are manual changes for specific versions; the resource does not modify other resources when installed.

Appearance menus

Patches are prepared for these repositories and revisions:

The package's integrations folder contains illenium-appearance.patch, fivem-appearance.patch, qb-clothing.patch, and skinchanger.patch. They are not applied automatically. In a development checkout of the menu, check the matching patch before applying it:

git apply --check /path/to/the-correct-patch.patch
git apply /path/to/the-correct-patch.patch

If the check fails, stop and adapt the change to the installed version; do not force the patch. Forks and newer revisions may differ. The fivem-appearance patch requires rebuilding the bundle with that menu's build:game workflow. These patches do not certify every version or replace testing on your server.

Saving sanitizes the technical decal so a menu does not persist it as the player's ordinary selection. Menus with their own appearance table must call the sanitizer at their save point. Weight is stored separately from outfits.

Save a custom appearance

The client export SanitizeAppearance returns a copy of the appearance. Supported formats are components, qb, and esx:

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

GuardarApariencia(appearanceCopy)

GuardarApariencia is an example call; replace it with your menu's save function. components accepts an array of components or an object with a components property; each component uses component_id, drawable, texture, and optionally palette. The qb format uses the decals field with item and texture; esx uses decals_1 and decals_2. The export returns a deep copy and preserves other fields without temporarily changing the ped. If the format adapter fails or the format is unrecognized, it returns the unchanged copy and logs a diagnostic.

Register a preview ped

If the menu uses a preview ped separate from the character, register the preview for the active character. Unregister it before deleting the entity:

local previewPed = ObtenerPreviewActual()

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

-- When the menu closes or is cancelled, before deleting the ped:
exports['CXG_GTFAT']:UnregisterPreviewPed(previewPed)
EliminarPreview(previewPed)

ObtenerPreviewActual and EliminarPreview are example calls; replace them with your menu's functions. Register only the active character's preview, not world peds or previews for other characters. Alternatively, set Config.GetPreviewPed to return the current ped or nil. RefreshAppearance(previewPed) requests a refresh of a ped that is already managed; it does not activate Fat by itself.

Server-resource exports

Server exports are privileged APIs for other server resources. Do not forward them directly from an event that a client can invoke.

local playerSource = source -- Player ID on the server
local kg, err = exports['CXG_GTFAT']:GetWeight(playerSource)
if kg == nil then
    print('No confirmed weight:', err)
end

local appliedKg, setError = exports['CXG_GTFAT']:SetWeight(playerSource, 92.5)
if appliedKg == nil then
    print('Could not set weight:', setError)
end

local addedKg, addError = exports['CXG_GTFAT']:AddWeight(playerSource, -2.0)
if addedKg == nil then
    print('Could not add weight:', addError)
end

local resetKg, resetError = exports['CXG_GTFAT']:ResetWeight(playerSource)
if resetKg == nil then
    print('Could not reset weight:', resetError)
end

The source argument is the server player ID, not a value sent by the client. All values are in kg. GetWeight returns the weight or nil, error. SetWeight and AddWeight return the normalized applied weight in kg or nil, error; SetWeight rejects out-of-range values and rounds to the nearest step, with ties rounded up. AddWeight accepts negative increments. ResetWeight writes defaultKg and also returns the applied weight in kg; it does not delete the stored value.

To open the UI for a player from another server resource:

local playerSource = source -- Player ID on the server
local opened, err = exports['CXG_GTFAT']:OpenWeightUI(playerSource)
if not opened then
    print('Could not open the scale:', err)
end

An optional station ID can be passed as the second argument: OpenWeightUI(source, 'gym'). Without a station, it applies the command access policy even if command registration is disabled. A true result confirms authorization and that the open request was sent; it does not confirm that the client has rendered the interface.

Server exports

RefreshCharacter is optional for multicharacter integrations; call it after the framework has made the intended identity available. The resource does not connect to Qbox automatically.

Errors may include not_ready, invalid_source, player_unavailable, character_unavailable, invalid_weight, out_of_range, permission_denied, context_denied, busy, storage_failed, storage_timeout, storage_unknown, or not_synced. Do not treat a storage error as confirmed weight or automatically retry a write with a storage_timeout or storage_unknown result.

Client exports

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 returns nil, 'not_synced' until a server-confirmed value arrives. GetFatStatus(ped?) and GetReservedDecals(ped) provide read-only information; they do not prove that the geometry rendered. GetReservedDecals can be used to hide reserved decals in menus. RefreshAppearance(previewPed?) only refreshes the managed player appearance or a registered preview.

RegisterPreviewPed(ped) and UnregisterPreviewPed(ped) let a menu hand its preview entity to the selector. Only the resource that registered the ped can unregister it. Registered previews are cleaned up when their owning resource stops.

SanitizeAppearance(ped, appearance, format) returns a copy of the appearance; nil, error is not its failure indicator. RegisterPreviewPed and UnregisterPreviewPed return true when the operation succeeds and false when the ped cannot be registered or removed.

Editable bridges

By default, CanAccess recognizes only ace and everyone. For jobs, groups, or custom access, implement the check with the server's actual API and return exactly true when access is granted. Exceptions and other values deny access. Job, group, and custom policy fields are data interpreted by your adapter.

A custom storage provider implements the signatures LoadWeight(characterId, context, done), SaveWeight(characterId, kg, context, done), and, if it needs to reconcile uncertain writes, ReconcileWeight(characterId, context, done). Loading calls done(true, kg) (use kg = nil when no value exists) or done(false, 'storage_failed'). Saving calls done(true) only after confirmation, or done(false, 'storage_failed'). Reconciliation calls done(true, true) only when no earlier write can complete later; if that cannot be guaranteed, call done(false, 'storage_unknown'). For genuinely asynchronous saves, set AsyncStorage = true; the callback must complete in a FiveM context that supports waiting. The API allows up to 10 seconds before reporting a timeout. Do not automatically retry after storage_timeout; first reconcile with a provider that guarantees an earlier write will not apply later. Do not mark a provider asynchronous if it returns before starting or ordering the write.

The OnWeightChanged, OnCharacterChanged, OnUIOpened, OnUIClosed, and Log hooks are for observing or logging changes. Hooks do not grant access or undo confirmed operations.

Checks before enabling it

Patches and adapters need validation against the actual server resources and versions. Before enabling the integration for players:

1. Repeat the Normal/Fat change with male and female freemode characters.
2. With Fat active, save and reload the appearance and outfit. Confirm that the technical decal is not saved as an ordinary selection and that weight remains separate from the outfit.
3. With per-character persistence enabled, restart the resource and reconnect. Confirm the same character recovers its weight and another character does not inherit it.
4. Open the appearance menu with a registered preview and confirm it represents the current character. When cancelling or closing the menu, unregister it before deleting the entity.

Completing these steps on your server is necessary to validate your specific combination of menu, framework, and clothing. The existence of a patch alone does not certify those results.