What You Need

Two things: VS Code and LÖVE. On a lab computer both are already installed and you can skip straight to the next section.

LÖVE is doing two jobs at once. It runs your Lua code, and it is also the drawing library this course uses. That is why there is nothing else to install — no separate Lua, no package manager, and nothing in this course needs an internet connection once you have the workspace folder.

Working on your own computer? Install VS Code from code.visualstudio.com and LÖVE from love2d.org. Get LÖVE 11.5 if you are offered a choice — error messages change wording between versions, and that is the one this course is written against. On a Mac, install it by running brew install --cask love if you can, because that puts LÖVE somewhere the Run button can find it.

Get the Workspace

1. Download it. lua-workspace.zip
2. Unzip it. Right-click the file and choose Extract All. You want the folder somewhere you can find again — your Documents folder is fine, your Downloads folder is not.
3. Open the folder in VS Code. File > Open Folder, then pick the lua-workspace folder itself. Not the folder above it, and not a file inside it.
4. Say yes to the extensions. VS Code will offer to install three recommended extensions. Click Install. The Run button does not exist until you do, and the offer only appears once.

If you missed the extension prompt, open the Extensions panel and type @recommended in its search box. The same three will be listed.

Your First Program

Inside the workspace there are two folders whose names start with template-. You never work in them. You copy one, rename the copy, and work in that. Every activity in this course starts the same way.

1. Right-click template-console and choose Copy, then Paste. You get a second folder.
2. Rename it to 1-01-first-run.
3. Open main.lua inside it. It already contains this:

1
io.write("What is your name? ")
2
local name = io.read()
3
print("Nice to meet you " .. name)

Press the Run button — the ▷ at the top right. A terminal panel opens at the bottom, asks for your name, and waits. Type it and press Enter:

What is your name? Ada [Enter]
Nice to meet you Ada

That is the whole loop for this course: copy a template, write, press Run, read what came out.

Two Templates, and They Are Not Interchangeable

template-console — a program that prints text and reads what you type. No window opens. main.lua is ordinary Lua: it runs from the top of the file to the bottom and then the program ends.

template-game — a program that opens a window and draws in it. Here main.lua is a set of functions that LÖVE calls for you, over and over, many times a second:

1
function love.draw()
2
    love.graphics.print("Hello World!", 400, 300)
3
end
4

5
function love.keypressed(key)
6
    if key == "escape" then
7
        love.event.quit()
8
    end
9
end

You did not write the code that calls those. LÖVE calls love.draw every frame, and love.keypressed whenever a key goes down. Think of them as boxes the engine opens: you decide what goes inside, and something else decides when to look. We come back to what function really means later in the quarter, and by then you will have been writing them for weeks.

What the Run Button Actually Runs

Run runs the folder, not the file. It looks at whichever file you have open, finds the folder that file is sitting in, and runs the main.lua there.

Most of the time this is exactly what you want: you can have any file in the activity folder open, press Run, and the activity runs. Two rules keep it that way.

• One activity per folder, each with its own main.lua and conf.lua. That is what copying a template gives you.
• No folders inside an activity folder. Open a file one level down and Run points at the wrong place.

Where Your Work Goes

One folder per activity, sitting next to the two templates, named the way the activity page tells you. Nothing else to organize.

Reading an Error

Read the message before you change anything. Where the message appears depends on which template you copied, so that is the first thing to notice.

It started, then stopped

A console program that asks for something that is not there:

local scores = {90, 85, 78}
print("Third score: " .. scores[3])
print("Fourth score: " .. scores[4])

Third score: 78

Error: main.lua:3: attempt to concatenate a nil value

  main.lua:3: in main chunk

Notice that the first line printed. The program ran, got to line 3, and stopped there. A list with three things in it has no third-and-then-some — there is no scores[4], so there was nothing to join onto the text.

Nothing runs at all

A missing end:

local x = 5
if x > 3 then
    print("big")

Error: Syntax error: main.lua:4: 'end' expected (to close 'if' at line 2) near '<eof>'

Nothing printed, because the program never started. Read this one carefully — it names two lines. Line 4 is where Lua gave up looking, and line 2 is where the thing it was looking for should have been closed. The mistake is almost always at the second number, not the first.

A blue screen instead of your game

When a program that draws hits an error, LÖVE takes over the window and fills it with a blue screen showing what went wrong and the line it happened on. Read it, press Escape to close it, fix the line, run it again.

The tell is whether anything happened first. Output and then a stop means the program ran and hit something part way through. Nothing at all means it never got started, and that is nearly always a missing end or an unclosed quote.

If Something Goes Wrong

The window is black and nothing is happening

Your program is waiting for you to type something. Click the terminal panel at the bottom and look — there is a prompt sitting there. This is the single most common thing that looks like a crash and is not, and it happens when a program both draws and reads input, which is why the activities never ask you to do both.

A blue screen appeared and I cannot get rid of it

Press Escape. That closes it and ends the program. The blue screen is LÖVE reporting an error rather than anything being stuck, so read what it says before you dismiss it — it names the line.

The Run button is not there

The Code Runner extension did not install. Open the Extensions panel, search @recommended, and install all three.

Something about lovec not being recognized

LÖVE is not installed, or the Run button cannot find it. On your own computer this is the most likely thing to go wrong, and it is a setup problem rather than a problem with your code. Tell me and bring the exact message.

Run does nothing, or runs the wrong activity

Check which file you have open. Run uses the folder that file is in, so an open file from a different activity runs that activity. If you put a folder inside your activity folder, take it back out.

I opened VS Code and everything looks plain

You opened the wrong folder. VS Code has to be opened at lua-workspace itself, not at the folder containing it, or the settings that make any of this work are not loaded. Close it and reopen with File > Open Folder.

The program will not stop

Either the terminal is scrolling forever or the window is frozen. Press the trash-can button at the top of the terminal panel — its tooltip says Kill Terminal. Pressing Run again does not help, and neither does closing the file. Ctrl+C sometimes works and sometimes does nothing, so go straight to the button.

Something else

Tell me, and say what you pressed and what appeared. A setup problem is not something you should spend the period on.