notnull games

Wren

🐦Wren is a small, class-based scripting language with a lovely syntax. The null0 API hangs off a Null0 class, and zero-argument calls are getters.

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

building

You do not install wren, 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-wren:latest mygame

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

Wren notes

import "null0" for Null0, BLUE - the API hangs off the Null0 class.
Callbacks are Fn values assigned to top-level variables.

a cart, in Wren

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

// simple wren cart for null0 (interpreted)
//
// the null0 API lives on the Null0 class, and structs (Color/Vector/
// Rectangle/Dimensions/SfxParams) are classes - see null0.wren for the
// whole list. callbacks are module-level Fn variables.

import "null0" for Null0, BLUE, RED, WHITE, KEY_SPACE, FONT_DEFAULT

var counter = 0

var load = Fn.new {
  System.print("wren cart says \"hi\"")
  System.print("Press buttons to see reaction.")
  System.print("Press SPACE to see text on screen.")
}

var buttonDown = Fn.new { |button, player|
  System.print("buttonDown: %(button) %(player)")
}

var update = Fn.new {
  counter = counter + 1
  Null0.clear(BLUE)
  Null0.draw_rectangle(10, 10, 100, 50, RED)
  if (Null0.key_down(KEY_SPACE)) {
    Null0.draw_text(FONT_DEFAULT, "Space pressed!", 50, 50, WHITE)
  }
}

// other callbacks you can implement:
// var unload = Fn.new {}
// var buttonUp = Fn.new { |button, player| }
// var keyUp = Fn.new { |key| }
// var keyDown = Fn.new { |key| }
// var mouseDown = Fn.new { |button| }
// var mouseUp = Fn.new { |button| }
// var mouseMoved = Fn.new { |x, y| }

carts/wren/simple/main.wren

callbacks

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

var update = Fn.new {}

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

more Wren carts

demo - source

the API, in Wren

Every null0 function, spelled the way Wren 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.

static color_tint(color, tint)

Fade a color.

static color_fade(color, alpha)

Change the brightness of a color.

static color_brightness(color, factor)

Invert a color.

static color_invert(color)

Blend 2 colors together.

static color_alpha_blend(dst, src)

Change contrast of a color.

static color_contrast(color, contrast)

Interpolate colors.

static color_bilinear_interpolate(color00, color01, color10, color11, coordinateX, coordinateY)

graphics (75)

Create a new blank image.

static new_image(width, height, color)

Copy an image to a new image.

static image_copy(image)

Create an image from a region of another image.

static image_subimage(image, x, y, width, height)

Clear the screen.

static clear(color)

Draw a single pixel on the screen.

static draw_point(x, y, color)

Draw a line on the screen.

static draw_line(startPosX, startPosY, endPosX, endPosY, color)

Draw a filled rectangle on the screen.

static draw_rectangle(posX, posY, width, height, color)

Draw a filled triangle on the screen.

static draw_triangle(x1, y1, x2, y2, x3, y3, color)

Draw a filled ellipse on the screen.

static draw_ellipse(centerX, centerY, radiusX, radiusY, color)

Draw a filled circle on the screen.

static draw_circle(centerX, centerY, radius, color)

Draw a filled polygon on the screen.

