ApiThreeDotZero: Contents
  Introduction
  API
    Variables
    Functions and their table
      Screen
      Colors
      Controls
      Images
      Timers
      Sprites
      Debug
      System
      Fonts
      Maps
      Scroll Maps
      Canvas
      Rumble
      Motion
      DateTime
      Wifi
      Sound
      INI Files

Api Three Dot Zero

3.0 API.

Introduction

The variables or functions that you will find here may be defined in the Lua libraries (libs tag) or in the C code (nds tag).

API

Variables

  • MICROLUA_VERSION (libs): version of Micro Lua (String).
  • SCREEN_WIDTH, SCREEN_HEIGHT (libs): width and height of the screens.
  • NB_FPS (libs): number of frame per second automatically updated each second. You can display it with a screen.print() between screen.startDrawing() and screen.stopDrawing(). Don’t display it in the debug console.
  • SCREEN_UP, SCREEN_DOWN (libs): screen number where to draw. See examples for more details.
  • RAM and VRAM (libs): destination where to load some object. See examples for more details.
  • ATTR_X1, ATTR_Y1, ATTR_X2, ATTR_Y2, ATTR_X3, ATTR_Y3, ATTR_COLOR, ATTR_COLOR1, ATTR_COLOR2, ATTR_COLOR3, ATTR_COLOR4, ATTR_TEXT, ATTR_VISIBLE, ATTR_FONT, ATTR_IMAGE (libs): attributes used in canvas.
not documented: PLAY_LOOP, PLAY_ONCE, mustCountFPS

Functions and their table

Screen

Void render() (libs)

Refresh the screen.

Void startDrawing() & Void stopDrawing() (libs, deprecated)

All your drawing instructions must be between these two functions.

Void screen.switch() (nds)

Switch the screens.

Void screen.print(screen, x, y, text [, color]) (nds)

Print a text on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x (Number): x-coordinate where to draw
  • y (Number): y-coordinate where to draw
  • text (String): text to print
  • color (Color): color of the text
Void screen.printFont(screen, x, y, text , color, font) (nds)

Print a text on the screen using a special font.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x (Number): x-coordinate where to draw
  • y (Number): y-coordinate where to draw
  • text (String): text to print
  • color (Color): color of the text
  • font (Font) : special font
Void screen.blit(screen, x, y, image, [, sourcex, sourcey] [, width, height]) (nds)

Blit an image on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x (Number): x-coordinate where to draw
  • y (Number): y-coordinate where to draw
  • image (Image): image to blit
  • sourcex, sourcey (Number): coordinates in the source image to draw
  • width, height (Number): width and height of the rectangle to draw
Void screen.drawLine(screen, x0, y0, x1, y1, color) (nds)

Draw a line on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x0, y0, x1, y1 (Number): coordinates of the line
  • color (Color): color of the line
Void screen.drawRect(screen, x0, y0, x1, y1, color) (nds)

Draw a rectangle on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x0, y0, x1, y1 (Number): coordinates of the rectangle
  • color (Color): color of the rectangle
Void screen.drawFillRect(screen, x0, y0, x1, y1, color) (nds)

Draw a fill rectangle on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x0, y0, x1, y1 (Number): coordinates of the rectangle
  • color (Color): color of the rectangle
Void screen.drawGradientRect(screen, x0, y0, x1, y1, color1, color2, color3, color4) (nds)

Draw a gradient rectangle on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x0, y0, x1, y1 (Number): coordinates of the rectangle
  • color1, color2, color3, color4 (Color): colors of the rectangle
Void screen.drawTextBox(screen, x0, y0, x1, y1, text [, color]) (nds)

Draw a text box on the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • x0, y0, x1, y1 (Number): coordinates of the text box
  • text (String): text to print
  • color (Color): color of the text box
not documented: screen.init, screen_getMainLcd, screen_startDrawing2D, screen_endDrawing, screen_waitForVBL, screen.setSpaceBetweenScreens

Colors

Color Color.new(r, g, b) (nds)

Create a new color.
  • r (Number): red mask (from 0 to 31)
  • g (Number): green mask (from 0 to 31)
  • b (Number): blue mask (from 0 to 31)

Controls

Void Controls.read() (libs)

Read the controls and update all control structures.

Stylus

These are numbers or booleans. Everything here is defined in the libs.

Stylus.X: x-coordinate of the stylus

Stylus.Y: y-coordinate of the stylus

Stylus.held: is the stylus held on the screen

Stylus.released: is the stylus released

Stylus.doubleClick: true if stylus do a double click

Stylus.deltaX: delta x of the stylus movement

Stylus.deltaY: delta y of the stylus movement

Stylus.newPress: true if stylus do a new press

Keys

These are booleans. Everything here is defined in the libs.

([KEY] can take the following values : A, B, X, Y, L, R, Start, Select, Up, Down, Left, Right)

Keys.held.[KEY]: is the key held?

Keys.released.[KEY]: is the key released?

Keys.newPress.[KEY]: true if the key does a new press

Images

Image Image.load(path, destination) (nds)

Create a new image in memory from an image file (PNG, JPG or GIF).
  • path (String): path of the image to load
  • destination (Number): destination of the image in memory (can be RAM of VRAM)
Void Image.destroy(image) (nds)

Destroy the image.
  • image (Image): image to destroy
To completely destroy an image, do:
myImage:destroy()
myImage = nil
Number Image.width(image) (nds)

Get the width of the image.
  • image (Image): image to use
Number Image.height(image) (nds)

Get the height of the image.
  • image (Image): image to use
Void Image.scale(image, width, height) (nds)

Scale the image.
  • image (Image): image to scale
  • width (Number): new width of the image
  • height (Number): new height of the image
Void Image.rotate(image, angle [, centerx, centery]) (nds)

Rotate the image around rotation center.
  • image (Image): image to rotate
  • angle (Number): angle of roattion (between 0 and 511)
  • centerx (Number): x-coordinate of the new rotation center
  • centery (Number): y-coordinate of the new rotation center
Void Image.rotateDegree(image, angle [, centerx, centery]) (nds)

Rotate the image around rotation center, the angle is given in degree.
  • image (Image): image to rotate
  • angle (Number): angle of rotation in degree (between 0 and 360)
  • centerx (Number): x-coordinate of the new rotation center
  • centery (Number): y-coordinate of the new rotation center
Void Image.mirrorH(image) (nds)

Mirror the image horizontally.
  • image (Image): image to mirror
Void Image.mirrorV(image) (nds)

Mirror the image vertically.
  • image (Image): image to mirror
Void Image.setTint(image, color) (nds)

Set the tint of the image.
  • image (Image): image to tint
  • color (Color): color of the image

Timers

The unit is the millisecond.

Timer Timer.new() (libs)

Create a new timer, you can start it.

Number timer:time() (libs)

Return the time of the timer.

Void timer:start() (libs)

Start a timer.

Void timer:stop() (libs)

Stop a timer.

Void timer:reset() (libs)

Reset a timer.

Sprites

Sprite Sprite.new(path, frameWidth, frameHeight, dest) (libs)

Create a sprite from an image file.
  • path (String): path of the file which contains the sprite
  • frameWidth (Number): width of the frames
  • frameHeight (Number): height of the frames
  • dest (Number): destination (RAM or VRAM)
Void sprite:drawFrame(screen, x, y, nbFrame) (libs)

Draw a frame of the sprite.
  • screen (Number): screen (SCREEN_UP or SCREEN_DOWN)
  • x (Number): X-coordinate where to draw the frame
  • y (Number): Y-coordinate where to draw the frame
  • nbFrame (Number): number of the frame to draw
Void sprite:addAnimation(tabAnim, delay) (libs)

Create an animation.
  • tabAnim (Table): the table of the animation frames
  • delay (Number): delay between each frame
Void sprite:playAnimation(screen, x, y, nbAnim) (libs)

Play an animation on the screen.
  • screen (Number): screen (SCREEN_UP or SCREEN_DOWN)
  • x (Number): X-coordinate where to draw the frame
  • y (Number): Y-coordinate where to draw the frame
  • nbAnim (Number): number of the animation to play
Void sprite:resetAnimation(nbAnim) (libs)

Reset an animation.
  • nbAnim (Number): number of the animation
Void sprite:startAnimation(nbAnim) (libs)

Start an animation.
  • nbAnim (Number): number of the animation
Void sprite:stopAnimation(nbAnim) (libs)

Stop an animation.
  • nbAnim (Number): number of the animation
Boolean sprite:isAnimationAtEnd(nbAnim) (libs)

Return true if the animation has drawn the last frame.
  • nbAnim (Number): number of the animation
not documented: SpriteAnimation

Debug

Void Debug.ON() (libs)

Activate the debug mode.

Void Debug.OFF() (libs)

Desactivate the debug mode.

Void Debug.print(text) (libs)

Print a debug line.
  • text (String): text to print
Void Debug.clear() (libs)

Clear the debug console.

Void Debug.setColor(color) (libs)

Set the debug text color.
  • color (Color): color of the text
not documented: isDebugOn, debugText, debugColor

System

String System.currentDirectory() (libs)

Get the current working directory.

Void System.changeDirectory(path) (libs)

Change the current working directory.
  • path (String): path of the directory
Void System.remove(name) (libs)

Remove a file or an empty folder.
  • name (String): name of the file or directory to remove
Void System.rename(oldName, newName) (libs)

Rename file or an empty folder.
  • oldName (String): name of the file or directory to rename
  • newName (String): new name of the file or directory
Void System.makeDirectory(name) (libs)

Create a new directory.
  • name (String): path and name of the directory
Table System.listDirectory(path) (libs)

List all files and folders of a directory.
  • path (String): path of the directory to list
  • NOTE: See examples for more details.

Fonts

Font Font.load(path) (nds)

Create a new font from a font file (oslib and µLibrary format).
  • Path (String): path of the file to load
Void Font.destroy(font) (nds)

Destroy the font.
  • font (Font): font to destroy
To completely destroy a font, do:
Font.destroy(font)
font = nil
Void Font.print(screen, font, x, y, text [, color]) (nds, deprecated)

Please use screen.printFont which really handles the color.

Print a text with a special font.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • font (Font): font to use
  • x (Number): x-coordinate where to draw
  • y (Number): y-coordinate where to draw
  • text (String): text to print
  • color (Color): color of the text
Number Font.getCharHeight(font) (nds)

Get the height of the characters of a font.
  • font (Font): font to use
Number getStringWidth(font, text) (nds)

Get the width of a text with a specific font.
  • font (Font): font to use
  • text (String): text
not documented: destroy

Maps

Map Map.new(image, mapfile, width, height, tileWidth, tileHeight) (nds)

Create a new map by giving a map file.
  • image (Image): image which contains tiles
  • mapfile (String): path to the map file (.map)
  • width (Number): width of the map in tiles
  • height (Number): height of the map in tiles
  • tileWidth (Number): width of the tiles in pixels
  • tileHeight (Number): height of the tiles in pixels
Void Map.destroy(map) (nds)

Destroy a map.
  • map (Map): map to destroy
Void Map.draw(screen, map, x, y, width, height) (nds)

Draw a map.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • map (Map): map to destroy
  • x (Number): x-coordinate where to draw the map
  • y (Number): y-coordinate where to draw the map
  • width (Number): x number of tiles to draw
  • height (Number): y number of tiles to draw
Void Map.scroll(map, x, y) (nds)

Scroll a map.
  • map (Map): map to scroll
  • x (Number): x number of tiles to scroll
  • y (Number): y number of tiles to scroll
Void Map.space(map, x, y) (nds)

Set the space between each tiles of a map.
  • map (Map): map to modify
  • x (Number): x space between tiles
  • y (Number): y space between tiles
Void Map.setTile(map, x, y, tile) (nds)

Change a tile value.
  • map (Map): map to modify
  • x (Number): x-coordinate of the tile to change in the map table
  • y (Number): y-coordinate of the tile to change in the map table
  • tile (Number): new tile value
Number Map.getTile(map, x, y) (nds)

Get a tile value.
  • map (Map): map to read
  • x (Number): x-coordinate of the tile to get
  • y (Number): y-coordinate of the tile to get

Scroll Maps

ScrollMap ScrollMap.new(image, mapfile, width, height, tileWidth, tileHeight) (nds)

  • image (Image): image which contains tiles
  • mapfile (String): path to the map file (.map)
  • width (Number): width of the map in tiles
  • height (Number): height of the map in tiles
  • tileWidth (Number): width of the tiles in pixels
  • tileHeight (Number): height of the tiles in pixels
Void ScrollMap.destroy(scrollmap) (nds)

Destroy a ScrollMap. Void ScrollMap.draw(screen, scrollmap) (nds)

Draw a ScrollMap. Void ScrollMap.scroll(scrollmap, x, y) (nds)

Scroll a ScrollMap.
  • scrollmap (ScrollMap): ScrollMap to scroll
  • x (Number): x scrolling in pixel
  • y (Number): y scrolling in pixel
Void ScrollMap.setTile(scrollmap, x, y, tile) (nds)

Change a tile value.
  • scrollmap (ScrollMap): ScrollMap to modify
  • x (Number): x-coordinate of the tile to change in the scrollmap table
  • y (Number): y-coordinate of the tile to change in the scrollmap table
  • tile (Number): new tile value
Number ScrollMap.getTile(scrollmap, x, y) (nds)

Get a tile value.
  • scrollmap (ScrollMap): ScrollMap to read
  • x (Number): x-coordinate of the tile to get
  • y (Number): y-coordinate of the tile to get

Canvas

Canvas Canvas.new() (nds)

Create a new canvas.

Void Canvas.destroy(canvas) (nds)

Destroy a canvas. Must be followed by canvas = nil.
  • Canvas (Canvas): canvas to destroy
CanvasObject Canvas.newLine(x1, y1, x2, y2, color) (nds)

Create a new line.
  • x1, y1, x2, y2 (Number): coordinates of the line
  • color (Color): color of the line
CanvasObject Canvas.newPoint(x1, y1, color) (nds)

Create a new point.
  • x1, y1 (Number): coordinates of the point
  • color (Color): color of the point
CanvasObject Canvas.newRect(x1, y1, x2, y2, color) (nds)

Create a new rectangle.
  • x1, y1, x2, y2 (Number): coordinates of the rectangle
  • color (Color): color of the rectangle
CanvasObject Canvas.newFillRect(x1, y1, x2, y2, color) (nds)

Create a new fill rectangle.
  • x1, y1, x2, y2 (Number): coordinates of the rectangle
  • color (Color): color of the rectangle
CanvasObject Canvas.newGradientRect(x1, y1, x2, y2, color1, color2, color3, color4) (nds)

Create a new gradient rectangle.
  • x1, y1, x2, y2 (Number): coordinates of the rectangle
  • color1, color2, color3, color4 (Color): colors of the fill rectangle
CanvasObject Canvas.newText(x1, y1, text [, color]) (nds)

Create a new text.
  • x1, y1 (Number): coordinates of the text
  • text (String): text
  • color (Color): color of the text
CanvasObject Canvas.newTextFont(x1, y1, text, color, font) (nds)

Create a new text with a special font.
  • x1, y1 (Number): coordinates of the text
  • text (String): text
  • color (Color): color of the text
  • font (Font): special font of the text
CanvasObject Canvas.newTextBox(x1, y1, x2, y2, text [, color]) (nds)

Create a new textbox.
  • x1, y1, x2, y2 (Number): coordinates of the textbox
  • text (String): text
  • color (Color): color of the textbox
CanvasObject Canvas.newImage(x1, y1, image [, x2, y2] [, x3, y3]) (nds)

Create a new image.
  • x1, y1 (Number): coordinates of the image
  • x2, y2 (Number): coordinates in the source image to draw
  • x3, y3 (Number): width and height of the rectangle to draw
Void Canvas.add(canvas, object) (nds)

Add a CanvasObject in a canvas.
  • canvas (Canvas): canvas to draw
  • object (CanvasObject): object to add
Void Canvas.draw(screen, canvas, x, y) (nds)

Draw a canvas to the screen.
  • screen (Number): screen where to draw (SCREEN_UP or SCREEN_DOWN)
  • canvas (Canvas): canvas to draw
  • x (Number): x-coordinate where to draw
  • y (Number): y-coordinate where to draw
Void Canvas.setAttr(object, attrName, attrValue) (nds)

Set an attribute value.
  • object (CanvasObject): object to modify
  • attName (Constant): attribute to modify. Must be ATTR_XXX. See “some useful variables” for more details
  • attrValue (?): new value for the attribute. Must be the good type
? Canvas.getAttr(object, attrName) (nds)

Get an attribute value. Return type depends of the attribute (number, font or image).
  • object (CanvasObject): object to use
  • attName (Constant): attribute to get value. Must be ATTR_XXX. See “some useful variables” for more details

Rumble

Boolean Rumble.isInserted() (nds)

Check if a rumble pack is inserted.

Void Rumble.set(status) (nds)

Set the rumble status.
  • status (Boolean): status of the rumble (true: ON, false: OFF)

Motion

Boolean Motion.init (nds)

Init the motion system if a motion device is detected. Return true if a motion device is detected.

Void Motion.calibrate (nds)

Calibrate the motion system.

Number Motion.readX (nds)

Read the X tilt of the motion.

Number Motion.readY (nds)

Read the Y tilt of the motion.

Number Motion.readZ (nds)

Read the Z tilt of the motion.

Number Motion.accelerationX (nds)

Read the X acceleration of the motion.

Number Motion.accelerationY (nds)

Read the Y acceleration of the motion.

Number Motion.accelerationZ (nds)

Read the Z acceleration of the motion.

Number Motion.readGyro (nds)

Read the gyro value of the motion.

Number Motion.rotation (nds)

Read the rotation value of the motion.

DateTime

This should be DEPRECATED soon, as there is the os.date() basic Lua function.

DateTime DateTime.new() (libs)

Create a new DateTime object.

DateTime DateTime.getCurrentTime() (libs)

Create a new DateTime object with current time values.
  • Attributes (numbers):
year, month, day, hour, minute, second
  • NOTE: See examples for more details.

Wifi

Void Wifi.connectWFC() (nds)

Connect the DS to the Wifi connection. Use the firmware configurations. So, you need to configure your connection with an official DS game.

Void Wifi.disconnect() (nds)

Disconnect the DS form the Wifi connection.

Socket Wifi.createTCPSocket(host, port) (nds)

Create a TCP socket on a server.
  • host (String): hostname or IP adress of the server
  • port (Number): port to use
Socket Wifi.createUDPSocket(host, port) (nds)

Create an UDP socket on a server.
  • host (String): hostname or IP adress of the server
  • port (Number): port to use
Void Wifi.closeSocket(socket) (nds)

Close a socket (TCP or UDP).
  • socket (Socket): Socket to close
Void Wifi.send(socket, buffer) (nds)

Send data to a server using a socket.
  • socket (Socket): Socket to use
  • buffer (String): data to send
String Wifi.receive(socket, length) (nds)

Receive data from a server using a socket.
  • socket (Socket): Socket to use
  • length (Number): size of the data to receive

