# Tutorial
## Initialization and Deinitialization

Lua scripts are usually run in a VM (Virtual Machine). Therefore we first start one and then load the basic Lua libraries:
The byte pointer returned by luaL_newstate is needed for every Lua function call. Now you're done with initialization and can begin running scripts.
Closing the Lua VM afterwards is done by a single function:

## Running a simple script

Lua Scripts can be executed directly from Blitzmax Strings.
This code loads and compiles the script. luaL_loadString returns a value <> 0 if something went wrong.
These commands are not important for now, they're just there to get proper error messages.
This line actually executes the script. Again, if it's return value is <> 0, an error occurred. If everything worked though, the program will display a "Hello World!", as intended.

## Calling BlitzMax functions from Lua
### Basics

As you may have noticed, being able only to run a script but not to interact with BlitzMax isn't extraordinarily useful. Therefore the next step consists of learning how to call a BlitzMax function from a Lua script. Unfortunately we can't just use an arbitrary function, as the function has to follow a specific layout:
Obviously, the arguments submitted with the function in the Lua script aren't directly transmitted to the BlitzMax function. We'll have to handle them manually, but not right away. First we have to register the function to Lua:
BMXName can now be called from Lua (globally) as luaname. You may choose to name your functions the same as in BlitzMax, but you don't have to.

### Handling parameters from Lua

Let's say we've tried to call
from Lua using the example function above. Lua didn't complain about the additional parameters but we're not able to access them from within the function, either. Where have they gone? Lua has placed them onto the parameter stack. Each parameter is assigned an index through which it can be identified. The indices are consecutively numbered and begin with 1. Thus, 810 can be found at index 1 and "Hallo!" at index 2. Now we just need to know the respective commands to read the values from the parameter stack and we're done:

### Returning Values to Lua

Returning one or several values to the Lua script works similarly, but you don't have to specify indices as values are automatically appended to the stack. Here's an example:
In most cases you'll be returning only one or no value at all, but as shown, more are possible, too.

## Calling single Lua functions from BlitzMax

We know how to execute whole Lua scripts, but what if we only need a single function? In that case, you first have to put the function to be called onto the stack, then the parameters. Here's an example. Lua Script:
BlitzMax Code:
Returned values, if any, are placed onto the stack after the function was executed.

## Accessing Lua Globals from BlitzMax
### Defining or changing a global variable

The first command writes "Hallo!" onto the Stack and the second puts it into the global luaglobal.

### Reading a global variable

The first command puts the value onto the stack, the second puts it into the BlitzMax variable.

### Accessing all global variables

If you want to save the current status of your Lua VM, you need to find a way to get all global variables. One way to do this is using the lua_next function:
Note that this method returns not only global variables, but also functions, tables, etc. which you need to sort out using the lua_type command.