static draw_polygon(points, color) {

Draw a filled arc on the screen.

static draw_arc(centerX, centerY, radius, startAngle, endAngle, segments, color)

Draw a filled round-rectangle on the screen.

static draw_rectangle_rounded(x, y, width, height, cornerRadius, color)

Draw an image on the screen.

static draw_image(src, posX, posY)

Draw a tinted image on the screen.

static draw_image_tint(src, posX, posY, tint)

Draw an image, rotated, on the screen.

static draw_image_rotated(src, posX, posY, degrees, offsetX, offsetY, filter)

Draw an image, flipped, on the screen.

static draw_image_flipped(src, posX, posY, flipHorizontal, flipVertical, flipDiagonal)

Draw an image, scaled, on the screen.

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

Draw some text on the screen.

static draw_text(font, text, posX, posY, color)

Save an image to persistant storage.

static save_image(image, filename)

Load an image from a file in cart.

static load_image(filename)

Resize an image, return copy.

static image_resize(image, newWidth, newHeight, filter)

Scale an image, return copy.

static image_scale(image, scaleX, scaleY, filter)

Replace a color in an image, in-place.

static image_color_replace(image, color, replace)

Tint a color in an image, in-place.

static image_color_tint(image, color)

Fade a color in an image, in-place.

static image_color_fade(image, alpha)

Copy a font to a new font.

static font_copy(font)

Scale a font, return a new font.

static font_scale(font, scaleX, scaleY, filter)

Load a BMF font from a file in cart.

static load_font_bmf(filename, characters)

Load a BMF font from an image.

static load_font_bmf_from_image(image, characters)

Measure the size of some text.

static measure_text(font, text, textLength)

Meaure an image (use 0 for screen).

static measure_image(image)

Load a TTY font from a file in cart.

static load_font_tty(filename, glyphWidth, glyphHeight, characters)

Load a TTY font from an image.

static load_font_tty_from_image(image, glyphWidth, glyphHeight, characters)

Load a TTF font from a file in cart.

static load_font_ttf(filename, fontSize)

Invert the colors in an image, in-place.

static image_color_invert(image)

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

static image_alpha_border(image, threshold)

Crop an image, in-place.

static image_crop(image, x, y, width, height)

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

static image_alpha_crop(image, threshold)

Adjust the brightness of an image, in-place.

static image_color_brightness(image, factor)

Flip an image, in-place.

static image_flip(image, horizontal, vertical)

Change the contrast of an image, in-place.

static image_color_contrast(image, contrast)

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

static image_alpha_mask(image, alphaMask, posX, posY)

Create a new image, rotating another image.

static image_rotate(image, degrees, filter)

Create a new image of a gradient.

static image_gradient(width, height, topLeft, topRight, bottomLeft, bottomRight)

Unload an image.

static unload_image(image)

Unload a font.

static unload_font(font)

Clear an image.

static clear_image(destination, color)

Draw a single pixel on an image.

static draw_point_on_image(destination, x, y, color)

Draw a line on an image.

static draw_line_on_image(destination, startPosX, startPosY, endPosX, endPosY, color)

Draw a filled rectangle on an image.

static draw_rectangle_on_image(destination, posX, posY, width, height, color)

Draw a filled triangle on an image.

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

Draw a filled ellipse on an image.

static draw_ellipse_on_image(destination, centerX, centerY, radiusX, radiusY, color)

Draw a circle on an image.

static draw_circle_on_image(destination, centerX, centerY, radius, color)

Draw a filled polygon on an image.

static draw_polygon_on_image(destination, points, color) {

Draw a filled round-rectangle on an image.

static draw_rectangle_rounded_on_image(destination, x, y, width, height, cornerRadius, color)

Draw an image on an image.

static draw_image_on_image(destination, src, posX, posY)

Draw a tinted image on an image.

static draw_image_tint_on_image(destination, src, posX, posY, tint)

Draw an image, rotated, on an image.

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

Draw an image, flipped, on an image.

static draw_image_flipped_on_image(destination, src, posX, posY, flipHorizontal, flipVertical, flipDiagonal)

Draw an image, scaled, on an image.

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

Draw some text on an image.

static draw_text_on_image(destination, font, text, posX, posY, color)

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

static draw_rectangle_outline(posX, posY, width, height, thickness, color)

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

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

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

static draw_ellipse_outline(centerX, centerY, radiusX, radiusY, thickness, color)

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

static draw_circle_outline(centerX, centerY, radius, thickness, color)

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

static draw_polygon_outline(points, thickness, color) {

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

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

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

static draw_rectangle_rounded_outline(x, y, width, height, cornerRadius, thickness, color)

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

static draw_rectangle_outline_on_image(destination, posX, posY, width, height, thickness, color)

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

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

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

static draw_ellipse_outline_on_image(destination, centerX, centerY, radiusX, radiusY, thickness, color)

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

static draw_circle_outline_on_image(destination, centerX, centerY, radius, thickness, color)

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

static draw_polygon_outline_on_image(destination, points, thickness, color) {

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

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

gui (10)

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

static gui_begin_window(title, rect)

End the current GUI window.

static gui_end_window

A button. Returns true when it is clicked.

static gui_button(label)

A static text label.

static gui_label(text)

A block of wrapping text.

static gui_text(text)

A checkbox. Returns the (possibly changed) state.

static gui_checkbox(label, state)

A slider. Returns the (possibly changed) value.

static gui_slider(value, low, high)

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

static gui_layout_row(widths, height)

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

static gui_end

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

static gui_draw(dst)

input (12)

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

static key_pressed(key)

Is the key currently down?

static key_down(key)

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

static key_released(key)

Is the key currently up?

static key_up(key)

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

static gamepad_button_pressed(gamepad, button)

Is the button currently down?

static gamepad_button_down(gamepad, button)

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

static gamepad_button_released(gamepad, button)

Get current position of mouse.

static mouse_position

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

static mouse_button_pressed(button)

Is the button currently down?

static mouse_button_down(button)

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

static mouse_button_released(button)

Is the button currently up?

static mouse_button_up(button)

sound (7)

Load a sound from a file in cart.

static load_sound(filename)

Play a sound.

static play_sound(sound, loop)

Stop a sound.

static stop_sound(sound)

Unload a sound.

static unload_sound(sound)

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

static tts_sound(text, phonetic, pitch, speed, throat, mouth, sing)

Create Sfx sound.

static sfx_sound(params)

Create Sfx parameters.

static sfx_generate(type)

tile (38)

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

static load_tilemap(filename)

Unload a tilemap.

static unload_tilemap(tilemap)

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

static tile_update(tilemap, deltaTime)

Get the size of a tilemap, in tiles.

static tile_map_size(tilemap)

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

static tile_tile_size(tilemap)

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

static tile_map_prop(tilemap, name)

Get the number of custom properties on a tilemap.

static tile_map_prop_count(tilemap)

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

static tile_map_prop_at(tilemap, index)

Draw a tilemap on the screen.

static tile_draw(tilemap, posX, posY)

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

static tile_draw_tint(tilemap, posX, posY, tint)

Draw a tilemap on an image.

static tile_draw_on_image(dst, tilemap, posX, posY)

Render a whole tilemap to a new image.

static tilemap_image(tilemap)

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.

static tile_layer_count(tilemap)

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

static tile_layer_index(tilemap, name)

Get the name of a layer of a tilemap.

static tile_layer_name(tilemap, layer)

Get the kind of a layer of a tilemap.

static tile_layer_type(tilemap, layer)

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

static tile_layer_size(tilemap, layer)

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

static tile_layer_visible(tilemap, layer)

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

static tile_layer_prop(tilemap, layer, name)

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

static tile_layer_prop_count(tilemap, layer)

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

static tile_layer_prop_at(tilemap, layer, index)

Draw a single layer of a tilemap on the screen.

static tile_draw_layer(tilemap, layer, posX, posY)

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

static tile_draw_layer_tint(tilemap, layer, posX, posY, tint)

Draw a single layer of a tilemap on an image.

static tile_draw_layer_on_image(dst, tilemap, layer, posX, posY)

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

static tile_layer_image(tilemap, layer)

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

static tile_get_tile(tilemap, layer, column, row)

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.

static tile_set_tile(tilemap, layer, column, row, gid)

Draw a single tile from a tilemap on the screen.

static tile_draw_tile(tilemap, gid, posX, posY)

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

static tile_image(tilemap, gid)

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.

static tile_gid_prop(tilemap, gid, name)

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

static tile_gid_prop_count(tilemap, gid)

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

static tile_gid_prop_at(tilemap, gid, index)

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

static tile_object_count(tilemap, layer)

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

static tile_object(tilemap, layer, index)

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

static tile_object_index(tilemap, layer, name)

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

static tile_object_prop(tilemap, layer, index, name)

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

static tile_object_prop_count(tilemap, layer, index)

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

static tile_object_prop_at(tilemap, layer, index, propIndex)

utilities (5)

Get system-time (ms) since unix epoch.

static current_time

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

static delta_time

Get a random integer between 2 numbers.

static random_int(min, max)

Get the random-seed.

static random_seed_get

Set the random-seed.

static random_seed_set(seed)