BlendELF, Tutorial 1, BlendELF Basics

I assume you have already gotten yourself the BlendELF Development Kit, but if not, then head to http://blendelf.com and get yourself a one! The BlendELF Development Kit contains the engine executables and the level files we will be using for this tutorial.

First extract the developmet kit zip to a folder of your choice, preferably an empty one. My folder now looks like this:

Your folder might look a bit different, depending on what operating system you are using (I'm using Ubuntu 10.04 in the screen shot) and what version of blendelf you are using, but the point is that you have the necessary files in there. Also sometimes your operating system wont display the file extensions of the files (.exe/.dll/etc), but that shouldn't be a big problem either. Here is a little overview of the files in the development kit:

BlendELF.exe and the DLL files are used to execute the windows version of the engine
blendelf and the files in linux_libraries folder are used to execute the linux version of the engine
LICENSE.txt file contains the license of BlendELF and the licenses of the libraries that it uses
tools folder contains the blender scene exporter
docs folder contains the (Lua) API doc of BlendELF
cppsdk folder contains the C++ software development kit of BlendELF
dotnetsdk folder contains the .NET software development kit of BlendELF
levels folder contains sample levels for BlendELF

The levels folder should contain a file name level1.pak. PAK files are the BlendELF scene files. They contain all of the textures/models/entities/cameras/lights/armatures/etc of a single scene. Put the level1.pak file into the same folder where BlendELF.exe or blendelf files are.

My folder now looks like this:

You see that I added the level1.pak file there? Great! Now we have everything we need to load up a scene in BlendELF.

Go ahead and create a text file called init.lua into the folder you extracted the development kit to. Don't worry if your operating system warns you about the .lua extension. You can still open the file in a pure text editor like notepad in windows or gedit/kate/vim on linux.

My folder now looks like this:

Wait a second! Whats init.lua??

I'm glad you asked! Let me explain. init.lua is a Lua script file and most of the time, it will be the heart of your game. You will write the main loop of your game into the init.lua script file. The main loop will keep your game running as long as you don't quit the game. NOTE: it is really important that you put the init.lua script file into the same directory where BlendELF.exe/blendelf files are. Otherwise BlendELF wont find it.

Lua? Never heard of it...

Lua is a very light, portable and simple scripting language that is widely used in the game industry. For more information, please visit lua.org. Due to its simplicity, it is very easy to pick up, even for beginners. So lets get our hands dirty and put BlendELF to work!

Open up your init.lua script in a pure text editor, like notepad on windows and gedit/kate/vim on linux. First we need to load a scene. We can do that with the elf.LoadScene function which takes a single parameter, which is the file path to the PAK file you want to load. Lets write our first line:

Ok so now our script loads the scene, now we need our main loop. Lets write it after we loaded the scene:

Thats our whole init.lua script file! But before we run it, lets see what we did there...

We made a while loop for our main loop. Each time the while loop is ran, it checks if the elf.Run() function returns true, and if it does, it continues running. The do keyword is just to indicate that we are done with testing and we are good to go to the execution part of the loop. The end keyword on the third line indicates that we can go back to testing if we should still run the while loop.

The elf.Run function runs the whole engine for one frame (renders the scene and runs audio, physics and game logics) and returns true if everything was fine. If you by any chance call elf.Quit at any point of your game/application, then the elf.Run function will automatically detect that you did so, and next time it will return false and you application exits. The same happens if you close the engine window.

So we finally get to run the engine! On windows, double click BlendELF.exe. On linux, double click blendelf or run it from the console.

Help, it doesn't run!

That could be because your computer doesn't support at least OpenGL 2.0, or because your init.lua script contains an error. BlendELF prints errors to the console and saves them to elf.log file in the same directory as your BlendELF executable (BlendELF.exe or blendelf), so check either one for errors. The only type of error that BlendELF doesn't store to elf.log is an invalid handle error. That is because the invalid handle error doesn't stop the execution of a script, so writing it to elf.log several times during one frame could potentially slow the engine down too much. So check the console for those.

If everything goes well, you should see something like this:

Congratulations if you did! I hope you enjoyed the tutorial, and if you have any comments about it, please post to the forums.