Setup

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

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 plugins 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). [TODO: LIST OF EVENTS]

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.

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.

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, GameConsole or RemoteAdmin), set to 0 to disable all script commands.

script_executions_limit

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

Developer setup