notnull games

D

🇩D carts are built with ldc in -betterC mode: no druntime, no GC, but you keep templates, slices and D’s much nicer syntax.

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

building

You do not install ldc2 - 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-d:latest mygame

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

D notes

-betterC, so no druntime and no GC.

a cart, in D

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

import null0;

export extern(C) void load() {
    clear(BLUE);
    draw_circle(100, 100, 50, RED);
}

// callbacks (optional - implement as needed)

// export extern(C) void update() {}
// export extern(C) void unload() {}
// export extern(C) void buttonUp(GamepadButton button, uint player) {}
// export extern(C) void buttonDown(GamepadButton button, uint player) {}
// export extern(C) void keyUp(Key key) {}
// export extern(C) void keyDown(Key key) {}
// export extern(C) void mouseDown(MouseButton button) {}
// export extern(C) void mouseUp(MouseButton button) {}
// export extern(C) void mouseMoved(float x, float y) {}

carts/d/simple/main.d

callbacks

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

export extern(C) void load() {}

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

more D carts

demo - source

the API, in D

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

extern(C) Color* color_tint(Color color, Color tint);

Fade a color.

extern(C) Color* color_fade(Color color, float alpha);

Change the brightness of a color.

extern(C) Color* color_brightness(Color color, float factor);

Invert a color.

extern(C) Color* color_invert(Color color);

Blend 2 colors together.

extern(C) Color* color_alpha_blend(Color dst, Color src);

Change contrast of a color.

extern(C) Color* color_contrast(Color color, float contrast);

Interpolate colors.

extern(C) Color* color_bilinear_interpolate(Color color00, Color color01, Color color10, Color color11, float coordinateX, float coordinateY);

graphics (75)

Create a new blank image.

extern(C) Image new_image(int width, int height, Color color);

Copy an image to a new image.

extern(C) Image image_copy(Image image);

Create an image from a region of another image.

extern(C) Image image_subimage(Image image, int x, int y, int width, int height);

Clear the screen.

extern(C) void clear(Color color);

Draw a single pixel on the screen.

extern(C) void draw_point(int x, int y, Color color);

Draw a line on the screen.

extern(C) void draw_line(int startPosX, int startPosY, int endPosX, int endPosY, Color color);

Draw a filled rectangle on the screen.

extern(C) void draw_rectangle(int posX, int posY, int width, int height, Color color);

Draw a filled triangle on the screen.

extern(C) void draw_triangle(int x1, int y1, int x2, int y2, int x3, int y3, Color color);

Draw a filled ellipse on the screen.

extern(C) void draw_ellipse(int centerX, int centerY, int radiusX, int radiusY, Color color);

Draw a filled circle on the screen.

extern(C) void draw_circle(int centerX, int centerY, int radius, Color color);

Draw a filled polygon on the screen.

extern(C) void draw_polygon(const(Vector)* points, int numPoints, Color color);

Draw a filled arc on the screen.

extern(C) void draw_arc(int centerX, int centerY, float radius, float startAngle, float endAngle, int segments, Color color);

Draw a filled round-rectangle on the screen.

extern(C) void draw_rectangle_rounded(int x, int y, int width, int height, int cornerRadius, Color color);

Draw an image on the screen.

extern(C) void draw_image(Image src, int posX, int posY);

Draw a tinted image on the screen.

extern(C) void draw_image_tint(Image src, int posX, int posY, Color tint);

Draw an image, rotated, on the screen.

extern(C) void draw_image_rotated(Image src, int posX, int posY, float degrees, float offsetX, float offsetY, ImageFilter filter);

Draw an image, flipped, on the screen.

extern(C) void draw_image_flipped(Image src, int posX, int posY, bool flipHorizontal, bool flipVertical, bool flipDiagonal);

Draw an image, scaled, on the screen.

extern(C) void draw_image_scaled(Image src, int posX, int posY, float scaleX, float scaleY, float offsetX, float offsetY, ImageFilter filter);

Draw some text on the screen.

extern(C) void draw_text(Font font, const(char)* text, int posX, int posY, Color color);

Save an image to persistant storage.

extern(C) void save_image(Image image, const(char)* filename);

Load an image from a file in cart.

extern(C) Image load_image(const(char)* filename);

Resize an image, return copy.

extern(C) Image image_resize(Image image, int newWidth, int newHeight, ImageFilter filter);

