Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Resources

FADEMP3 · FREE IMAGE · FREE LAYER · FREE MP3 · FREE WAV · GETIMAGE · LOADIMG · LOADMP3 · LOADWAV · PLAYMP3 · PLAYWAV · PUTIMAGE · STOPMP3 · STOPWAV · base64toimg · base64tomp3 · base64towav

FADEMP3

Fade an MP3 in or out over duration seconds.

FADEMP3 direction, name, duration
fademp3(direction, name, duration)

Parameters

  • direction AS STRING - “in” or “out”.
  • name AS STRING - The MP3.
  • duration AS NUMBER - Seconds.

Example

SCREEN 320, 240
LOADMP3 "ready.mp3", "voice"
FADEMP3 "in", "voice", 1.5
FADEMP3 "out", "voice", 0.5
PRINT "faded"

Notes

It’s also the function fademp3, for when you want what it gives back.

FREE IMAGE

Free a loaded image.

FREE IMAGE name
free_image(name)

Parameters

  • name - Which one.

Example

SCREEN 320, 240
LOADIMG "hero.png", "tmp"
PUTIMAGE (10, 10), "tmp"
FREE IMAGE "tmp"
PRINT imagewidth("tmp")

Notes

It’s also the function free_image, for when you want what it gives back.

FREE LAYER

Free a layer.

FREE LAYER name
free_layer(name)

Parameters

  • name - Which one.

Example

SCREEN 320, 240
CREATE LAYER 2, 320, 240
WITH LAYER 2
    CIRCLE (160, 120), 30, 14
END WITH LAYER
FREE LAYER 2
PRINT "layer 2 is gone"

Notes

It’s also the function free_layer, for when you want what it gives back.

FREE MP3

Free a loaded MP3.

FREE MP3 name
free_mp3(name)

Parameters

  • name - Which one.

Example

SCREEN 320, 240
LOADMP3 "ready.mp3", "voice"
PLAYMP3 "voice"
STOPMP3 "voice"
FREE MP3 "voice"
PRINT "voice is unloaded"

Notes

It’s also the function free_mp3, for when you want what it gives back.

FREE WAV

Free a loaded WAV.

FREE WAV name
free_wav(name)

Parameters

  • name - Which one.

Example

SCREEN 320, 240
LOADWAV "explosion.wav", "boom"
PLAYWAV "boom"
FREE WAV "boom"
PRINT "boom is unloaded"

Notes

It’s also the function free_wav, for when you want what it gives back.

GETIMAGE

Copy a rectangle of the current layer into a new image.

GETIMAGE region, name
getimage(region, name)

Parameters

  • region AS VECTOR - The rectangle: ((x1, y1), (x2, y2)).
  • name AS STRING - The image’s name.

Example

SCREEN 320, 240
CIRCLE (32, 32), 20, 14, 14
GETIMAGE (0, 0) -> (63, 63), "ball"
PUTIMAGE (200, 100), "ball"
PRINT imagewidth("ball"), imageheight("ball")

Notes

It’s also the function getimage, for when you want what it gives back.

LOADIMG

Load an image file under a name, optionally as a spritesheet (client-side only in multiplayer).

LOADIMG filename, name
loadimg(filename, name)
LOADPNG filename, name [, spritesheet, tag, layers, slices]
loadimg(filename, name [, spritesheet, tag, layers, slices])

Also documents: layers, slices, spritesheet, tag

Parameters

  • filename AS STRING - The file, in the game folder.
  • name AS STRING - The name it is used by.

After !!

  • layers(value AS ARRAY) - Only these Aseprite layers, by name or 0-based index.
  • slices(on = TRUE) - Return the first Aseprite slice’s box on every frame: a list of ((x1, y1), (x2, y2)), 0-1 across the frame.
  • spritesheet(value AS COORDINATE) - Cut it into frames of (width, height).
  • tag(value AS STRING) - Only the Aseprite tag’s frames.

Examples

SCREEN 320, 240
LOADIMG "hero.png", "hero"
PRINT imagewidth("hero"), imageheight("hero")
PUTIMAGE (50, 50), "hero"

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(1)
SHOW SPRITE 0
PRINT "hero cut into 40x40 frames"

SCREEN 320, 240
// An Aseprite file, with its first slice's box on every frame.
boxes = LOADIMG("knight.ase", "knight") !! slices
PRINT boxes(0)

