The goal of this tutorial is to teach you the very basics of the GIANTS engine. You simply load an i3d with a cube in it and then rotate the cube by using LUA script.

Sample name: SampleI3DLoading
Script source code file: sample/i3dLoading/main.lua



The goal of this tutorial is to show you

• how the engine uses ids
• how to load i3d files
• how to access objects within a loaded i3d
• what the base callback functions of the engine are
• how to access keyboard commands

New functions in this tutorial

init()
keyEvent()
update()
rotate()
getRootNode()
loadI3DFile()
link()
getChildAt()
print()
requestExit()

The most important script file is your main.lua. It is a lua file that is loaded and executed when your exe file is started.

The first thing you need to know is how the engine exactly knows where your main.lua is. Well there has to be an xml file in the same folder as your exe with exactly the same name as your exe. In this case it is named SampleI3DLoading.xml. Open it with a text editor.


In the third line you see where your main.lua is located. If you want to move your main.lua, you have to change the path in this xml as well.

So, let's have a look at this main.lua, open it with any text editor. There are 5 essential functions: init(), mouseEvent(), keyEvent(), update() and draw(). Let's look at these functions in detail:

init()

init() is executed once when you start your exe. Let’s go through the function line by line:

 local worldRootNode = getRootNode();

The variable worldRootNode is defined and assigned with the result of a function called getRootNode();

If you meet a new function and you don’t exactly know what it does, simply look here and search for the function. Then you get detailed information about the function. In the tutorials those function descriptions are always blue.
Here is what you find if you search for the getRootNode function:

The descriptions of the functions are quite self-explanatory and can be really helpful.

It's important to see that the GIANTS engine works with ids also called handles. This function returns the id from the root node of your root scene graph.

Your entire world is attached to this root node. Each object you want to see later on must be a child of this root node.

Now we need to load the i3d that contains the cube we want to rotate later on.

 local sceneToLoad = loadI3DFile("sample/i3dLoading/cube.i3d");

With this function, you load an i3d file, and its id (which is an integer) is returned. Now that we’ve got both things, the worldRootNode and the i3d we want to load, we have to link them together, which is the next line of code.

 link(getRootNode(), sceneToLoad);

Now we want the cube's id to rotate. Be aware that the i3d we've already loaded is the whole scene which contains not only the cube, but also a light and the camera. So now we need to know which id the cube has. Since the cube is a child of the i3d we can use the following function:

 cubeId = getChildAt(sceneToLoad, 0);

First you name the i3d that you want the child from and then you say which child you want. 0 is the first child, 1 is the second. You need to know which child is your cube. Just open the cube .i3d with the Editor and you can see that the cube is the first position in your scenegraph (reading from top down)



A very important thing you need in programming are prints. The function needed here is simply called print(). The thing you want to print are the parameters. Be careful with strings, they always need quotes. You can link strings and variables by using .. as shown in the example.

 print("this is a print: cube id: " .. cubeId);

You can see the printed text in the in game console. Just press tilde '~' to make the console visible.

Now we have all the information we need, but one thing remains to be done. Since the camera is located right in the center (inside the cube actually) we won’t be able to see anything. So we grab the camera and move it a bit. With the getCamera() function we first get the id of the camera, because the setTranslation function needs to know which id has to be translated. The next parameters are the desired x, y, z values.

 setTranslation(getCamera(), 5, 10.0, 10.0);

Then we rotate the camera so that we can see our cube nicely. The function is similar to the setTranslation but you define the rotations around the three axes of course. You need a radian value, that’s why the functions math.rad() are used. They convert a degree value into a radian value.

setRotation(getCamera(), math.rad(-45), math.rad(20), 0);

mouseEvent()

We don’t use this function right now, but of course you can access the mouse commands with it.

keyEvent()

This function is used to access any keyboard commands. In this case, we only want to know if the escape key is pressed. If this is the case, then the program closes with the command requestExit();

update(dt)

The update function is a function that is called after every frame. The parameter dt is the time that has passed since the last update call in milliseconds.

So, this is the place where we can finally make our cube rotate. For this we use the rotate(dt) function. It needs the id of the object that should rotate, in this case the cubeId, and also the rate of rotation on the x, y and z-axis. We just let it rotate on the x-axis with the value of 0.08 degree per millisecond.

draw()

The draw function is needed to draw something onto the screen. This will be discussed later on.