notnull games

WAT

  • Template: cart_wat - press "Use this template" and you have a working game.
  • Docker image: ghcr.io/notnullgames/null0-cart-wat:latest
  • Your code: cart/main.wat, compiled with wat2wasm
  • Bindings: carts/wat/null0.wat (a reference list to copy from)
  • WASI is available, so ordinary file and stdio calls work.

building

You do not install wat2wasm - 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-wat:latest mygame

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

WAT notes

  • Raw wasm text - no include mechanism, so copy the imports you need out of null0.wat.
  • A Color is a *pointer to 4 bytes* you write into memory yourself.
  • No malloc, so struct-returning functions do not work on the web host.

a cart, in WAT

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

(module
  ;; null0 imports (see null0.wat for the full list)
  (import "null0" "clear" (func $clear (param i32)))
  (import "null0" "draw_circle" (func $draw_circle (param i32 i32 i32 i32)))

  (memory (export "memory") 1)

  ;; Color is a pointer to 4 bytes (r, g, b, a) in your memory, not a packed
  ;; scalar - see null0.wat for the full list of predefined color constants
  (data (i32.const 65536) "\00\79\f1\ff") ;; BLUE = rgba(0, 121, 241, 255)
  (global $blue i32 (i32.const 65536))
  (data (i32.const 65540) "\e6\29\37\ff") ;; RED = rgba(230, 41, 55, 255)
  (global $red i32 (i32.const 65540))

  ;; called on load
  (func (export "load")
    (call $clear (global.get $blue))
    (call $draw_circle
      (i32.const 100) (i32.const 100) (i32.const 50)
      (global.get $red)))

  ;; called on every frame
  (func (export "update"))

  ;; other callbacks you can implement:
  ;; (func (export "unload"))
  ;; (func (export "buttonUp") (param i32 i32))
  ;; (func (export "buttonDown") (param i32 i32))
  ;; (func (export "keyUp") (param i32))
  ;; (func (export "keyDown") (param i32))
  ;; (func (export "mouseDown") (param i32))
  ;; (func (export "mouseUp") (param i32))
  ;; (func (export "mouseMoved") (param f32 f32))
)
carts/wat/simple/main.wat

callbacks

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

(func (export "update") ...)

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

more WAT carts

the API, in WAT

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

(import "null0" "color_tint" (func $color_tint (param i32 i32) (result i32)))

Fade a color.

(import "null0" "color_fade" (func $color_fade (param i32 f32) (result i32)))

Change the brightness of a color.

(import "null0" "color_brightness" (func $color_brightness (param i32 f32) (result i32)))

Invert a color.

(import "null0" "color_invert" (func $color_invert (param i32) (result i32)))

Blend 2 colors together.

(import "null0" "color_alpha_blend" (func $color_alpha_blend (param i32 i32) (result i32)))

Change contrast of a color.

(import "null0" "color_contrast" (func $color_contrast (param i32 f32) (result i32)))

Interpolate colors.

(import "null0" "color_bilinear_interpolate" (func $color_bilinear_interpolate (param i32 i32 i32 i32 f32 f32) (result i32)))
graphics (75)

Create a new blank image.

(import "null0" "new_image" (func $new_image (param i32 i32 i32) (result i32)))

Copy an image to a new image.

(import "null0" "image_copy" (func $image_copy (param i32) (result i32)))

Create an image from a region of another image.

(import "null0" "image_subimage" (func $image_subimage (param i32 i32 i32 i32 i32) (result i32)))

Clear the screen.

(import "null0" "clear" (func $clear (param i32)))

Draw a single pixel on the screen.

(import "null0" "draw_point" (func $draw_point (param i32 i32 i32)))

Draw a line on the screen.

(import "null0" "draw_line" (func $draw_line (param i32 i32 i32 i32 i32)))

Draw a filled rectangle on the screen.

(import "null0" "draw_rectangle" (func $draw_rectangle (param i32 i32 i32 i32 i32)))

Draw a filled triangle on the screen.

(import "null0" "draw_triangle" (func $draw_triangle (param i32 i32 i32 i32 i32 i32 i32)))

Draw a filled ellipse on the screen.

