Working with Drawable Components and Props Using Collections

Inside GTAV, Ped drawable components and props are stored in named groups called collections. Previously, collections were unavailable for FiveM users and drawable components/props were indexed through a global index that changes on every Title Update (TU).

The new collection-based natives keep indexes stable across TUs.

How Drawable Indexing Works

Think of collections as buckets placed one after another. Each collection is named and contains multiple drawables.

Global index: Index of drawable starting from the beginning
Local index: Index starting from the beginning of each collection

Example:

Collection	`""`	`female_freemode_beach`	`custom_collection`
Local indexes	0, 1	0, 1, 2, 3	0, 1, 2
Global indexes	0, 1	2, 3, 4, 5	6, 7, 8

When a TU adds new DLC collections, custom collections shift. Collection-based indexes remain stable.

New Natives

General Info

GET_PED_COLLECTIONS_COUNT - Get total number of collections available for Ped
GET_PED_COLLECTION_NAME - Get collection name by collection number

Conversion Between Global and Local Indexing

GET_PED_COLLECTION_NAME_FROM_DRAWABLE / GET_PED_COLLECTION_LOCAL_INDEX_FROM_DRAWABLE - Get collection name and local index from global drawable index
GET_PED_COLLECTION_NAME_FROM_PROP / GET_PED_COLLECTION_LOCAL_INDEX_FROM_PROP - Get collection name and local index from global prop index
GET_PED_DRAWABLE_GLOBAL_INDEX_FROM_COLLECTION - Get global drawable index from collection name and local index
GET_PED_PROP_GLOBAL_INDEX_FROM_COLLECTION - Get global prop index from collection name and local index

Collection-Based Alternatives to Existing Natives

Old (global)	New (collection-based)
`SET_PED_COMPONENT_VARIATION`	`SET_PED_COLLECTION_COMPONENT_VARIATION`
`SET_PED_PROP_INDEX`	`SET_PED_COLLECTION_PROP_INDEX`
`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`

Example: List All Collections


function printFullCollectionsInfo(ped)
    local collectionsCount = GetPedCollectionsCount(ped)
    print(string.format("Found %d collections", collectionsCount))
    for i = 0, collectionsCount - 1 do
        local collectionName = GetPedCollectionName(ped, i)
        print(string.format("Collection %d: %s", i, collectionName))
    end
end
 
RegisterCommand('PrintCollections', function(source)
    printFullCollectionsInfo(PlayerPedId())
end, true)

Example: Set Ped Look Using Collections


function setLook(ped)
    -- Head from base game collection (empty string), local index 27
    SetPedCollectionComponentVariation(ped, 0, '', 27, 0, 0)
 
    -- Pants from mpHeist DLC collection, local index 9, texture 3
    SetPedCollectionComponentVariation(ped, 4, 'female_heist', 9, 3, 0)
 
    -- Hat from mpBiker DLC collection
    SetPedCollectionPropIndex(ped, 0, 'mp_f_bikerdlc_01', 0, 0, false)
end
 
RegisterCommand('SetLook', function(source)
    setLook(PlayerPedId())
end, true)

Benefits of Collection-Based Natives

Stable across TUs: Global indexes shift when Rockstar adds DLC collections
Future-proof: Server won’t break on game updates
Easier maintenance: No need to update custom component indexes after updates