Skip to content

Custom vehicles

A custom vehicle needs its model, textures and vehicle definition, together with any handling, tuning or other dependencies supplied with the pack.

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

client/
└── assets/
└── harbor_gt/
├── content.xml
├── stream/
│ ├── harbor_gt.yft
│ ├── harbor_gt_hi.yft
│ └── harbor_gt.ytd
└── data/
├── vehicles.meta
├── handling.meta
├── carcols.meta
└── carvariations.meta

Use the filenames and complete asset set supplied with your vehicle. Include the high-detail model and additional tuning models when the pack provides them. The content.xml in this folder makes it a separate resource root, so metadata paths resolve from assets/harbor_gt/.

If the vehicle comes as an RPF, follow RPF archives for its placement and metadata declarations.

For the loose files above, use this content.xml:

<?xml version="1.0" encoding="UTF-8"?>
<CDataFileMgr__ContentsOfDataFileXml>
<dataFiles>
<Item>
<filename>data/handling.meta</filename>
<fileType>HANDLING_FILE</fileType>
</Item>
<Item>
<filename>data/vehicles.meta</filename>
<fileType>VEHICLE_METADATA_FILE</fileType>
</Item>
<Item>
<filename>data/carcols.meta</filename>
<fileType>CARCOLS_FILE</fileType>
</Item>
<Item>
<filename>data/carvariations.meta</filename>
<fileType>VEHICLE_VARIATION_FILE</fileType>
</Item>
</dataFiles>
</CDataFileMgr__ContentsOfDataFileXml>

Declare only files included in the pack. Some vehicles reuse existing handling or have no custom tuning definitions. Keep the corresponding references supplied by the author and omit declarations for files that are absent.

If the pack includes custom vehicle layouts, add their metadata file with fileType set to VEHICLE_LAYOUTS_FILE. The loader processes handling and layouts before vehicle definitions, followed by car colours and vehicle variations. Models and textures are discovered automatically.

Use the vehicle’s modelName from vehicles.meta as its spawn name. In this example it is harbor_gt, matching the base model harbor_gt.yft.

Check these references when adapting a pack:

Reference What must match
Model name The exported vehicle model and its entries in vehicle and variation metadata.
Texture dictionary The texture dictionary referenced by the vehicle definition. Preserve any shared texture dependencies.
Handling ID An existing handling definition or the matching entry in the pack’s handling.meta.
Layout An available GTA layout or a layout registered by the pack.
Mod kits and tuning parts The kit references in carvariations.meta, definitions in carcols.meta and supplied tuning models.
Audio The sound definitions and banks required by the vehicle.

Choose unique names for custom models. Renaming a folder or archive leaves the asset names unchanged. When renaming a vehicle, update its asset filenames and metadata references together. See Names and loading order.

Publish the updated resources, restart the server to select the release, then restart GTA through the helper for the new asset set.

This server example creates the vehicle near the beach. Use your pack’s modelName and a position suitable for testing:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
const vehicle = new revo.Vehicle(
'harbor_gt',
{ x: -1220, y: -1765, z: 3.9 },
Math.PI / 2,
);
vehicle.numberPlate = 'CUSTOM';
vehicle.engineRunning = false;

Run the example from a configured server entry point. Clients load the model when the vehicle enters their stream. The constructor returns immediately, so check the result in-game after loading. The example uses dimension 0.

Check the body and textures, enter the vehicle, drive it and try any supplied extras, liveries or tuning parts. With two clients, check the vehicle from both views. Leave its streaming range and return to check that it loads again. See Creating and configuring vehicles and Vehicle customization for the scripting APIs.

Check the client logs for failed to load data file and unsupported data file type messages.

Symptom Check
The vehicle never appears Verify the spawn name, model files and VEHICLE_METADATA_FILE declaration. Confirm the player is near the spawn position and in the same dimension.
Textures are missing or incorrect Check the texture dictionary reference, supplied YTD files and duplicate asset names.
Handling is incorrect Check the handling ID and whether the required handling metadata loaded.
Entry or seating behaves incorrectly Check the vehicle layout and the model’s seat and door data.
Tuning parts are missing or incorrect Check the mod kit references, tuning models and conflicts with other packs.
Custom engine audio is missing Check the referenced audio dependencies and their metadata declarations.

Changes to vehicle metadata or the asset set require a GTA restart. Some replacements of existing models and textures can apply on reconnect. Follow the restart rules when publishing updates.