notnull games

Cyber

⚡Cyber is a fast, small scripting language. The VM is re-entered for each callback, so your top-level state persists between frames.

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

building

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

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

Cyber notes

use null0, then null0.clear(null0.BLUE).
The VM is re-entered per callback via persist_main, so top-level state persists across frames.

a cart, in Cyber

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

use null0

fn load():
    null0.clear(null0.BLUE)
    null0.draw_circle(100, 100, 50, null0.RED)

-- callbacks (optional - implement as needed)

-- fn update():
--     pass

-- fn unload():
--     pass

-- fn buttonUp(button int, player int):
--     pass

-- fn buttonDown(button int, player int):
--     pass

-- fn keyUp(key int):
--     pass

-- fn keyDown(key int):
--     pass

-- fn mouseDown(button int):
--     pass

-- fn mouseUp(button int):
--     pass

-- fn mouseMoved(x float, y float):
--     pass

carts/cyber/simple/main.cy

callbacks

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

func update():

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

more Cyber carts

demo - source

the API, in Cyber

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

fn color_tint(color Color, tint Color) -> Color

Fade a color.

fn color_fade(color Color, alpha f32) -> Color

Change the brightness of a color.

fn color_brightness(color Color, factor f32) -> Color

Invert a color.

fn color_invert(color Color) -> Color

Blend 2 colors together.

fn color_alpha_blend(dst Color, src Color) -> Color

Change contrast of a color.

fn color_contrast(color Color, contrast f32) -> Color

Interpolate colors.

fn color_bilinear_interpolate(color00 Color, color01 Color, color10 Color, color11 Color, coordinateX f32, coordinateY f32) -> Color

graphics (75)

Create a new blank image.

fn new_image(width i32, height i32, color Color) -> r32

Copy an image to a new image.

fn image_copy(image r32) -> r32

Create an image from a region of another image.

fn image_subimage(image r32, x i32, y i32, width i32, height i32) -> r32

Clear the screen.

fn clear(color Color)

Draw a single pixel on the screen.

fn draw_point(x i32, y i32, color Color)

Draw a line on the screen.

fn draw_line(startPosX i32, startPosY i32, endPosX i32, endPosY i32, color Color)

Draw a filled rectangle on the screen.

fn draw_rectangle(posX i32, posY i32, width i32, height i32, color Color)

Draw a filled triangle on the screen.

fn draw_triangle(x1 i32, y1 i32, x2 i32, y2 i32, x3 i32, y3 i32, color Color)

Draw a filled ellipse on the screen.

fn draw_ellipse(centerX i32, centerY i32, radiusX i32, radiusY i32, color Color)

Draw a filled circle on the screen.

fn draw_circle(centerX i32, centerY i32, radius i32, color Color)

Draw a filled polygon on the screen.

fn draw_polygon(points []Vector, color Color)

Draw a filled arc on the screen.

fn draw_arc(centerX i32, centerY i32, radius f32, startAngle f32, endAngle f32, segments i32, color Color)

Draw a filled round-rectangle on the screen.

fn draw_rectangle_rounded(x i32, y i32, width i32, height i32, cornerRadius i32, color Color)

Draw an image on the screen.

fn draw_image(src r32, posX i32, posY i32)

Draw a tinted image on the screen.

fn draw_image_tint(src r32, posX i32, posY i32, tint Color)

Draw an image, rotated, on the screen.

fn draw_image_rotated(src r32, posX i32, posY i32, degrees f32, offsetX f32, offsetY f32, filter i32)

Draw an image, flipped, on the screen.

fn draw_image_flipped(src r32, posX i32, posY i32, flipHorizontal bool, flipVertical bool, flipDiagonal bool)

Draw an image, scaled, on the screen.

fn draw_image_scaled(src r32, posX i32, posY i32, scaleX f32, scaleY f32, offsetX f32, offsetY f32, filter i32)

Draw some text on the screen.

fn draw_text(font r32, text str, posX i32, posY i32, color Color)

Save an image to persistant storage.

fn save_image(image r32, filename str)