Scale an image, return copy.

extern(C) Image image_scale(Image image, float scaleX, float scaleY, ImageFilter filter);

Replace a color in an image, in-place.

extern(C) void image_color_replace(Image image, Color color, Color replace);

Tint a color in an image, in-place.

extern(C) void image_color_tint(Image image, Color color);

Fade a color in an image, in-place.

extern(C) void image_color_fade(Image image, float alpha);

Copy a font to a new font.

extern(C) Font font_copy(Font font);

Scale a font, return a new font.

extern(C) Font font_scale(Font font, float scaleX, float scaleY, ImageFilter filter);

Load a BMF font from a file in cart.

extern(C) Font load_font_bmf(const(char)* filename, const(char)* characters);

Load a BMF font from an image.

extern(C) Font load_font_bmf_from_image(Image image, const(char)* characters);

Measure the size of some text.

extern(C) Dimensions* measure_text(Font font, const(char)* text, int textLength);

Meaure an image (use 0 for screen).

extern(C) Dimensions* measure_image(Image image);

Load a TTY font from a file in cart.

extern(C) Font load_font_tty(const(char)* filename, int glyphWidth, int glyphHeight, const(char)* characters);

Load a TTY font from an image.

extern(C) Font load_font_tty_from_image(Image image, int glyphWidth, int glyphHeight, const(char)* characters);

Load a TTF font from a file in cart.

extern(C) Font load_font_ttf(const(char)* filename, int fontSize);

Invert the colors in an image, in-place.

extern(C) void image_color_invert(Image image);

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

extern(C) Rectangle* image_alpha_border(Image image, float threshold);

Crop an image, in-place.

extern(C) void image_crop(Image image, int x, int y, int width, int height);

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

extern(C) void image_alpha_crop(Image image, float threshold);

Adjust the brightness of an image, in-place.

extern(C) void image_color_brightness(Image image, float factor);

Flip an image, in-place.

extern(C) void image_flip(Image image, bool horizontal, bool vertical);

Change the contrast of an image, in-place.

extern(C) void image_color_contrast(Image image, float contrast);

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

extern(C) void image_alpha_mask(Image image, Image alphaMask, int posX, int posY);

Create a new image, rotating another image.

extern(C) Image image_rotate(Image image, float degrees, ImageFilter filter);

Create a new image of a gradient.

extern(C) Image image_gradient(int width, int height, Color topLeft, Color topRight, Color bottomLeft, Color bottomRight);

Unload an image.

extern(C) void unload_image(Image image);

Unload a font.

extern(C) void unload_font(Font font);

Clear an image.

extern(C) void clear_image(Image destination, Color color);

Draw a single pixel on an image.

extern(C) void draw_point_on_image(Image destination, int x, int y, Color color);

Draw a line on an image.

extern(C) void draw_line_on_image(Image destination, int startPosX, int startPosY, int endPosX, int endPosY, Color color);

Draw a filled rectangle on an image.

extern(C) void draw_rectangle_on_image(Image destination, int posX, int posY, int width, int height, Color color);

Draw a filled triangle on an image.

extern(C) void draw_triangle_on_image(Image destination, int x1, int y1, int x2, int y2, int x3, int y3, Color color);

Draw a filled ellipse on an image.

extern(C) void draw_ellipse_on_image(Image destination, int centerX, int centerY, int radiusX, int radiusY, Color color);

Draw a circle on an image.

extern(C) void draw_circle_on_image(Image destination, int centerX, int centerY, int radius, Color color);

Draw a filled polygon on an image.

extern(C) void draw_polygon_on_image(Image destination, const(Vector)* points, int numPoints, Color color);

Draw a filled round-rectangle on an image.

extern(C) void draw_rectangle_rounded_on_image(Image destination, int x, int y, int width, int height, int cornerRadius, Color color);

Draw an image on an image.

extern(C) void draw_image_on_image(Image destination, Image src, int posX, int posY);

Draw a tinted image on an image.

extern(C) void draw_image_tint_on_image(Image destination, Image src, int posX, int posY, Color tint);

Draw an image, rotated, on an image.

extern(C) void draw_image_rotated_on_image(Image destination, Image src, int posX, int posY, float degrees, float offsetX, float offsetY, ImageFilter filter);

Draw an image, flipped, on an image.

