notnull games

Lua

🌙Lua is the classic game-scripting language, and null0 uses GopherLua so it works inside the host’s interpreter. Plain globals, tables for structs, require for extra files.

Template: cart_lua - press "Use this template" and you have a working game.
Docker image: ghcr.io/notnullgames/null0-cart-lua:latest
Your code: cart/main.lua, interpreted by GopherLua, baked into main.wasm
Bindings: carts/lua/null0.lua (editor definitions - the runtime provides the API itself)
WASI is available, so ordinary file and stdio calls work.

building

You do not install GopherLua, baked into main.wasm - the docker image has it, and the current null0 bindings, baked in. That is the whole point: there is nothing in your project to keep in sync with the engine.

docker run --rm --user $(id -u):$(id -g) \
  -v ./cart:/src -v ./webroot:/out \
  ghcr.io/notnullgames/null0-cart-lua:latest mygame

The template wraps that in npm start, which also serves the result and rebuilds when you save.

Lua notes

The API is plain globals, structs are tables, and require works for extra cart files.
GopherLua, not C Lua - the host interpreter has no exception-handling, which C Lua needs.
null0.lua is LuaLS definitions for your editor; it is not shipped inside the cart.

a cart, in Lua

This is carts/lua/simple/main.lua in the engine repo - the same file CI builds into the cart below, so it always compiles.

-- simple lua cart for null0 (interpreted, via GopherLua)
--
-- the null0 API is available as plain globals - no require() needed, same as
-- the JS carts. structs (Color/Vector/Rectangle/Dimensions/SfxParams) are
-- plain tables, e.g. {r = 0, g = 121, b = 241, a = 255}
--
-- null0.lua (in carts/lua) has definitions for every function & constant, so
-- any LuaLS-based editor can complete them for you.

local counter = 0

function load()
  print('lua cart says "hi"')
  print('Press buttons to see reaction.')
  print('Press SPACE to see text on screen.')
end

function buttonDown(button, player)
  print('buttonDown:', button, player)
end

function update()
  counter = counter + 1
  clear(BLUE)
  draw_rectangle(10, 10, 100, 50, RED)
  if key_down(KEY_SPACE) then
    draw_text(FONT_DEFAULT, 'Space pressed!', 50, 50, WHITE)
  end
end

-- other callbacks you can implement:
-- function unload() end
-- function buttonUp(button, player) end
-- function keyUp(key) end
-- function keyDown(key) end
-- function mouseDown(button) end
-- function mouseUp(button) end
-- function mouseMoved(x, y) end

carts/lua/simple/main.lua

callbacks

A cart implements the callbacks it cares about. In Lua they look like this:

function update() end

See anatomy of a cart for the full list and what each one is passed.

more Lua carts

demo - source
tile - source

the API, in Lua

Every null0 function, spelled the way Lua spells it. These are read out of the generated bindings themselves, so they match what your editor completes.

colors (7)

Tint a color with another color.

function color_tint(color, tint) end

Fade a color.

function color_fade(color, alpha) end

Change the brightness of a color.

function color_brightness(color, factor) end

Invert a color.

function color_invert(color) end

Blend 2 colors together.

function color_alpha_blend(dst, src) end

Change contrast of a color.

function color_contrast(color, contrast) end

Interpolate colors.

function color_bilinear_interpolate(color00, color01, color10, color11, coordinateX, coordinateY) end

graphics (75)

Create a new blank image.

function new_image(width, height, color) end

Copy an image to a new image.

function image_copy(image) end

Create an image from a region of another image.

function image_subimage(image, x, y, width, height) end

Clear the screen.

function clear(color) end

Draw a single pixel on the screen.

function draw_point(x, y, color) end

Draw a line on the screen.

function draw_line(startPosX, startPosY, endPosX, endPosY, color) end

Draw a filled rectangle on the screen.

function draw_rectangle(posX, posY, width, height, color) end

Draw a filled triangle on the screen.

function draw_triangle(x1, y1, x2, y2, x3, y3, color) end

Draw a filled ellipse on the screen.

function draw_ellipse(centerX, centerY, radiusX, radiusY, color) end

Draw a filled circle on the screen.

function draw_circle(centerX, centerY, radius, color) end

Draw a filled polygon on the screen.

function draw_polygon(points, color) end

Draw a filled arc on the screen.

function draw_arc(centerX, centerY, radius, startAngle, endAngle, segments, color) end

Draw a filled round-rectangle on the screen.

function draw_rectangle_rounded(x, y, width, height, cornerRadius, color) end

