[Feature Request] Authoritative replacement of the base default.ymt data manifest and selective remapping of its data-file entries

[RED-ITA]

Summary

FiveM currently exposes mechanisms for:

• adding data files through the extra-content system (data_file);
• adding initialization manifests (init_meta);
• inserting manifests before or after the primary level meta (before_level_meta / after_level_meta);
• replacing the primary level meta (replace_level_meta).

It does not expose a mechanism that authoritatively replaces the base default.ymt manifest before the game consumes it through dataFileMgr__loadDefDat, nor a mechanism that remaps individual base data-file registrations contained in that manifest before their respective managers are initialized.

I am requesting one or both of the following:

Minimum viable API

files {
    'default.ymt'
}

replace_default_meta 'default.ymt'

This would make the specified resource file replace the base default manifest for the current game session, analogously to how replace_level_meta replaces the primary level meta.

Preferred safer API

files {
    'vehiclemodelsets.meta'
}

replace_default_data_file
    'common:/data/ai/vehiclemodelsets.meta'
    'vehiclemodelsets.meta'

This would preserve the Rockstar default.ymt itself, but replace the filename of one matching base CDataFileMgr__DataFile entry before that entry is registered and loaded. Its original fileType, flags, registerAs, contents, and installPartition would remain unchanged.

The selective API would be safer and more build-resilient for ordinary resources. A full replace_default_meta would remain useful for total conversions and advanced engine-level modifications.

---

Motivation

A number of base data files are registered by default.ymt, before the primary gta5.meta and outside the normal resource data_file extra-content path.

In the extracted default.ymt used for this reproduction, the root is:

<CDataFileMgr__ContentsOfDataFileXml>

and the manifest directly registers, among many other files:

<Item>
  <filename>common:/data/ai/vehiclemodelsets.meta</filename>
  <fileType>AMBIENT_VEHICLE_MODEL_SET_FILE</fileType>
  <registerAs />
  <locked value="false" />
  <loadCompletely value="false" />
  <overlay value="false" />
  <patchFile value="false" />
  <disabled value="false" />
  <persistent value="false" />
  <enforceLsnSorting value="true" />
  <contents />
  <installPartition>PARTITION_NONE</installPartition>
</Item>

The same manifest also registers base handling, dispatch, ambient ped/prop model sets, weapon metadata, ped/task data, action tables, UI/controller metadata, RPFs, and other engine data.

The attached extracted manifest contains:

• 80 CDataFileMgr__DataFile entries;
• 67 distinct fileType values.

This request is therefore not specific to one file. vehiclemodelsets.meta is only a concrete, reproducible example of a broader missing capability: authoritative per-session replacement of base data registrations that are currently loaded from default.ymt.

---

Concrete reproduction: vehiclemodelsets.meta

Goal

Override the vanilla ambient vehicle model set:

LOWRIDERS_MODDED_BALLAS

which is referenced by verified Ballas vehicle scenario points.

Test modification

The custom vehiclemodelsets.meta was changed so that LOWRIDERS_MODDED_BALLAS contained only one vehicle model:

BUCCANEER

The entry was also given the Vagos/yellow body-colour configuration, making both model selection and variation visually unambiguous.

The test intentionally removed all other models from the Ballas set. Therefore, a TORNADO cannot be selected from the custom definition under any interpretation.

Test A: normal data_file

Standalone resource:

fx_version 'cerulean'
game 'gta5'

files {
    'vehiclemodelsets.meta'
}

data_file 'AMBIENT_VEHICLE_MODEL_SET_FILE' 'vehiclemodelsets.meta'

Conditions:

• no other resource mounted an AMBIENT_VEHICLE_MODEL_SET_FILE;
• the client and server were fully restarted;
• the scenario point was allowed to generate from a clean state;
• the scenario point was verified to reference LOWRIDERS_MODDED_BALLAS.

Expected:

Only a yellow Buccaneer can spawn.

Actual:

A purple Tornado from the vanilla Ballas model set spawned.

This is stronger than a colour-only test: the spawned model does not exist anywhere in the custom set.

Test B: primary level meta

