Workshop: Modules

This guide documents the Modules feature and how to write custom C# code for use in Unturned.

Intro

Note: 3rd-party modules can't be loaded with BattlEye enabled. To disable BattlEye you can select the alternative launch option in Steam "Play without BattlEye", or temporarily move your modules out of the Unturned directory before starting the game with BattlEye.

I'm currently working on cleaning up and modularizing Unturned's code into a "Framework" component which will contain core editor and gameplay elements, and a "Unturned" component housing Unturned-specific features like zombies or crafting.

The goal is that then you can create your own Modules which can add new features to Unturned itself, convert it into a completely different game (e.g. HL1 -> TF2), or build off of other modules to improve functionality.

Right now very few Unturned features are built with this module support in mind, but over time we'll get there! I'm also currently considering opening Unturned's sourcecode to GitHub so that you can submit pull requests for any changes you need. In the meantime the functionality is there to get started with a custom module as instructed below:

Module

All module files go in the Unturned/Modules directory. For security reasons they are not allowed on the Steam Workshop, but they are fairly straightforward to install.

To get started you can create a folder to house your module. Inside of this you will have any number of *.module files which show in the Workshop/Modules window or when using the "Modules" command.

Below is an example of a .module file, in this case saved as Example.module, and here are the explanations of what each variable does:

IsEnabled gets set by the game from the modules menu, or you can alter it manually for example to temporarily disable a module on the server.

Name is the linked identifier for this module. Other modules will use this name for their dependencies, so do not change it. You can change the display name in the localization files.

Version represents main.major.minor.patch. It is displayed and used for dependencies and checking installed modules when joining a server.

Assemblies are a list of the .dll files which make up the actual code of your module. Path is relative to the folder the .module file is in. Role can be set to Client, Server, Both_Optional and Both_Required. Client assemblies aren't loaded on the dedicated server and vice versa. Both_Optional is for cases where a client can safely join the server even if they don't have the module, maybe showing error messages when interacting with missing features. Both_Required is for total conversions where missing the assembly breaks everything, so clients are rejected from the server.

Dependencies are a list of modules that must be loaded before this one. The load order is automatically calculated. If a module with that name and at least that version aren't available this module isn't loaded.

Additionally alongside your .module file(s) you can include localization .dat with a "Name" and "Description" key and an "Icon.png" shown in the menu.

{
        "IsEnabled": true,
	"Name": "UnturnedExampleMod",
	"Version": "2.1.0.3",
	"Assemblies":
	[
		{
			"Path": "/UnturnedExampleModule.dll",
			"Role": "Both_Required"
		},
		{
			"Path": "/UnturnedExampleModuleCommands.dll",
			"Role": "Server"
		}
	],
	"Dependencies":
	[
		{
			"Name": "Core",
			"Version": "3.0.0.0"
		},
		{
			"Name": "OtherMod",
			"Version": "2.5.0.0"
		}
	]
}

C#

To set up the assemblies for your mod you'll want to create a new project in Visual Studio and add Unturned/Unturned_Data/Managed/Assembly-CSharp.dll and Unturned/Unturned_Data/Managed/UnityEngine.dll as references. In the future these will be references to the Framework and Unturned modules. You can configure your build output to put just the project .dll file in your module folder, or manually copy it over after building.

In these early days of Unturned scripting support your mod might break with higher frequency as my code is cleaned up and moved into separate .module files to better support custom mods, but I'll do my best to avoid that. I'd recommend you try to maintain backwards compatibility as well incase other mods depend on yours.

Modules are hooked into essentially the earliest point in the game's startup, so you have quite a bit of control. To define your module's entry (initialize) and exit (shutdown) points implement the IModuleNexus interface from SDG.Framework.Modules in as many of your classes as you like. These classes will be instantiated when loading the modules, but held onto to avoid garbage collection. Weird interface name maybe, but I've always liked naming my main class "Nexus"!

[ChronicRogue22]

erm, ive been looking through guides and stuff, i cant join any servers cause its missing a module but idk how to disable my modules

[Ceans]

Take a look at the flow's tutorial

[flow____]

Take a look at my Tutorial
http://steamcommunity.com/sharedfiles/filedetails/?id=834599848

[Vasko]

lol

[the_blaster179]

Just noticed that in the .module exemplar, you have a formatting error in it where it shows [/nocode] in it, and it could confuse some people.

[rockhopper]

SO i don't understand, when we are to "create a project" do we create a c# console file? or what?

[monctrum]

I think that something like TWD Modules will be cool, you know. Killing zombies Headshot Only, and when someone dies, spawn zombie on him. Ok, the second thing would be harder beacause of zones... But I don't understand this tutorial so... I'll wait for video on YT,

[LeeIzaZombie]

I think there's an example in Bundles/Sources/ not sure... I did my first module by implementing interface in a class and using the references

[Azim]

Can u put an example.module , which will print 'hello world' somewhere, with all it's .dll s 'n stuff? So we can read, understand and do our best?

[Azim]

Hey, Nelson, all u did - very interesting, but can u explain, please, how it all should work?
I setted up my visual studio as it said here, but how module will work? f.e. i wanna make anti-cheat, which will check the game's files for their change dates|amount and compare to example, serverside will ask client on connect, and if tho,ething wrong, it will kick player. I have it all more detailed in my head. But the Q is - how should i do it? what kind of project to create, how to save files.dll and how to formalize them all together?