User:Monster Iestyn/Lua custom commands tutorial

Okay ladies and gents and otherwise, we are going to make us some custom commands today!

This is a pretty basic thing to do in Lua with SRB2, so it's worth learning if you're starting out

The begins

One of the functions that any Lua scripter, new or expert, should know is the print command. If you're aware of the vanilla Lua version of this function though, be aware that we hijacked this a bit. But only a little! Instead of printing text messages to stdout (the name of which is going to look like nonsense gibberish to coding newbies, so we won't refer to it again), it prints text messages to SRB2's console.

Okay, first of all, make a new text file in your SRB2 folder, named myfirstlua.lua. Open it up with a text editor of your choice, though preferably something like notepad++ would be good (it has syntax highlighting features!).

Put the following contents into said text file:

print("Hello world!")

Then, start up SRB2, and add myfirstlua.lua from your folder into the game. Check the console, and you should see...

Hello world!

Congrats, you just made your first working Lua script! But alas, this message only appears when you actually load the script itself into the game! Once it has been loaded, it'll never appear again. =( Wouldn't it be better if we could make a console command that printed this message whenever we executed it?

On a fun note, if you wanted to make any other messages appear instead of "Hello world!" (keeping in mind we're keeping things simple, no variables or anything), go ahead!

print("Monster Iestyn is an amazing Lua scripter!")

Keep in mind that the text must be between two quote marks (") otherwise it won't work properly. There may be some characters that won't print properly normally, but we'll get to that later maybe.

The second part

Okay, now we're going turn our "Hello world!" console print test into a console command! But, in order to do this, we need to meet a new friend: COM_AddCommand

Now, using COM_AddCommand is a little more complicated than our first function, print. With print, you only needed one argument, which was the text message to print in the console. With COM_AddCommand, you need two arguments: the name of the command, and the function for the command to call when you execute it in the console.

What is a function, you may ask? I'm not sure how exactly to explain this very well, but the best I can say is what it does: whenever you call a function somewhere else, all the code you put inside it will be run that instant. When creating a function, you start with local function, then the name of the function (e.g.: myfirstfunction), then its arguments inside a set of parentheses (as in these things: ()). Since we won't have any arguments in our first example, the parentheses should have nothing in them! After that, is the code we want the function to run when called, which in our case will be print("Hello world!") (or whatever you want). Last of all, is the word end, which marks the end of the function.

Anyway, let's get to the good stuff:

local function myfirstfunction()
	print("Hello world!")
end

COM_AddCommand("test", myfirstfunction)

This code creates a new console command named test, which when called itself calls the function myfirstfunction.

Try it out and see if it works (if it doesn't I'll eat my non-existent hat). All you have to do is type test into the console, press enter, and

Hello world!

should appear in it. And huzzah, we just made a custom console command!

Did you want to name it something else though? Go ahead if you like, this is your script after all, not mine.

local function myfirstfunction()
	print("Monster Iestyn is the greatest tutorial maker ever!")
end

COM_AddCommand("iamthebest", myfirstfunction)

Some clever-clogs might point out that you can actually define the function within COM_AddCommand, like this:

COM_AddCommand("iamclever", do
	print("I am a smartie!")
end)

But this basically just does the same sort of thing as what I showed you already. It just means you don't need to give a name to your function. But on the other hand, you can't actually use that function anywhere else if you do!

I like the first way better because the second way just makes people get confused about ends and everything. And clarity is good.

Part the third

(to be written once I decide how to go on a bit further with this tutorial)