Skip to content

Load custom assets

Place custom GTA assets in the client files included by resources.pack.path. The client discovers them in the downloaded bundle and registers them while the game world loads. Metadata declarations in content.xml tell GTA how to load files such as vehicle definitions, handling data and archetypes.

With resources.pack.path = "client", a loose object pack can use this layout:

client/
├── scripts/
├── ui/
└── assets/
└── street_props/
├── content.xml
└── stream/
├── street_bin.ydr
├── street_bin.ytd
└── street_props.ytyp

Use the filenames from your exported asset pack. The assets and stream folder names are organizational. Discovery scans the whole resource bundle recursively.

Each non-empty top-level folder forms a resource root. A nested content.xml creates another root at its own folder. In this example, the declarations in assets/street_props/content.xml use assets/street_props/ as their root. Each file belongs to its nearest resource root.

Files directly in the bundle root are supported too. Keep each asset pack in its own folder so its metadata and files stay together.

For the example above, put this in assets/street_props/content.xml:

<?xml version="1.0" encoding="UTF-8"?>
<CDataFileMgr__ContentsOfDataFileXml>
<dataFiles>
<Item>
<filename>stream/street_props.ytyp</filename>
<fileType>DLC_ITYP_REQUEST</fileType>
</Item>
</dataFiles>
</CDataFileMgr__ContentsOfDataFileXml>

The .ydr model and .ytd texture dictionary are discovered automatically. DLC_ITYP_REQUEST loads the archetype definitions from the .ytyp file. Use the authored model name when creating an object in your scripts.

Each metadata entry needs a filename and fileType. Choose the type that matches the file’s contents:

Metadata fileType
Archetype definitions, including MLO definitions DLC_ITYP_REQUEST
Vehicle handling HANDLING_FILE
Vehicle definitions VEHICLE_METADATA_FILE
Ped definitions PED_METADATA_FILE
Clothing and prop shop definitions SHOP_PED_APPAREL_META_FILE

Use forward slashes and paths relative to the resource root. For example, stream/street_props.ytyp resolves inside assets/street_props/. Keep paths inside that root and preserve the spelling and case of the exported files.

content.xml is optional for a pack that only needs streaming registration. Add it when the pack requires metadata loading. Streaming files and .rpf archives are discovered automatically, without a separate file list.

For a larger pack, includedDataFiles can reference another XML file:

<CDataFileMgr__ContentsOfDataFileXml>
<includedDataFiles>
<Item>metadata/props.xml</Item>
</includedDataFiles>
</CDataFileMgr__ContentsOfDataFileXml>

Move the earlier declaration into metadata/props.xml, keeping the same XML structure. Paths inside it still resolve from the resource root. The example’s stream/street_props.ytyp stays unchanged.

Included files must remain inside the resource. Missing files and include cycles stop loading. Existing packs can also use includedXmlFiles, where each Item contains an embedded dataFiles array. Keep each declaration in one place to avoid loading the same metadata twice.

Most streaming assets use their filename as their name in GTA’s shared asset namespace. Two different folders containing street_bin.ydr can therefore conflict. Give custom models unique names and update their metadata references together. Preserve collection folders and prefixes supplied by clothing packs.

Resource roots and files are traversed in path order. Metadata declarations are prioritized so handling and vehicle layouts precede vehicle definitions, followed by car colours and vehicle variations. Other declarations retain their relative order. There is no configurable resource dependency graph.

Keep backups and unused packs outside the client source folder. Renaming a folder to disabled leaves its files eligible for packaging and discovery.

Package the files using the publishing workflow, then restart the server to select the release. For the first installation of an asset pack, restart GTA through the helper as well.

Check the client logs for metadata loading errors, then create or visit the asset in-game. A successful resource download verifies delivery. The game still needs valid asset data and all referenced dependencies to load it.

Log message or symptom Check
invalid content.xml at offset ... Fix the XML syntax at the reported location.
content.xml dataFiles Item ... has no filename or fileType Supply both fields for that metadata entry.
resource path escapes its root Keep the referenced file inside the resource and correct its relative path.
unsupported data file type Check the fileType name and whether the installed game build supports it.
failed to load data file Check the path, the file format and the dependencies supplied with the pack.
A different model or texture appears Check for duplicate asset names across loose files and archives.

Adding or removing native assets, changing content.xml or metadata, and changing maps or collision files require a GTA restart. Some replacements of existing models and textures can apply during reconnect when the game can release them. Follow the client’s restart message when one appears. See When to restart GTA.