Basic scene setup

Step 1: Create the project

Create a directory on your harddisk, i.e.

c:/luxtutorial

Create a textfile named main.lua. Open the file and write in the first line

print "Hello World"

Step 2: Start the project

Start the luxinia.exe file with the argument -p c:/luxtutorial (and replace the path with your directory you created in step 2).

If successful, you should be able to see the two windows that luxinia opens:

Create a shortcut or configure your editor to start luxinia that way - we will need to start luxinia quite often from now on (anytime we change some files - though it is possible to reload luafiles, this is an advanced topic).

Step 3: Create a simple rendering queue

When starting, there is no rendering queue set (introduced in .97). There is however a very simple function call that will restore a quite simple rendering queue, clearing the background with a color:

view = UtilFunctions.simplerenderqueue()

view.rClear:colorvalue(0.0, 0.0, 0.0, 0) 
  -- ^^ clear with black backgroundcolor

If you start it, you will see a black background in the luxinia window.

You can change the colorvalue by replacing the 0.0 values by values between 0 and 1. The first value stands for red, the second for green, the third for blue and the fourth value for the alphavalue, which does not affect the visual appearance at the moment. Color arguments are always passed in this form, if not clearly stated different. This color model is also refered as RGBA.

You can change now the background colors and see the changes

Step 4: The console

Any global variable can be manipulated from the console inside luxinia. Every variable in lua is global if it is not declared as local.

Start Luxinia and open (and close again) the console by pressing the F1 key. You will see a blue console and you can start typing text. Type

view.rClear:colorvalue(1.0, 0.0, 0.0, 0)

and see what is happening (of course, the background will turn red).

Step 5: Handling errors

When developing code, you will encounter errors. There are two types of errors:
  • Compiling errors
  • Runtime errors
Compiling errors occur if the textfile that is being compiled as luacode has syntax errors. Most often, you will just forget to close a bracket, putting a comma at the correct place, and so on. These are called syntax errors. Syntax errors are often easy to be traced. For example:

 
print "Hello World
print "OK"

Obviously, we didn't close the string by putting a " at the end of "Hello World". Any error will be delegated to the console, just like in this case:

(click to enlarge)

Reading these errors the right way is important to trace mistakes.

A runtime error can be quite different. For example

view = UtilFunctions.simplerenderqueue()

view.rClear:colorvalue(0.0, 0.0, 0.0) 
    -- oups, forgotten  the alpha value!

Console output:

 1 rcmdclear 4 floats required
stack traceback:
        [C]: in function 'colorvalue'
        d:/tutorial/main.lua:3: in main chunk
The projectpath d:\tutorial could not be loaded. So
rry. Error was:
1 rcmdclear 4 floats required

So what to do now? Syntax errors are often easy to track down. Lua says in which line the error occured, like

 file.lua:23: unfinished string near '<eof>'
The :23 afer file.lua (which says in which file the error occured) tells us, that there was a string that startet in line 23 that was not finished. always start with the line number and check what could be wrong there. The lua compiler tries to keep the error message readable, but sometimes, it cannot help too much.

The runtime error above occurs, when the script is executed. A function that was called (in this case colorvalue), produced an error that said, that the function requires a rcmdclear argument and four float values. We passed the first value when we used the colon operator.

view.rClear:colorvalue (...) is 100% equivalent to view.rClear.colorvalue (view.rClear,...) or rcmdclear.colorvalue(view.rClear,...).

The colon operators passes always the first argument from the string before! Always check if the function was called with a colon or point! Beginners and sometimes even advanced programmers (in some nasty cases) tend always to struggle with that problem!

The stacktrace which is refered in the error output refers to the functions that were called. I.e. if we have that script here:

function makingerror()
  error("reached this")
end

function foo ()
  makingerror()
end

foo()

The stacktrace will be printed like this:

 d:/dev/lua/luxiniaprojects/tut/main.lua:2: reached this
 stack traceback:
        [C]: in function 'error'
        d:/tutorial/main.lua:2: in function 'makingerror'
        d:/tutorial/main.lua:6: in function 'foo'
        d:/tutorial/main.lua:9: in main chunk

We notice here, that the stacktrace begins in a function that is marked as [C] - this means, that the function is located in the C part of the program. In most cases, the error is however introduced before that function was called, so we can go back by reading the next line of the stacktrace, which refers to the file and the linenumber 2. You can see, that any function call is listed in that output, and we can go back and see, which function called which one.