Getting Started with Visual Studio Code for SRB2 Lua

This guide is derived from Ash's guide on the SRB2 Wiki, which can be found here.

Before I begin, I'd like to make note of the files required to follow this guide, as well as give credit where it is due.

Visual Studio Code may be downloaded and installed from this website.
The required extension to begin coding must be downloaded here.

This guide is inspired by Ash's guide on the SRB2 wiki. Without it, I would never have used Visual Studio Code to script. This guide also uses the SRB2 Lua extension by LJ Sonic, which is a fork of sumneko's Lua extension. If you find you have any problems with this guide, do let me know. If there is a problem with the extension itself, please report it at the extension's GitLab repository.

• 1.0 Introduction to Visual Studio Code​
  • 1.1 What can Visual Studio Code do?​
  • 1.2 What can't Visual Studio Code do?​
• 2.0 Install Visual Studio Code​
• 3.0 Install the SRB2 Lua extension​
  • 3.1 Configure the SRB2 Lua extension​
• 4.0 Create your first mod using Visual Studio Code​
  • 4.1 Simple first script​
  • 4.2* Error suppression​
  • 4.3 Autocompletion with hook parameters​
  • 4.4 Loading your mod​
• 5.0* Create your own libraries using Visual Studio Code​
  • 5.1* Function signatures and comments​
  • 5.2* Classes​

1.1 What Can Visual Studio Code Do?​

Visual Studio Code, which I shall refer to as VS Code for brevity in most of the guide, is a free and lightweight text editor developed by Microsoft. It is designed to be highly customizable, and as such does not come with tools to develop for specific languages out-of-the-box. Some of the most useful features of VS Code include:

• Syntax highlighting for many programming languages,
• Auto-completion to suggest functions, variables, and parameters,
• Built-in Git support for version control,
• Linting support that allow you to catch errors without entering the game.

With the correct setup, VS Code can be a tool that saves many seconds, minutes, or even hours over its competition, SLADE and Notepad++, which have none of these features.

1.2 What Can’t Visual Studio Code Do?​

Despite its powerful features, VS Code has some limitations that can make it appear inaccessible or unattractive to potential users:

• Unlike SLADE, VS Code does not support converting textures into SRB2-compatible lumps,
• It cannot edit maps like SLADE can,
• and cannot access, nor modify PK3 files.
• The linter is fallible; though better than nothing it can and will create false-positives and false-negatives.

However, nothing is stopping you from running these applications alongside each other for the best possible modding experience.

For the remainder of the guide, I will be showing this guide as displayed on a Windows machine. However, it should apply for most, if not all systems where Visual Studio Code is supported.

We begin by visiting Visual Studio Code's official site, found here. Do not confuse Visual Studio Code for its similarly named -- and particularly less lightweight -- brother, Visual Studio. Visual Studio is not capable of editing Lua.
Click Download for Windows, or whatever it might say for your platform, and run the installer. Once it is finished, open the application.


Congratulations! You have successfully installed Visual Studio Code.

In order for the suite of features, such as linting, syntax highlighting, and auto-completion to take effect, we must first install the SRB2 Lua extension, which enables these features. Begin by downloading this file from the SRB2 Wiki.

Unzip it in a folder you believe you will not move often.

Open Visual Studio Code, and click the Search bar found at the top of the window.

Type "> Install From VSIX", and click the first option that appears.
Find and input the .vsix file we extracted earlier.

You have now installed the SRB2 Lua extension. To verify, click the Extensions icon on the left side of the window:

and locate the SRB2 Lua extension.

3.1 Configure the SRB2 Lua Extension​

As it is now, we have not configured the extension to work correctly with SRB2 code. To correct this, click the cog next to the SRB2 Lua extension in the previous image.

Near the bottom of the file, locate the "Lua > Workspace: Library" setting:

Click "Add Item," and enter the directory where "srb2defs.lua" is located, which should be in the same folder as the .vsix file we have installed.

For safety, change these two options to the values shown below:

You have now configured Visual Studio Code for use with SRB2 Lua.

Let's begin by creating our first mod with Visual Studio Code. Create a new folder in the folder where SRB2 is installed, and name it whatever you want. For the purposes of this guide, I will be naming it "Our First Mod".

In this folder, add a sub-directory named "Lua", like so:

