FS2 Open Lua Scripting

This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.

What You Need

You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.

Here we go!

Comments

A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)

For example, this:

--This is a comment
mn.loadMission("sm2-10.fs2") --Load a mission
--Greetings!

Will do exactly the same thing as this:

mn.loadMission("sm2-10.fs2")

Variables

A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here is a variable, as it may be seen in the wild:

x = 42
--x is 42
y = x
--y, copycat that it is, is now also equal to 42

Types

However, variables can hold different types of data. These basic types are:

Boolean

A boolean is a simple variable - it can be true, or false.

--It's Monday, and Dilbert is at the office
working = true
--Oops, he just opened Solitaire
working = false

Numbers

A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.

--A variable can be a whole number, like this
x = 5
--Or it can be a decimal value
x = 3.141592654
--Or you can divide two numbers for a fraction
x = 3/4

Strings

A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.

--A cow says moo!
cow = "moo"
--A friend's name
friend = "Bob"

Note that actual string content is contained within double quotation marks, to mark it as a string.

nil

nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.

--Today I got a new dog
dog = "Spot"
--But then he ran away
dog = nil

Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).

Userdata/objects

Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".

--Assuming we have a my_car object, this will copy it to your_car
your_car = my_car
--Congratulations! But maybe you want to customize it?
--Note how I refer to the member variable, color
your_car.color = "Red"

Handles

A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.

--Get the "GTF Ulysses" ship type
--For this, I use the function 'getShipclassByName'
ulysses = tb.getShipclassByName("GTF Ulysses")
--Now get rid of the handle
ulysses = nil
--Even though we've gotten rid of the handle, the Ulysses will still exist.

Scope

The scope of a variable is the area where it exists. By default, all variables exist everywhere; however, if you define your own function, writing 'local' in front of the variable name will tell Lua that the variable should only exist within that function.

Note that this means that if you make a variable called 'x' in one hook, and a variable called 'x' in another hook, they will actually be the same value.

Functions

A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions.

For example:

doSomething()

This single line of code would, presumeably tell Lua to do 'something'. What that something is, depends on what the function is supposed to do. Note the two parentheses after the function name; these tell Lua to run the function. (There are reasons to use function names without the parentheses, but that is one of those 'advanced topics')

Here's all the different kinds of functions you can have:

--A function provided by itself
x = cos(y)
--A function provided by a library
x = ma.cos(y)
--A function provided by an object
x = y:cos()

In every case, x would be set to the cosine of y, which is 1.

Functions may also have multiple arguments:

gr.drawString("Hello!", 5, 10)

This tells Freespace 2 to draw the string "Hello!" on-screen, starting at the point 5 pixels down from the top of the screen, and 10 pixels from the left of the screen.

Finally, a full example!

By this point, you may be bored of all this exposition. So let's actually use variables and functions to do something in Freespace!

For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:

#Global Hooks
$Splash:	[
	--Set the color to white
	gr.setColor(255, 255, 255)
	--Write "Hello, world!"
	gr.drawString("Hello, world!", 5, 10)
]
#End

Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.

Making your own functions (Optional)

So, let's make the doSomething() function do, well, something.

doSomething = function()
	color = "red"
end

As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"

Now, let's use our new doSomething() function.

color = "black"
doSomething()
--After using doSomething(), color is now red

Functions can also return values.

--Make a new function
doSomethingElse = function()
	return 10
end
x = 0
doSomething()
--x is now 27
x = doSomethingElse()
--x is now 10

Libraries

A library provides various functions, which may in turn provide various objects or handles with their own functions. All Freespace 2 libraries are named using two letters. "Graphics" is "gr", "Mouse" is "ms", and so on.

You can see how functions in a graphics are referenced in the "Hello, world!" example above.

To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries and functions supported by that build.