This documentation is for the planned specification and includes features not yet implemented
A NFive plugin consists of a directory containing a plugin definition file (
nfive.yml), data files and optionally a plugin definition lock file (
nfive.lock). NFive plugins can either run server side, client side or both.
A plugin must contain the following files as a minimum:
nfive.yml- This metadata file contains the plugin properties as well as what files and dependencies to load at runtime.
A plugin definition consists of a file named
nfive.yml, which defines the directory it is in as the root folder of a plugin.
The definition file is in YAML and can contain the following fields:
The name field is used as the plugin's unique identifier.
The name field is made up of two strings separated with a forwards slash (
/), where the first string is the plugin owner's name and the second is the project name.
If you plan on publishing your plugin to the official NFive plugin hub, then the name field must exactly match the URL to the repository on GitHub, e.g.
- Don't put "nfive" or "fivem" in the name, its assumed
- Names should be short but also descriptive of the functionality
- Check to see if other plugins use the same name on the plugin hub
The version field must be a valid Semantic Versioning 2.0 version number. The name and version together form an identifier that is assumed to be completely unique. Changes to the plugin should come along with changes to the version.
The license should specify the license your plugin is released under, so people how how they can use it.
The value should be a current SPDX license identifier:
If your plugin is licensed under multiple common licenses, use an SPDX license expression string, like this:
license: (ISC OR GPL-3.0-or-later)
If you are using a license that hasn’t been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:
license: SEE LICENSE IN <filename>
Then include a file named
<filename> at the top level of the plugin.
The map field is a simple boolean indicating if the plugin should be marked in FiveM as a map resource. Defaults to
map: true # FiveM will treat the plugin as a map resource
The server section defines what .NET assembly files are needed and to be loaded by the NFive server.
The field consists of two lists of files,
include. Main is a list of plugin assemblies which should be scanned for controllers to load. Include is a list of additional .NET assemblies which are required to be loaded for the
main assemblies to function.
The listed files automatically have
.net.dll appended to the end, as this is a requirement of FiveM.
server: main: - Owner.Project.Server include: - Owner.Project.Shared
The client section defines what .NET assembly files are needed and to be loaded by the FiveM client when connecting to the server.
The client section consists of three lists of files,
files, a list of
stream objects and a
Main is a list of plugin assemblies which should be scanned for services to load. Include is a list of additional .NET assemblies which are required to be loaded for the
main assemblies to function. Files is a list of extra data files which should be send to the client by the server, but not loaded into .NET.
include section files automatically have
.net.dll appended to the end, as this is a requirement of FiveM. The files are loaded into .NET in the order they are listed in the definition.
A stream object consists of
type fields. File must be the name of a file already listed in
files and the type must be one of FiveM's data file types.
loading_screen field is optional and if defined tells FiveM to use one of the
files as the loading screen to show when the client connects. There can only be one loading screen defined across all installed plugins. Defaults to undefined.
If the plugin definition file does not contain a
client section at all then the plugin with be marked as "server side only" in FiveM and not sent to the client.
client: main: - Owner.Project.Client include: - Owner.Project.Shared files: - Overlays/ExampleOverlay.html - Overlays/Example.js - Overlays/main.js - Overlays/style.css - Overlays/font.woff2 - loading.html - vehicles.meta stream: - file: vehicles.meta type: VEHICLE_METADATA_FILE loading_screen: loading.html
Dependencies are specified in a simple object that maps a plugin name to a version range. The version range is a string which has one or more space-separated descriptors.
The order dependencies appear in the list is the order they will be evaluated and loaded by the NFive, with the last loaded taking priority.
See versioning for more details about specifying version ranges.
versionMust match version exactly
>versionMust be greater than version
~version"Approximately equivalent to version"
^version"Compatible with version"
1.2.x1.2.0, 1.2.1, etc., but not 1.3.0
*Matches any version, only recommended during development
version1 - version2Same as
range1 || range2Passes if either range1 or range2 are satisfied
Repositories is a list of repository objects, each defining where a plugin, which is not on the plugin hub, can be located.
A repository consists of the plugin
path. Currently the only supported
local which will check for a plugin on the local disk.
path must be valid local filesystem path to the plugin directory.
repositories: - name: Owner/Project type: local path: C:\NFive\owner-project
A definition lock file (
nfive.lock) is a YAML file automatically created by
nfpm, which contains a full tree of all installed plugins and resolved version numbers.