FiveM Merge
About
fivem-merge is a library made with Node.js which can pack multiple vehicle resources into one resource.
Also comes with a CLI tool.
Prerequisites
Node.js and NPM is required.
Installation
With npm:
$ npm install -g fivem-merge
With yarn:
$ yarn global add fivem-merge
Usage
With shell inside your server’s resource directory:
$ vmerge --help
$ vmerge car1 car2 carEtc --output cars
fivem-merge is also a library and therefore can be used in Node.js
const vmerge = require('fivem-merge');
vmerge([ './car1', './car2', './carEtc' ], {
outputPath: './cars'
}) // => Promise<undefined|error>
Examples
With shell inside your server’s resource directory:
$ # merges the 18lamborghini and the 17lamborghini resources into a new resource called lamborghinis
$ vmerge 18lamborghini 17lamborghini --output lamborghinis
$ # merges fd vehicle resources into one pack
$ vmerge fd1 fd2 fd3 fd4 --output fd
$ # use relative directories and --output shortname -o
$ vmerge ./resources/coolcar ./resources/bestcar -o ./resources/[vehicles]/goodcars
$ # merge resources into an already merged resource
$ vmerge ./src/car1 ./src/car2 ./resources/vehicles -o ./resources/newVehicles && rmdir ./resources/vehicles && mv ./resources/newVehicles ./resources/vehicles
$ # if you don't want meta files to be linted automatically, add the `--no-lint` parameter
For Node.js
const vmerge = require('fivem-merge');
/**
* an array of vehicle resources to merge together
* @type {string[]}
*/
const resourcesToMerge
/** @type {Object} */
const options = {
/**
* whether output XML files should be linted for human readability
* @type {Boolean}
* @default true
*/
lintOutput: true,
/**
* the output directory of the merge resource
* @type {string}
*/
outputPath: './vehicles',
}
vmerge(resourcesToMerge, options)
How it works
The fivem-merge API creates a temp directory with a fxmanifest.lua containing a files table and data_file statements of all your selected resources’ manifests combined (also compatible with FXv1 __resource.lua).
All data files will be merged into the data folder. Unused or empty data files will be omitted.
Streamed files will then get moved into their own stream/<gamename> folder. If there are any vehicles with the same game or file name, an error will be emitted and will exit. You will need to manually fix this.
Once all these operations have been complete, the temp directory will get moved to your --output directory.
Keep in mind
fivem-merge is currently in an unstable release version, you will probably find bugs.
In case you do encounter a breaking error, getting frustrated and uninstalling the package doesn’t help.
Instead, open an issue for support and so we can fix it, or if you’re a developer make a pull request.
fivem-merge cannot merge scripts (including any vehicle_names.lua).
If any of your resources contain anything unmerge-able, a warning will be emitted with details to merge manually.
Due to my limited knowledge (and limited documentation), fivem-merge currently only supports the following data files:
HANDLING_FILEVEHICLE_METADATA_FILECARCOLS_FILEVEHICLE_VARIATION_FILEVEHICLE_LAYOUTS_FILECONTENT_UNLOCKING_META_FILE
An error will be emitted and the application will exit with code 1 if the API meets a data file not of the above.
If you would like to help make other data files supported, message me on Discord or make a pull request.
NOTICE
This tool is intended to be used by server owners whom have source files to their vehicles to easily pack them automatically.
I do not recommend nor condone deleting the original files after using this tool, being intended for build operations and is currently in a non-stable version.