extern(C) void draw_image_flipped_on_image(Image destination, Image src, int posX, int posY, bool flipHorizontal, bool flipVertical, bool flipDiagonal);

Draw an image, scaled, on an image.

extern(C) void draw_image_scaled_on_image(Image destination, Image src, int posX, int posY, float scaleX, float scaleY, float offsetX, float offsetY, ImageFilter filter);

Draw some text on an image.

extern(C) void draw_text_on_image(Image destination, Font font, const(char)* text, int posX, int posY, Color color);

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

extern(C) void draw_rectangle_outline(int posX, int posY, int width, int height, int thickness, Color color);

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

extern(C) void draw_triangle_outline(int x1, int y1, int x2, int y2, int x3, int y3, int thickness, Color color);

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

extern(C) void draw_ellipse_outline(int centerX, int centerY, int radiusX, int radiusY, int thickness, Color color);

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

extern(C) void draw_circle_outline(int centerX, int centerY, int radius, int thickness, Color color);

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

extern(C) void draw_polygon_outline(const(Vector)* points, int numPoints, int thickness, Color color);

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

extern(C) void draw_arc_outline(int centerX, int centerY, float radius, float startAngle, float endAngle, int segments, int thickness, Color color);

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

extern(C) void draw_rectangle_rounded_outline(int x, int y, int width, int height, int cornerRadius, int thickness, Color color);

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

extern(C) void draw_rectangle_outline_on_image(Image destination, int posX, int posY, int width, int height, int thickness, Color color);

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

extern(C) void draw_triangle_outline_on_image(Image destination, int x1, int y1, int x2, int y2, int x3, int y3, int thickness, Color color);

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

extern(C) void draw_ellipse_outline_on_image(Image destination, int centerX, int centerY, int radiusX, int radiusY, int thickness, Color color);

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

extern(C) void draw_circle_outline_on_image(Image destination, int centerX, int centerY, int radius, int thickness, Color color);

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

extern(C) void draw_polygon_outline_on_image(Image destination, const(Vector)* points, int numPoints, int thickness, Color color);

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

