notnull games

Go

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

building

You do not install tinygo - 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-go:latest mygame

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

Go notes

  • The API is CamelCase here, wrapping the raw //go:wasmimport declarations.
  • There is no working directory - os.ReadFile("/main.lua") works, os.ReadFile("main.lua") does not.

a cart, in Go

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

package main

import null0 "null0"

//export load
func load() {
	null0.Clear(null0.BLUE)
	null0.DrawCircle(100, 100, 50, null0.RED)
}

// callbacks (optional - implement as needed)

// //export update
// func update() {}

// //export unload
// func unload() {}

// //export buttonUp
// func buttonUp(button null0.GamepadButton, player uint32) {}

// //export buttonDown
// func buttonDown(button null0.GamepadButton, player uint32) {}

// //export keyUp
// func keyUp(key null0.Key) {}

// //export keyDown
// func keyDown(key null0.Key) {}

// //export mouseDown
// func mouseDown(button null0.MouseButton) {}

// //export mouseUp
// func mouseUp(button null0.MouseButton) {}

// //export mouseMoved
// func mouseMoved(x, y float32) {}

func main() {}
carts/go/simple/main.go

This toolchain needs an entry point to exist even though null0 never uses it for gameplay. Leave it empty: func main() {}

callbacks

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

//export load
func load() {}

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

more Go carts

the API, in Go

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

func ColorTint(color Color, tint Color) Color

Fade a color.

func ColorFade(color Color, alpha float32) Color

Change the brightness of a color.

func ColorBrightness(color Color, factor float32) Color

Invert a color.

func ColorInvert(color Color) Color

Blend 2 colors together.

func ColorAlphaBlend(dst Color, src Color) Color

Change contrast of a color.

func ColorContrast(color Color, contrast float32) Color

Interpolate colors.

func ColorBilinearInterpolate(color00 Color, color01 Color, color10 Color, color11 Color, coordinateX float32, coordinateY float32) Color
graphics (75)

Create a new blank image.

func NewImage(width int32, height int32, color Color) Image

Copy an image to a new image.

func ImageCopy(image Image) Image

Create an image from a region of another image.

func ImageSubimage(image Image, x int32, y int32, width int32, height int32) Image

Clear the screen.

func Clear(color Color)

Draw a single pixel on the screen.

func DrawPoint(x int32, y int32, color Color)

Draw a line on the screen.

func DrawLine(startPosX int32, startPosY int32, endPosX int32, endPosY int32, color Color)

Draw a filled rectangle on the screen.

func DrawRectangle(posX int32, posY int32, width int32, height int32, color Color)

Draw a filled triangle on the screen.

func DrawTriangle(x1 int32, y1 int32, x2 int32, y2 int32, x3 int32, y3 int32, color Color)

Draw a filled ellipse on the screen.

func DrawEllipse(centerX int32, centerY int32, radiusX int32, radiusY int32, color Color)

Draw a filled circle on the screen.

func DrawCircle(centerX int32, centerY int32, radius int32, color Color)

Draw a filled polygon on the screen.

func DrawPolygon(points []Vector, numPoints int32, color Color)

Draw a filled arc on the screen.

func DrawArc(centerX int32, centerY int32, radius float32, startAngle float32, endAngle float32, segments int32, color Color)

Draw a filled round-rectangle on the screen.

func DrawRectangleRounded(x int32, y int32, width int32, height int32, cornerRadius int32, color Color)

Draw an image on the screen.

func DrawImage(src Image, posX int32, posY int32)

Draw a tinted image on the screen.

func DrawImageTint(src Image, posX int32, posY int32, tint Color)

Draw an image, rotated, on the screen.

func DrawImageRotated(src Image, posX int32, posY int32, degrees float32, offsetX float32, offsetY float32, filter ImageFilter)

Draw an image, flipped, on the screen.

func DrawImageFlipped(src Image, posX int32, posY int32, flipHorizontal bool, flipVertical bool, flipDiagonal bool)

Draw an image, scaled, on the screen.

func DrawImageScaled(src Image, posX int32, posY int32, scaleX float32, scaleY float32, offsetX float32, offsetY float32, filter ImageFilter)