Draw an image on the screen.

function draw_image(src, posX, posY) end

Draw a tinted image on the screen.

function draw_image_tint(src, posX, posY, tint) end

Draw an image, rotated, on the screen.

function draw_image_rotated(src, posX, posY, degrees, offsetX, offsetY, filter) end

Draw an image, flipped, on the screen.

function draw_image_flipped(src, posX, posY, flipHorizontal, flipVertical, flipDiagonal) end

Draw an image, scaled, on the screen.

function draw_image_scaled(src, posX, posY, scaleX, scaleY, offsetX, offsetY, filter) end

Draw some text on the screen.

function draw_text(font, text, posX, posY, color) end

Save an image to persistant storage.

function save_image(image, filename) end

Load an image from a file in cart.

function load_image(filename) end

Resize an image, return copy.

function image_resize(image, newWidth, newHeight, filter) end

Scale an image, return copy.

function image_scale(image, scaleX, scaleY, filter) end

Replace a color in an image, in-place.

function image_color_replace(image, color, replace) end

Tint a color in an image, in-place.

function image_color_tint(image, color) end

Fade a color in an image, in-place.

function image_color_fade(image, alpha) end

Copy a font to a new font.

function font_copy(font) end

Scale a font, return a new font.

function font_scale(font, scaleX, scaleY, filter) end

Load a BMF font from a file in cart.

function load_font_bmf(filename, characters) end

Load a BMF font from an image.

function load_font_bmf_from_image(image, characters) end

Measure the size of some text.

function measure_text(font, text, textLength) end

Meaure an image (use 0 for screen).

function measure_image(image) end

Load a TTY font from a file in cart.

function load_font_tty(filename, glyphWidth, glyphHeight, characters) end

Load a TTY font from an image.

function load_font_tty_from_image(image, glyphWidth, glyphHeight, characters) end

Load a TTF font from a file in cart.

function load_font_ttf(filename, fontSize) end

Invert the colors in an image, in-place.

function image_color_invert(image) end

Calculate a rectangle representing the available alpha border in an image.

function image_alpha_border(image, threshold) end

Crop an image, in-place.

function image_crop(image, x, y, width, height) end

Crop an image based on the alpha border, in-place.

function image_alpha_crop(image, threshold) end

Adjust the brightness of an image, in-place.

function image_color_brightness(image, factor) end

Flip an image, in-place.

function image_flip(image, horizontal, vertical) end

Change the contrast of an image, in-place.

function image_color_contrast(image, contrast) end

Use an image as an alpha-mask on another image.

function image_alpha_mask(image, alphaMask, posX, posY) end

Create a new image, rotating another image.

function image_rotate(image, degrees, filter) end

Create a new image of a gradient.

function image_gradient(width, height, topLeft, topRight, bottomLeft, bottomRight) end

Unload an image.

function unload_image(image) end

Unload a font.

function unload_font(font) end

Clear an image.

function clear_image(destination, color) end

Draw a single pixel on an image.

function draw_point_on_image(destination, x, y, color) end

Draw a line on an image.

function draw_line_on_image(destination, startPosX, startPosY, endPosX, endPosY, color) end

Draw a filled rectangle on an image.

function draw_rectangle_on_image(destination, posX, posY, width, height, color) end

Draw a filled triangle on an image.

function draw_triangle_on_image(destination, x1, y1, x2, y2, x3, y3, color) end

Draw a filled ellipse on an image.

function draw_ellipse_on_image(destination, centerX, centerY, radiusX, radiusY, color) end

Draw a circle on an image.

function draw_circle_on_image(destination, centerX, centerY, radius, color) end

Draw a filled polygon on an image.

function draw_polygon_on_image(destination, points, color) end

Draw a filled round-rectangle on an image.

function draw_rectangle_rounded_on_image(destination, x, y, width, height, cornerRadius, color) end

Draw an image on an image.

function draw_image_on_image(destination, src, posX, posY) end

Draw a tinted image on an image.

function draw_image_tint_on_image(destination, src, posX, posY, tint) end

Draw an image, rotated, on an image.

function draw_image_rotated_on_image(destination, src, posX, posY, degrees, offsetX, offsetY, filter) end

Draw an image, flipped, on an image.

function draw_image_flipped_on_image(destination, src, posX, posY, flipHorizontal, flipVertical, flipDiagonal) end

Draw an image, scaled, on an image.

function draw_image_scaled_on_image(destination, src, posX, posY, scaleX, scaleY, offsetX, offsetY, filter) end