Notes

It’s also the function loadimg, for when you want what it gives back.

LOADMP3

Load an MP3 from the game’s files under a name.

LOADMP3 filename, name
loadmp3(filename, name)

Parameters

  • filename AS STRING - The file.
  • name AS STRING - The name it is played by.

Example

SCREEN 320, 240
LOADMP3 "ready.mp3", "voice"
PLAYMP3 "voice"
PRINT "the voice is playing"

Notes

It’s also the function loadmp3, for when you want what it gives back.

LOADWAV

Load a sound file under a name (client-side only in multiplayer).

LOADWAV filename, name
loadwav(filename, name)

Parameters

  • filename AS STRING - The file, in the game folder.
  • name AS STRING - The name it is played by.

Example

SCREEN 320, 240
LOADWAV "explosion.wav", "Boom"
PLAYWAV "boom"
PRINT "loaded and played"

Notes

It’s also the function loadwav, for when you want what it gives back.

PLAYMP3

Play an MP3 loaded with loadmp3.

PLAYMP3 name [, looping, volume]
playmp3(name [, looping, volume])

Also documents: crossfade, events_on, section

Parameters

  • name AS STRING - The MP3.
  • looping AS BOOLEAN = NULL - Yes loops it until it’s stopped.
  • volume AS NUMBER = NULL - Volume, 0 to 1.

After !!

  • crossfade(value AS NUMBER) - Blend a looped section’s seam over this many seconds.
  • events_on(value AS ARRAY) - Times, in seconds, that fire the event <NAME>_CUE.
  • section(value AS RANGE) - Play (and loop) only start ... end, in seconds.

Examples

SCREEN 320, 240
LOADMP3 "ready.mp3", "voice"
PLAYMP3 "voice", TRUE, 0.5
STOPMP3 "voice"

SCREEN 320, 240
// Loop only a part of the clip, its seam blended.
LOADMP3 "ready.mp3", "voice"
PLAYMP3 "voice", TRUE, 1 !! section(0.1 ... 0.3) crossfade(0.05)
STOPMP3

Notes

It’s also the function playmp3, for when you want what it gives back.

PLAYWAV

Play a loaded sound.

PLAYWAV name [, looping, volume]
playwav(name [, looping, volume])

Also documents: at

Parameters

  • name AS STRING - The sound’s name.
  • looping AS NUMBER = NULL - Loop it (non-zero).
  • volume AS NUMBER = NULL - Volume, 0-1.

After !!

  • at(value AS COORDINATE) - Where it’s heard: (x, y), with x from -1 (left) to 1 (right) and 0 the middle; y is kept for 3D sound and not used yet.

Example

SCREEN 320, 240
LOADWAV "explosion.wav", "boom"
PLAYWAV "boom", 0, 0.8 !! at((0.8, 0))   // louder, on the right
PLAYWAV "boom", 1
STOPWAV "boom"

Notes

It’s also the function playwav, for when you want what it gives back.

PUTIMAGE

Draw an image on the current layer.

PUTIMAGE at, name [, frame]
putimage(at, name [, frame])

Also documents: alpha, flip_x, flip_y, map, map_area, origin, region, rotate, rotate_origin, scale, scale_to

Parameters

  • at AS COORDINATE - Where: (x, y).
  • name AS STRING - The image.
  • frame AS NUMBER = NULL - Spritesheet frame.

After !!

  • alpha(value AS NUMBER) - Opacity, 0-1.
  • flip_x(on = TRUE) - Mirror horizontally.
  • flip_y(on = TRUE) - Mirror vertically.
  • map(value) - Draw a grid of the image’s frames, given with map_area: a grid of rows, map(row, column), each a frame number (1-based; 0 or less skips the cell).
  • map_area(value AS VECTOR) - The cells of map to draw, ((x1, y1), (x2, y2)).
  • origin(value AS COORDINATE) - The point of the image placed at at, 0-1 across it.
  • region(value AS VECTOR) - Draw only this part of the image, in its pixels.
  • rotate(value AS NUMBER) - Rotation in degrees.
  • rotate_origin(value AS COORDINATE) - The point it turns about, 0-1 across it (ROTATE’s origin).
  • scale(value) - Scale: (sx, sy) (1 is actual size).
  • scale_to(value AS COORDINATE) - Scale it to (width, height) pixels.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