(import "null0" "draw_ellipse" (func $draw_ellipse (param i32 i32 i32 i32 i32)))

Draw a filled circle on the screen.

(import "null0" "draw_circle" (func $draw_circle (param i32 i32 i32 i32)))

Draw a filled polygon on the screen.

(import "null0" "draw_polygon" (func $draw_polygon (param i32 i32 i32)))

Draw a filled arc on the screen.

(import "null0" "draw_arc" (func $draw_arc (param i32 i32 f32 f32 f32 i32 i32)))

Draw a filled round-rectangle on the screen.

(import "null0" "draw_rectangle_rounded" (func $draw_rectangle_rounded (param i32 i32 i32 i32 i32 i32)))

Draw an image on the screen.

(import "null0" "draw_image" (func $draw_image (param i32 i32 i32)))

Draw a tinted image on the screen.

(import "null0" "draw_image_tint" (func $draw_image_tint (param i32 i32 i32 i32)))

Draw an image, rotated, on the screen.

(import "null0" "draw_image_rotated" (func $draw_image_rotated (param i32 i32 i32 f32 f32 f32 i32)))

Draw an image, flipped, on the screen.

(import "null0" "draw_image_flipped" (func $draw_image_flipped (param i32 i32 i32 i32 i32 i32)))

Draw an image, scaled, on the screen.

(import "null0" "draw_image_scaled" (func $draw_image_scaled (param i32 i32 i32 f32 f32 f32 f32 i32)))

Draw some text on the screen.

(import "null0" "draw_text" (func $draw_text (param i32 i32 i32 i32 i32)))

Save an image to persistant storage.

(import "null0" "save_image" (func $save_image (param i32 i32)))

Load an image from a file in cart.

(import "null0" "load_image" (func $load_image (param i32) (result i32)))

Resize an image, return copy.

(import "null0" "image_resize" (func $image_resize (param i32 i32 i32 i32) (result i32)))

Scale an image, return copy.

(import "null0" "image_scale" (func $image_scale (param i32 f32 f32 i32) (result i32)))

Replace a color in an image, in-place.

(import "null0" "image_color_replace" (func $image_color_replace (param i32 i32 i32)))

Tint a color in an image, in-place.

(import "null0" "image_color_tint" (func $image_color_tint (param i32 i32)))

Fade a color in an image, in-place.

(import "null0" "image_color_fade" (func $image_color_fade (param i32 f32)))

Copy a font to a new font.

(import "null0" "font_copy" (func $font_copy (param i32) (result i32)))

Scale a font, return a new font.

(import "null0" "font_scale" (func $font_scale (param i32 f32 f32 i32) (result i32)))

Load a BMF font from a file in cart.

(import "null0" "load_font_bmf" (func $load_font_bmf (param i32 i32) (result i32)))

Load a BMF font from an image.

(import "null0" "load_font_bmf_from_image" (func $load_font_bmf_from_image (param i32 i32) (result i32)))

Measure the size of some text.

(import "null0" "measure_text" (func $measure_text (param i32 i32 i32) (result i32)))

Meaure an image (use 0 for screen).

(import "null0" "measure_image" (func $measure_image (param i32) (result i32)))

Load a TTY font from a file in cart.

(import "null0" "load_font_tty" (func $load_font_tty (param i32 i32 i32 i32) (result i32)))

Load a TTY font from an image.

(import "null0" "load_font_tty_from_image" (func $load_font_tty_from_image (param i32 i32 i32 i32) (result i32)))

Load a TTF font from a file in cart.

(import "null0" "load_font_ttf" (func $load_font_ttf (param i32 i32) (result i32)))

Invert the colors in an image, in-place.

(import "null0" "image_color_invert" (func $image_color_invert (param i32)))

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

(import "null0" "image_alpha_border" (func $image_alpha_border (param i32 f32) (result i32)))

Crop an image, in-place.

(import "null0" "image_crop" (func $image_crop (param i32 i32 i32 i32 i32)))

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

(import "null0" "image_alpha_crop" (func $image_alpha_crop (param i32 f32)))

Adjust the brightness of an image, in-place.

(import "null0" "image_color_brightness" (func $image_color_brightness (param i32 f32)))

Flip an image, in-place.

(import "null0" "image_flip" (func $image_flip (param i32 i32 i32)))

Change the contrast of an image, in-place.

(import "null0" "image_color_contrast" (func $image_color_contrast (param i32 f32)))

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

(import "null0" "image_alpha_mask" (func $image_alpha_mask (param i32 i32 i32 i32)))

Create a new image, rotating another image.

(import "null0" "image_rotate" (func $image_rotate (param i32 f32 i32) (result i32)))

Create a new image of a gradient.

(import "null0" "image_gradient" (func $image_gradient (param i32 i32 i32 i32 i32 i32) (result i32)))

Unload an image.

(import "null0" "unload_image" (func $unload_image (param i32)))

Unload a font.

(import "null0" "unload_font" (func $unload_font (param i32)))

Clear an image.

(import "null0" "clear_image" (func $clear_image (param i32 i32)))

Draw a single pixel on an image.

(import "null0" "draw_point_on_image" (func $draw_point_on_image (param i32 i32 i32 i32)))

Draw a line on an image.

(import "null0" "draw_line_on_image" (func $draw_line_on_image (param i32 i32 i32 i32 i32 i32)))

Draw a filled rectangle on an image.

(import "null0" "draw_rectangle_on_image" (func $draw_rectangle_on_image (param i32 i32 i32 i32 i32 i32)))

Draw a filled triangle on an image.

(import "null0" "draw_triangle_on_image" (func $draw_triangle_on_image (param i32 i32 i32 i32 i32 i32 i32 i32)))

Draw a filled ellipse on an image.

(import "null0" "draw_ellipse_on_image" (func $draw_ellipse_on_image (param i32 i32 i32 i32 i32 i32)))

Draw a circle on an image.

(import "null0" "draw_circle_on_image" (func $draw_circle_on_image (param i32 i32 i32 i32 i32)))

Draw a filled polygon on an image.

(import "null0" "draw_polygon_on_image" (func $draw_polygon_on_image (param i32 i32 i32 i32)))

Draw a filled round-rectangle on an image.

(import "null0" "draw_rectangle_rounded_on_image" (func $draw_rectangle_rounded_on_image (param i32 i32 i32 i32 i32 i32 i32)))

Draw an image on an image.

(import "null0" "draw_image_on_image" (func $draw_image_on_image (param i32 i32 i32 i32)))

Draw a tinted image on an image.

(import "null0" "draw_image_tint_on_image" (func $draw_image_tint_on_image (param i32 i32 i32 i32 i32)))

Draw an image, rotated, on an image.

(import "null0" "draw_image_rotated_on_image" (func $draw_image_rotated_on_image (param i32 i32 i32 i32 f32 f32 f32 i32)))

Draw an image, flipped, on an image.

(import "null0" "draw_image_flipped_on_image" (func $draw_image_flipped_on_image (param i32 i32 i32 i32 i32 i32 i32)))

Draw an image, scaled, on an image.

(import "null0" "draw_image_scaled_on_image" (func $draw_image_scaled_on_image (param i32 i32 i32 i32 f32 f32 f32 f32 i32)))

Draw some text on an image.

(import "null0" "draw_text_on_image" (func $draw_text_on_image (param i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_rectangle_outline" (func $draw_rectangle_outline (param i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_triangle_outline" (func $draw_triangle_outline (param i32 i32 i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_ellipse_outline" (func $draw_ellipse_outline (param i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_circle_outline" (func $draw_circle_outline (param i32 i32 i32 i32 i32)))

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

(import "null0" "draw_polygon_outline" (func $draw_polygon_outline (param i32 i32 i32 i32)))

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

(import "null0" "draw_arc_outline" (func $draw_arc_outline (param i32 i32 f32 f32 f32 i32 i32 i32)))

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

(import "null0" "draw_rectangle_rounded_outline" (func $draw_rectangle_rounded_outline (param i32 i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_rectangle_outline_on_image" (func $draw_rectangle_outline_on_image (param i32 i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_triangle_outline_on_image" (func $draw_triangle_outline_on_image (param i32 i32 i32 i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_ellipse_outline_on_image" (func $draw_ellipse_outline_on_image (param i32 i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_circle_outline_on_image" (func $draw_circle_outline_on_image (param i32 i32 i32 i32 i32 i32)))

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

(import "null0" "draw_polygon_outline_on_image" (func $draw_polygon_outline_on_image (param i32 i32 i32 i32 i32)))

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

(import "null0" "draw_rectangle_rounded_outline_on_image" (func $draw_rectangle_rounded_outline_on_image (param i32 i32 i32 i32 i32 i32 i32 i32)))
gui (10)

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

(import "null0" "gui_begin_window" (func $gui_begin_window (param i32 i32) (result i32)))

End the current GUI window.

(import "null0" "gui_end_window" (func $gui_end_window))

A button. Returns true when it is clicked.

(import "null0" "gui_button" (func $gui_button (param i32) (result i32)))

A static text label.

(import "null0" "gui_label" (func $gui_label (param i32)))

A block of wrapping text.

(import "null0" "gui_text" (func $gui_text (param i32)))

A checkbox. Returns the (possibly changed) state.

(import "null0" "gui_checkbox" (func $gui_checkbox (param i32 i32) (result i32)))

A slider. Returns the (possibly changed) value.

(import "null0" "gui_slider" (func $gui_slider (param f32 f32 f32) (result f32)))

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

(import "null0" "gui_layout_row" (func $gui_layout_row (param i32 i32 i32)))

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

(import "null0" "gui_end" (func $gui_end))

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

(import "null0" "gui_draw" (func $gui_draw (param i32)))
input (12)

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

(import "null0" "key_pressed" (func $key_pressed (param i32) (result i32)))

Is the key currently down?

(import "null0" "key_down" (func $key_down (param i32) (result i32)))

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

(import "null0" "key_released" (func $key_released (param i32) (result i32)))

Is the key currently up?

(import "null0" "key_up" (func $key_up (param i32) (result i32)))

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

(import "null0" "gamepad_button_pressed" (func $gamepad_button_pressed (param i32 i32) (result i32)))

Is the button currently down?

(import "null0" "gamepad_button_down" (func $gamepad_button_down (param i32 i32) (result i32)))

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

(import "null0" "gamepad_button_released" (func $gamepad_button_released (param i32 i32) (result i32)))

Get current position of mouse.

(import "null0" "mouse_position" (func $mouse_position (result i32)))

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

(import "null0" "mouse_button_pressed" (func $mouse_button_pressed (param i32) (result i32)))

Is the button currently down?

(import "null0" "mouse_button_down" (func $mouse_button_down (param i32) (result i32)))

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

(import "null0" "mouse_button_released" (func $mouse_button_released (param i32) (result i32)))

Is the button currently up?

(import "null0" "mouse_button_up" (func $mouse_button_up (param i32) (result i32)))
sound (7)

Load a sound from a file in cart.

(import "null0" "load_sound" (func $load_sound (param i32) (result i32)))

Play a sound.

(import "null0" "play_sound" (func $play_sound (param i32 i32)))

Stop a sound.

(import "null0" "stop_sound" (func $stop_sound (param i32)))

Unload a sound.

(import "null0" "unload_sound" (func $unload_sound (param i32)))

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

(import "null0" "tts_sound" (func $tts_sound (param i32 i32 i32 i32 i32 i32 i32) (result i32)))

Create Sfx sound.

(import "null0" "sfx_sound" (func $sfx_sound (param i32) (result i32)))

Create Sfx parameters.

(import "null0" "sfx_generate" (func $sfx_generate (param i32) (result i32)))
tile (38)

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

(import "null0" "load_tilemap" (func $load_tilemap (param i32) (result i32)))

Unload a tilemap.

(import "null0" "unload_tilemap" (func $unload_tilemap (param i32)))

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

(import "null0" "tile_update" (func $tile_update (param i32 f32)))

Get the size of a tilemap, in tiles.

(import "null0" "tile_map_size" (func $tile_map_size (param i32) (result i32)))

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

(import "null0" "tile_tile_size" (func $tile_tile_size (param i32) (result i32)))

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

(import "null0" "tile_map_prop" (func $tile_map_prop (param i32 i32) (result i32)))

Get the number of custom properties on a tilemap.

(import "null0" "tile_map_prop_count" (func $tile_map_prop_count (param i32) (result i32)))

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

(import "null0" "tile_map_prop_at" (func $tile_map_prop_at (param i32 i32) (result i32)))

Draw a tilemap on the screen.

(import "null0" "tile_draw" (func $tile_draw (param i32 i32 i32)))

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

(import "null0" "tile_draw_tint" (func $tile_draw_tint (param i32 i32 i32 i32)))

Draw a tilemap on an image.

(import "null0" "tile_draw_on_image" (func $tile_draw_on_image (param i32 i32 i32 i32)))

Render a whole tilemap to a new image.

(import "null0" "tilemap_image" (func $tilemap_image (param i32) (result i32)))

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.

(import "null0" "tile_layer_count" (func $tile_layer_count (param i32) (result i32)))

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

(import "null0" "tile_layer_index" (func $tile_layer_index (param i32 i32) (result i32)))

Get the name of a layer of a tilemap.

(import "null0" "tile_layer_name" (func $tile_layer_name (param i32 i32) (result i32)))

Get the kind of a layer of a tilemap.

(import "null0" "tile_layer_type" (func $tile_layer_type (param i32 i32) (result i32)))

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

(import "null0" "tile_layer_size" (func $tile_layer_size (param i32 i32) (result i32)))

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

(import "null0" "tile_layer_visible" (func $tile_layer_visible (param i32 i32) (result i32)))

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

(import "null0" "tile_layer_prop" (func $tile_layer_prop (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_layer_prop_count" (func $tile_layer_prop_count (param i32 i32) (result i32)))

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

(import "null0" "tile_layer_prop_at" (func $tile_layer_prop_at (param i32 i32 i32) (result i32)))

Draw a single layer of a tilemap on the screen.

(import "null0" "tile_draw_layer" (func $tile_draw_layer (param i32 i32 i32 i32)))

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

(import "null0" "tile_draw_layer_tint" (func $tile_draw_layer_tint (param i32 i32 i32 i32 i32)))

Draw a single layer of a tilemap on an image.

(import "null0" "tile_draw_layer_on_image" (func $tile_draw_layer_on_image (param i32 i32 i32 i32 i32)))

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

(import "null0" "tile_layer_image" (func $tile_layer_image (param i32 i32) (result i32)))

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

(import "null0" "tile_get_tile" (func $tile_get_tile (param i32 i32 i32 i32) (result i32)))

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.

(import "null0" "tile_set_tile" (func $tile_set_tile (param i32 i32 i32 i32 i32)))

Draw a single tile from a tilemap on the screen.

(import "null0" "tile_draw_tile" (func $tile_draw_tile (param i32 i32 i32 i32)))

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

(import "null0" "tile_image" (func $tile_image (param i32 i32) (result i32)))

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.

(import "null0" "tile_gid_prop" (func $tile_gid_prop (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_gid_prop_count" (func $tile_gid_prop_count (param i32 i32) (result i32)))

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

(import "null0" "tile_gid_prop_at" (func $tile_gid_prop_at (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_object_count" (func $tile_object_count (param i32 i32) (result i32)))

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

(import "null0" "tile_object" (func $tile_object (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_object_index" (func $tile_object_index (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_object_prop" (func $tile_object_prop (param i32 i32 i32 i32) (result i32)))

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

(import "null0" "tile_object_prop_count" (func $tile_object_prop_count (param i32 i32 i32) (result i32)))

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

(import "null0" "tile_object_prop_at" (func $tile_object_prop_at (param i32 i32 i32 i32) (result i32)))
utilities (5)

Get system-time (ms) since unix epoch.

(import "null0" "current_time" (func $current_time (result i64)))

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

(import "null0" "delta_time" (func $delta_time (result f32)))

Get a random integer between 2 numbers.

(import "null0" "random_int" (func $random_int (param i32 i32) (result i32)))

Get the random-seed.

(import "null0" "random_seed_get" (func $random_seed_get (result i64)))

Set the random-seed.

(import "null0" "random_seed_set" (func $random_seed_set (param i64)))