Draw some text on the screen.

func DrawText(font Font, text string, posX int32, posY int32, color Color)

Save an image to persistant storage.

func SaveImage(image Image, filename string)

Load an image from a file in cart.

func LoadImage(filename string) Image

Resize an image, return copy.

func ImageResize(image Image, newWidth int32, newHeight int32, filter ImageFilter) Image

Scale an image, return copy.

func ImageScale(image Image, scaleX float32, scaleY float32, filter ImageFilter) Image

Replace a color in an image, in-place.

func ImageColorReplace(image Image, color Color, replace Color)

Tint a color in an image, in-place.

func ImageColorTint(image Image, color Color)

Fade a color in an image, in-place.

func ImageColorFade(image Image, alpha float32)

Copy a font to a new font.

func FontCopy(font Font) Font

Scale a font, return a new font.

func FontScale(font Font, scaleX float32, scaleY float32, filter ImageFilter) Font

Load a BMF font from a file in cart.

func LoadFontBmf(filename string, characters string) Font

Load a BMF font from an image.

func LoadFontBmfFromImage(image Image, characters string) Font

Measure the size of some text.

func MeasureText(font Font, text string, textLength int32) Dimensions

Meaure an image (use 0 for screen).

func MeasureImage(image Image) Dimensions

Load a TTY font from a file in cart.

func LoadFontTty(filename string, glyphWidth int32, glyphHeight int32, characters string) Font

Load a TTY font from an image.

func LoadFontTtyFromImage(image Image, glyphWidth int32, glyphHeight int32, characters string) Font

Load a TTF font from a file in cart.

func LoadFontTtf(filename string, fontSize int32) Font

Invert the colors in an image, in-place.

func ImageColorInvert(image Image)

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

func ImageAlphaBorder(image Image, threshold float32) Rectangle

Crop an image, in-place.

func ImageCrop(image Image, x int32, y int32, width int32, height int32)

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

func ImageAlphaCrop(image Image, threshold float32)

Adjust the brightness of an image, in-place.

func ImageColorBrightness(image Image, factor float32)

Flip an image, in-place.

func ImageFlip(image Image, horizontal bool, vertical bool)

Change the contrast of an image, in-place.

func ImageColorContrast(image Image, contrast float32)

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

func ImageAlphaMask(image Image, alphaMask Image, posX int32, posY int32)

Create a new image, rotating another image.

func ImageRotate(image Image, degrees float32, filter ImageFilter) Image

Create a new image of a gradient.

func ImageGradient(width int32, height int32, topLeft Color, topRight Color, bottomLeft Color, bottomRight Color) Image

Unload an image.

func UnloadImage(image Image)

Unload a font.

func UnloadFont(font Font)

Clear an image.

func ClearImage(destination Image, color Color)

Draw a single pixel on an image.

func DrawPointOnImage(destination Image, x int32, y int32, color Color)

Draw a line on an image.

func DrawLineOnImage(destination Image, startPosX int32, startPosY int32, endPosX int32, endPosY int32, color Color)

Draw a filled rectangle on an image.

func DrawRectangleOnImage(destination Image, posX int32, posY int32, width int32, height int32, color Color)

Draw a filled triangle on an image.

func DrawTriangleOnImage(destination Image, x1 int32, y1 int32, x2 int32, y2 int32, x3 int32, y3 int32, color Color)

Draw a filled ellipse on an image.

func DrawEllipseOnImage(destination Image, centerX int32, centerY int32, radiusX int32, radiusY int32, color Color)

Draw a circle on an image.

func DrawCircleOnImage(destination Image, centerX int32, centerY int32, radius int32, color Color)

Draw a filled polygon on an image.

func DrawPolygonOnImage(destination Image, points []Vector, numPoints int32, color Color)

Draw a filled round-rectangle on an image.

func DrawRectangleRoundedOnImage(destination Image, x int32, y int32, width int32, height int32, cornerRadius int32, color Color)

Draw an image on an image.

func DrawImageOnImage(destination Image, src Image, posX int32, posY int32)

Draw a tinted image on an image.

func DrawImageTintOnImage(destination Image, src Image, posX int32, posY int32, tint Color)

