Address clothing by collection and local index
The official collection-native manual documents these APIs for GTA V on the client. Store the ped model, collection name, component or prop slot, local drawable index and texture index rather than relying solely on a global drawable number.
Why global indexes change
The base-game collection comes first, followed by official DLC collections and then custom collections. A new official DLC can insert entries before custom clothing, shifting its global numbers. A local index counts from the start of its named collection, so that insertion does not shift the local index.
The base-game collection name is the empty string "". Other names come from the name attribute of CPedVariationInfo in the corresponding YMT. A resource folder name or a user-facing clothing label is not necessarily the collection name.
| Hypothetical collection | Local indexes | Global indexes before a new DLC |
|---|---|---|
Base game "" | 0–1 | 0–1 |
| Official DLC | 0–2 | 2–4 |
| Custom collection | 0–1 | 5–6 |
Adding two official entries before the custom collection changes its global indexes to 7–8, but its local indexes remain 0–1. This reduces title-update migration work; it does not guarantee that renamed, removed or incompatible clothing assets work forever.
Discover collections and convert existing records
| Native | Purpose |
|---|---|
GET_PED_COLLECTIONS_COUNT | Count collections available for the selected ped. |
GET_PED_COLLECTION_NAME | Resolve a collection by its enumerated index. |
GET_PED_COLLECTION_NAME_FROM_DRAWABLE | Resolve the collection containing a global component drawable. |
GET_PED_COLLECTION_LOCAL_INDEX_FROM_DRAWABLE | Convert that global component drawable into a collection-local index. |
GET_PED_COLLECTION_NAME_FROM_PROP | Resolve the collection containing a global prop drawable. |
GET_PED_COLLECTION_LOCAL_INDEX_FROM_PROP | Convert that global prop drawable into a collection-local index. |
GET_PED_DRAWABLE_GLOBAL_INDEX_FROM_COLLECTION | Convert a named collection and local component index back to a global number. |
GET_PED_PROP_GLOBAL_INDEX_FROM_COLLECTION | Convert a named collection and local prop index back to a global number. |
Run conversion while the old record’s ped model, clothing resources and game build are still known. A shifted global number alone cannot reconstruct which item the player originally selected. Back up persisted outfits, migrate once with a schema version and preserve an explicit fallback for an unavailable collection.
Component and prop operations
| Older global-index API | Collection-based API |
|---|---|
SET_PED_COMPONENT_VARIATION | SET_PED_COLLECTION_COMPONENT_VARIATION |
SET_PED_PROP_INDEX | SET_PED_COLLECTION_PROP_INDEX |
SET_PED_PRELOAD_VARIATION_DATA | SET_PED_COLLECTION_PRELOAD_VARIATION_DATA |
SET_PED_PRELOAD_PROP_DATA | SET_PED_COLLECTION_PRELOAD_PROP_DATA |
GET_NUMBER_OF_PED_DRAWABLE_VARIATIONS | GET_NUMBER_OF_PED_COLLECTION_DRAWABLE_VARIATIONS |
GET_NUMBER_OF_PED_PROP_DRAWABLE_VARIATIONS | GET_NUMBER_OF_PED_COLLECTION_PROP_DRAWABLE_VARIATIONS |
GET_NUMBER_OF_PED_TEXTURE_VARIATIONS | GET_NUMBER_OF_PED_COLLECTION_TEXTURE_VARIATIONS |
GET_NUMBER_OF_PED_PROP_TEXTURE_VARIATIONS | GET_NUMBER_OF_PED_COLLECTION_PROP_TEXTURE_VARIATIONS |
IS_PED_COMPONENT_VARIATION_VALID | IS_PED_COLLECTION_COMPONENT_VARIATION_VALID |
IS_PED_COMPONENT_VARIATION_GEN9_EXCLUSIVE | IS_PED_COLLECTION_COMPONENT_VARIATION_GEN9_EXCLUSIVE |
GET_PED_DRAWABLE_VARIATION | GET_PED_DRAWABLE_VARIATION_COLLECTION_LOCAL_INDEX and GET_PED_DRAWABLE_VARIATION_COLLECTION_NAME |
GET_PED_PROP_INDEX | GET_PED_PROP_COLLECTION_LOCAL_INDEX and GET_PED_PROP_COLLECTION_NAME |
Count textures for the chosen local drawable, not for a similarly numbered global drawable. Check Gen9-only content against the selected game track. Use the native reference for the complete signature of each named API; component slots and prop anchors are different arguments.
Inspect the current outfit without changing it
This client command reports the current pants slot and checks the round-trip conversion. It is a read-only diagnostic and does not assume a particular freemode ped or installed DLC:
RegisterCommand('docoutfit', function()
local ped = PlayerPedId()
if ped == 0 or not DoesEntityExist(ped) then return end
local component = 4
local collection = GetPedDrawableVariationCollectionName(ped, component)
local localIndex = GetPedDrawableVariationCollectionLocalIndex(ped, component)
local globalIndex = GetPedDrawableVariation(ped, component)
if type(collection) ~= 'string' or localIndex < 0 then
print('No usable collection mapping for this component.')
return
end
local converted = GetPedDrawableGlobalIndexFromCollection(ped, component, collection, localIndex)
print(('Collection %q, local %s, global %s, round-trip %s')
:format(collection, localIndex, globalIndex, converted == globalIndex))
end, false)To enumerate the catalog, iterate collection indexes from zero to GetPedCollectionsCount(ped) - 1, then inspect component slots 0–11 and the applicable prop anchors with the respective count functions. Zero counts and unavailable entries are valid results, not a reason to guess an index.
Apply a validated component
A client-side helper can reject out-of-range choices before calling the setter:
local function applyComponent(ped, component, collection, drawable, texture, palette)
if not DoesEntityExist(ped) then return false end
if not IsPedCollectionComponentVariationValid(ped, component, collection, drawable, texture) then
return false
end
SetPedCollectionComponentVariation(ped, component, collection, drawable, texture, palette)
return true
endThe helper assumes the caller already validated argument types, the slot range and the chosen palette. A real clothing service must also authorize paid or restricted items on the server. A successful setter call is not proof of persistence or ownership.
For props, use the collection prop setter and the prop drawable/texture counts. A sentinel for “no prop” is not an ordinary valid drawable; handle removal separately according to the prop API. Do not copy a female freemode example onto an unrelated ped and expect matching collections.
Test a title update
Record several existing outfits, migrate their global identifiers on the old build, then load the new build with the same owned clothing resources. Check names, local indexes, textures and visual results; test missing collections, invalid indexes and Gen9-exclusive variations. Compare the round trip only within the same build. Keep the old records until rollback has been tested. These native calls require a client; static documentation tests only verify the published contract inventory.