The normal data_file declaration was removed. A custom gta5.meta, already loaded through:

replace_level_meta 'gta5'

was given this entry:

<Item>
  <filename>resources:/RED_VehicleModelSets/vehiclemodelsets.meta</filename>
  <fileType>AMBIENT_VEHICLE_MODEL_SET_FILE</fileType>
</Item>

After another full cold start, the result was unchanged: the scenario still resolved the vanilla Ballas set and spawned a purple Tornado.

Conclusion from the reproduction

The custom file can be exposed to FiveM, but neither the normal extra-content route nor an additional registration in the primary level meta makes it the authoritative base definition used by the scenario.

The original registration is made earlier by default.ymt:

default.ymt
  -> common:/data/ai/vehiclemodelsets.meta
  -> AMBIENT_VEHICLE_MODEL_SET_FILE
  -> vanilla ambient model sets initialized

Later additive registrations do not reliably replace the already-established base data.

---

Why the current APIs do not solve this

Current resource processing in ResourcesTest.cpp maps the relevant manifest entries as follows:

init_meta
    -> streaming::AddDefMetaToLoadList(...)

before_level_meta / after_level_meta
    -> streaming::AddMetaToLoadList(...)

replace_level_meta
    -> streaming::SetNextLevelPath(...)

data_file
    -> streaming::AddDataFileToLoadList(...)

These are distinct paths with distinct semantics.

replace_level_meta has a true replacement path because SetNextLevelPath changes which primary level meta is loaded.

By contrast, the current default-data hook in LoadStreamingFile.cpp effectively does:

static void LoadDefDats(void* dataFileMgr, const char* name, bool enabled)
{
    g_dataFileMgr = dataFileMgr;

    trace("Loading content XML: %s\n", name);

    dataFileMgr__loadDefDat(dataFileMgr, name, enabled);
}

The incoming default manifest path is always forwarded unchanged to the original dataFileMgr__loadDefDat.

There is currently no equivalent of:

SetNextDefaultMetaPath(...)

and no pre-registration map capable of replacing a matching CDataFileMgr__DataFile::filename inside the base default manifest.

init_meta is additive. It queues another manifest through AddDefMetaToLoadList; it does not replace the path passed to the original default loader.

data_file is also additive and routes the file through the game’s extra-content/DLC mounter system. Existing Cfx issue discussion already notes that some Rockstar DLC loaders do not support overwriting existing data, even where they support adding new data. This is particularly relevant to base-game definitions and ambient model sets.

Related existing reports:

• citizenfx/fivem#1245 — base vehicle metadata replacement limitations; the discussion also explicitly mentions partial/incorrect vehiclemodelsets.meta behavior.
• citizenfx/fivem#3473 — vehiclemodelsets.meta not being read correctly and causing client crashes in custom scenario use cases.

---

Requested behaviour

Option 1: full default-manifest replacement

Proposed resource manifest syntax:

fx_version 'cerulean'
game 'gta5'

files {
    'default.ymt',
    'vehiclemodelsets.meta'
}

replace_default_meta 'default.ymt'

Required semantics:

1. The declared file is used instead of the original base default manifest for that game initialization.
2. The original default manifest must not be processed first.
3. The replacement is session-scoped and associated with the declaring resource.
4. Only one full default-meta replacement may be active.
5. A second resource attempting to declare one must produce a deterministic fatal error naming both resources.
6. The path is exact; no implicit .meta suffix should be added because the original asset is a .ymt/PSO manifest.
7. The replacement must be known before the first relevant dataFileMgr__loadDefDat call.
8. If the declaration becomes available too late, FiveM must reject it with a clear “requires full game reload” error rather than silently loading it additively.
9. restart <resource> after initialization must not attempt unsafe live replacement. It should either:
   • mark the change as pending until the next full game reload; or
   • reject the restart with an explicit diagnostic.
10. On session shutdown or server change, the override state must be cleared and the next session must rebuild it from active resource metadata.

Option 2: selective base data-file replacement

Preferred resource manifest syntax:

fx_version 'cerulean'
game 'gta5'

