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 server with EXILED installed jump to Step 4 to 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. Download the files SCriPt.LabAPI.dll and dependencies.zip
  3. Place the contents of dependencies.zip in your /LabAPI/dependencies/global/ directory
  4. Place SCriPt.LabAPI.dll in your LabAPI plugins folder
  5. Run the game and check there were no errors in the console
  6. Begin writing Lua scripts in the /LabAPI/SCriPt/Scripts/ directory
  7. 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. For example, if you have a script called HelloWorld, it should be in a file called HelloWorld.lua.

Hello World

Like any good programming tutorial, let's start with a "Hello World" script. Create a new file in the "Scripts/AutoLoad" 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()
 Events.Player.Joined:add(hello_user.onPlayerJoined)
end

function hello_user:unload()
 Events.Player.Joined:remove(hello_user.onPlayerJoined)
end

function hello_user:onPlayerJoined(args)
    Server:SendBroadcast("Welcome to the server, " .. args.Player.Nickname .. "!")
    print("Player " .. args.Player.Nickname .. " has joined the server.")
end

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

  • hello_user = SCriPt.Module('HelloUser') creates a 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()... and hello_user:unload() are special functions that are called when the script is loaded and unloaded. This is where you should add and remove your event listeners. They are automatically called when the scripts loads and unloads.
  • Events.Player.Joined:add(hello_user.onPlayerJoined) adds the onPlayerJoined function to the Player.Joined event. This means that when a player joins the server, the onPlayerJoined function will be called.
  • function hello_user:onPlayerJoined(args) is the function that will be called when a player joins the server. It takes a single argument, args, which contains information about the player that joined.
  • Server:SendBroadcast("Welcome to the server, " .. args.Player.Nickname .. "!") sends a message to all players on the server 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. This is limited to what RemoteAdmin commands a plugin exposes, but it's a good start.