Draw some text on an image.

function draw_text_on_image(destination, font, text, posX, posY, color) end

Draw a outlined (with thickness) rectangle on the screen.

function draw_rectangle_outline(posX, posY, width, height, thickness, color) end

Draw a outlined (with thickness) triangle on the screen.

function draw_triangle_outline(x1, y1, x2, y2, x3, y3, thickness, color) end

Draw a outlined (with thickness) ellipse on the screen.

function draw_ellipse_outline(centerX, centerY, radiusX, radiusY, thickness, color) end

Draw a outlined (with thickness) circle on the screen.

function draw_circle_outline(centerX, centerY, radius, thickness, color) end

Draw a outlined (with thickness) polygon on the screen.

function draw_polygon_outline(points, thickness, color) end

Draw a outlined (with thickness) arc on the screen.

function draw_arc_outline(centerX, centerY, radius, startAngle, endAngle, segments, thickness, color) end

Draw a outlined (with thickness) round-rectangle on the screen.

function draw_rectangle_rounded_outline(x, y, width, height, cornerRadius, thickness, color) end

Draw a outlined (with thickness) rectangle on an image.

function draw_rectangle_outline_on_image(destination, posX, posY, width, height, thickness, color) end

Draw a outlined (with thickness) triangle on an image.

function draw_triangle_outline_on_image(destination, x1, y1, x2, y2, x3, y3, thickness, color) end

Draw a outlined (with thickness) ellipse on an image.

function draw_ellipse_outline_on_image(destination, centerX, centerY, radiusX, radiusY, thickness, color) end

Draw a outlined (with thickness) circle on an image.

function draw_circle_outline_on_image(destination, centerX, centerY, radius, thickness, color) end

Draw a outlined (with thickness) polygon on an image.

function draw_polygon_outline_on_image(destination, points, thickness, color) end

Draw a outlined (with thickness) round-rectangle on an image.

function draw_rectangle_rounded_outline_on_image(destination, x, y, width, height, cornerRadius, thickness, color) end

gui (10)

Begin a GUI window. Returns false if the window is collapsed or closed - skip its contents, but still call gui_end_window.

function gui_begin_window(title, rect) end

End the current GUI window.

function gui_end_window() end

A button. Returns true when it is clicked.

function gui_button(label) end

A static text label.

function gui_label(text) end

A block of wrapping text.

function gui_text(text) end

A checkbox. Returns the (possibly changed) state.

function gui_checkbox(label, state) end

A slider. Returns the (possibly changed) value.

function gui_slider(value, low, high) end

Set the current layout row - the column widths (negative for flexible), and the row height.

function gui_layout_row(widths, height) end

Finish building the GUI for this frame. Called automatically at the end of update if you do not call it.

function gui_end() end

Draw the GUI to an image (0 is the screen).

function gui_draw(dst) end

input (12)

Has the key been pressed? (tracks unpress/read correctly.)

function key_pressed(key) end

Is the key currently down?

function key_down(key) end

Has the key been released? (tracks press/read correctly.)

function key_released(key) end

Is the key currently up?

function key_up(key) end

Has the button been pressed? (tracks unpress/read correctly.)

function gamepad_button_pressed(gamepad, button) end

Is the button currently down?

function gamepad_button_down(gamepad, button) end

Has the button been released? (tracks press/read correctly.)

function gamepad_button_released(gamepad, button) end

Get current position of mouse.

function mouse_position() end

Has the button been pressed? (tracks unpress/read correctly.)

function mouse_button_pressed(button) end

Is the button currently down?

function mouse_button_down(button) end

Has the button been released? (tracks press/read correctly.)

function mouse_button_released(button) end

Is the button currently up?

function mouse_button_up(button) end

sound (7)

Load a sound from a file in cart.

function load_sound(filename) end

Play a sound.

function play_sound(sound, loop) end

Stop a sound.

function stop_sound(sound) end

Unload a sound.

function unload_sound(sound) end

Speak some text and return a sound. Set things to 0 for defaults.

function tts_sound(text, phonetic, pitch, speed, throat, mouth, sing) end

Create Sfx sound.

function sfx_sound(params) end

Create Sfx parameters.

function sfx_generate(type) end

tile (38)

Load a tilemap (a Tiled map, exported as JSON) from a file in cart.

function load_tilemap(filename) end

Unload a tilemap.

function unload_tilemap(tilemap) end

Update a tilemap's animation timers (deltaTime is in seconds).

function tile_update(tilemap, deltaTime) end

