search

Exiled-Team / EXILED

A high-level plugin framework for SCP: Secret Laboratory servers. It offers an event system for developers to hook in order to manipulate or change game code, or implement their own functions.
https://www.exiled.to/
Other
274 stars 177 forks source link
csharp exiled harmony mono nwapi plugin scp-sl unity yaml

readme

EXILED - EXtended In-runtime Library for External Development

[CI](https://github.com/Exiled-Team/EXILED/actions/workflows/main.yml/badge.svg?branch=master) GitHub Releases Downloads ![Github Commits](https://img.shields.io/github/commit-activity/w/Exiled-Team/EXILED/dev?style=for-the-badge&logo=git) Chat on Discord

EXILED is a high-level plugin framework for SCP: Secret Laboratory servers. It offers an event system for developers to hook into in order to manipulate or change game code or implement their own functions. All EXILED events are coded with Harmony, meaning they require no direct editing of server assemblies to function, which allows for two unique benefits.

Localized READMEs

Installation

Installation of EXILED is quite simple. It loads itself through Northwood’s Plugin API. That's why there are two folders inside the Exiled.tar.gz in release files. SCP Secret Laboratory contains the necessary files to load EXILED features in EXILED folder. All you need to do is move these two folders into the appropriate path, which are explained below, and you are done!

If you choose to use the installer it will, if run correctly, take care of installing all EXILED features.

Windows

Automatic installation (more information)

Note: Make sure you're on the user that runs the server, or you have Admin privileges before running the Installer.

Manual installation

Installing plugins

That's it, EXILED should now be installed and active the next time you boot up your server. Note that EXILED by themselves will do almost nothing, so make sure to get new plugins from our Discord server

Linux

Automatic installation (more information)

Note: If you are installing EXILED on a remote server, make sure you run the Installer as the same user that runs your SCP:SL servers (or root)

Manual installation

Installing plugins

That's it, EXILED should now be installed and active the next time you boot up your server. Note that EXILED by themselves will do almost nothing, so make sure to get plugins from our Discord server

Config

EXILED by itself offers some config options. All of them are auto-generated at the server startup, they are located at ~/.config/EXILED/Configs/(ServerPortHere)-config.yml file (%AppData%\EXILED\Configs\(ServerPortHere)-config.yml on Windows).

Plugin configs will NOT be in the aforementioned config_gameplay.txt file, instead, plugin configs are set in the ~/.config/EXILED/Configs/(ServerPortHere)-config.yml file (%AppData%\EXILED\(ServerPortHere)-config.yml on Windows). However, some plugins might get their config settings from other locations on their own, this is simply the default EXILED location for them, so refer to the individual plugin if there are issues.

For Developers

If you wish to make a plugin for EXILED, it's quite simple to do so. If you would like more of a tutorial please visit our Getting Started Page..

For more comprehensive and actively updated tutorials, see the EXILED website.

But make sure to follow these rules when publishing your plugins:

To use MEC, you will need to reference Assembly-CSharp-firstpass.dll from the server files and include using MEC;. Example of calling a simple coroutine, that repeats itself with a delay between each loop:

using MEC;
using Exiled.API.Features;

public void SomeMethod()
{
    Timing.RunCoroutine(MyCoroutine());
}

public IEnumerator<float> MyCoroutine()
{
    for (;;) //repeat the following infinitely
    {
        Log.Info("Hey I'm a infinite loop!"); //Call Log.Info to print a line to the game console/server logs.
        yield return Timing.WaitForSeconds(5f); //Tells the coroutine to wait 5 seconds before continuing, since this is at the end of the loop, it effectively stalls the loop from repeating for 5 seconds.
    }
}

It is strongly recommended that you do some googling or ask around in the Discord if you are unfamiliar with MEC and would like to learn more, get advice, or need help. Questions, no matter how 'stupid' they are, will always be answered as helpfully and clearly as possible to help plugin developers to excel. Better code is better for everyone.

Dynamic Updates

EXILED as a framework supports dynamic reloading of plugin assemblies without requiring a server reboot. For example, if you start the server with just Exiled.Events as the only plugin, and wish to add a new one, you do not need to reboot the server to complete this task. You can simply use the Remote Admin or Server Console command reload plugins to reload all EXILED plugins, including new ones that weren't loaded before.

This also means that you can update plugins without having to fully reboot the server as well. However, there are a few guidelines that must be followed by the plugin developer for this to be achieved properly:

For Hosts

All of these can be achieved in either the OnReloaded() or OnDisabled() methods in the plugin class. When EXILED reloads plugins, it calls OnDisabled(), then OnReloaded(), then it will load in the new assemblies, and then executes OnEnabled().

Note that it’s new assemblies. If you replace an assembly with another one of the same name, it will NOT be updated. This is due to the GAC (Global Assembly Cache), if you attempt to 'load' and assembly that is already in the cache, it will always use the cached assembly instead. For this reason, if your plugin supports dynamic updates, you must build each version with a different assembly name in the build options (renaming the file will not work). Also, since the old assembly is not "destroyed" when it is no longer needed, if you fail to unsubscribe from events, unpatch your harmony instance, kill coroutines, etc., that code will continue to run as well as the new version's code. This is an extremely bad idea to let happen.

As such, plugins that support dynamic updates MUST follow these guidelines or they will be removed from the discord server due to potential risk to server hosts.

Not every plugin must support dynamic updates. If you do not intend to support dynamic updates, that's perfectly fine. Just avoid changing the assembly name of your plugin when you build a new version. In such cases make sure server hosts know they will need to completely reboot their servers to update your plugin.