files {
    'vehiclemodelsets.meta'
}

replace_default_data_file
    'common:/data/ai/vehiclemodelsets.meta'
    'vehiclemodelsets.meta'

Required semantics:

1. Match the original entry by its canonical, normalized VFS path.
2. Replace only the entry’s filename.
3. Preserve:
   • fileType;
   • registerAs;
   • locked;
   • loadCompletely;
   • overlay;
   • patchFile;
   • disabled;
   • persistent;
   • enforceLsnSorting;
   • contents;
   • installPartition.
4. Perform the replacement before the corresponding base manager/mounter consumes the entry.
5. Allow multiple resources to replace different original paths.
6. Reject conflicting claims for the same original path with a deterministic error naming both resources.
7. If the original path is absent in the active game build, produce a clear warning or error.
8. Include the active game build and replacement mapping in relevant cache/session identity so mappings cannot leak across builds or servers.
9. Do not silently fall back to the original file if the replacement is declared but missing or invalid.

This selective API would avoid requiring server developers to redistribute and maintain a full build-specific default.ymt, while still using the authoritative base-loader phase.

---

Suggested implementation direction

The exact integration point depends on when resource metadata is available relative to the first default-manifest load, but the required invariant is simple:

replacement declaration resolved
    BEFORE
original default.ymt is passed to dataFileMgr__loadDefDat

Full replacement: illustrative implementation

In the resource bridge:

namespace streaming
{
    void SetNextDefaultMetaPath(
        const std::string& path,
        const std::string& ownerResource
    );
}

Resource manifest handling:

for (auto& meta : metaData->GetEntries("replace_default_meta"))
{
    streaming::SetNextDefaultMetaPath(
        resourceRoot + meta.second,
        resource->GetName()
    );
}

State:

struct DefaultMetaOverride
{
    std::string path;
    std::string ownerResource;
};

static std::optional<DefaultMetaOverride> g_defaultMetaOverride;
static bool g_defaultMetaConsumed = false;

Default loader hook:

static void LoadDefDats(
    void* dataFileMgr,
    const char* originalName,
    bool enabled
)
{
    g_dataFileMgr = dataFileMgr;

    const char* effectiveName = originalName;

    if (g_defaultMetaOverride)
    {
        if (!ValidateDefaultMetaPath(g_defaultMetaOverride->path))
        {
            GlobalError(
                "Invalid replace_default_meta path '%s' declared by resource '%s'",
                g_defaultMetaOverride->path,
                g_defaultMetaOverride->ownerResource
            );
            return;
        }

        effectiveName = g_defaultMetaOverride->path.c_str();
    }

    g_defaultMetaConsumed = true;

    trace(
        "Loading default content XML: %s%s\n",
        effectiveName,
        g_defaultMetaOverride ? " (resource override)" : ""
    );

    dataFileMgr__loadDefDat(
        dataFileMgr,
        effectiveName,
        enabled
    );
}

This code is only illustrative. The important part is that the original call receives the replacement path instead of the Rockstar path.

Timing caveat

If resource OnStart metadata is not available before the current LoadDefDats call, simply adding SetNextDefaultMetaPath to the existing OnStart loop would be insufficient.

In that case, FiveM would need one of the following:

• an earlier metadata collection phase for initialization-affecting manifest entries;
• deferred execution of the default-manifest load until resource metadata has been resolved;
• a controlled full game reload once the server’s initialization manifest is known.

A late additive call must not be presented as a replacement.

Selective replacement: implementation alternatives

A selective API could be implemented in at least two ways.

A. Rewrite entries before registration

Maintain a session-scoped map:

struct DefaultDataFileOverride
{
    std::string originalPath;
    std::string replacementPath;
    std::string ownerResource;
};

static std::unordered_map<
    std::string,
    DefaultDataFileOverride
> g_defaultDataFileOverrides;

During parsing/insertion of each CDataFileMgr__DataFile from the base default manifest:

auto normalized = NormalizeDataFilePath(entry->filename);

if (auto it = g_defaultDataFileOverrides.find(normalized);
    it != g_defaultDataFileOverrides.end())
{
    entry->filename = it->second.replacementPath;
}

