w4

Documentation

Overview

Callbacks

The are 2 callbacks that you can register by assigning a function to them:

• Start is called once at the very beginning.
• Update is called on each frame update.

Drawing functions

The library provides the following functions directly calling the host functions in WASM-4:

• Blit: copy raw sprite bytes from memory onto the frame buffer.
• BlitSub: like Blit but copies only the given region of a sprite.
• DrawLine: draw a line between two given points.
• DrawHorLine: draw horizontal line.
• DrawVertLine: draw vertical line.
• DrawEllipse: draw an ellipse (aka oval) or a circle.
• DrawRect: draw a rectangle (or square)
• DrawText: draw text using the built-in 8x8 font.
• PlayTone: play a sound.
• Trace: write a log message into the console.
• Save: write bytes into a persistent storage (save the game).
• Load: read bytes from the persistent storage (load the game).

Memory access

Unlike the default WASM-4 bindings, the library doesn't require direct memory manipulation. Instead, there is a set of wrapper singletones for accessing specific regions of memory:

• Palette defines the 4 colors used to render the next frame.
• DrawColors defines which colors from the palette the draw functions should use.
• Gamepads lets you check which buttons on the gamepads are pressed.
• Mouse provides information about the mouse cursor position and pressed mouse buttons.
• SystemFlags allows modifying the WASM-4 behavior.
• NetPlay provides information about multiplayer.
• FrameBuffer provides direct access to the frame buffer in memory.

Methods available for each of these singletones aren't shown in the web documetation because their types are private. Use your IDE to see available methods and their docs.

Types

The library defines the following helper types for working with memory:

• Color is used to set colors for the Palette.
• DrawColor is used by DrawColors to map draw functions colors to the palette.

Index

• Variables
• func Blit(sprite []byte, p Point, s Size, f BlitFlags)
• func BlitSub(sprite []byte, dst Point, s Size, src Point, stride u8, f BlitFlags)
• func DrawEllipse(p Point, s Size)
• func DrawHorLine(p Point, len u8)
• func DrawLine(p1, p2 Point)
• func DrawRect(p Point, s Size)
• func DrawText(text string, p Point)
• func DrawVertLine(p Point, len u8)
• func Load(buf []byte) uint
• func PlayTone(t Tone)
• func Save(buf []byte) uint
• func Trace(text string)
• type BlitFlags
• type Channel
• type Color
• type DrawColor
• type DutyCycle
• type Pan
• type Point
  • func (p Point) AddSize(s Size) Point
  • func (p Point) AsSize() Size
  • func (p Point) ComponentMax(other Point) Point
  • func (p Point) ComponentMin(other Point) Point
  • func (p Point) Wrap() Point
  • func (p Point) XAxis() Point
  • func (p Point) YAxis() Point
• type Size
  • func (s Size) AddSize(other Size) Size
  • func (s Size) AsPoint() Point
  • func (s Size) ComponentMax(other Size) Size
  • func (s Size) ComponentMin(other Size) Size
• type Tone

Examples

• Blit
• Color
• DrawEllipse
• DrawHorLine
• DrawLine
• DrawRect
• DrawText
• DrawVertLine
• Load
• Save
• Trace

Variables

var DrawColors = drawColors{}

Defines which colors from the palette should be used by the draw functions.

https://wasm4.org/docs/guides/basic-drawing#the-draw_colors-register

var FrameBuffer = memory[0xa0-offset:]

Array of 160x160 pixels, with each pixel packed into 2 bits (colors 0 to 3).

https://wasm4.org/docs/guides/basic-drawing#direct-framebuffer-access

var Gamepad gamepad = 0x12

The gamepad of the local player.

The same as Gamepads[0].

var Gamepads = gamepads{0x12, 0x13, 0x14, 0x15}

An array of 4 gamepads.

• The first one is always available and is the local player.
• The second one can be either a local hotseat player or a remote one.
• Gamepads 3 and 4 are always remote players.

https://wasm4.org/docs/guides/user-input#gamepad

var Mouse = mouse{}

The mouse position and mouse buttons (left, right, and middle) state.

https://wasm4.org/docs/guides/user-input#mouse

var NetPlay = netplay{}

Multiplayer state.

https://wasm4.org/docs/guides/multiplayer#the-netplay-memory-register

var Palette = palette{}

Set of 4 colors used to render the current frame buffer on the screen.

Which colors from the palette are used to draw a specific element is controlled by DrawColors.

https://wasm4.org/docs/guides/basic-drawing#the-palette-register

var Start func()

The callaback function to call on the game start.