Draw an image, rotated, on an image.

func DrawImageRotatedOnImage(destination Image, src Image, posX int32, posY int32, degrees float32, offsetX float32, offsetY float32, filter ImageFilter)

Draw an image, flipped, on an image.

func DrawImageFlippedOnImage(destination Image, src Image, posX int32, posY int32, flipHorizontal bool, flipVertical bool, flipDiagonal bool)

Draw an image, scaled, on an image.

func DrawImageScaledOnImage(destination Image, src Image, posX int32, posY int32, scaleX float32, scaleY float32, offsetX float32, offsetY float32, filter ImageFilter)

Draw some text on an image.

func DrawTextOnImage(destination Image, font Font, text string, posX int32, posY int32, color Color)

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

func DrawRectangleOutline(posX int32, posY int32, width int32, height int32, thickness int32, color Color)

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

func DrawTriangleOutline(x1 int32, y1 int32, x2 int32, y2 int32, x3 int32, y3 int32, thickness int32, color Color)

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

func DrawEllipseOutline(centerX int32, centerY int32, radiusX int32, radiusY int32, thickness int32, color Color)

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

func DrawCircleOutline(centerX int32, centerY int32, radius int32, thickness int32, color Color)

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

func DrawPolygonOutline(points []Vector, numPoints int32, thickness int32, color Color)

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

func DrawArcOutline(centerX int32, centerY int32, radius float32, startAngle float32, endAngle float32, segments int32, thickness int32, color Color)

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

func DrawRectangleRoundedOutline(x int32, y int32, width int32, height int32, cornerRadius int32, thickness int32, color Color)

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

func DrawRectangleOutlineOnImage(destination Image, posX int32, posY int32, width int32, height int32, thickness int32, color Color)

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

func DrawTriangleOutlineOnImage(destination Image, x1 int32, y1 int32, x2 int32, y2 int32, x3 int32, y3 int32, thickness int32, color Color)

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

func DrawEllipseOutlineOnImage(destination Image, centerX int32, centerY int32, radiusX int32, radiusY int32, thickness int32, color Color)

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

func DrawCircleOutlineOnImage(destination Image, centerX int32, centerY int32, radius int32, thickness int32, color Color)

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

func DrawPolygonOutlineOnImage(destination Image, points []Vector, numPoints int32, thickness int32, color Color)

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

