The Native Client game engine powered by Lua


Interface to the NaCl container.


nacl.prefetch ( resource_table )

Causes Aroma to block and fetch a collection of resources at once. The browser will download all the resources in parallel, which will take much less time than requesting them individually.

This will not return any of the resources, it will only cache their values on the client so when you do ask for the request later it will be available without blocking the game.

  images = {


nacl.track_event ( category , action , label , value , interactive )

This will attempt to send a custom event to Google Analytics. Only works if Google Analytics is available on the game page.

if player.beat_game then
  nacl.track_event("my_game", "player_event", "win")


The aroma object serves two parts. It contains all Aroma submodules, which are also listed on this page, and it is where callback functions are assigned.

Callbacks are functions that you create and assign to the aroma object. They will be called by the engine when certain events happen.

You only need to assign these callback functions when if you are using them, leaving them out is perfectly okay. You should never need to call these functions manually (but you can).

Here is the complete list of callbacks:


aroma.draw ( )

Where all of your drawing code should go.

function aroma.draw()"hello world", 10, 10)


aroma.focus ( has_focus )

Called when the focus of the game window has changed

function aroma.focus(has_focus)
  print("Focus changed:", has_focus)


aroma.keypressed ( key_name , key_code )

Called when a key is pressed down. Given two arguments:

  • key_name — A string representing the name of the key pressed

  • key_code — An integer representing the code of the key

function aroma.keypressed(key_name, key_code)
  print("Key pressed:", key_name, key_code)


aroma.keyreleased ( key_name , key_code )

Callen when a key is released.

Arguments are the same as aroma.keypressed.


aroma.update ( dt )

Where game state updates should go. Takes one argument, dt, the amount of time in seconds since the last frame.

You should not draw from this function, nothing will show up.

function aroma.update(dt)
  player.x = player.x + speed * dt

Functions responsible for drawing things on the screen or changing the state of drawing.

draw ( drawable , x , y , [rotate] , [scale_x] , [scale_y] , [origin_x] , [origin_y] )

Draws a drawable object on the screen. Right now the only drawable objects are images.

rotate is clockwise rotation in degrees.

origin_x and origin_y can be used to control the origin of rotation.

drawq ( drawable , quad , x , y , [rotate] , [scale_x] , [scale_y] , [origin_x] , [origin_y] )

Similar to, but takes a Quad as second argument.

A Quad can be used to only draw a portion of an image. Useful for drawing sprites from a single image.

local img ="hi.png")
local q =, 5, 10, 10, img:getWidth(), img:getHeight())

-- draws the part of the image specified by the quad at 10, 10
function aroma.draw(), q, 10, 10)


font = ( font_name , [alphabet] )

Creates a new font and returns it. Fonts are rendered by the browser in a <canvas> tag and then passed back to Aroma.

font_name must be a valid CSS font value.

alphabet is an optional string whose characters will be the glyphs available in the font. Defaults to all numbers, letters, and symbols on an English keyboard.

Custom fonts can be made available by embedding fonts into the stylesheet of the host page using @font-face.

local monospace ="32px monospace")

-- only numbers can be written with this font
local numbers ="10pt serif", "0987654321")


image = ( image_url )

Loads and image by url and returns it as an Image object.

Images can be drawn to the screen using

local image ="hello.png")

function aroma.draw(), 10, 10)


font = ( image , alphabet )

Creates a new font from an image and returns it. Unlike, letters are extracted from a bitmap instead a typeface from the browser.

  • image — An image url or an ImageData object.
  • alphabet — A string of letters as they appear in the image.

The image must be formatted as a single row of letters where each letter is separated by a spacer color:

number font

The spacer color is always the top left color in the image, so place a spacer column as the leftmost thing in the image. The spacer column can be any width.

The rightmost part of the image must also be a spacer column, or the last letter will be left out.

-- write some text with the font above
local number_font ="numbers.png", " 1234567890")

function aroma.draw()"1337", 10, 10)


quad = ( x , y , width , height , source_width , source_height )

Creates a new Quad for use with

source_width and source_height are typically the width and height of the image the quad is being used on.

x, y, width, height represent the rectangle that should be drawn from the image.


shader = ( vertex_shader_source , fragment_shader_source )

Create a new shader.

pop ( )

Pops the current transformation off the transformation stack.

print ( [font] , text , x , y , [rotate] , [scale_x] , [scale_y] , [origin_x] , [origin_y] )

Draws text on the screen. If font is not provided, the default font will be used. See

push ( )

Copies and pushes the current transformation onto the transformation stack.

rectangle ( [render_style] , x , y , width , height )

Draws a rectangle on the screen.

The color of the rectangle is the current color. See

render_style is an optional string that determines how the rectangle is drawn. "fill" is the default. Must be one of the following:

  • "fill"
  • "line"

reset ( )

Resets graphics state to default. This includes:

  • Background color
  • Drawing color
  • Blend mode

rotate ( deg )

Modifies the current transformation to rotate all draws by deg degrees.

The center of origin is at (0,0). It is helpful to combine this with translation control the center of origin relative to the object being drawing.

scale ( sx , sy )

Modifies the current transformation by scaling all draws by sx and sy.

setBackgroundColor ( red , green , blue , alpha )

Set the color the screen is cleared to after every frame.


red , green , blue , alpha = ( )

Gets the current color for drawing.

setColor ( red , green , blue , [alpha] )

Set the current color for drawing.

-- draw a red rectangle
function aroma.draw(),0,0),10, 50,50)

setDefaultShader ( shader )

Replaces the shader responsible for all drawing. Be careful with this. If the shader does not work in a specific way then nothing may be drawn or Aroma may crash.

shader must be a shader created with

setFont ( font )

Sets the current font. font must be a font return by


font = ( )

Gets the current font.


height = ( )

Gets the height of the viewport in pixels.

setLineWidth ( width )

Set the width of lines lines drawn.


width = ( )

Gets the width of the viewport in pixels.

translate ( tx , tx )

Modifies the current transformation by translating all draws by tx and ty.

function aroma.draw(), 20)
  -- will be drawn at 25, 25, 5, 10, 10)


Images can be drawn with


width = image:getWidth ( )

Gets the width of the image.


height = image:getHeight ( )

Gets the height of the image.


image:setWrap ( horiz_wrap , vert_wrap )

Sets the wrapping mode of the image when overdrawn (by something like drawq). By default wrap is set to "clamp".

Possible values for each:

  • "clamp" — the color at the edge of the texture will be used to fill the extra space.

  • "repeat" — The texture will repeat to fill extra space.


image:setFilter ( min_filter , mag_filter )

Sets how images are filtered when they are scaled. By default wrap is set to "linear" for both min and mag.

  • min_filter — applied when the image is rendered smaller than its original dimensions.

  • mag_filter — applied when the image is rendered larger its original dimensions.

Posible values include:

  • "linear" — The colors of nearby pixels are blended, creates a smoothing effect.

  • "nearest" — no blending is done. This is the best filter to use when working with pixel art.


Represents a loaded font. Created with

Can be drawn with setFont or print.


Represents a rectangular portion of something. Created with

Drawn with


quad:flip ( x , y )
  • x — Flips Quad horizontally if true

  • y — Flips Quad vertically if true

Functions for working with sound.


audio = ( source_url , [source_type] )

Loads a new source by url. Returns an AudioSource.

source_type is an optional value that determines how the sound is loaded. "static" is the default. The following types are valid:

  • "static" — The function will block until the entire audio source is loaded into memory and ready be played. Uses the Web Audio API. Suitable for short samples such as sound effects.

  • "streaming" — Uses the <audio> tag. The function will not wait for the entire file to download, will only verify that the file exists. Playback of the sound might be delayed. Can also be unreliable. Suitable for background music.

local bg ="game/theme.ogg", "streaming")
local effect ="game/shoot.ogg")

bg:play() -- not guaranteed to play immediately, could still be downloading

effect:play() -- guaranteed to play


A static or stremaing audio srouce. Created with


source:play ( )


source:pause ( )


source:stop ( )


source:setLooping ( looping )


Functions for manipulating images and image data.


data = aroma.image.newImageData ( image_url )


Functions for querying information about the keyboard.


is_down = aroma.keyboard.isDown ( key_name )

Checks if a key is currently pressed down.

function aroma.update()
  if aroma.keyboard.isDown(" ") then
    print("Space is pressed!")


Functions relating to the internal timer.


fps = aroma.timer.getFPS ( )

Gets the frames per second of the game.


time = aroma.timer.getTime ( )

Gets the value of the internal timer in seconds. The value by itself is meaningless but it useful when compared against other times.