(( This tutorial also been posted on ndsupdate.com by yours truly. hehe ))

I see the world of DS Lua is quite small as it is, and so, many people would probably like to contribute to the great DS community. DS Lua allows you to code your games without too much programming experience and I so decided to make a tutorial to allow everyone to be able to understand it simply. I'll be making a serie of tutorial in this thread as the versions will evolve with time.

Before beginning two notes. First, my grammar might be slightly bad because I am not native english, so please bear with it. As for me, I just began coding DS Lua today, so, doing this tutorial, I will be learning as well. I have a lot of programming experience, so it comes to be easy for me, but I will make it as simple as possible so even people with almost no programming experience learns it and can use it as well. Although, I'd HIGHLY suggest to learn programming basics (such as syntaxes and variables) as I won't start explaining them in details.

Getting Started
First you indeed need some programs to be able to use DS Lua. They all can be found around the internet. Also, you may need a Nintendo DS and a Flashkit. Personally, I do not own a DS as of yet, but I can use my girlfriend's one which is a Firmware v3 DS with a SuperCard SD Flashkit (using the lastest firmware) and Flashme as pass key.

In terms of software, we will be getting our "development kit" ready. Lua is an interpreted language, as so, it doesn't need to be compiled (from code to binary executable file) but in the case of the Nintendo DS, it must be packed into a ROM file to be able to work. I will explain as we go.

