Skip to content

Setup

Jump to bottom
Adam Szerszenowicz edited this page Jun 9, 2025 · 26 revisions

User setup

In this section you will learn how to install and configure SLCS plugin and how script creation works in default configuration.

⌨️ Plugin installation

Warning

This section was written for Northwood Plugin API version of the plugin. For Lab API version follow the official installation guide.

Plugin can be installed automatically or manually. Automatic installation is recommended since it's easier and faster than the manual approach.

🚘 Automatic installation

  1. Open your LocalAdmin terminal and execute the following command: p install Pogromca-SCP/SLCommandScript
  2. Restart your server once the plugin is installed.

✋ Manual installation

  1. Download SLCommandScript.dll and dependencies.zip files from latest release.
  2. Place downloaded *.dll file in your server's plugins folder.
  3. Unzip the contents of the downloaded *.zip file into your server's plugin dependencies folder.
  4. Restart your server if it's already running.

📂 Files structure

Once you start your server with plugin installed you should see SLCommandScript folder created in your server's configuration directory. Inside you should see the following items:

  • scripts folder
  • pluginConfig.yml
  • scriptsLoaderConfig.yml

Files with *.yml extension store plugin configuration. You can find more details about configuration in section below. The scripts folder is the place where server scripts should be placed. By default it should contain 4 subdirectories. Scripts put in each folder will be registered to different consoles:

  • client -> Client in-game console
  • events -> Scripts from this folder are used for events handling
  • ra -> RemoteAdmin console
  • server -> LocalAdmin terminal (doesn't work on non-dedicated servers)

Note

Folders might be inactive or behave differently depending on configuration and used scripts loader implementation.

✏️ Creating scripts

To add new script create a file with *.slcs extension in a folder of your choosing. Once the file is created the plugin will attempt to register your new script to appropriate console. Your script won't be registered if a command with identical name or alias already exists, so you should always check commands in your target console before adding new scripts.

Tip

If your script's name is already taken, simply rename the file. The plugin will detect name change and try to register script with updated name. No server restarts needed.

Warning

RemoteAdmin suggestions won't show new scripts until next round restart.

To execute a script open your target console and input the name of your script without file extension. For example if you want to run a script test.slcs located in ra folder you need to open RemoteAdmin console and type test.

Note

Script names are case insensitive. test gives the same results as TeSt.

Tip

Client console also requires a dot prefix added to every script command. (ex. you should use .test instead of test)

To remove a script delete associated file or change its file extension. Removal might break other scripts if they were relying on removed script so always perform removals with caution.

🪺 Creating nested commands

You can also create additional subdirectories inside your scripts folders and put scripts and additional subdirectories inside them. Subfolders are registered as parent commands which can store multiple subcommands. For example to execute peanut_run.slcs script inside rounds subdirectory you need to type rounds peanut_run in console. Nested commands can be used for scripts categorization or to reduce potential name conflicts.

Tip

Client console dot prefix needs to be added only to the first parent command name. (ex. .rounds peanut_run)

Warning

Parent command always fails, so try to always provide a valid subcommand.

➡️ Creating event handlers

Scripts put in events folder are registered as event handlers. Those scripts are executed automatically by server when an appropriate in-game event occurs. They cannot be accessed from any console or script. The name of your script must match the name of the event you want to handle. Optional On prefix is also allowed if preferable (ex. both PlayerJoined and OnPlayerJoined are valid event handler names). See full list of events here

Note

Event names are case insensitive. PlayerJoined gives the same results as playerJoined.

Important

Each event can be handled by only one script! New handler created for the same event will override the existing one.

#️⃣ Adding script metadata

You can also add metadata to your scripts. The plugin expects the metadata to be located in separate JSON file in the same directory and with the same name as the associated script (ex. my_script.json contains metadata for my_script.slcs).

Important

Metadata files work only with regular scripts. Event handlers are not supported.

Warning

If the file is not in proper JSON format the metadata will not be updated!

Metadata attributes are case sensitive, attribute Description is not the same as description!!!

Description

An explanatory text describing what is the purpose of a script or how it should be used. Has no effects on interpter.

Usage

An array of strings showing what kind of arguments a script is expecting. Has no effects on interpter.

Arity

A minimum amount of arguments required to run a script. Interpreter is not started if script invoker does not provide enough arguments.

RequiredPerms

An array of permissions that are required to run a script. Interpreter is not started if script invoker does not have all listed permissions. Uses standard permissions system but it can be hooked to other systems by setting custom permissions resolver implementation in plugin configuration.

{
    "Description": "Bans a specific player from server for 24 hours.",
    "Usage": ["Player", "Reason (Optional)"],
    "Arity": 1,
    "RequiredPerms": ["KickingAndShortTermBanning", "BanningUpToDay"]
}

⚙️ Plugin configuration

The behavior of SLCS can be altered with configuration. This section explains how each setting can affect the behavior of plugin or scripts.

Important

Configuration values are only read when the plugin is initializing. Changing values won't take effect until the plugin is restarted. You can install PluginCommands to toggle plugins off/on without restarting the server.

🔌 Plugin Config

pluginConfig.yml contains general plugin configuration.

scripts_loader_implementation

Scripts loader is responsible for managing scripts at runtime and the used scripting language pipeline. This setting allows you to choose which scripts loader should be loaded with the plugin. The default provided implementation works on server's local file system exactly as described in this documentation and applies standard unmodified SLCS language pipeline. Using a custom scripts loader implementation can change the way how scripts are managed on the server and how SLCS interpreter behaves. If you want to you can use a custom scripts loader to replace SLCS with a completely different scripting language.

enable_helper_commands

If this option is enabled, the plugin will register a helper command slcshelper to all consoles defined in allowed_script_command_types config property. Helper command can provide simplified overview of language syntax or a list of available iterables and a mechanism to check what variables they provide.

🔎 Scripts Loader Config

scriptsLoaderConfig.yml contains configuration for scripts loader. The effects may vary between different implementations. Here's a description of effects for default implementation.

custom_permissions_resolver

Here you can provide a custom permissions resolver implementation to use when verifying player permissions. By default the scripts use in-game permission system. If you're running a server with a custom permissions system you might consider to use an appropriate permissions resolver as well.

enable_script_event_handlers

Set this setting to false in order to disable event handling with scripts.

allowed_script_command_types

Defines allowed script command types (Console, Client or RemoteAdmin), set to 0 to disable all script commands.

Important

Before version 2.0.0 the Client command type was named GameConsole.

script_executions_limit

Defines a maximum amount of concurrent executions a single script can have, use it to set max recursion depth.

Developer setup

To start utilizing or extending SLCS within your own project simply add a NuGet package reference to SLCommandScript.Core library. It exposes all interfaces, objects and utilities that you will need. Check developer guide to learn more

<PackageReference Include="SLCommandScript.Core" />

The library heavily relies on types built into the game and sometimes adding a reference to SCP:SL assemblies might be necessary. This can be achieved by providing a full or relational path to server *.dll files. Consider creating a dedicated environment variable pointing to directory where the dedicated server is installed.

<Reference Include="NorthwoodLib" HintPath="$(SL_REFERENCES)/NorthwoodLib.dll" />

Your project should target .NET Framework v4.8 if it's supposed to be a server plugin or dependency. Projects targeting newer platforms can also work outside server extension environment but they are very likely to have unexpected behavior, especially when referencing types from game assemblies.

<TargetFramework>net48</TargetFramework>

Clone this wiki locally