Load an image from a file in cart.

fn load_image(filename str) -> r32

Resize an image, return copy.

fn image_resize(image r32, newWidth i32, newHeight i32, filter i32) -> r32

Scale an image, return copy.

fn image_scale(image r32, scaleX f32, scaleY f32, filter i32) -> r32

Replace a color in an image, in-place.

fn image_color_replace(image r32, color Color, replace Color)

Tint a color in an image, in-place.

fn image_color_tint(image r32, color Color)

Fade a color in an image, in-place.

fn image_color_fade(image r32, alpha f32)

Copy a font to a new font.

fn font_copy(font r32) -> r32

Scale a font, return a new font.

fn font_scale(font r32, scaleX f32, scaleY f32, filter i32) -> r32

Load a BMF font from a file in cart.

fn load_font_bmf(filename str, characters str) -> r32

Load a BMF font from an image.

fn load_font_bmf_from_image(image r32, characters str) -> r32

Measure the size of some text.

fn measure_text(font r32, text str, textLength i32) -> Dimensions

Meaure an image (use 0 for screen).

fn measure_image(image r32) -> Dimensions

Load a TTY font from a file in cart.

fn load_font_tty(filename str, glyphWidth i32, glyphHeight i32, characters str) -> r32

Load a TTY font from an image.

fn load_font_tty_from_image(image r32, glyphWidth i32, glyphHeight i32, characters str) -> r32

Load a TTF font from a file in cart.

fn load_font_ttf(filename str, fontSize i32) -> r32

Invert the colors in an image, in-place.

fn image_color_invert(image r32)

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

fn image_alpha_border(image r32, threshold f32) -> Rectangle

Crop an image, in-place.

fn image_crop(image r32, x i32, y i32, width i32, height i32)

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

fn image_alpha_crop(image r32, threshold f32)

Adjust the brightness of an image, in-place.

fn image_color_brightness(image r32, factor f32)

Flip an image, in-place.

fn image_flip(image r32, horizontal bool, vertical bool)

Change the contrast of an image, in-place.

fn image_color_contrast(image r32, contrast f32)

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

fn image_alpha_mask(image r32, alphaMask r32, posX i32, posY i32)

Create a new image, rotating another image.

fn image_rotate(image r32, degrees f32, filter i32) -> r32

Create a new image of a gradient.

fn image_gradient(width i32, height i32, topLeft Color, topRight Color, bottomLeft Color, bottomRight Color) -> r32

Unload an image.

fn unload_image(image r32)

Unload a font.

fn unload_font(font r32)

Clear an image.

fn clear_image(destination r32, color Color)

Draw a single pixel on an image.

fn draw_point_on_image(destination r32, x i32, y i32, color Color)

Draw a line on an image.

fn draw_line_on_image(destination r32, startPosX i32, startPosY i32, endPosX i32, endPosY i32, color Color)

Draw a filled rectangle on an image.

fn draw_rectangle_on_image(destination r32, posX i32, posY i32, width i32, height i32, color Color)

Draw a filled triangle on an image.

fn draw_triangle_on_image(destination r32, x1 i32, y1 i32, x2 i32, y2 i32, x3 i32, y3 i32, color Color)

Draw a filled ellipse on an image.

fn draw_ellipse_on_image(destination r32, centerX i32, centerY i32, radiusX i32, radiusY i32, color Color)

Draw a circle on an image.

fn draw_circle_on_image(destination r32, centerX i32, centerY i32, radius i32, color Color)

Draw a filled polygon on an image.

fn draw_polygon_on_image(destination r32, points []Vector, color Color)

Draw a filled round-rectangle on an image.

fn draw_rectangle_rounded_on_image(destination r32, x i32, y i32, width i32, height i32, cornerRadius i32, color Color)

Draw an image on an image.

fn draw_image_on_image(destination r32, src r32, posX i32, posY i32)

Draw a tinted image on an image.

fn draw_image_tint_on_image(destination r32, src r32, posX i32, posY i32, tint Color)

Draw an image, rotated, on an image.