Sound

Sound banks

Void Sound.loadBank(filename) (nds)

Load a soundbank from a file in memory.
  • filename (String): path of the file to load
Void Sound.unloadBank() (nds)

Unload the sound bank from the memory.

Mods

Void Sound.loadMod(id) (nds)

Load a module in memory.
  • id (Number): id of the module to load
Void Sound.unloadMod(id) (nds)

Unload a module from the memory.
  • id (Number): id of the module to unload
Void Sound.startMod(id, playmode) (nds)

Start playing a module already loaded in memory.
  • id (Number): id of the module to play
  • playmode (Number): playing mode (PLAY_ONCE or PLAY_LOOP)
Void Sound.pause() (nds)

Pause all modules.

Void Sound.resume() (nds)

Resume all modules.

Void Sound.stop() (nds)

Stop all modules.

Void Sound.setPosition(id, position) (nds)

Set the cursor position of a module.
  • id (Number): id of the module
Boolean Sound.isActive() (nds)

Return true if the player is active and false if it's not.

Void Sound.startJingle(id) (nds)

Start playing a module as a jingle.
  • id (Number): id of the module to play
Void Sound.setModVolume(volume) (nds)

Set the volume of the played module.
  • volume (Number): new volume value between 0 and 1024
Void Sound.setJingleVolume(volume) (nds)

Set the volume of the played jingle.
  • volume (Number): new volume value between 0 and 1024
Void Sound.setModTempo(tempo) (nds)

Set the tempo of the module player.
  • tempo (Number): new tempo value between 512 and 2048
Void Sound.setModPitch(pitch) (nds)

Set the pitch of the module player.
  • pitch (Number): new pitch value

SFX

Void Sound.loadSFX(id) (nds)

Load a SFX in the meory.
  • id (Number): id of the SFX to load
Void Sound.unloadSFX(id) (nds)

Unload a SFX in the meory.
  • id (Number): id of the SFX to unload
Handle Sound.startSFX(id) (nds)

Start a sound effect already loaded in memory. Return and handle to this SFX.
  • id (Number): id of the SFX to start
Void Sound.stopSFX(handle) (nds)

Stop a played SFX.
  • handle (Handle): handle of a SFX, given by the startSFX function
Void Sound.releaseSFX(handle) (nds)

Mark an effect as low priority.
  • handle (Handle): handle of a SFX, given by the startSFX function
Void Sound.stopAllSFX() (nds)

Stop all payed SFX.

Void Sound.setSFXVolume(handle, volume) (nds)

Set the volume of a playing SFX.
  • handle (Handle): handle of a SFX, given by the startSFX function
  • volume (Number): new volume value between 0 and 255 (different from Mods)
Void Sound.setSFXPanning(handle, panning) (nds)

Set the panning of a playing SFX.
  • handle (Handle): handle of a SFX, given by the startSFX function
  • panning (Number): new panning value between 0 (left) and 255 (right)
Void Sound.setSFXPitch(handle, pitch) (nds)

Set the pitch of a playing SFX.
  • handle (Handle): handle of a SFX, given by the startSFX function
  • pitch (Number): new pitch value
Void Sound.setSFXScalePitch(handle, scale) (nds)

Set the scaling pitch ratio of a playing SFX.
  • handle (Handle): handle of a SFX, given by the startSFX function
  • scale (Number): new scale pitch value

INI Files

Table INI.load(filename) (libs)

Load an INI file and create a table with it.
  • filename (String): file to load
Void INI.save(filename, tab) (libs)

Save a table in an INI file.
  • filename (String): file to load
  • tab (Table): table to save
Example :

An INI file contains :
[infos]
name=toto
age=25
tab = INI.load(“myfile.ini”)
tab[“infos”][“name”] = “tata”
INI.save(“myfile.ini”, tab)
This exemple changes the line name=toto into name=tata.

These tables can only contains Strings!!! If you want to store integers convert them with the tostring() function!