Micro Lua DS

From GameBrew

Macro Lua DS
Last Updated2014/01/04

MicroLua brings the programming language Lua on the Nintendo DS for homebrew development. Based on brunni's µLibrary, µLua is a Lua interpreter featuring fast drawings and many important functionalities. You can exploit your Nintendo DS with the simplistic yet powerful Lua language.

On your cartridge, MicroLua is a NDS executable that shows as its frontend a great graphical shell from which you can explore your cartridge and run Lua scripts written for µLua.


  • Fast drawing: as MicroLua is based on Brunni's library, the µLibrary, MicroLua provides fast 2D drawing using the 3D GPU. This also includes alpha transparency, and PNG/GIF transparency (as MicroLua can load PNG, JPEG and GIF image formats).
  • Even faster drawing: MicroLua also features Canvas, an object-oriented drawing system with high performances while allowing you to change drawing attributes after their creation.
  • Complete Sprites and Maps systems: with automated animations and dynamic maps, that is to say you can change the map composition through you program.
  • Wifi and Nifi: this project provides full access to the Web with the Wifi connection of the Nintendo DS, and also to the console-to-console connectivity.
  • Sound system: based on the Mixmod library, µLua can play MOD and WAV sounds.
  • Access to FAT: MicroLua gives you full access to the content of your card, and features a built-in library to handle INI-like config files.
  • Rumble and motion features: if you have the required hardwware, you can exploit it thanks to MicroLua to shake your console and make it feel your movements.


Copy the lua folder to the root (and this is really important, you have to put the lua folder to the root, ie. the / folder, the one which contains all the others). Then copy the binary file microlua.nds wherever you wish on your card.

If you have troubles while launching uLua, like Unable to load libs.lua, check that the lua folder is at the right place, that is to say in the root (and that the libs.lua file is in /lua/libs/ directory).

For more detailed instructions, please look at this page.

User guide

When you find a good uLua script, you will have probably either a single file (little script) or a directory. Just copy what you get into the scripts folder.

Then, boot your Nintendo DS, launch MicroLua. You can see on the bottom screen a file list: this is the content of your scripts folder.

For a complete manual of MicroLua, look at the page.

Developer guide:

If you intend to make your own uLua scripts, here are some tips. These advices are available on the official page, more up-to-date and complete.

Some utilitaries (Windows only) are available for download on the SourceForge; they include:

  • A Lua compiler, which precompiles your scripts for faster execution. However, this is not often useful, and other people will not be able to look at the code
  • A font converter, to use your own fonts in your scripts
  • A map converter, from GBA graphics to NDS
  • A soundbank maker, to make your scripts more vivid with some sound

You can test code on the computer with MicroLua Simulator (MLS), a good homebrew made by Ced\_le\_pingouin. Or you can also test with DeSmuME, a NDS emulator which can make MicroLua run.


D-Pad Up/Down - Navigate through your card

Right - Open a folder

A - Launch a script (file), Launch file (on folder that contains index.lua)

Known issues

Please refer to



  • Fix the Sprite module which was using a deprecated function that was removed from Lua.


New features:

  • Support for the EFS lib: you can embed some files into the binary of MicroLua, which makes a nice way to distribute your scripts (available through the sources of MicroLua).
  • Our INI lib can now crypt the tables (Motus algorithm) before saving them.
  • Upon creating a Timer, you can pass as an argument an initial time, so the timer will be set to this time (in milliseconds) instead of 0; this is also available for the method ':reset([time])'.


  • The INI library can seamlessly handle table with a simple structure, that is to say raw 'key = value' pairs without any '[example]' sections; thus an argument has been added to 'INI.load()' so the function knows what to do ('' automatically detects the structure).
  • Already loaded Image can be used while creating a new Sprite instance; just give it to the function in place of the path (giving a path is still supported).
  • All the user-readable files are now presented with MarkDown.
  • The Timers' method ':time()' is now ':getTime()' as part of the goal of giving better names to the getters and setters.
  • Instead of the whole DateTime system, you can now use the Lua's functions 'os.time()' and ''; thus DateTime does no longer exists.
  • Some variables in 'boot.lua' are now destroyed before running the shell.
  • '' accept the character "t" in is mode argument (this was the default behaviour anyway).
  • The default shell now displays the version of Lua.
  • The way the EFS is handled upon compilation has been improved: the folder 'efsroot' is no longer necessary if the EFS is not needed.
  • The BAT files for Windows now make a better use of the make command (the general behaviour is unchanged).

Bug fixes:

  • Fix the display of memory usage in Debug mode (it was in kilobytes, not in bytes).
  • Fix 'System.listDirectory()': the function now works properly in an folder different than the current one.
  • Fix the time functions now working on 3DS: MicroLua implements a workaround for this problem (which comes from the fundamental libnds that Microlua has no power on it), you can find it here.
  • Fix '' and 'dsUser.message': there was a problem while converting the UTF-16 provided by the libnds to simple chars

Changes for Microlua developers:

  • The Makefile has been cleaned and improved:
    • the part for the EFS has been improved.
    • there are a few more targets: all, cleanall, export.
  • With the migration to SourceForge, the whole repository structure has changed (and the 'docs' folder has been removed).
  • Out Lua sources have been updated to Lua 5.2.2; its folder is now simply called 'lua' to ease future updates.
  • The warnings from our code have been fixed (the ones from the EFSlib are too weird).


All the thanks will first go to Risike, the true owner of the project, the Creator, our God (let's stop here), as the project originally comes from him. He released the first version of MicroLua in 2008, and maintained it until 2009 (v3.0). At this point, he stated that he didn't want to continue this project and released it open source.

One last thing about uLua: some people confuse MicroLua with Lua. Lua is a language, basically used on computers either stand-alone or as a plugin engine. uLua is meant to be an adaptation of Lua for the Nintendo DS. So please, MicroLua is NOT a language; LUA is the language.

The main MicroLua's site (actually this is a forum). The active community will help you progress and share your scripts.

MicroLua's project hosting on Google servers. If you want to have the real last MicroLua release, go check it!

The official Lua website. You can find here all the informations relative to the language; this will probably be useful to you if you intend to make some homebrews with uLua unless you already know by heart the language.

External links