Get the size of a tilemap, in tiles.

function tile_map_size(tilemap) end

Get the size of a single tile of a tilemap, in pixels.

function tile_tile_size(tilemap) end

Get a custom property of a tilemap, by name (PROP_NONE when there is no such property.)

function tile_map_prop(tilemap, name) end

Get the number of custom properties on a tilemap.

function tile_map_prop_count(tilemap) end

Get a custom property of a tilemap, by index (PROP_NONE when out of range.)

function tile_map_prop_at(tilemap, index) end

Draw a tilemap on the screen.

function tile_draw(tilemap, posX, posY) end

Draw a tilemap on the screen, tinted by a color.

function tile_draw_tint(tilemap, posX, posY, tint) end

Draw a tilemap on an image.

function tile_draw_on_image(dst, tilemap, posX, posY) end

Render a whole tilemap to a new image.

function tilemap_image(tilemap) end

Get the number of layers in a tilemap. Layers are numbered depth-first, so the children of a group layer have their own indexes too.

function tile_layer_count(tilemap) end

Get the index of a layer of a tilemap, by name (-1 when there is no such layer.)

function tile_layer_index(tilemap, name) end

Get the name of a layer of a tilemap.

function tile_layer_name(tilemap, layer) end

Get the kind of a layer of a tilemap.

function tile_layer_type(tilemap, layer) end

Get the size of a layer of a tilemap, in tiles.

function tile_layer_size(tilemap, layer) end

Get whether a layer of a tilemap is visible. Drawing a layer that Tiled marked hidden draws nothing.

function tile_layer_visible(tilemap, layer) end

Get a custom property of a layer of a tilemap, by name (PROP_NONE when there is no such property.)

function tile_layer_prop(tilemap, layer, name) end

Get the number of custom properties on a layer of a tilemap.

function tile_layer_prop_count(tilemap, layer) end

Get a custom property of a layer of a tilemap, by index (PROP_NONE when out of range.)

function tile_layer_prop_at(tilemap, layer, index) end

Draw a single layer of a tilemap on the screen.

function tile_draw_layer(tilemap, layer, posX, posY) end

Draw a single layer of a tilemap on the screen, tinted by a color.

function tile_draw_layer_tint(tilemap, layer, posX, posY, tint) end

Draw a single layer of a tilemap on an image.

function tile_draw_layer_on_image(dst, tilemap, layer, posX, posY) end

Render a single layer of a tilemap to a new image.

function tile_layer_image(tilemap, layer) end

Get the gid of the tile at a column/row in a tilemap layer.

function tile_get_tile(tilemap, layer, column, row) end

Set the gid of the tile at a column/row in a tilemap layer. Swapping a gid is how a cart keeps changing state in the map itself.

function tile_set_tile(tilemap, layer, column, row, gid) end

Draw a single tile from a tilemap on the screen.

function tile_draw_tile(tilemap, gid, posX, posY) end

Get a copy of the image of a single tile in a tilemap.

function tile_image(tilemap, gid) end

Get a custom property of a tile of a tilemap, by name (PROP_NONE when there is no such property.) These come from the tileset, so every tile with this gid shares them.

function tile_gid_prop(tilemap, gid, name) end

Get the number of custom properties on a tile of a tilemap.

function tile_gid_prop_count(tilemap, gid) end

Get a custom property of a tile of a tilemap, by index (PROP_NONE when out of range.)

function tile_gid_prop_at(tilemap, gid, index) end

Get the number of objects on an object-layer of a tilemap.

function tile_object_count(tilemap, layer) end

Get an object from an object-layer of a tilemap.

function tile_object(tilemap, layer, index) end

Get the index of an object on an object-layer of a tilemap, by name (-1 when there is no such object.)

function tile_object_index(tilemap, layer, name) end

Get a custom property of an object of a tilemap, by name (PROP_NONE when there is no such property.)

function tile_object_prop(tilemap, layer, index, name) end

Get the number of custom properties on an object of a tilemap.

function tile_object_prop_count(tilemap, layer, index) end

Get a custom property of an object of a tilemap, by index (PROP_NONE when out of range.)

function tile_object_prop_at(tilemap, layer, index, propIndex) end

utilities (5)

Get system-time (ms) since unix epoch.

function current_time() end

Get the change in time (seconds) since the last update run.

function delta_time() end

Get a random integer between 2 numbers.

function random_int(min, max) end

Get the random-seed.

function random_seed_get() end

Set the random-seed.

function random_seed_set(seed) end