Introduction

A plugin is a software add-on that can be installed to enhance a game server, for example, by monitoring server activity or potentially adding functionality to the game.

A plugin developer may publish their plugin at uMod.org. When a plugin submission is approved it will become available for installation using the uMod Agent.

The uMod Agent is the officially supported command-line tool to manage plugins installations.

Plugin file

A plugin file is C# (CSharp) code file (with a .cs file extension) that is installed into the umod/plugins directory.

Lock file

The lock file tracks the current plugin installation, including what version of a plugin is installed and any dependencies that plugin may have.

Side-loading

It's still possible to side-load plugins by copying plugin files into the umod/plugins directory. Side-loaded plugins are not tracked in the lock file and cannot be updated with the update command.

Opt-in

The lock file will track plugins installed with the require command. The uMod Agent will not track side-loaded plugins.

Require

The require command installs new plugins.

umod require Logger

Version contraints

By specifying a version mask after a plugin name, the plugin will be constrained to minimum and maximum allowable versions. For example...

umod require Logger 2.*

Explicitly defining version contraints is not necessary (assuming the latest major version is desired). If a version is not specified, the default version constraint will use the latest major version with a wildcard to always use the latest minor or patch updates.

When managing large plugin installations, using version constraints ensures stability between updates. A major version update, by definition, is not backwards compatible and could very likely break compatibility with other plugins.

In such scenarios, a version constraint is critical to ensuring that plugin installation uses the versions we know are compatible. As a result, a server administrator can safely automate plugin updates until they have a chance to verify the latest major versions are still compatible.

Update

The update command updates a plugin to the latest version (or the latest version that also adheres to any version constraints)

umod update Logger

Update version constraint

Each plugin specified with update command, like the require command, may be accompanied by a version mask.

For example, if we have Logger installed with the version constraint 2.* and a new major version is released...

umod update Logger 3.*

The uMod Agent will attempt to resolve a valid installation that adheres to all existing and new version constraints (including all dependency constraints).

Update from lock file

If switching servers, a lock file may be copied to the new server without copying every plugin. Run the umod update command to install all of the plugins specified in the lock file.

Remove

The remove command will uninstall a plugin and any dependencies of that plugin.

umod remove Logger

New

The new command allows for the quick creation of important files from templates to easily bootstrap server operation and development.

Project

Create a solution (.sln) file in the umod directory and a project (.csproj) file in the umod/plugins directory.

The project file will have platform configuration and uMod references pre-defined.

umod new project --author="<authorName>"

Add Project References

Add references to the server assemblies into the uMod project .csproj project file.

umod add reference *

Plugin

Create a plugin (.cs) file in the umod/plugins directory

umod new plugin MyPlugin --author="<authorName>" --description="<description>" --no-test

Test

Create a MSTest (.cs) test file in the umod/tests directory

umod new test MyPluginText --author="<authorName>"