fn draw_image_rotated_on_image(destination r32, src r32, posX i32, posY i32, degrees f32, offsetX f32, offsetY f32, filter i32)

Draw an image, flipped, on an image.

fn draw_image_flipped_on_image(destination r32, src r32, posX i32, posY i32, flipHorizontal bool, flipVertical bool, flipDiagonal bool)

Draw an image, scaled, on an image.

fn draw_image_scaled_on_image(destination r32, src r32, posX i32, posY i32, scaleX f32, scaleY f32, offsetX f32, offsetY f32, filter i32)

Draw some text on an image.

fn draw_text_on_image(destination r32, font r32, text str, posX i32, posY i32, color Color)

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

fn draw_rectangle_outline(posX i32, posY i32, width i32, height i32, thickness i32, color Color)

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

fn draw_triangle_outline(x1 i32, y1 i32, x2 i32, y2 i32, x3 i32, y3 i32, thickness i32, color Color)

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

fn draw_ellipse_outline(centerX i32, centerY i32, radiusX i32, radiusY i32, thickness i32, color Color)

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

fn draw_circle_outline(centerX i32, centerY i32, radius i32, thickness i32, color Color)

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

fn draw_polygon_outline(points []Vector, thickness i32, color Color)

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

fn draw_arc_outline(centerX i32, centerY i32, radius f32, startAngle f32, endAngle f32, segments i32, thickness i32, color Color)

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

fn draw_rectangle_rounded_outline(x i32, y i32, width i32, height i32, cornerRadius i32, thickness i32, color Color)

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

fn draw_rectangle_outline_on_image(destination r32, posX i32, posY i32, width i32, height i32, thickness i32, color Color)

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

fn draw_triangle_outline_on_image(destination r32, x1 i32, y1 i32, x2 i32, y2 i32, x3 i32, y3 i32, thickness i32, color Color)

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

fn draw_ellipse_outline_on_image(destination r32, centerX i32, centerY i32, radiusX i32, radiusY i32, thickness i32, color Color)

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

fn draw_circle_outline_on_image(destination r32, centerX i32, centerY i32, radius i32, thickness i32, color Color)

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

fn draw_polygon_outline_on_image(destination r32, points []Vector, thickness i32, color Color)

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

