The Complete GTA 5 & FiveM Developer Guide Vehicle_Names.Lua

Why FiveM shows NULL instead of your vehicle name, and how vehicle_names.lua fixes it: AddTextEntry, GXT2 lookup order, modShopLabel and slot names.

Mastering vehicle_names.lua: FiveM Custom Vehicle Labels & GXT2 Runtime Architecture

You add a car, it spawns, it drives — and the notification in the corner says NULL. Or a raw spawn code. Or a hash.

Nothing is broken. The engine looked for a display string, did not find one, and printed the fallback. vehicle_names.lua is the client script that registers those strings at runtime, so the lookup succeeds.

This guide covers the full resolution pipeline from gameName to GXT2 to AddTextEntry, how to label tuning parts and mod slots as well as vehicles, and the three mistakes that cause labels to disappear after a restart.

1. The Core Architecture of Vehicle Naming in RAGE & FiveM

When adding custom add-on vehicles to Grand Theft Auto V and FiveM, developers often encounter unlocalized string identifiers such as NULL, raw spawn codes, or hash values displaying in the bottom-right vehicle entry notification, mechanic tuning menus, and garage user interfaces.

In the base game engine, all user interface strings are compiled into binary localized lookup tables (.gxt2 files). Because compiling custom GXT2 files for every individual add-on pack is inefficient and hard to maintain across multiple resources, FiveM exposes client-side runtime text registration natives. The file vehicle_names.lua serves as the client-side localization script that binds internal RAGE text labels and model hashes to human-readable strings at runtime.

2. How the String Resolution Pipeline Works

When a player enters a vehicle or selects an aftermarket modification in a mod shop, the RAGE UI engine processes the text identifier through a specific resolution hierarchy:

• Step 1 (Metadata Extraction): The engine reads the <gameName> string from vehicles.meta or the <modShopLabel> string from carcols.meta.
• Step 2 (GXT Lookup): The engine checks the internal global text table for a matching GXT key entry.
• Step 3 (Native Lookup / Memory Cache): If the entry is missing from static game files, the engine searches the runtime text buffer populated via AddTextEntry or AddTextEntryByHash.
• Step 4 (Fallback Rendering): If no string matches the lookup key in memory, the engine returns a null pointer, rendering NULL or the raw untranslated label to the UI screen.

3. Implementing vehicle_names.lua: Code Structure

The runtime registration script executes entirely on the client side using the AddTextEntry native function (or hash-based variants) wrapped inside a thread execution container:

Key Function Signatures

• AddTextEntry(entryKey, displayText): Registers a direct string key to human-readable text. Case-insensitive in lookup, but standardized uppercase strings are best practice.
• AddTextEntryByHash(entryHash, displayText): Accepts a direct unsigned 32-bit joaat hash of the model or label (e.g., GetHashKey('TT_PURSUIT_GT')). Useful when mapping dynamic or procedural labels.

4. Metadata Dependency & Mapping Matrix

For labels to display accurately across all menus and UI overlays, the string parameters must align precisely across the XML metadata files:

5. Resource Manifest Configuration (fxmanifest.lua)

Because vehicle_names.lua is a client-side execution script rather than a raw data file, it must be mounted under the client_script or client_scripts directive:

6. Developer Troubleshooting & Common Pitfalls

• Vehicle Shows 'NULL' on Entry: Ensure the first parameter in AddTextEntry matches the <gameName> tag in vehicles.meta, NOT the <modelName> or folder name.
• Missing Tuning Part Names in Mechanic Shops: If custom mod parts appear blank or as hashes, confirm that every <modShopLabel> declared in carcols.meta has a corresponding AddTextEntry line registered in vehicle_names.lua.
• Labels Disappear After Resource Restart: Running restart [resource_name] on a live server executes the thread again immediately; ensure there are no syntax errors in the Lua file that would halt script execution upon startup.
• String Truncation: Keep display names concise. Standard RAGE notifications will truncate text that exceeds the UI box boundary.

SUPPORT & COMMUNITY CONTACT

Add taxis and medical response with the FiveM city fleet pack, or browse all lore-friendly FiveM cars.