var SystemFlags = systemFlags{}

Flags that modify WASM-4's operation.

By default all flags are off.

var Update func()

The callback function to call for each game frame refresh.

Functions

func Blit

func Blit(sprite []byte, p Point, s Size, f BlitFlags)

Copies pixels to the framebuffer.

• https://wasm4.org/docs/guides/sprites
• https://wasm4.org/docs/reference/functions#blit-spriteptr-x-y-width-height-flags

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	var smiley = []byte{
		0b11000011,
		0b10000001,
		0b00100100,
		0b00100100,
		0b00000000,
		0b00100100,
		0b10011001,
		0b11000011,
	}
	size := w4.Size{Width: 8, Height: 8}
	w4.Blit(smiley, w4.Point{X: 76, Y: 76}, size, 0)
}

func BlitSub

func BlitSub(sprite []byte, dst Point, s Size, src Point, stride u8, f BlitFlags)

Copies a subregion within a larger sprite atlas to the framebuffer.

https://wasm4.org/docs/reference/functions#blitsub-spriteptr-x-y-width-height-srcx-srcy-stride-flags

func DrawEllipse

func DrawEllipse(p Point, s Size)

Draws an oval (or circle).

The point is coordinates of the left-upper corner of the bounding box. The size is the size of the bounding box.

https://wasm4.org/docs/reference/functions#oval-x-y-width-height

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	// Draw a circle with 30 pixels diameter.
	w4.DrawEllipse(w4.Point{X: 10, Y: 10}, w4.Size{Width: 30, Height: 30})
}

func DrawHorLine

func DrawHorLine(p Point, len u8)

Draws a horizontal line between (x, y) and (x + len - 1, y).

https://wasm4.org/docs/reference/functions#hlinex-y-len

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.DrawHorLine(w4.Point{X: 10, Y: 20}, 30)
}

func DrawLine

func DrawLine(p1, p2 Point)

Draws a line between two points.

https://wasm4.org/docs/reference/functions#line-x1-y1-x2-y2

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.DrawLine(
		w4.Point{X: 10, Y: 20},
		w4.Point{X: 20, Y: 10},
	)
}

func DrawRect

func DrawRect(p Point, s Size)

Draws a rectangle.

https://wasm4.org/docs/reference/functions#rect-x-y-width-height

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	// Draw a square 30 pixels side length.
	w4.DrawRect(w4.Point{X: 10, Y: 10}, w4.Size{Width: 30, Height: 30})
}

func DrawText

func DrawText(text string, p Point)

Draws text using the built-in system font.

The string may contain new-line (\n) characters.

The font is 8x8 pixels per character.

• https://wasm4.org/docs/reference/functions#text-str-x-y
• https://wasm4.org/docs/guides/text

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.DrawText("Hello world!", w4.Point{X: 10, Y: 10})
}

func DrawVertLine

func DrawVertLine(p Point, len u8)

Draws a vertical line between (x, y) and (x, y + len - 1).

https://wasm4.org/docs/reference/functions#vlinex-y-len

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.DrawVertLine(w4.Point{X: 40, Y: 50}, 30)
}

func Load

func Load(buf []byte) uint

Reads bytes from persistent storage into the buffer.

Make sure the buffer has cap enough to fit the data.

https://wasm4.org/docs/guides/saving-data?code-lang=go#reading-data-from-disk

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	data := make([]byte, 1024)
	w4.Load(data)
}

func PlayTone

func PlayTone(t Tone)

Play a sound tone.

• https://wasm4.org/docs/guides/audio
• https://wasm4.org/docs/reference/functions#tone-frequency-duration-volume-flags

func Save

func Save(buf []byte) uint

Writes bytes from the buffer into persistent storage.

https://wasm4.org/docs/guides/saving-data?code-lang=go#writing-data-to-disk

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	data := []byte("some data")
	w4.Save(data)
}

func Trace

func Trace(text string)

Prints a message to the debug console.

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.Trace("Some message")
}

Types

type BlitFlags

type BlitFlags u8

Flags used with Blit and BlitSub.

const (
	// Use two bits per pixel
	TwoBPP BlitFlags = 1
	// Flip the image horizontally.
	FlipX BlitFlags = 2
	// Flip the image vertically.
	FlipY BlitFlags = 4
	// Rotate the image 90 degrees counterclockwise.
	Rotate BlitFlags = 8
)

type Channel

type Channel u8

const (
	Pulse1   Channel = 0
	Pulse2   Channel = 1
	Triangle Channel = 2
	Noise    Channel = 3
)

type Color