func DrawRectangleRoundedOutlineOnImage(destination Image, x int32, y int32, width int32, height int32, cornerRadius int32, thickness int32, 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.

func GuiBeginWindow(title string, rect Rectangle) bool

End the current GUI window.

func GuiEndWindow()

A button. Returns true when it is clicked.

func GuiButton(label string) bool

A static text label.

func GuiLabel(text string)

A block of wrapping text.

func GuiText(text string)

A checkbox. Returns the (possibly changed) state.

func GuiCheckbox(label string, state bool) bool

A slider. Returns the (possibly changed) value.

func GuiSlider(value float32, low float32, high float32) float32

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

func GuiLayoutRow(widths []int32, numWidths int32, height int32)

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

func GuiEnd()

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

func GuiDraw(dst Image)
input (12)

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

func KeyPressed(key Key) bool

Is the key currently down?

func KeyDown(key Key) bool

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

func KeyReleased(key Key) bool

Is the key currently up?

func KeyUp(key Key) bool

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

func GamepadButtonPressed(gamepad int32, button GamepadButton) bool

Is the button currently down?

func GamepadButtonDown(gamepad int32, button GamepadButton) bool

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

func GamepadButtonReleased(gamepad int32, button GamepadButton) bool

Get current position of mouse.

func MousePosition() Vector

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

func MouseButtonPressed(button MouseButton) bool

Is the button currently down?

func MouseButtonDown(button MouseButton) bool

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

func MouseButtonReleased(button MouseButton) bool

Is the button currently up?

func MouseButtonUp(button MouseButton) bool
sound (7)

Load a sound from a file in cart.

func LoadSound(filename string) Sound

Play a sound.

func PlaySound(sound Sound, loop bool)

Stop a sound.

func StopSound(sound Sound)

Unload a sound.

func UnloadSound(sound Sound)

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

func TtsSound(text string, phonetic bool, pitch int32, speed int32, throat int32, mouth int32, sing bool) Sound

Create Sfx sound.

func SfxSound(params SfxParams) Sound

Create Sfx parameters.

func SfxGenerate(type_ SfxPresetType) SfxParams
tile (38)

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

func LoadTilemap(filename string) Tilemap

Unload a tilemap.

func UnloadTilemap(tilemap Tilemap)

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

func TileUpdate(tilemap Tilemap, deltaTime float32)

Get the size of a tilemap, in tiles.

func TileMapSize(tilemap Tilemap) Dimensions

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

func TileTileSize(tilemap Tilemap) Dimensions

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

func TileMapProp(tilemap Tilemap, name string) TilemapProp

Get the number of custom properties on a tilemap.

func TileMapPropCount(tilemap Tilemap) int32

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

func TileMapPropAt(tilemap Tilemap, index int32) TilemapProp

Draw a tilemap on the screen.

func TileDraw(tilemap Tilemap, posX int32, posY int32)

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

func TileDrawTint(tilemap Tilemap, posX int32, posY int32, tint Color)

Draw a tilemap on an image.

func TileDrawOnImage(dst Image, tilemap Tilemap, posX int32, posY int32)

Render a whole tilemap to a new image.

func TilemapImage(tilemap Tilemap) Image

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.

func TileLayerCount(tilemap Tilemap) int32

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

func TileLayerIndex(tilemap Tilemap, name string) int32

Get the name of a layer of a tilemap.

func TileLayerName(tilemap Tilemap, layer int32) string

Get the kind of a layer of a tilemap.

func TileLayerType(tilemap Tilemap, layer int32) TileLayerKind

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

func TileLayerSize(tilemap Tilemap, layer int32) Dimensions

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

func TileLayerVisible(tilemap Tilemap, layer int32) bool

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

func TileLayerProp(tilemap Tilemap, layer int32, name string) TilemapProp

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

func TileLayerPropCount(tilemap Tilemap, layer int32) int32

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

func TileLayerPropAt(tilemap Tilemap, layer int32, index int32) TilemapProp

Draw a single layer of a tilemap on the screen.

func TileDrawLayer(tilemap Tilemap, layer int32, posX int32, posY int32)

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

func TileDrawLayerTint(tilemap Tilemap, layer int32, posX int32, posY int32, tint Color)

Draw a single layer of a tilemap on an image.

func TileDrawLayerOnImage(dst Image, tilemap Tilemap, layer int32, posX int32, posY int32)

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

func TileLayerImage(tilemap Tilemap, layer int32) Image

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

func TileGetTile(tilemap Tilemap, layer int32, column int32, row int32) int32

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.

func TileSetTile(tilemap Tilemap, layer int32, column int32, row int32, gid int32)

Draw a single tile from a tilemap on the screen.

func TileDrawTile(tilemap Tilemap, gid int32, posX int32, posY int32)

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

func TileImage(tilemap Tilemap, gid int32) Image

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.

func TileGidProp(tilemap Tilemap, gid int32, name string) TilemapProp

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

func TileGidPropCount(tilemap Tilemap, gid int32) int32

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

func TileGidPropAt(tilemap Tilemap, gid int32, index int32) TilemapProp

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

func TileObjectCount(tilemap Tilemap, layer int32) int32

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

func TileObject(tilemap Tilemap, layer int32, index int32) TilemapObject

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

func TileObjectIndex(tilemap Tilemap, layer int32, name string) int32

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

func TileObjectProp(tilemap Tilemap, layer int32, index int32, name string) TilemapProp

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

func TileObjectPropCount(tilemap Tilemap, layer int32, index int32) int32

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

func TileObjectPropAt(tilemap Tilemap, layer int32, index int32, propIndex int32) TilemapProp
utilities (5)

Get system-time (ms) since unix epoch.

func CurrentTime() uint64

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

func DeltaTime() float32

Get a random integer between 2 numbers.

func RandomInt(min int32, max int32) int32

Get the random-seed.

func RandomSeedGet() uint64

Set the random-seed.

func RandomSeedSet(seed uint64)