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.
Organize an asset pack
Section titled “Organize an asset pack”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.ytypUse 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.
Register metadata
Section titled “Register metadata”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.
Split declarations across XML files
Section titled “Split declarations across XML files”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.
Names and loading order
Section titled “Names and loading order”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.
Publish and check the result
Section titled “Publish and check the result”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.