type Color struct {
	// Red channel, from 0 to 255.
	R u8

	// Green channel, from 0 to 255.
	G u8

	// Blue channel, from 0 to 255.
	B u8
}

BGR888 color in the palette.

https://wasm4.org/docs/guides/basic-drawing#the-palette-register

Example

package main

import (
	"github.com/orsinium-labs/wasm4go/w4"
)

func main() {
	w4.Palette.Set(
		w4.Color{R: 0xfb, G: 0xf7, B: 0xf3},
		w4.Color{R: 0xe5, G: 0xb0, B: 0x83},
		w4.Color{R: 0x42, G: 0x6e, B: 0x5d},
		w4.Color{R: 0x20, G: 0x28, B: 0x3d},
	)
}

type DrawColor

type DrawColor u8

A color from the palette used bu draw functions.

https://wasm4.org/docs/guides/basic-drawing#the-draw_colors-register

const (
	// Do not draw this color.
	//
	// Can be used to draw shapes without fill or without outline.
	Transparent DrawColor = 0

	// The 1st color in the palette. Usually a very light, almost white, color.
	Light DrawColor = 1

	// The 2nd color in the palette. Usually a bright and intensive accent color.
	Primary DrawColor = 2

	// The 3rd color in the palette. Usually a distinc color but darker than primary.
	Secondary DrawColor = 3

	// The 4th color in the palette. A very dark color, used for night or contrast.
	Dark DrawColor = 4
)

type DutyCycle

type DutyCycle u8

The duty cycle of the tone.

https://wasm4.org/docs/guides/audio#duty-cycle

const (
	DutyCycle1p8 DutyCycle = 0
	DutyCycle1p4 DutyCycle = 4
	DutyCycle1p2 DutyCycle = 8
	DutyCycle3p4 DutyCycle = 12
)

type Pan

type Pan u8

Panning

https://wasm4.org/docs/guides/audio#panning

const (
	Center Pan = 0
	Left   Pan = 16
	Right  Pan = 32
)

type Point

type Point struct {
	X u8
	Y u8
}

A point on the plane.

func (Point) AddSize

func (p Point) AddSize(s Size) Point

Add size width to the point x and size height to the point y.

func (Point) AsSize

func (p Point) AsSize() Size

Convert the Point to a Size with width equal to x and height equal to y.

func (Point) ComponentMax

func (p Point) ComponentMax(other Point) Point

The componentwise maximum of two Points.

func (Point) ComponentMin

func (p Point) ComponentMin(other Point) Point

The componentwise minimum of two Points.

func (Point) Wrap

func (p Point) Wrap() Point

If the point is outside of the screen, wrap it around to fit on the screen.

func (Point) XAxis

func (p Point) XAxis() Point

A point with equal x value and y set to 0.

func (Point) YAxis

func (p Point) YAxis() Point

A point with equal y value and x set to 0.

type Size

type Size struct {
	Width  u8
	Height u8
}

Size of a 2D shape.

func (Size) AddSize

func (s Size) AddSize(other Size) Size

Add two sizes together componentwise.

func (Size) AsPoint

func (s Size) AsPoint() Point

Convert Size to a Point with x set to width and y set to height.

func (Size) ComponentMax

func (s Size) ComponentMax(other Size) Size

The componentwise maximum of two Sizes.

func (Size) ComponentMin

func (s Size) ComponentMin(other Size) Size

The componentwise minimum of two Sizes.

type Tone

type Tone struct {
	// Start wave frequency in hertz.
	StartFreq uint

	// End wave frequency in hertz, used to describe a pitch slide effect.
	//
	// https://wasm4.org/docs/guides/audio#frequency-slide
	EndFreq uint

	// Volume of the sustain duration, between 0 and 100.
	//
	// https://wasm4.org/docs/guides/audio#volume
	SustainVol u8

	// Volume of the attack duration, between 0 and 100.
	AttackVol u8

	Channel   Channel
	DutyCycle DutyCycle
	Pan       Pan

	// Duration of the tone in frames (1/60th of a second), up to 255 frames.
	// Sustain time of ADSR envelope.
	//
	// https://wasm4.org/docs/guides/audio#adsr-envelope
	Sustain u8

	// Attack time of ADSR envelope.
	//
	// https://wasm4.org/docs/guides/audio#adsr-envelope
	Attack u8

	// Decay time of ADSR envelope.
	//
	// https://wasm4.org/docs/guides/audio#adsr-envelope
	Decay u8

	// Release time of ADSR envelope.
	//
	// https://wasm4.org/docs/guides/audio#adsr-envelope
	Release u8
}