The actual structure owns fixed-size buffers and engine-managed strings, so the production implementation would need to respect the correct ownership and lifetime rules rather than assigning a temporary std::string.

B. Exact-path VFS redirection

Install a session-scoped exact-path redirect before the default manifest is consumed:

common:/data/ai/vehiclemodelsets.meta
    ->
resources:/RED_VehicleModelSets/vehiclemodelsets.meta

This approach must:

• redirect both Open and GetAttributes;
• normalize case and separators consistently;
• avoid recursive redirects;
• be torn down on session reset;
• include the replacement in cache identity;
• remain limited to explicitly declared exact paths.

The entry-rewrite approach is semantically cleaner because it preserves the original CDataFileMgr flags while changing only the source file.

---

Lifecycle and safety requirements

This feature touches managers that may retain pointers to parsed data for the lifetime of the game session. It should therefore be initialization-only.

No live unload/reload

FiveM should not attempt to unload and reinsert arbitrary base metadata when the owning resource stops. Doing so could create:

• dangling pointers;
• stale hash-table entries;
• double frees;
• manager-specific corruption;
• cross-resource state inconsistencies.

After the default manifest is consumed:

resource stop/restart
    -> replacement remains fixed for current initialized session
    -> change applies only after a full reload

Server switching

A client connecting to server A and then server B must not retain A’s base-data override.

The replacement state should be cleared as part of the same full game/session reset boundary used for other initialization-sensitive data. If the engine cannot safely reconstruct the relevant managers in place, joining a server with a different default-meta fingerprint should trigger a full game reload.

Conflict handling

Full replacement:

one active owner only

Selective replacements:

multiple owners allowed only for distinct original paths

Any conflict should be a hard, deterministic error rather than load-order-dependent “last resource wins” behaviour.

Build compatibility

A full default.ymt is inherently game-build-sensitive. Recommended protections:

• include the active game build in diagnostics;
• optionally allow a resource to declare a required /gameBuild: dependency;
• reject a selective override if the original path is absent;
• never silently reuse a cached manifest from another build;
• identify Legacy and Enhanced behaviour separately if their bootstrap manifests differ.

Invalid replacement data

Malformed base data can crash the game before normal script diagnostics are available. The loader should report, where technically possible:

• owner resource;
• replacement path;
• original path;
• fileType;
• active game build;
• whether failure occurred while parsing the default manifest or while invoking the target data-file mounter.

A declared replacement that cannot be opened should fail explicitly rather than fall back to vanilla and create a false-positive test result.

Pure mode and policy

The feature’s interaction with pure mode should be explicitly defined.

Possible policies:

• permit it under the same trust model as replace_level_meta;
• require a server policy capability for base-data overrides;
• disallow selected high-risk fileType values while allowing others;
• expose only the selective API by default and gate full replacement.

The important point is deterministic, documented behaviour.

---

Diagnostics requested

Useful client log output:

Default meta override registered:
  owner: RED_DefaultData
  replacement: resources:/RED_DefaultData/default.ymt
  game build: 3751

or, for selective replacement:

Default data-file override registered:
  owner: RED_VehicleModelSets
  original: common:/data/ai/vehiclemodelsets.meta
  replacement: resources:/RED_VehicleModelSets/vehiclemodelsets.meta
  file type: AMBIENT_VEHICLE_MODEL_SET_FILE
  game build: 3751

On application:

Replacing default data-file registration:
  common:/data/ai/vehiclemodelsets.meta
  -> resources:/RED_VehicleModelSets/vehiclemodelsets.meta

On conflict:

Fatal: resources 'A' and 'B' both replace
common:/data/ai/vehiclemodelsets.meta

On late registration:

replace_default_meta from resource 'A' was registered after
the default manifest had already been consumed.
A full game reload is required.

---

Acceptance criteria