First, you need DS Lua Player (lastest version being 0.4 as I am writting this). You can find this on their website ( http://www.dslua.com/ ). You will need to download the GBFS Flavour of it to be able to make it work with the emulator (which is much faster than passing your time constantly transferring your rom to your CF or SD).

Then, I highly suggest to get an emulator to be able to work it out. Dualis is the best emulator out there for this purpose. Get the lastest version (20.1) on their website ( http://dualis.1emulation.com/ ). It supports sound, stylus, and double screen, impressive, eh ?

Ok, now we got the Lua Player, the Emulator, so we need a development environment. You can use notepad (which tend to be slightly boring after a while because it obviously lack of features), or you can use something else as long as you can do text file editing with it. As we speak, I start considering making a DS Lua IDE, but that's for later anyway. I highly suggest getting Crimson Editor ( http://www.crimsoneditor.com/ ) as this is what I use and the whole interface is quite self-explanatory.

Good, so, we got all our basic programs to be able to begin making our first "hello world" application ! A great world of possibilities is in front of us, so, let's get going !

Preparing the developping environment
Good, so you've installed all your softwares, we are now ready to begin setting up our environment to make things very easy for us (and avoid going back and forth between window in order to test). Programmers are lazy people, less time it takes, better it is for them ! Actually, there is a good reason to that and it's not lazyness, hehe. First things first.

Go to your DSLua directory (where you extracted the files) and locate the folder "Scripts". As these are valuable examples for your learning, just rename it to "Example" and create a new directory called "scripts". Why ? When we'll create the final rom, the software will pack whatever is in the "scripts" directory with the player's rom to create our final rom. Done ? Good ! Now, located the file PACK.BAT and right-click on it to select "Edit". It will open a notepad with a bunch of stuff written in it. Don't worry, you must not care about this, as this is the process of packing the whole thing into the final rom.

Now, go to the end of the file and add this line:

I highly suggest (for your own sanity) to have a copy of dualis emulator at the same place as the PACK.BAT if you really don't want to, then before "dualis.exe" in the line, add the path of where it's located. The command-line is the path to the nds file of the final rom, ready to be executed. This makes things easier. Just save the file and you are done.

THE NEXT STEP IS COMPLETLY OPTIONAL AND IT'S IF YOU ARE USING CRIMSON EDITOR. IF YOU DO NOT WISH TO USE THIS, SKIP TO THE NEXT SECTION "HELLO WORLD EXAMPLE". Ok, so, if you are using Crimson Editor, you can configure a macro to automatically pack your rom and execute as you test. Avoids anymore interaction with windows during your programming and it's even faster. To do that, follow those steps:

1. Open Crimson Editor
2. Click on "Tools" then "Preferences"
3. Select "User Tools"
4. In Menu Text input "DS Lua Run", in Command, click on the browser button (...) and select your PACK.BAT file, no need of arguments and the initial dir is the path to your PACK.BAT (without the filename). Finally, click on the "Hot Key" field and press on the button you wish to associate this to. I usually use F5 or F9. Then remove the check beside "Close on Exit" and make sure that "Save before execute" is checked. Then click on "OK" and you are done.

Whenever you'll want to test your game, you will be able to do so by pressing the hotkey you associated this with, so, if you chose F9 for example, by pressing F9 it will save the file (some standards must be followed, so, continue reading this before) and will run PACK.BAT. This makes things even more easier.

Hello World Example
Good, now you have a fully working environment ! Time to start coding our first program. If you never code before the "Hello World" is a big convention when you begin learning a programming language. So let's start easy. Here's the program as it looks like, note that I added line numbers but those are not there generally.

Example 01: 01 - Hello.lua

Lines 1, 2, 6 and 11 are comment lines. They are ignored by the interpreter. If you wish to make comments into your code (which I highly suggest) you have to put -- at the beginning of the line for each lines. If you want to make a multi-line comment use --[[ ]]-- brackets. "--[[" opens the comment and "]]--" closes it. Everything between that is ignored by the interpreter.

Line 3 to 5 are mandatory for your software to work. On line 3, we create a variable with the value "0". Why ? Because we don't want to read a number, it's easier to read text like "SCREEN_BOTTOM". On line 4, we create our background for our game so we get it ready to send it to the screen. On line 5, we initialize the bottom screen of the DS (as this example will only use the bottom screen). We used "BGBotText" to say that Text will be displayed on the Bottom Screen.

Lines 7 to 10 are text displaying functions. Use "print" to display text on the screen you initialized, in this case the bottom screen.

Line 12 is basically "Wait for a key" which will wait for the user to input any key to continue. The program will stop as there is no more lines after 12 and will exit the execution.

Good. I can understand that the whole "Bottom" and "Top" screen is hard right now, and we'll demystify it as we evolve in the tutorial. Now, save your script with the extention .lua (example: hello.lua) in your "scripts" directory and run PACK.BAT (if you are using Crimson Editor with the tutorial, press your hotkey that you previously configured). If everything went perfectly you will be able to use your .lua file.

Perfect ! What we mainly learned in this part is how to read the Lua code and be able to display text on the bottom screen. We also learned basic key input function. There is still a lot to learn, and we will continue by demystifying the whole "Bottom and Top" screen things.

DS big Feature, the Dual Screens.
What is a DS without both of it's screen ? A 3D version of the GBA, indeed. But that's not what we want. Before thinking about "how can i use the stylus" we need to know how properly use the dual screens (top and bottom) and what exactly the "Initialization" does. We've seen in the previous example how to basically initialize the bottom screen to display basic text using the "print" function, now we will learn a little bit more about the functionality of both screens to use them. There is no example as I will explain more in detail how to use both of them.

As you can see from the previous example we started by putting a value in the variable called SCREEN_BOTTOM, why ? Because the function of initialization requires ABSOLUTLY a numerical value. We can so guess that 0 is for the bottom screen (touchscreen) and 1 if for the top screen (normal screen). It is just easier to put those values in variables as variables has more "english" names and it's much easier to understand.

So, now, how exactly the whole thing of initialization works ? It seems hard at first, but it's actually fairly easy to understand.


First like we create a variable to contain the data from the function Screen.LoadTextBG() which basically loads all the data needed to display the text on the selected screen. And then, we initialize the bottom screen using that data (which is basically the fonts and everything needed). So now, your bottom screen is totally ready to display text.

But Screen.LoadTextBG() isn't the only function you can use for the initalization. Let's see what we can do also.

Screen.LoadTextBG() :: Returns Data required to display text to a variable
Screen.Load8BitBG() :: Returns data required to display 8 bits background
Screen.LoadTileBG() :: Returns data required to display tiled background

Let's stick to those for now, and we'll see them more in depth in the tutorial. For now, we have to realize one thing. Coding for the DS is like coding two games into one, so controlling two screens for one game. Everything you do will affect both screens depending on your code. You will understand what I mean later.

So, what do we know now ? We know what initializing the screen means, but this is not all. The screens works as they were layers... Woops ! Harder here... not. It's actually really easy. Let's take back our screen initializing function Screen.Initialize and let's modify it a little.


First thing we did here was to create the data for Top and Bottom screen and put them into variables so we can use them. On the next block of line, we start initializing both screen with the same data, but not loaded in the same order. On the first screen.initialize we put the Text in front and the background in the back, so we will see the text. In the second example, the text is behind the background, so, what happens ? We do not see the text even though it's there because it's hidden by the background. So, how exactly does this works ?


This wouldn't work, it's just an example to make it more english. So we can understand that we put in front what we don't wanna be hidden (like text) and we put in the back what we want to use as a background (like background image).

Now, we know even more about what the hell was the initialization and so, we can read even more of the code ! Good thing, right ? Now, we are far than being done with all the tutorials, but for now you already know a lot. Try reading the examples and understanding them, and later on I will post more tutorials !

Until then, happy programming ! (Don't forget to check out this thread for more tutorials)

Thanks for pointing this out, this is a great alternative that I didn't thought myself, hehe.

More of the tutorial will come as I finish learning some of it !

Here's how to do that:

Start with PACK.BAT (Auto Dualis or not)

Edit it and at the end of the code add:

CD (enter root directory here)\bundle
Del DSLUA-PACK.sc.nds
Del DSLUA.sc.nds.bin
Del DSLUA.DS.GBA.bin
Del DSLUA.nds.bin

That leaves only DSLUA-PACK.ds.gba and DSLUA-PACK.nds, which DOES save lots o time, and also some disk space. Note that this method PERMANENTLY deletes those other files, DOES NOT send them to the recycle bin. But the pack works without em, so who cares?