The install.xml file is used to describe how to load a mod and as such the file you usually work with the most. It offers many different options, ranging from simply loading a few new files to more options such as overwriting single meta file entries. While the autogenerator tries to create a usable install.xml file for mods without one, in many cases the file structure makes it hard to properly guess what file goes where, so manual refining is necessary. A fully commented example file showcasing all different features can be found at the end of this post.
File Information
Every install.xml contains information about a mod, such as the name, name of the author, the version and more. These details are not necessary to install a mod, but it should be considered best-practice to provide them.
The IsExtension tag at the root level is special as it indicates for a mod to be placed at the bottom of the load order list when it is first installed. This allows the mod to overwrite files from other mods.
Common Tags and Attributes
All tags currently support only one common attribute called allowDuplicate. If set to true, the parser will no longer discard multiple resources with the same path (by default, only the first resource is loaded and a warning logged). This is necessary for certain files that need to be loaded both, as a streaming file and a data file such as YTYP.
All high-level tags (ResourceGroup, Addon and Replacement) support a scriptName tag as a unique identifier. This name can be referenced by ResourceGroups as well as for planned support to toggle individual resources.
Addon resources & Replacement resources
There are two slightly different ways of handling files: Addon files which add new stuff to the game and replacement files which overwrite existing files. Addon files can in most cases be loaded while the game is already running whereas replacement ones should be loaded when the game is starting as they might already be in use otherwise. This is the major difference between the two. Keeping these resources separate makes it easy to understand what is happening in many cases, but can also lead to some unnecessary verbose install.xml. You are hence given the option to mix any addon or replacement tag in a generic Resource. We still recommend to split the declarations to keep things clean, but you are free to do something like this:
<Resources>
<Resource name=>
<StreamingFiles isAddon="true">stream/addon/props</StreamingFiles>
<StreamingFiles isAddon="true">stream/addon/textures</StreamingFiles>
<DataFile type="DLC_ITYP_REQUEST" allowDuplicate="true">stream/addon/props/coastal_props.ytyp</DataFile>
<FileEntryReplacement type="VEHICLE_METADATA_FILE">data/individual/overwrite_vehicles.meta</FileEntryReplacement>
<FileReplacements>stream/replace/maps</FileReplacements>
<FileReplacements>stream/replace/textures</FileReplacements>
<FileReplacement>
<GamePath>update:/common/data/gameconfig.xml</GamePath>
<FilePath>gameconfig.xml</FilePath>
</FileReplacement>
</Resource>
</Resources>
If you refer to the separate Addon and Replacement sections in this document, you will see that the tags have been mixed here. This is perfectly valid and might be easier for your specific usecase. It comes with a few caveats though: Since it is no longer clear whether a streaming file is an addon or a replacement resource, by default it will be treated as a replacement and not support being added into a running game. You can use the isAddon attribute as laid out above to explicitly declare it as an addon resource. The other tags should all work how you would expect them to work in their respective section.
Addon Resources
Within the Addons tag, multiple Addon resources can be defined. Ideally, by using the name attribute they are logically grouped to make identifying them easy. Five different ways of loading addon resources are available, two for streaming files, two for data files and one for FiveM resources. Addon resources can generally be loaded while the game is already running.
Streaming Files
All models in GTA V have to be loaded as streaming files. There are two ways of doing this, both very similar. The following example shows how to load a single streaming file from a path:
<StreamingFile>addon/17silver_hi.yft</StreamingFile>
Ped addon components also require a DlcName tag to make sure they are placed in the correct DLC.
<StreamingFile>
<DlcName>mp_f_samclothes</DlcName>
<FilePath>mp_f_freemode_01_mp_f_samclothes.ymt</FilePath>
</StreamingFile>
To register a streaming file under various different names (useful when sharing a ydr with multiple ytd files), you can use multiple GamePath tags.
<StreamingFile allowDuplicate="true">
<GamePath>prop_ballistic_shield_corrections.ydr</GamePath>
<GamePath>prop_ballistic_shield_fib.ydr</GamePath>
<GamePath>prop_ballistic_shield_noose.ydr</GamePath>
<GamePath>prop_ballistic_shield_sahp.ydr</GamePath>
<GamePath>prop_ballistic_shield_sheriff.ydr</GamePath>
<GamePath>prop_ballistic_shield_swat.ydr</GamePath>
<FilePath>variations/prop_ballistic_shield_new.ydr</FilePath>
</StreamingFile>
To instead load all files from a folder, use the StreamingFiles tag:
<StreamingFiles>addon/stream</StreamingFiles>
For ped addon components things work a little bit differently again since every component also needs the model name in its name. Therefore, a convenience overload is provided to prepend this name to all streaming files within a folder.
<StreamingFiles>
<GamePath>mp_f_freemode_01_mp_f_samclothes</GamePath>
<FilePath>mp_f_freemode_01_mp_f_samclothes</FilePath>
</StreamingFiles>
Data Files
Files such as meta files need to be loaded as data files. Data files have different types internally, such as VEHICLE_METADATA_FILE which is important when dealing with them. To load a single data file it is recommend to also specify its type, to make sure they are loaded correctly. For a few common types the type is guessed based on the file name, but providing the type is a cleaner solution.
<DataFile type="VEHICLE_METADATA_FILE">addon/vehicles.meta</DataFile>
Similarly to load multiple data files, the DataFiles tag can be used. Note that this will only work for known data types since no type can be specified here.
<DataFiles>addon/data</DataFiles>
FiveM files
There is also experimental support for FiveM resources, mostly focusing on vehicle mods. These should always be loaded as addon resources, unless the author has given different instructions. To load them only the path for the resource lua file is required, everything else is loaded automatically. Note that currently no scripting support is available, which means that for instance custom vehicle names are not registered in the game.
<ResourceLua>addon/__resource.lua</ResourceLua>
Replacement Resources
Within the Replacements tag, multiple Replacement resources can be defined. Ideally, by using the name attribute they are logically grouped to make identifying them easy. Replacement resources provide a way to override existing game resources which would normally be done by directly replacing files in a RPF. Hence replacement resources have certain limitations compared to Addon resources. They cannot be loaded while the game is already running, as the resource to override might have already been loaded by the game. In addition, they often require extra parameters to work properly.
Full File Replacement
The most straightforward way for replacement resources is simply replacing one file with another. For streaming files, it is usually sufficient to simply provide the path to the new file, given that it has the same name as the file it is supposed to override as can be seen below.
<FileReplacement>replace/police2.yft</FileReplacement>
Should the new file have a different name than the file it is supposed to replace, it is necessary to specify the game path. Multiple GamePath tags are supported to override different resources with the same file.
<FileReplacement>
<GamePath>police2.ytd</GamePath>
<FilePath>replace/my_police2.ytd</FilePath>
</FileReplacement>
It is also possible to override by using the full game path.
<FileReplacement>
<GamePath>dlc_patchDay3NG/x64/levels/gta5/vehicles/police2_hi.yft</GamePath>
<FilePath>replace/police2_hi.yft</FilePath>
</FileReplacement>
If the names match the names of the files that should be replaced, files can also be loaded directly from a folder.
<FileReplacements>replace/newPolice</FileReplacements>
This is especially useful when replacing ped component models and textures, since they have many files. As a convenience, game path is also supported here so that all files in FilePath will have GamePath prepended to them.
<FileReplacements>
<GamePath>mp_f_freemode_01_female_heist</GamePath>
<FilePath>replace/mp_f_freemode_01_female_heist</FilePath>
</FileReplacements>
When dealing with many peds in a folder, it can be useful to use the subFolderGamePath attribute. This automatically maps all peds in subfolders using the folder name as the gamepath.
<FileReplacements subFolderGamePath="true">stream/replace/peds/mp_peds</FileReplacements>
For data files, it is generally recommend to use the update path to make sure the correct one is replaced.
<FileReplacement>
<GamePath>update:/common/data/handling.meta</GamePath>
<FilePath>replace/handling.meta</FilePath>
</FileReplacement>
Single File Entry Replacement
One advanced feature of replacement resources is the ability to only replace certain data file entries within a data file. This could be used to alter the handling of one specific vehicle for instance, without having to provide a full new handling.meta file. In this case, it is necessary to specify the type of the file. It is also important to include all parent tags in the replacement file in the same way you would for an addon resource. See the example below and the full example file at the end of the post for a more detailed example.
<FileEntryReplacement type="VEHICLE_METADATA_FILE">replace/vehicles.meta</FileEntryReplacement>
RPF File Support
You can also load an RPF file, for instance if certain resources are not yet supported natively by LML. There are three different ways of loading a RPF file.
<!-- Load the dlc directly via name-->
<DlcRpf>dlc.rpf</DlcRpf>
<!-- Or load a dlc.rpf from a subfolder -->
<DlcRpf>vicecity</DlcRpf>
<!-- Or load a DLC from a totally different folder. This disables existence checks for the actual folder and file when parsing
as we do not have any knowledge of other folders. -->
<DlcRpf>addonDLC:/vicecity_sounds/</DlcRpf>
Resource Groups
One of the newer features in LML are resources groups, mostly intended for more complicated mods. These groups allow you to group (!) multiple resources to make it easy for the user to disable them. That way you can ship different variations or features of your mod and allow the user to simply enable and disable those depending on their preferences. These groups including their associated resources are visible in the Mod Manager. Consider the following example:
<ResourceGroups>
<ResourceGroup name="Essentials" scriptName="essentials" required="true">
<Description>Contains all essentiall files to run your mod</Description>
<Resources>
<Resource>vehicles</Resource>
<Resource>peds</Resource>
<Resource>boats</Resource>
</Resources>
</ResourceGroup>
<ResourceGroup name="New Model Sets" scriptName="modelsets" disabledByDefault="true">
<Description>Replace game model sets with our new custom models</Description>
<Resources>
<Resource>modelsets</Resource>
</Resources>
</ResourceGroup>
</ResourceGroups>
As you can see, there are a few attributes that can be used on groups. The required attribute prevents the user from disabling this resource group so that it is always loaded. The disabledByDefault tag gets parsed when the mod is first downloaded or installed and will automatically disable this group. It can then be enabled by the user at any time. To uniquely identify a resource group, the scriptName attribute is used. For the UI name the name attribute is used together with the Description tag.
Resource Folder
A simple feature to make LML more useful for mods that do not solely consist of file modifications, such as script mods or ELS vehicles. By specifying these folders, all files from there will be automatically copied into the game directory when installing the mod. This is not verified or done again on game launch for performance reasons. It is a glorified file copy system and since nothing is known about the files that are being copied there is no support to toggle or remove anything. This feature is probably most useful for ELS cars to move the light settings to the right place. Example to copy everything from filesToCopy to the game root folder:
<ResourceFolders>
<GameFolder>filesToCopy</GameFolder>
</ResourceFolders>
Example file
Please find a fully commented example below: