notnull games

AssemblyScript

  • Template: cart_as - press "Use this template" and you have a working game.
  • Docker image: ghcr.io/notnullgames/null0-cart-assemblyscript:latest
  • Your code: cart/main.ts, compiled with asc
  • Bindings: carts/as/null0.ts (baked into the docker image for you)
  • WASI is available, so ordinary file and stdio calls work.

building

You do not install asc - 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-assemblyscript:latest mygame

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

AssemblyScript notes

  • Import what you use: import { clear, draw_circle, BLUE } from './null0'.
  • Built with --runtime stub, so there is no GC - treat allocations as permanent.

a cart, in AssemblyScript

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

// AssemblyScript null0 cart example

import { clear, DARKBLUE } from 'null0.ts'

export function load(): void {
  clear(DARKBLUE)
}
carts/as/simple/main.ts

callbacks

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

export function load(): void {}

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

more AssemblyScript carts

the API, in AssemblyScript

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

export declare function color_tint(color: Color, tint: Color): Color;

Fade a color.

export declare function color_fade(color: Color, alpha: f32): Color;

Change the brightness of a color.

export declare function color_brightness(color: Color, factor: f32): Color;

Invert a color.

export declare function color_invert(color: Color): Color;

Blend 2 colors together.

export declare function color_alpha_blend(dst: Color, src: Color): Color;

Change contrast of a color.

export declare function color_contrast(color: Color, contrast: f32): Color;

Interpolate colors.

export declare function color_bilinear_interpolate(color00: Color, color01: Color, color10: Color, color11: Color, coordinateX: f32, coordinateY: f32): Color;
graphics (75)

Create a new blank image.

export declare function new_image(width: i32, height: i32, color: Color): u32;

Copy an image to a new image.

export declare function image_copy(image: u32): u32;

Create an image from a region of another image.

export declare function image_subimage(image: u32, x: i32, y: i32, width: i32, height: i32): u32;

Clear the screen.

export declare function clear(color: Color): void;

Draw a single pixel on the screen.

export declare function draw_point(x: i32, y: i32, color: Color): void;

Draw a line on the screen.

export declare function draw_line(startPosX: i32, startPosY: i32, endPosX: i32, endPosY: i32, color: Color): void;

Draw a filled rectangle on the screen.

export declare function draw_rectangle(posX: i32, posY: i32, width: i32, height: i32, color: Color): void;

Draw a filled triangle on the screen.

export declare function draw_triangle(x1: i32, y1: i32, x2: i32, y2: i32, x3: i32, y3: i32, color: Color): void;

Draw a filled ellipse on the screen.

export declare function draw_ellipse(centerX: i32, centerY: i32, radiusX: i32, radiusY: i32, color: Color): void;

Draw a filled circle on the screen.

export declare function draw_circle(centerX: i32, centerY: i32, radius: i32, color: Color): void;

Draw a filled polygon on the screen.

export declare function draw_polygon(points: usize, numPoints: i32, color: Color): void;

Draw a filled arc on the screen.

export declare function draw_arc(centerX: i32, centerY: i32, radius: f32, startAngle: f32, endAngle: f32, segments: i32, color: Color): void;

Draw a filled round-rectangle on the screen.

export declare function draw_rectangle_rounded(x: i32, y: i32, width: i32, height: i32, cornerRadius: i32, color: Color): void;

Draw an image on the screen.

export declare function draw_image(src: u32, posX: i32, posY: i32): void;

Draw a tinted image on the screen.

export declare function draw_image_tint(src: u32, posX: i32, posY: i32, tint: Color): void;

Draw an image, rotated, on the screen.

export declare function draw_image_rotated(src: u32, posX: i32, posY: i32, degrees: f32, offsetX: f32, offsetY: f32, filter: ImageFilter): void;

Draw an image, flipped, on the screen.

export declare function draw_image_flipped(src: u32, posX: i32, posY: i32, flipHorizontal: bool, flipVertical: bool, flipDiagonal: bool): void;

Draw an image, scaled, on the screen.

export declare function draw_image_scaled(src: u32, posX: i32, posY: i32, scaleX: f32, scaleY: f32, offsetX: f32, offsetY: f32, filter: ImageFilter): void;

Draw some text on the screen.

export declare function draw_text(font: u32, text: usize, posX: i32, posY: i32, color: Color): void;

Save an image to persistant storage.

export declare function save_image(image: u32, filename: usize): void;

Load an image from a file in cart.

export declare function load_image(filename: usize): u32;

Resize an image, return copy.

export declare function image_resize(image: u32, newWidth: i32, newHeight: i32, filter: ImageFilter): u32;

Scale an image, return copy.

export declare function image_scale(image: u32, scaleX: f32, scaleY: f32, filter: ImageFilter): u32;

Replace a color in an image, in-place.

export declare function image_color_replace(image: u32, color: Color, replace: Color): void;

Tint a color in an image, in-place.

export declare function image_color_tint(image: u32, color: Color): void;

Fade a color in an image, in-place.

export declare function image_color_fade(image: u32, alpha: f32): void;

Copy a font to a new font.

export declare function font_copy(font: u32): u32;

Scale a font, return a new font.

export declare function font_scale(font: u32, scaleX: f32, scaleY: f32, filter: ImageFilter): u32;

Load a BMF font from a file in cart.

export declare function load_font_bmf(filename: usize, characters: usize): u32;

Load a BMF font from an image.

export declare function load_font_bmf_from_image(image: u32, characters: usize): u32;

Measure the size of some text.

export declare function measure_text(font: u32, text: usize, textLength: i32): Dimensions;

Meaure an image (use 0 for screen).

export declare function measure_image(image: u32): Dimensions;

Load a TTY font from a file in cart.

export declare function load_font_tty(filename: usize, glyphWidth: i32, glyphHeight: i32, characters: usize): u32;

Load a TTY font from an image.

export declare function load_font_tty_from_image(image: u32, glyphWidth: i32, glyphHeight: i32, characters: usize): u32;

Load a TTF font from a file in cart.

export declare function load_font_ttf(filename: usize, fontSize: i32): u32;

Invert the colors in an image, in-place.

export declare function image_color_invert(image: u32): void;

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

export declare function image_alpha_border(image: u32, threshold: f32): Rectangle;

Crop an image, in-place.

export declare function image_crop(image: u32, x: i32, y: i32, width: i32, height: i32): void;

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

export declare function image_alpha_crop(image: u32, threshold: f32): void;

Adjust the brightness of an image, in-place.

export declare function image_color_brightness(image: u32, factor: f32): void;

Flip an image, in-place.

export declare function image_flip(image: u32, horizontal: bool, vertical: bool): void;

Change the contrast of an image, in-place.

export declare function image_color_contrast(image: u32, contrast: f32): void;

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

export declare function image_alpha_mask(image: u32, alphaMask: u32, posX: i32, posY: i32): void;

Create a new image, rotating another image.

export declare function image_rotate(image: u32, degrees: f32, filter: ImageFilter): u32;

Create a new image of a gradient.

export declare function image_gradient(width: i32, height: i32, topLeft: Color, topRight: Color, bottomLeft: Color, bottomRight: Color): u32;

Unload an image.

export declare function unload_image(image: u32): void;

Unload a font.

export declare function unload_font(font: u32): void;

Clear an image.

export declare function clear_image(destination: u32, color: Color): void;

Draw a single pixel on an image.

export declare function draw_point_on_image(destination: u32, x: i32, y: i32, color: Color): void;

Draw a line on an image.

export declare function draw_line_on_image(destination: u32, startPosX: i32, startPosY: i32, endPosX: i32, endPosY: i32, color: Color): void;

Draw a filled rectangle on an image.

export declare function draw_rectangle_on_image(destination: u32, posX: i32, posY: i32, width: i32, height: i32, color: Color): void;

Draw a filled triangle on an image.

export declare function draw_triangle_on_image(destination: u32, x1: i32, y1: i32, x2: i32, y2: i32, x3: i32, y3: i32, color: Color): void;

Draw a filled ellipse on an image.

export declare function draw_ellipse_on_image(destination: u32, centerX: i32, centerY: i32, radiusX: i32, radiusY: i32, color: Color): void;

Draw a circle on an image.

export declare function draw_circle_on_image(destination: u32, centerX: i32, centerY: i32, radius: i32, color: Color): void;

Draw a filled polygon on an image.

export declare function draw_polygon_on_image(destination: u32, points: usize, numPoints: i32, color: Color): void;

Draw a filled round-rectangle on an image.

export declare function draw_rectangle_rounded_on_image(destination: u32, x: i32, y: i32, width: i32, height: i32, cornerRadius: i32, color: Color): void;

Draw an image on an image.

export declare function draw_image_on_image(destination: u32, src: u32, posX: i32, posY: i32): void;

Draw a tinted image on an image.

export declare function draw_image_tint_on_image(destination: u32, src: u32, posX: i32, posY: i32, tint: Color): void;

Draw an image, rotated, on an image.

export declare function draw_image_rotated_on_image(destination: u32, src: u32, posX: i32, posY: i32, degrees: f32, offsetX: f32, offsetY: f32, filter: ImageFilter): void;

Draw an image, flipped, on an image.

export declare function draw_image_flipped_on_image(destination: u32, src: u32, posX: i32, posY: i32, flipHorizontal: bool, flipVertical: bool, flipDiagonal: bool): void;

Draw an image, scaled, on an image.

export declare function draw_image_scaled_on_image(destination: u32, src: u32, posX: i32, posY: i32, scaleX: f32, scaleY: f32, offsetX: f32, offsetY: f32, filter: ImageFilter): void;

Draw some text on an image.

export declare function draw_text_on_image(destination: u32, font: u32, text: usize, posX: i32, posY: i32, color: Color): void;

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

export declare function draw_rectangle_outline(posX: i32, posY: i32, width: i32, height: i32, thickness: i32, color: Color): void;

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

export declare function draw_triangle_outline(x1: i32, y1: i32, x2: i32, y2: i32, x3: i32, y3: i32, thickness: i32, color: Color): void;

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

export declare function draw_ellipse_outline(centerX: i32, centerY: i32, radiusX: i32, radiusY: i32, thickness: i32, color: Color): void;

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

export declare function draw_circle_outline(centerX: i32, centerY: i32, radius: i32, thickness: i32, color: Color): void;

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

export declare function draw_polygon_outline(points: usize, numPoints: i32, thickness: i32, color: Color): void;

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

export declare function draw_arc_outline(centerX: i32, centerY: i32, radius: f32, startAngle: f32, endAngle: f32, segments: i32, thickness: i32, color: Color): void;

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

export declare function draw_rectangle_rounded_outline(x: i32, y: i32, width: i32, height: i32, cornerRadius: i32, thickness: i32, color: Color): void;

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

export declare function draw_rectangle_outline_on_image(destination: u32, posX: i32, posY: i32, width: i32, height: i32, thickness: i32, color: Color): void;

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

export declare function draw_triangle_outline_on_image(destination: u32, x1: i32, y1: i32, x2: i32, y2: i32, x3: i32, y3: i32, thickness: i32, color: Color): void;

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

export declare function draw_ellipse_outline_on_image(destination: u32, centerX: i32, centerY: i32, radiusX: i32, radiusY: i32, thickness: i32, color: Color): void;

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

export declare function draw_circle_outline_on_image(destination: u32, centerX: i32, centerY: i32, radius: i32, thickness: i32, color: Color): void;

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

export declare function draw_polygon_outline_on_image(destination: u32, points: usize, numPoints: i32, thickness: i32, color: Color): void;

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

export declare function draw_rectangle_rounded_outline_on_image(destination: u32, x: i32, y: i32, width: i32, height: i32, cornerRadius: i32, thickness: i32, color: Color): void;
gui (10)

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

export declare function gui_begin_window(title: usize, rect: Rectangle): bool;

End the current GUI window.

export declare function gui_end_window(): void;

A button. Returns true when it is clicked.

export declare function gui_button(label: usize): bool;

A static text label.

export declare function gui_label(text: usize): void;

A block of wrapping text.

export declare function gui_text(text: usize): void;

A checkbox. Returns the (possibly changed) state.

export declare function gui_checkbox(label: usize, state: bool): bool;

A slider. Returns the (possibly changed) value.

export declare function gui_slider(value: f32, low: f32, high: f32): f32;

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

export declare function gui_layout_row(widths: usize, numWidths: i32, height: i32): void;

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

export declare function gui_end(): void;

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

export declare function gui_draw(dst: u32): void;
input (12)

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

export declare function key_pressed(key: Key): bool;

Is the key currently down?

export declare function key_down(key: Key): bool;

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

export declare function key_released(key: Key): bool;

Is the key currently up?

export declare function key_up(key: Key): bool;

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

export declare function gamepad_button_pressed(gamepad: i32, button: GamepadButton): bool;

Is the button currently down?

export declare function gamepad_button_down(gamepad: i32, button: GamepadButton): bool;

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

export declare function gamepad_button_released(gamepad: i32, button: GamepadButton): bool;

Get current position of mouse.

export declare function mouse_position(): Vector;

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

export declare function mouse_button_pressed(button: MouseButton): bool;

Is the button currently down?

export declare function mouse_button_down(button: MouseButton): bool;

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

export declare function mouse_button_released(button: MouseButton): bool;

Is the button currently up?

export declare function mouse_button_up(button: MouseButton): bool;
sound (7)

Load a sound from a file in cart.

export declare function load_sound(filename: usize): u32;

Play a sound.

export declare function play_sound(sound: u32, loop: bool): void;

Stop a sound.

export declare function stop_sound(sound: u32): void;

Unload a sound.

export declare function unload_sound(sound: u32): void;

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

export declare function tts_sound(text: usize, phonetic: bool, pitch: i32, speed: i32, throat: i32, mouth: i32, sing: bool): u32;

Create Sfx sound.

export declare function sfx_sound(params: SfxParams): u32;

Create Sfx parameters.

export declare function sfx_generate(type: SfxPresetType): SfxParams;
tile (38)

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

export declare function load_tilemap(filename: usize): u32;

Unload a tilemap.

export declare function unload_tilemap(tilemap: u32): void;

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

export declare function tile_update(tilemap: u32, deltaTime: f32): void;

Get the size of a tilemap, in tiles.

export declare function tile_map_size(tilemap: u32): Dimensions;

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

export declare function tile_tile_size(tilemap: u32): Dimensions;

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

export declare function tile_map_prop(tilemap: u32, name: usize): TilemapProp;

Get the number of custom properties on a tilemap.

export declare function tile_map_prop_count(tilemap: u32): i32;

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

export declare function tile_map_prop_at(tilemap: u32, index: i32): TilemapProp;

Draw a tilemap on the screen.

export declare function tile_draw(tilemap: u32, posX: i32, posY: i32): void;

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

export declare function tile_draw_tint(tilemap: u32, posX: i32, posY: i32, tint: Color): void;

Draw a tilemap on an image.

export declare function tile_draw_on_image(dst: u32, tilemap: u32, posX: i32, posY: i32): void;

Render a whole tilemap to a new image.

export declare function tilemap_image(tilemap: u32): u32;

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.

export declare function tile_layer_count(tilemap: u32): i32;

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

export declare function tile_layer_index(tilemap: u32, name: usize): i32;

Get the name of a layer of a tilemap.

export declare function tile_layer_name(tilemap: u32, layer: i32): usize;

Get the kind of a layer of a tilemap.

export declare function tile_layer_type(tilemap: u32, layer: i32): TileLayerKind;

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

export declare function tile_layer_size(tilemap: u32, layer: i32): Dimensions;

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

export declare function tile_layer_visible(tilemap: u32, layer: i32): bool;

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

export declare function tile_layer_prop(tilemap: u32, layer: i32, name: usize): TilemapProp;

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

export declare function tile_layer_prop_count(tilemap: u32, layer: i32): i32;

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

export declare function tile_layer_prop_at(tilemap: u32, layer: i32, index: i32): TilemapProp;

Draw a single layer of a tilemap on the screen.

export declare function tile_draw_layer(tilemap: u32, layer: i32, posX: i32, posY: i32): void;

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

export declare function tile_draw_layer_tint(tilemap: u32, layer: i32, posX: i32, posY: i32, tint: Color): void;

Draw a single layer of a tilemap on an image.

export declare function tile_draw_layer_on_image(dst: u32, tilemap: u32, layer: i32, posX: i32, posY: i32): void;

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

export declare function tile_layer_image(tilemap: u32, layer: i32): u32;

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

export declare function tile_get_tile(tilemap: u32, layer: i32, column: i32, row: i32): 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.

export declare function tile_set_tile(tilemap: u32, layer: i32, column: i32, row: i32, gid: i32): void;

Draw a single tile from a tilemap on the screen.

export declare function tile_draw_tile(tilemap: u32, gid: i32, posX: i32, posY: i32): void;

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

export declare function tile_image(tilemap: u32, gid: i32): u32;

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.

export declare function tile_gid_prop(tilemap: u32, gid: i32, name: usize): TilemapProp;

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

export declare function tile_gid_prop_count(tilemap: u32, gid: i32): i32;

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

export declare function tile_gid_prop_at(tilemap: u32, gid: i32, index: i32): TilemapProp;

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

export declare function tile_object_count(tilemap: u32, layer: i32): i32;

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

export declare function tile_object(tilemap: u32, layer: i32, index: i32): TilemapObject;

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

export declare function tile_object_index(tilemap: u32, layer: i32, name: usize): i32;

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

export declare function tile_object_prop(tilemap: u32, layer: i32, index: i32, name: usize): TilemapProp;

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

export declare function tile_object_prop_count(tilemap: u32, layer: i32, index: i32): i32;

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

export declare function tile_object_prop_at(tilemap: u32, layer: i32, index: i32, propIndex: i32): TilemapProp;
utilities (5)

Get system-time (ms) since unix epoch.

export declare function current_time(): u64;

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

export declare function delta_time(): f32;

Get a random integer between 2 numbers.

export declare function random_int(min: i32, max: i32): i32;

Get the random-seed.

export declare function random_seed_get(): u64;

Set the random-seed.

export declare function random_seed_set(seed: u64): void;