fn draw_rectangle_rounded_outline_on_image(destination r32, x i32, y i32, width i32, height i32, cornerRadius i32, thickness i32, color 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.

fn gui_begin_window(title str, rect Rectangle) -> bool

End the current GUI window.

fn gui_end_window()

A button. Returns true when it is clicked.

fn gui_button(label str) -> bool

A static text label.

fn gui_label(text str)

A block of wrapping text.

fn gui_text(text str)

A checkbox. Returns the (possibly changed) state.

fn gui_checkbox(label str, state bool) -> bool

A slider. Returns the (possibly changed) value.

fn gui_slider(value f32, low f32, high f32) -> f32

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

fn gui_layout_row(widths []i32, height i32)

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

fn gui_end()

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

fn gui_draw(dst r32)

input (12)

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

fn key_pressed(key i32) -> bool

Is the key currently down?

fn key_down(key i32) -> bool

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

fn key_released(key i32) -> bool

Is the key currently up?

fn key_up(key i32) -> bool

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

fn gamepad_button_pressed(gamepad i32, button i32) -> bool

Is the button currently down?

fn gamepad_button_down(gamepad i32, button i32) -> bool

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

fn gamepad_button_released(gamepad i32, button i32) -> bool

Get current position of mouse.

fn mouse_position() -> Vector

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

fn mouse_button_pressed(button i32) -> bool

Is the button currently down?

fn mouse_button_down(button i32) -> bool

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

fn mouse_button_released(button i32) -> bool

Is the button currently up?

fn mouse_button_up(button i32) -> bool

sound (7)

Load a sound from a file in cart.

fn load_sound(filename str) -> r32

Play a sound.

fn play_sound(sound r32, loop bool)

Stop a sound.

fn stop_sound(sound r32)

Unload a sound.

fn unload_sound(sound r32)

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

fn tts_sound(text str, phonetic bool, pitch i32, speed i32, throat i32, mouth i32, sing bool) -> r32

Create Sfx sound.

fn sfx_sound(params SfxParams) -> r32

Create Sfx parameters.

fn sfx_generate(type_ i32) -> SfxParams

tile (38)

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

fn load_tilemap(filename str) -> r32

Unload a tilemap.

fn unload_tilemap(tilemap r32)

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

fn tile_update(tilemap r32, deltaTime f32)

Get the size of a tilemap, in tiles.

fn tile_map_size(tilemap r32) -> Dimensions

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

fn tile_tile_size(tilemap r32) -> Dimensions

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

fn tile_map_prop(tilemap r32, name str) -> TilemapProp

Get the number of custom properties on a tilemap.

fn tile_map_prop_count(tilemap r32) -> i32

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

fn tile_map_prop_at(tilemap r32, index i32) -> TilemapProp

Draw a tilemap on the screen.

fn tile_draw(tilemap r32, posX i32, posY i32)

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

fn tile_draw_tint(tilemap r32, posX i32, posY i32, tint Color)

Draw a tilemap on an image.

fn tile_draw_on_image(dst r32, tilemap r32, posX i32, posY i32)

Render a whole tilemap to a new image.

fn tilemap_image(tilemap r32) -> r32

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.

fn tile_layer_count(tilemap r32) -> i32

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

fn tile_layer_index(tilemap r32, name str) -> i32

Get the name of a layer of a tilemap.

fn tile_layer_name(tilemap r32, layer i32) -> str

Get the kind of a layer of a tilemap.

fn tile_layer_type(tilemap r32, layer i32) -> i32

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

fn tile_layer_size(tilemap r32, layer i32) -> Dimensions

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

fn tile_layer_visible(tilemap r32, layer i32) -> bool

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

fn tile_layer_prop(tilemap r32, layer i32, name str) -> TilemapProp

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

fn tile_layer_prop_count(tilemap r32, layer i32) -> i32

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

fn tile_layer_prop_at(tilemap r32, layer i32, index i32) -> TilemapProp

Draw a single layer of a tilemap on the screen.

fn tile_draw_layer(tilemap r32, layer i32, posX i32, posY i32)

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

fn tile_draw_layer_tint(tilemap r32, layer i32, posX i32, posY i32, tint Color)

Draw a single layer of a tilemap on an image.

fn tile_draw_layer_on_image(dst r32, tilemap r32, layer i32, posX i32, posY i32)

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

fn tile_layer_image(tilemap r32, layer i32) -> r32

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

fn tile_get_tile(tilemap r32, 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.

fn tile_set_tile(tilemap r32, layer i32, column i32, row i32, gid i32)

Draw a single tile from a tilemap on the screen.

fn tile_draw_tile(tilemap r32, gid i32, posX i32, posY i32)

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

fn tile_image(tilemap r32, gid i32) -> r32

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.

fn tile_gid_prop(tilemap r32, gid i32, name str) -> TilemapProp

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

fn tile_gid_prop_count(tilemap r32, gid i32) -> i32

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

fn tile_gid_prop_at(tilemap r32, gid i32, index i32) -> TilemapProp

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

fn tile_object_count(tilemap r32, layer i32) -> i32

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

fn tile_object(tilemap r32, 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.)

fn tile_object_index(tilemap r32, layer i32, name str) -> i32

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

fn tile_object_prop(tilemap r32, layer i32, index i32, name str) -> TilemapProp

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

fn tile_object_prop_count(tilemap r32, layer i32, index i32) -> i32

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

fn tile_object_prop_at(tilemap r32, layer i32, index i32, propIndex i32) -> TilemapProp

utilities (5)

Get system-time (ms) since unix epoch.

fn current_time() -> r64

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

fn delta_time() -> f32

Get a random integer between 2 numbers.

fn random_int(min i32, max i32) -> i32

Get the random-seed.

fn random_seed_get() -> r64

Set the random-seed.

fn random_seed_set(seed r64)