User:Radicalicious/SRB2 Lua Beginner Tutorial Part 1

If you've stumbled onto this page then I assume you're here to learn some Lua. This tutorial is to teach the basics of SRB2's integrated Lua scripting language, which can be used to make a lot of custom things.

Let's start with the basics:

1. Create a file in your SRB2 directory called "SonicChangeColor.lua".

2. Open up that file in your text editor of choice. I use Notepad++, but regular notepad works fine too.

Once you have that file open, continue.

For the sake of simplicity, we will create an ability that turns Sonic red while holding the Custom 1 button. (NOTE: The Custom 1 button is not binded by default, you will need to manually bind it in the Settings menu.) Enter this code into the file:

local function turnSonicRed()
    for p in players.iterate
        
    end
end

The above code:

1. Creates a function called turnSonicRed().

2. Checks every player currently in the game, allowing us to refer to individual players as 'p'.

This is usually what every good Lua script that modifies player statistics starts with. Now, let's check for a button press.

local function turnSonicRed()
    for p in players.iterate
        if p.mo.skin == "sonic"
            if p.cmd.buttons & BT_CUSTOM1
                p.mo.color = SKINCOLOR_RED
            else
                p.mo.color = p.skincolor
            end
        end
    end
end

Woah, that's a lot of code. What does it all do? Let's break it down:

1. Checks the 'p.mo.skin' value to see if the player is currently Sonic.

2. Checks the player's button inputs to see if the player is pressing Custom 1.

3. If the player is pressing Custom 1, set their skin color to red. If they aren't, reset their skin color to the one they had before (always blue in singleplayer).

You can load it into the game just fine, but nothing's gonna happen. Why is that? Well, there's nothing that calls the function. How do we remedy that? Simple. SRB2's Lua contains a feature called hooks, which allows you to run code when certain things happen. For our purposes, we need the 'ThinkFrame' hook. This hook makes the code runs every frame, before the game renders that frame. Add this below the final 'end' that closes off the function:

addHook("ThinkFrame", turnSonicRed)

That should make the code run every frame. If you did everything correctly, load the .lua file into SRB2. You should be able to turn red while playing as Sonic.

Now, what did this code even do? You probably just copy-pasted it and BAM, colored Sonic. Let's take an in-depth look. Let's start with "players.iterate".

for p in players.iterate ... end

'players.iterate' is a list of every player_t object (human player) in the level. When the code says 'for p in players.iterate', 'p' is essentially a player. This allows code to be executed to every individual player currently in the map. So when this happens:

if p.mo.skin == "sonic"

..it checks every player currently in the map (p), uses mo.skin (mo being their object attributes and skin being their skin's 'name' property from S_SKIN) to refer to the skin, and if their skin is Sonic, then we execute code.

if p.cmd.buttons & BT_CUSTOM1 ... end

What does this do? We know it checks if the player is pressing Custom 1, but how does it work? Well, p.cmd is a 'ticcmd_t' object that determines what buttons to press and when do move or do things while those buttons are pressed. When we check if 'p.cmd.buttons & BT_CUSTOM1', we are checking if p.cmd's 'button' value contains the constant 'BT_CUSTOM1', corresponding to the value that the game gives when pressing that button. In SRB2's Lua, there are many constants that exist, for many different uses. BT_* constants represent button presses, for example.

So if you read this tutorial, you should know:

1. How 'for p in players.iterate' works.

2. What all the 'if' statements do.

3. How to add a function to a hook.

In Part 2 of this tutorial, we will learn how to interact with in-game objects. The tutorial will be here soon. Stay cool, and happy modding.