Getting Started - tayjay/SCriPt GitHub Wiki

Setting up your environment

These instructions will guide you through setting up a new SCP:SL server locally for testing. If you already have a LabAPI server, jump to Step 3 for the plugin-specific instructions.

  1. First off, if you don't have one, we need a game server to run this on. This can be your local computer if you want. Follow NorthWood's Instructions to setup a local SCP:SL server.
  2. Make sure LabAPI is installed on the server.
  3. Download SCriPt.LabAPI.dll from the latest release and place it in your LabAPI plugins folder (usually /LabAPI/plugins/global/).
    • MoonSharp is bundled inside the plugin and loaded automatically on startup — you do not need to download or install it separately. If you have an old MoonSharp.Interpreter.dll sitting in /LabAPI/dependencies/, delete it so the bundled (correct) version is used.
  4. Run the game and check there were no errors in the console.
  5. Begin writing Lua scripts in the /LabAPI/SCriPt/Scripts/global/ directory (see Scripts Structure below).
  6. Make sure you can connect to the server. Direct Connect to 127.0.0.1 if it's running on your local computer.

Scripts Structure

If you check the SCriPt folder, you will see a few folders. Here's how they work:

  • Data: This folder holds persistent data for your scripts. See the Data page for more information.
  • Docs: This folder contains automatically generated documentation through the lua docs command. It is used to simplfy the process of writing these docs, but feel free to give it a run.
  • Scripts: This folder is where you will write your scripts. Each script should be in its own file, and the file name should match the script name (e.g. a script called HelloWorld lives in HelloWorld.lua). It contains a few sub-folders:
    • global: Scripts here load on every server/port. This is where most of your scripts go.
    • <port>: A folder named after a port number (e.g. 7777) loads only on that specific server. Useful when running multiple servers from one install.
    • lib: Shared library modules that scripts pull in with require(...). Files here are not run on their own — see the Libraries page.

Hello World

Like any good programming tutorial, let's start with a "Hello World" script. Create a new file in the Scripts/global folder called HelloWorld.lua and put the following code in it:

print('Hello, World!')

When you launch the server, you will see [Info] [Lua] Hello, World! in the console. It doesn't do anything fancy, but if you see this then you're ready to proceed.

Writing your first script

The start of any good project is a plan. What do you want to do? In this example I want the server to automatically do the following:

  • When a player joins, they are greeted with a message

Simple enough, a good way to structure your idea is to keep the event based nature of this plugin in mind, for example:

  • When X happens, do Y

Let's look at the code that will do this and break it down. Create a new file in the "Scripts" folder called "HelloUser.lua" and put the following code in it:

hello_user = SCriPt.Module('HelloUser')

function hello_user.load()
    -- mod.on registers the callback and auto-removes it when the script unloads.
    hello_user.on(Events.Player.Joined, hello_user.onPlayerJoined)
end

-- Event callbacks take a single 'args' parameter, so define them with a DOT (.), not a colon (:).
-- A colon adds a hidden 'self' parameter, and your 'args' would arrive as nil.
function hello_user.onPlayerJoined(args)
    Server.SendBroadcast("Welcome to the server, " .. args.Player.DisplayName .. "!")
    print("Player " .. args.Player.DisplayName .. " has joined the server.")
end

Most of this code is boilerplate, but let's break it down:

  • hello_user = SCriPt.Module('HelloUser') creates a module table to hold our functions. With how scripts load it is best to keep them in their own tables, and to not execute code directly, instead relying on functions and events to trigger your code at the right time.
  • hello_user.load() is a special function called automatically when the script loads. This is where you register your event listeners. There is also an optional hello_user.unload() for cleanup, but it is rarely needed (see below).
  • hello_user.on(Events.Player.Joined, hello_user.onPlayerJoined) subscribes the onPlayerJoined function to the Player.Joined event. Using mod.on (instead of Events.Player.Joined.add) means the callback is automatically removed when the script unloads, so you don't need an unload function just to clean up events.
  • function hello_user.onPlayerJoined(args) is called when a player joins. It takes a single args parameter holding the event data. Define event callbacks with a dot (.) — a colon (:) adds a hidden self parameter and your args would arrive as nil.
  • Server.SendBroadcast(...) sends a broadcast to everyone, welcoming the new player.

Now, when a player joins the server, a broadcast message will be sent welcoming them. The print function is used so you can see it happen in the console too.

For more real examples of scripts check out the Example Scripts Page

Using other Plugins

See the Extensions page for information on how to use other plugins in your scripts.

You can always call RemoteAdmin commands using the Server.RACommand("command") function (note: this requires the full_access config option — see the Dangerous page). This is limited to what RemoteAdmin commands a plugin exposes, but it's a good start.