Edit

Definition

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.

Definition File

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:

name (required)

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. MyUsername/repo-name.

Tips:

  • 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

version (required)

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.

description

Brief description of the plugin and its use. Used to help people discover your plugin on the plugin hub or with nfpm search.

license

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:

license: LGPL-3.0-or-later

You can check the full list of SPDX license IDs and ideally use one that is OSI approved.

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.

map

The map field is a simple boolean indicating if the plugin should be marked in FiveM as a map resource. Defaults to false.

map: true # FiveM will treat the plugin as a map resource

server

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, main and 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

client

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, main, include and files, a list of stream objects and a loading_screen field.

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.

The main and 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 file and 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.

The 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

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.

  • version Must match version exactly
  • >version Must be greater than version
  • >=version etc
  • <version etc
  • <=version etc
  • ~version "Approximately equivalent to version"
  • ^version "Compatible with version"
  • 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
  • * Matches any version, only recommended during development
  • version1 - version2 Same as >=version1 <=version2
  • range1 || range2 Passes if either range1 or range2 are satisfied

repositories

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 name, type and path. Currently the only supported type is 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

Lock File

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.

If this file exists in the same directory as the definition file, then nfpm install will use this file to restore exact versions, ensuring all users will be working in the same environment.

Last updated on 5/14/2019
← HubNext →