1. With no replacement declared, the base game behaves identically to current FiveM.
2. A full replacement causes dataFileMgr__loadDefDat to receive the resource path instead of the Rockstar default-manifest path.
3. A selective replacement changes the source path of the matching base entry before its mounter runs.
4. The Ballas reproduction described above spawns only the custom BUCCANEER; a vanilla TORNADO can no longer be selected from the replaced set.
5. Vehicle variations from the custom base vehiclemodelsets.meta are parsed through the same base-loader path used by Rockstar, rather than through the later DLC mounter path.
6. Two full replacement declarations produce an explicit conflict error.
7. Two selective declarations for the same original path produce an explicit conflict error.
8. Selective declarations for different original paths can coexist.
9. Stopping or restarting the resource after initialization does not attempt unsafe live unloading.
10. Switching servers does not leak the previous server’s override.
11. Missing or invalid replacement files produce a clear error containing the owner resource and path.
12. Cache/session identity includes the active game build and override mapping.
13. Behaviour is documented separately for GTAV Legacy and GTAV Enhanced where necessary.

---

Scope and broader benefit

The attached extracted default.ymt registers 80 base data entries across 67 distinct fileType values. Examples include:

HANDLING_FILE
VEHICLEEXTRAS_FILE
DISPATCH_DATA_FILE
AMBIENT_PED_MODEL_SET_FILE
AMBIENT_PROP_MODEL_SET_FILE
AMBIENT_VEHICLE_MODEL_SET_FILE
PED_METADATA_FILE
PED_PERSONALITY_FILE
PED_PERCEPTION_FILE
PED_HEALTH_FILE
PED_TASK_DATA_FILE
MOTION_TASK_DATA_FILE
WEAPON_METADATA_FILE
WEAPONINFO_FILE
WEAPONCOMPONENTSINFO_FILE
LOADOUTS_FILE
DEFORMABLE_OBJECTS_FILE
TUNABLE_OBJECTS_FILE
CAMERA_METADATA_FILE
EXPLOSION_INFO_FILE
ACTION_TABLE_DEFINITIONS
ACTION_TABLE_RESULTS
ACTION_TABLE_IMPULSES
ACTION_TABLE_INTERRELATIONS
ACTION_TABLE_DAMAGES
ACTION_TABLE_BRANCHES
ACTION_TABLE_STEALTH_KILLS
ACTION_TABLE_VFX

Authoritative replacement would not guarantee that arbitrary malformed content is safe, nor that every manager accepts every theoretical modification. Each data-file loader would still enforce its own format and engine assumptions.

What it would provide is the missing foundational capability:

custom file registered through the same authoritative base path
instead of being appended later through a DLC/extra-content mounter

This would solve a class of limitations rather than adding a one-off workaround for vehiclemodelsets.meta.

---

Why both APIs are worth considering

replace_default_meta

Advantages:

• comparatively small conceptual change;
• analogous to replace_level_meta;
• useful for total conversions;
• exposes the full base bootstrap to advanced creators.

Disadvantages:

• highly build-sensitive;
• one resource must own the entire manifest;
• easy to break initialization with an outdated or incomplete file;
• poor composability.

replace_default_data_file

Advantages:

• surgical;
• composable for non-conflicting paths;
• preserves the Rockstar manifest and entry flags;
• less build-sensitive;
• easier to validate;
• addresses the common use case directly.

Disadvantages:

• likely requires a deeper hook into default-manifest entry registration or VFS path resolution;
• needs careful ownership and lifetime handling.

My preferred outcome would be the selective API, with full replacement available as an advanced escape hatch. Implementing either one authoritatively before loadDefDat would resolve the current limitation.

---

Attachments / reproducible material

I can provide:

1. the extracted default.ymt.pso.xml;
2. the complete modified vehiclemodelsets.meta;
3. a minimal standalone resource using data_file;
4. the custom primary gta5.meta test;
5. CodeWalker evidence showing that the tested scenario point references LOWRIDERS_MODDED_BALLAS;
6. screenshots/video showing a vanilla purple Tornado spawning while the custom set contains only a yellow Buccaneer;
7. client logs from a complete cold start.

Thank you for considering this. The request is intentionally broader than a special-case fix for one ambient model-set file, but it can be implemented with strict initialization-only semantics and deterministic conflict handling to avoid unsafe runtime mutation.