In Visual Studio Code, click File > Open Folder > ...\Our First Mod.
In the folder view, right click the Lua folder, and click New File. Name it "Hello.lua".

Now, let's write some code!

4.1 Simple First Script​

Here's a simple script that prints out "Hello, {name}!" whenever Custom 1 is pressed. Awesome- ah, wait!

Ah, it caught us! We forgot to add "then"! But... that's perfectly valid syntax in SRB2, isn't it? If you would prefer omitting "then" and "do" while scripting, proceed to 4.2. If not, skip to 4.3.

4.2 Error Suppression​

Return to the extension settings menu by clicking the cog on the SRB2 Lua extension once more, and search "Disable."



Now, let's see which error we should disable. Hm...

Ah! There it is. "miss-symbol." Click "Add Item", and find "miss-symbol" in the drop down. Now, this code is pure and error free! Let's test it out on this code:

Oh, come on! Another error? err-nonstandard-symbol... well, if we suppress that, then even symbols that don't exist, like _= will make it through. Let's just add all of the symbols that SRB2 does support!

Now you're ready to move on to the next part of the guide.

4.3 Autocompletion with Hook Parameters​

If you were typing the previous script by hand, you might notice that when you typed a constant like BT_, many names showed up, like this:

But oddly, when you typed player., the same thing doesn't occur:

This is because the linter has no idea what player is right now, so it just assumes it can be anything. The wiki states that the one and only argument to "PlayerThink"'s function is a player_t, so let's specify that to the linter:


Now that it knows what player should be, we can perform a name lookup on it:

This is especially useful if you don't want to keep switching between the wiki and the text editor, and to prevent typos. Let's revert the code back to how it was:


and continue.

4.4 Loading Your Mod​

If you've made it this far, congratulations! You've completed nearly every step to get started with Visual Studio Code, and can now load your mod! Let's begin by opening the game:

Now, open the developer console by pressing the grave key (`) located at the top left of the keyboard, typically below "esc" and above "tab":
Type "addfolder MY_FOLDER_NAME", with MY_FOLDER_NAME being whatever you named your mod's folder in quotes. In my case, it'd be "addfolder "Our First Mod"":

Now, hit enter and test it out! You have successfully loaded your mod into the game! Note that the structure of your mod folder should mimic the structure of a PK3, if you were using one.

Although this is largely something that can be probed by reviewing the initial "srb2defs.lua" file, I'll go into detail on how exactly to create your own libraries and library files. To begin, let's create a file called "modlib.lua" with the following contents:


This specifies to the linter that this file contains definitions of data. To make sure it isn't loaded, move it outside of the Lua folder.

5.1 Function signatures & comments​

In order to include a function signature, outline the function prototype (the function's name, and its parameters.) Let's define a hypothetical action, A_DoNothing(actor, var1, var2):


As it is now, no additional information about the function is provided. First, we should decorate it with the parameters. Start by adding three dashes and an @ symbol, then press tab.


The comment field will give information about the function, and ---@param simply informs the user what type to provide to the function. Filling out the details, we can flesh out the function signature:

Additionally, you can specify the return type, though this is unnecessary when the function does not return anything:

Now, you can apply this information to all exposed library functions.

5.2 Creating classes​

Classes sound scary, but they are simply a way to specify how a table should be perceived, kind of like userdata. For example, we know that a mobj_t value always holds an x, y, and z values, and that these values are always fixed_t. We can use classes to hint at these things so that the linter has an easier time with autocompletion.

Let's begin with a hypothetical -- but common -- scenario; a player should hold character-specific data. We'll call it a "kirber_t", and it'll have two fields: Stupid, which is a true or false value, and HowStupid, which is an integer. Well, how can we tell the linter how we want this structure to be laid out? We can use the "---@class" comment to lay out a specific structure, and refer to it later on, like so:



But, how do we 'refer to it later on?' Well, the same way we have during this whole guide, with "---@param":

Alternatively, you can even use the "---@class" comment to specify what class a table is of:

or have it be the return type of some hypothetical function:

If you have read this guide to its end, I thank you for your time and consideration of this guide, and I hope your experience with VSCode is a smooth one. If there is anything you find particularly ambiguous in this guide, do let me know in the comments section, or shoot me a message on Discord at @kirberburgy.