PUTIMAGE (50, 50), "hero"
PUTIMAGE (100, 50), "hero", 1 !! scale((2, 2)) alpha(0.5)
PUTIMAGE (160, 120), "hero", 0 !! rotate(45) origin((0.5, 0.5)) flip_x

Notes

It’s also the function putimage, for when you want what it gives back.

STOPMP3

Stop the MP3 called name, or every one when it is omitted.

STOPMP3 [name]
stopmp3([name])

Parameters

  • name AS STRING = NULL - Which one.

Example

SCREEN 320, 240
LOADMP3 "ready.mp3", "voice"
PLAYMP3 "voice", TRUE
STOPMP3 "voice"
STOPMP3
PRINT "every clip stopped"

Notes

It’s also the function stopmp3, for when you want what it gives back.

STOPWAV

Stop the WAV called name, or every one when it is omitted.

STOPWAV [name]
stopwav([name])

Parameters

  • name AS STRING = NULL - Which one.

Example

SCREEN 320, 240
LOADWAV "explosion.wav", "boom"
PLAYWAV "boom", 1
STOPWAV "boom"
STOPWAV
PRINT "silence"

Notes

It’s also the function stopwav, for when you want what it gives back.

base64toimg

Function-form analog of LOADIMG that takes a base64-encoded PNG payload instead of a file path. Designed to compose with FETCH — load an image over the network, then register it as a named texture in one more line. Accepts either raw base64 or a full data:image/png;base64,... URI; the data URI prefix is stripped automatically. Same dim-parsing and sprite-sheet semantics as LOADIMG. Errors halt with a clear runtime error — gate the call on FETCH’s STATUSCODE if the source might fail. It can be written base64toimg(base64, image_name) or base64toimg(base64, image_name, sheet_w, sheet_h).

base64toimg(base64, image_name, sheet_w = NULL, sheet_h = NULL)

Parameters

  • base64 - Base64-encoded PNG payload, or a data:image/png;base64,... URI
  • image_name - Reference name for later use with PUTIMAGE (case-insensitive)
  • sheet_w = NULL
  • sheet_h = NULL

Examples

SCREEN 320, 240
dot = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
SCREEN 320, 240
PRINT base64toimg(dot, "dot")
PRINT imagewidth("dot")
PUTIMAGE (10, 10), "dot" !! scale((8, 8))

SCREEN 320, 240
// A data: URI works too; the prefix is stripped.
uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
IF base64toimg(uri, "Pixel") THEN PRINT imageheight("pixel")

base64tomp3

Function-form analog of LOADMP3 that takes a base64-encoded MP3 payload instead of a file path. Designed to compose with FETCH. Accepts either raw base64 or a full data:audio/mpeg;base64,... URI; the data URI prefix is stripped automatically. Client-only — calling from a server-side multiplayer interpreter is a fatal runtime error, matching LOADMP3’s gating. The audio_name is case-insensitive — BASE64TOMP3(data, "Theme") and PLAYMP3 "theme" agree.

base64tomp3(base64, audio_name)

Parameters

  • base64 - Base64-encoded MP3 payload, or a data:audio/mpeg;base64,... URI
  • audio_name - Reference name for later playback (case-insensitive)

Example

SCREEN 320, 240
FUNCTION load_theme(payload)
    // payload: base64 text, e.g. the body of a FETCH
    IF me.isclient THEN RETURN base64tomp3(payload, "Theme")
    RETURN FALSE
END FUNCTION
PRINT "load_theme is ready"

base64towav

Function-form analog of LOADWAV that takes a base64-encoded WAV payload instead of a file path. Designed to compose with FETCH. Accepts either raw base64 or a full data:audio/wav;base64,... URI; the data URI prefix is stripped automatically. Client-only — calling from a server-side multiplayer interpreter is a fatal runtime error, matching LOADWAV’s gating. The audio_name is case-insensitive — BASE64TOWAV(data, "Boom") and PLAYWAV "boom" agree.

base64towav(base64, audio_name)

Parameters

  • base64 - Base64-encoded WAV payload, or a data:audio/wav;base64,... URI
  • audio_name - Reference name for later playback (case-insensitive)

Example

SCREEN 320, 240
wav = "UklGRiQAAABXQVZFZm10IA=="
IF base64towav(wav, "Boom") THEN PLAYWAV "boom"
PRINT "decoded"