extern(C) void draw_rectangle_rounded_outline_on_image(Image destination, int x, int y, int width, int height, int cornerRadius, int thickness, 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.

extern(C) bool gui_begin_window(const(char)* title, Rectangle rect);

End the current GUI window.

extern(C) void gui_end_window();

A button. Returns true when it is clicked.

extern(C) bool gui_button(const(char)* label);

A static text label.

extern(C) void gui_label(const(char)* text);

A block of wrapping text.

extern(C) void gui_text(const(char)* text);

A checkbox. Returns the (possibly changed) state.

extern(C) bool gui_checkbox(const(char)* label, bool state);

A slider. Returns the (possibly changed) value.

extern(C) float gui_slider(float value, float low, float high);

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

extern(C) void gui_layout_row(const(int)* widths, int numWidths, int height);

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

extern(C) void gui_end();

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

extern(C) void gui_draw(Image dst);

input (12)

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

extern(C) bool key_pressed(Key key);

Is the key currently down?

extern(C) bool key_down(Key key);

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

extern(C) bool key_released(Key key);

Is the key currently up?

extern(C) bool key_up(Key key);

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

extern(C) bool gamepad_button_pressed(int gamepad, GamepadButton button);

Is the button currently down?

extern(C) bool gamepad_button_down(int gamepad, GamepadButton button);

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

extern(C) bool gamepad_button_released(int gamepad, GamepadButton button);

Get current position of mouse.

extern(C) Vector* mouse_position();

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

extern(C) bool mouse_button_pressed(MouseButton button);

Is the button currently down?

extern(C) bool mouse_button_down(MouseButton button);

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

extern(C) bool mouse_button_released(MouseButton button);

Is the button currently up?

extern(C) bool mouse_button_up(MouseButton button);

sound (7)

Load a sound from a file in cart.

extern(C) Sound load_sound(const(char)* filename);

Play a sound.

extern(C) void play_sound(Sound sound, bool loop);

Stop a sound.

extern(C) void stop_sound(Sound sound);

Unload a sound.

extern(C) void unload_sound(Sound sound);

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

extern(C) Sound tts_sound(const(char)* text, bool phonetic, int pitch, int speed, int throat, int mouth, bool sing);

Create Sfx sound.

extern(C) Sound sfx_sound(const(SfxParams)* params);

Create Sfx parameters.

extern(C) SfxParams* sfx_generate(SfxPresetType type);

tile (38)

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

extern(C) Tilemap load_tilemap(const(char)* filename);

Unload a tilemap.

extern(C) void unload_tilemap(Tilemap tilemap);

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

extern(C) void tile_update(Tilemap tilemap, float deltaTime);

Get the size of a tilemap, in tiles.

extern(C) Dimensions* tile_map_size(Tilemap tilemap);

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

extern(C) Dimensions* tile_tile_size(Tilemap tilemap);

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

extern(C) TilemapProp* tile_map_prop(Tilemap tilemap, const(char)* name);

Get the number of custom properties on a tilemap.

extern(C) int tile_map_prop_count(Tilemap tilemap);

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

extern(C) TilemapProp* tile_map_prop_at(Tilemap tilemap, int index);

Draw a tilemap on the screen.

extern(C) void tile_draw(Tilemap tilemap, int posX, int posY);

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

extern(C) void tile_draw_tint(Tilemap tilemap, int posX, int posY, Color tint);

Draw a tilemap on an image.

extern(C) void tile_draw_on_image(Image dst, Tilemap tilemap, int posX, int posY);

Render a whole tilemap to a new image.

extern(C) Image tilemap_image(Tilemap 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.

extern(C) int tile_layer_count(Tilemap tilemap);

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

extern(C) int tile_layer_index(Tilemap tilemap, const(char)* name);

Get the name of a layer of a tilemap.

extern(C) char* tile_layer_name(Tilemap tilemap, int layer);

Get the kind of a layer of a tilemap.

extern(C) TileLayerKind tile_layer_type(Tilemap tilemap, int layer);

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

extern(C) Dimensions* tile_layer_size(Tilemap tilemap, int layer);

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

extern(C) bool tile_layer_visible(Tilemap tilemap, int layer);

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

extern(C) TilemapProp* tile_layer_prop(Tilemap tilemap, int layer, const(char)* name);

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

extern(C) int tile_layer_prop_count(Tilemap tilemap, int layer);

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

extern(C) TilemapProp* tile_layer_prop_at(Tilemap tilemap, int layer, int index);

Draw a single layer of a tilemap on the screen.

extern(C) void tile_draw_layer(Tilemap tilemap, int layer, int posX, int posY);

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

extern(C) void tile_draw_layer_tint(Tilemap tilemap, int layer, int posX, int posY, Color tint);

Draw a single layer of a tilemap on an image.

extern(C) void tile_draw_layer_on_image(Image dst, Tilemap tilemap, int layer, int posX, int posY);

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

extern(C) Image tile_layer_image(Tilemap tilemap, int layer);

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

extern(C) int tile_get_tile(Tilemap tilemap, int layer, int column, int 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.

extern(C) void tile_set_tile(Tilemap tilemap, int layer, int column, int row, int gid);

Draw a single tile from a tilemap on the screen.

extern(C) void tile_draw_tile(Tilemap tilemap, int gid, int posX, int posY);

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

extern(C) Image tile_image(Tilemap tilemap, int 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.

extern(C) TilemapProp* tile_gid_prop(Tilemap tilemap, int gid, const(char)* name);

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

extern(C) int tile_gid_prop_count(Tilemap tilemap, int gid);

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

extern(C) TilemapProp* tile_gid_prop_at(Tilemap tilemap, int gid, int index);

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

extern(C) int tile_object_count(Tilemap tilemap, int layer);

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

extern(C) TilemapObject* tile_object(Tilemap tilemap, int layer, int index);

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

extern(C) int tile_object_index(Tilemap tilemap, int layer, const(char)* name);

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

extern(C) TilemapProp* tile_object_prop(Tilemap tilemap, int layer, int index, const(char)* name);

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

extern(C) int tile_object_prop_count(Tilemap tilemap, int layer, int index);

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

extern(C) TilemapProp* tile_object_prop_at(Tilemap tilemap, int layer, int index, int propIndex);

utilities (5)

Get system-time (ms) since unix epoch.

extern(C) ulong current_time();

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

extern(C) float delta_time();

Get a random integer between 2 numbers.

extern(C) int random_int(int min, int max);

Get the random-seed.

extern(C) ulong random_seed_get();

Set the random-seed.

extern(C) void random_seed_set(ulong seed);