Graphics

ASIMAGE · CIRCLE · CLS · COLOR · CREATE LAYER · CREATE MAP · DESTROY POLYGON · FONT RESET · FRAME · HIDE POLYGON · LINE · LOADFONT · LOCATE · MEMORYBUFFER · NEWIMAGE · PALETTE · POLYGON · PRESET · PRINT · PSET · RESET LAYERS · SCENE · SCREEN · SCREEN TEXT · SET CURSOR · SET IMAGE · SET LAYER · SET PALETTE · SET POLYGON · SET SCROLL · SETFONT · SHADER · SHOW POLYGON · TEXTTOIMAGE · TOSPRITESHEET · UPDATE MAP · WINDOW · getscroll · imageheight · imagewidth · maptile · maptilex · maptiley · mapworldtilex · mapworldtiley · mutation · point · pointrgb · realheight · realstart · realwidth · screenheight · screenwidth · transition · transition_str · typing

ASIMAGE

Make an image from palette indices (-1 transparent), row by row.

ASIMAGE pixels, name, width, height
asimage(pixels, name, width, height)

Parameters

pixels AS ARRAY - The indices: a flat list, or a list of rows.
name AS STRING - The image’s name.
width AS NUMBER - Width in pixels.
height AS NUMBER - Height in pixels.

Example

SCREEN 320, 240
heart = [[-1, 4, -1, 4, -1], [4, 12, 4, 12, 4], [4, 12, 12, 12, 4], [-1, 4, 12, 4, -1], [-1, -1, 4, -1, -1]]
ASIMAGE heart, "heart", 5, 5
PUTIMAGE (100, 100), "heart"
PRINT imagewidth("heart"), imageheight("heart")

Notes

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

CIRCLE

Draw a circle, optionally filled.

CIRCLE center, radius [, color, fill]
circle(center, radius [, color, fill])

Parameters

center AS COORDINATE - The centre: (x, y).
radius AS NUMBER - Radius in pixels.
color AS NUMBER = NULL - Outline palette index (or colour).
fill AS NUMBER = NULL - Fill palette index (or colour).

Example

SCREEN 320, 240
CIRCLE (160, 120), 40, 12
CIRCLE (60, 60), 20, 14, 14

Notes

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

CLS

Clear the current layer, optionally to a colour and with a transition effect.

CLS [color]
cls([color])

Also documents: effect, effect_shader, size, speed, to_image

Parameters

color AS NUMBER = NULL - Palette index (or colour) to clear to.

After !!

effect(value AS STRING) - “fade”, “melt”, “block”, “dissolve”, “wipex” or “wipey”.
effect_shader(value AS STRING) - A named transition shader, instead of a built-in effect.
size(value AS NUMBER) - Block size in pixels for the “block” effect (default 8).
speed(value AS NUMBER) - How fast the effect runs.
to_image(value AS STRING) - Clear the layer to this loaded image instead of a colour; with an effect, transition to it.

Example

SCREEN 320, 240
CLS 1
PRINT "a blue screen"

Notes

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

COLOR

Set the text colour, and optionally the background colour.

COLOR fg [, bg]
color(fg [, bg])

Parameters

fg AS NUMBER - Foreground palette index (or colour).
bg AS NUMBER = NULL - Background palette index (or colour).

Example

SCREEN 320, 240
COLOR 14, 1
PRINT "yellow on blue"
COLOR 15
PRINT "white again"

Notes

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

CREATE LAYER

Create a drawing layer of a given size.

CREATE LAYER id, width, height
create_layer(id, width, height)

Also documents: visible

Parameters

id AS NUMBER - Layer number.
width AS NUMBER - Width in pixels.
height AS NUMBER - Height in pixels.

After !!

visible(on = TRUE) - Given off, the layer starts hidden, to set up before set_layer shows it.

Example

SCREEN 320, 240
CREATE LAYER 1, 320, 240
WITH LAYER 1
    CIRCLE (160, 120), 30, 12
END WITH LAYER
PRINT "a circle on layer 1"

Notes

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

CREATE MAP

Put a map’s layers on screen layers: from a .map.json file, a TILEMAP’s name, or a grid of tiles.

CREATE MAP source [, map_layers]
create_map(source [, map_layers])

Also documents: layer_to, meta, size, speed, tileset, tilesize, visible, wrap_x, wrap_y

Parameters

source - A .map.json file, a TILEMAP’s name, or the tiles themselves (a grid or a list of rows): those are one layer.
map_layers = NULL - Which of the map’s layers, 0 the lowest: one, a run of them (a range, or a list of consecutive ones), or a layer’s name in a TILEMAP. Left out, layer 0, or as many from 0 as layer_to has screen layers.

After !!

layer_to(value) - The screen layer it goes on, or the run of them the map’s layers go on, one each. Required.
meta(value) - With tiles: a grid of text, each tile’s metadata.
size(value AS COORDINATE) - With tiles: (width, height) in tiles, if not the grid’s.
speed(value AS NUMBER) - Tile-animation speed, frames a second.
tileset(value AS STRING) - With tiles: the tile set image.
tilesize(value) - With tiles: the tile size, n or (w, h).
visible(on = TRUE) - Given off, every layer it makes starts hidden, to set up before set_layer shows it.
wrap_x(on = TRUE) - Wrap horizontally.
wrap_y(on = TRUE) - Wrap vertically.

Examples

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET LAYER 3
PRINT maptile(0, 0, 0), maptile(1, 1, 0)

SCREEN 320, 240
LOADIMG "greyscale.png", "tiles"
rows = [[1, 1, 1, 1], [0, 2, 0, 0], [3, 3, 3, 3]]
CREATE MAP rows !! layer_to(0) tileset("tiles") tilesize(32)
SET LAYER 3
PRINT maptile(1, 1, 0)

Notes

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

DESTROY POLYGON

Remove a bound polygon: its shape, collider and behaviors.

DESTROY POLYGON id
destroy_polygon(id)

Parameters

id AS NUMBER - Polygon number.

Example

SCREEN 320, 240
rock = MUTATION((0, 0), (20, 0), (10, 20))
SET POLYGON 0 !! bind(rock) fill(6) location((100, 100))
DESTROY POLYGON 0
PRINT "gone; the shape still has", LEN(rock), "points"

Notes

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

FONT RESET

Go back to the default font and size.

FONT RESET
font_reset()

Example

SCREEN 320, 240
LOADFONT "font.ttf", "title"
SETFONT 24, "title"
PRINT "Big title"
FONT RESET
PRINT "back to the default"

Notes

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

HIDE POLYGON

Hide a bound polygon.

HIDE POLYGON id
hide_polygon(id)

Parameters

id AS NUMBER - Polygon number.

Example

SCREEN 320, 240
box = MUTATION((0, 0), (30, 0), (30, 30), (0, 30))
SET POLYGON 0 !! bind(box) fill(4) location((50, 50))
HIDE POLYGON 0
PRINT "hidden"

Notes

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

LINE

Draw a line from one point to another, or the box they span (box), filled or not.

LINE span [, color]
line(span [, color])

Also documents: box, fill

Parameters

span AS VECTOR - From one end to the other: (x1, y1) -> (x2, y2).
color AS NUMBER = NULL - Palette index (or colour).

After !!

box(on = TRUE) - Draw the box the two points span (B).
fill(on = TRUE) - Fill that box.

Example

SCREEN 320, 240
LINE (0, 0) -> (319, 239), 15
LINE (20, 20) -> (100, 60), 4 !! box
LINE (120, 20) -> (200, 60), 2 !! box fill

Notes

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

LOADFONT

Load a font (TTF/OTF) from the game’s files under a name.

LOADFONT filename, name
loadfont(filename, name)

Parameters

filename AS STRING - The file.
name AS STRING - The name it is used by.

Example

SCREEN 320, 240
LOADFONT "font.ttf", "story"
SETFONT 16, "story"
PRINT "Once upon a time"

Notes

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

LOCATE

Move the text cursor to a row and column (1-based), and/or set the pixel position they count from (origin).

LOCATE [row, col]
locate([row, col])

Also documents: origin, relative

Parameters

row AS NUMBER = NULL - Text row, from 1.
col AS NUMBER = NULL - Text column, from 1.

After !!

origin(value AS COORDINATE) - A pixel position the rows and columns count from.
relative(on = TRUE) - Move relative to the current position.

Examples

SCREEN 320, 240
LOCATE 5, 10
PRINT "Row 5, column 10"

SCREEN 320, 240
LOCATE 1, 1 !! origin((100, 50))
PRINT "Boxed text"

Notes

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

NEWIMAGE

Make a new image filled with one colour, optionally cut into frames (!! spritesheet((w, h))).

NEWIMAGE width, height, color, name
newimage(width, height, color, name)

Also documents: spritesheet

Parameters

width AS NUMBER - Width in pixels.
height AS NUMBER - Height in pixels.
color AS NUMBER - The colour it is filled with.
name AS STRING - The image’s name.

After !!

spritesheet(value AS COORDINATE) - Cut it into frames of (width, height).

Example

SCREEN 320, 240
NEWIMAGE 16, 16, 12, "block"
PUTIMAGE (50, 50), "block"
NEWIMAGE 32, 8, 4, "strip" !! spritesheet((8, 8))
PRINT imagewidth("strip")

Notes

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

PALETTE

Set palette entry index to red, green, blue and optionally alpha (0-255), or to one packed colour.

PALETTE index, r [, g, b, a]
palette(index, r [, g, b, a])

Parameters

index AS NUMBER - Palette index.
r AS NUMBER - Red, 0-255 — or, given alone, the whole colour packed as 0xRRGGBB / 0xAARRGGBB.
g AS NUMBER = NULL - Green, 0-255.
b AS NUMBER = NULL - Blue, 0-255.
a AS NUMBER = NULL - Alpha, 0-255 (opaque when omitted).

Example

SCREEN 320, 240
PALETTE 20, 255, 128, 0
CIRCLE (160, 120), 30, 20, 20
PALETTE 21, 0xFF00FF
LINE (0, 0) -> (100, 0), 21

Notes

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

POLYGON

Draw a shape: outlined, filled, or textured through its UVs.

POLYGON points, color [, fill, texture]
polygon(points, color [, fill, texture])

Also documents: offset, rotate, rotate_origin, scale, scale_to, uv, uv_offset, uv_rotate, uv_rotate_origin, uv_scale, uv_scale_to

Parameters

points AS ARRAY - The points: a list of (x, y), or a MUTATION.
color AS NUMBER - Outline palette index (or colour); -1 for none.
fill AS NUMBER = NULL - Fill palette index (or colour).
texture AS STRING = NULL - An image drawn across it, mapped by uv.

After !!

offset(value AS COORDINATE) - Move the finished shape by (x, y); applied last.
rotate(value AS NUMBER) - Rotate it, in degrees, about its centre.
rotate_origin(value AS COORDINATE) - The point rotate turns it about (ROTATE’s origin).
scale(value AS COORDINATE) - Scale it about its centre: (sx, sy).
scale_to(value AS COORDINATE) - Scale it about its centre to (width, height).
uv(value AS ARRAY) - Each point’s texture coordinates, 0-1 across the image: a list of (u, v), or a MUTATION.
uv_offset(value AS COORDINATE) - Move the UVs by (u, v); applied last.
uv_rotate(value AS NUMBER) - Rotate the UVs, in degrees.
uv_rotate_origin(value AS COORDINATE) - The point uv_rotate turns them about.
uv_scale(value AS COORDINATE) - Scale the UVs about their centre.
uv_scale_to(value AS COORDINATE) - Scale the UVs to (width, height).

Examples

SCREEN 320, 240
POLYGON [(50, 50), (150, 50), (100, 150)], 15
POLYGON [(10, 10), (90, 10), (90, 90), (10, 90)], 14, 10

SCREEN 320, 240
ship = [(0, -14), (-9, 10), (9, 10)]
POLYGON ship, 15, 9 !! rotate(30) rotate_origin((0, 0)) offset((160, 120))

Notes

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

PRESET

Erase one pixel (make it transparent).

PRESET at
preset(at)

Parameters

at AS COORDINATE - Where: (x, y).

Example

SCREEN 320, 240
LINE (10, 10) -> (20, 10), 15
PRESET (15, 10)
PRINT "a gap in the line"

Notes

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

PRINT

Writes its values on the screen, with a space between them.

PRINT values... [, rate, words, same_line]
print(values... [, rate, words, same_line])

Also documents: rate, same_line, words

Parameters

values…
rate AS NUMBER = NULL
words = FALSE
same_line = FALSE

After !!

rate(ms AS NUMBER) - Types it out a character at a time, this many milliseconds apart.
same_line(on = TRUE) - Keeps the cursor at the end, so the next PRINT carries on from there.
words(on = TRUE) - Wraps it at the edge of the screen between words, not inside them.

Examples

SCREEN 320, 240
PRINT "score", 10
PRINT [1, 2, 3], {hp: 3}, (4, 5), TRUE

SCREEN 320, 240
PRINT "Loading" !! same_line
PRINT "..." !! rate(5)
PRINT "A long line that wraps at the edge of the screen between its words, not in the middle of one." !! words

Notes

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

PSET

Set one pixel.

PSET at [, color]
pset(at [, color])

Parameters

at AS COORDINATE - Where: (x, y).
color AS NUMBER = NULL - Palette index (or colour); the current colour when omitted.

Example

SCREEN 320, 240
FOR x = 0 ... 99
    PSET (x, 50 + x MOD 10), 14
NEXT
PRINT "a sawtooth of dots"

Notes

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

RESET LAYERS

Remove every layer but 0, and draw on layer 0.

RESET LAYERS
reset_layers()

Example

SCREEN 320, 240
CREATE LAYER 1, 320, 240
CREATE LAYER 2, 320, 240
RESET LAYERS
PRINT "only layer 0 is left"

Notes

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

SCREEN

Open the screen at a size, or in a classic mode (mode), or at the display’s own size (native).

SCREEN [width, height, scale_x, scale_y, title]
screen([width, height, scale_x, scale_y, title])

Also documents: letterbox, mode, native

Parameters

width AS NUMBER = NULL - Width in pixels.
height AS NUMBER = NULL - Height in pixels.
scale_x AS NUMBER = NULL - Horizontal pixel scale.
scale_y AS NUMBER = NULL - Vertical pixel scale.
title AS STRING = NULL - Window title.

After !!

letterbox(on = TRUE) - Letterbox when the window’s shape differs (default on, as in BASIC).
mode(value AS NUMBER) - A classic QBASIC screen mode, instead of a size.
native(on = TRUE) - Use the display’s native size.

Examples

SCREEN 320, 240
PRINT screenwidth, screenheight

SCREEN 640, 360, 2, 2, "My Game" !! letterbox(FALSE)
PRINT screenwidth

Notes

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

SCREEN TEXT

Open a character-cell screen of columns x rows.

SCREEN TEXT columns, rows [, scale_x, scale_y]
screen_text(columns, rows [, scale_x, scale_y])

Also documents: letterbox, modern

Parameters

columns AS NUMBER - Characters across.
rows AS NUMBER - Rows down.
scale_x AS NUMBER = NULL - Horizontal scale (default 1).
scale_y AS NUMBER = NULL - Vertical scale (default 1).

After !!

letterbox(on = TRUE) - Keep the aspect ratio with bars when the window does not match (default on).
modern(on = TRUE) - The modern character set instead of ASCII.

Example

SCREEN TEXT 40, 25
PRINT "forty columns, twenty-five rows"

Notes

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

SET CURSOR

Show a loaded image as the mouse cursor, or, with off, the system cursor.

SET CURSOR [image]
set_cursor([image])

Also documents: hotspot, off

Parameters

image AS STRING = NULL - The image.

After !!

hotspot(value AS COORDINATE) - The pixel of the image that is the pointer’s tip: (x, y).
off(on = TRUE) - Back to the system cursor.

Example

SCREEN 320, 240
LOADIMG "hero.png", "pointer"
SET CURSOR "pointer" !! hotspot((0, 0))
SET CURSOR !! off

Notes

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

SET IMAGE

Draw into an image instead of the layer; "" goes back to the layer.

SET IMAGE name
set_image(name)

Parameters

name AS STRING - The image, or "" for the layer.

Example

SCREEN 320, 240
NEWIMAGE 32, 32, 1, "canvas"
SET IMAGE "canvas"
CIRCLE (16, 16), 10, 14, 14
SET IMAGE ""
PUTIMAGE (100, 100), "canvas"

Notes

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

SET LAYER

Make a layer the one drawing goes to, and optionally change how it shows.

SET LAYER id
set_layer(id)

Also documents: alpha, clear_clip, clear_shader, clip, height, horizon, plane, shader, shader_params, visible, wrap_x, wrap_y, zoom

Parameters

id AS NUMBER - Layer number.

After !!

alpha(value AS NUMBER) - Layer opacity, 0-1.
clear_clip(on = TRUE) - Remove the clip.
clear_shader(on = TRUE) - Remove the layer’s shader.
clip(value AS VECTOR) - Draw the layer only inside this screen rectangle.
height(value AS NUMBER) - A perspective plane’s camera height.
horizon(value AS NUMBER) - A perspective plane’s vanishing screen row.
plane(value AS STRING) - “affine”, “perspective” or “flat”: a Mode 7-style plane, or back to flat.
shader(value AS STRING) - Run a shader over the layer.
shader_params(value) - Values for the shader’s @parameters, by name: a number for a USE NUMBER, three or four numbers from 0 to 1 for a USE COLOR, a picture’s name for a USE IMAGE. A name the shader doesn’t have is an error. Without shader=, update numeric parameters of the attached shader in place (the layer must have one); this is nonblocking and may be used inside FRAME.
visible(on = TRUE) - Show the layer, or hide it when given off.
wrap_x(on = TRUE) - Wrap horizontally when scrolled.
wrap_y(on = TRUE) - Wrap vertically when scrolled.
zoom(value AS NUMBER) - An affine plane’s uniform scale.

Examples

SCREEN 320, 240
CREATE LAYER 1, 320, 240
SET LAYER 1 !! alpha(0.5)
CIRCLE (160, 120), 40, 12, 12
SET LAYER 0
PRINT "a see-through circle on layer 1"

SCREEN 320, 240
CREATE LAYER 1, 320, 240
SET LAYER 1 !! visible(FALSE)
SET LAYER 1 !! visible

Notes

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

Whether a colour is a palette index (the default) or a literal 0xAARRGGBB value: alpha, red, green, blue. SET PALETTE FALSE takes literal colours from then on, and SET PALETTE TRUE goes back to the palette. With the palette off, transparent is an alpha of 0, and -1 is opaque white.

SET PALETTE on
set_palette(on)

Parameters

on AS BOOLEAN - Yes for palette indices, no for direct colour: literal 0xAARRGGBB values.

Example

SCREEN 320, 240
SET PALETTE FALSE
CIRCLE (160, 120), 30, 0xFFFF8000, 0xFFFF8000
SET PALETTE TRUE
CIRCLE (60, 60), 20, 14

Notes

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

SET POLYGON

Bind a shape to polygon id so it is drawn every frame, and set how it looks, collides and moves. Without bind it configures a polygon already bound.

SET POLYGON id
set_polygon(id)

Also documents: alpha, bbox, behavior, behavior_params, bind, clear_behaviors, clear_max_acceleration, clear_max_velocity, clear_parent, clear_pattern, clear_shader, color, fill, flip_x, flip_y, ghost, layer, location, max_acceleration, max_velocity, one_way, origin, parent, parent_polygon, pattern, pattern_params, remove_behavior, reset, rigid, rotate, rotate_origin, scale, scale_to, shader, shader_params, solid, sprites, sync, sync_room, tag, texture, uv, velocity, visible, z_order

Parameters

id AS NUMBER - Polygon number.

After !!

alpha(value AS NUMBER) - Opacity, 0-1.
bbox(value AS VECTOR) - Collision box, from its top-left to its bottom-right, 0-1 across the shape, so (0, 0) to (1, 1) is the whole shape.
behavior(value AS STRING) - Attach a behavior.
behavior_params(value) - Values for the behavior’s @parameters, by name.
bind(value AS ARRAY) - The shape whose points are the polygon’s vertices.
clear_behaviors(on = TRUE) - Remove every behavior.
clear_max_acceleration(on = TRUE) - Remove its acceleration cap.
clear_max_velocity(on = TRUE) - Remove its speed cap.
clear_parent(on = TRUE) - Detach from the parent.
clear_pattern(on = TRUE) - Stop its pattern.
clear_shader(on = TRUE) - Remove its shader.
color(value AS NUMBER) - Outline palette index (or colour).
fill(value AS NUMBER) - Fill palette index (or colour).
flip_x(on = TRUE) - Mirror horizontally.
flip_y(on = TRUE) - Mirror vertically.
ghost(on = TRUE) - Drop its collider.
layer(value AS NUMBER) - The layer it draws above.
location(value AS COORDINATE) - Place it: (x, y) is where its ORIGIN goes.
max_acceleration(value AS COORDINATE) - Cap its acceleration per axis: (x, y).
max_velocity(value AS COORDINATE) - Cap its speed per axis: (x, y).
one_way(value) - Solid from one side only: “top”, “bottom”, “left” or “right”; off for ONEWAY OFF.
origin(value AS COORDINATE) - The anchor it is placed by, 0-1 across its extent.
parent(value AS NUMBER) - Attach to a sprite.
parent_polygon(value AS NUMBER) - Attach to a bound polygon.
pattern(value AS STRING) - Run a pattern.
pattern_params(value) - Values for the pattern’s @parameters, by name.
remove_behavior(value) - Remove a behavior, or a list of them. Removed before behavior= is added.
reset(on = TRUE) - Clear velocity, acceleration, pose, behaviors and pattern.
rigid(on = TRUE) - Orbit and turn with the parent, not just follow it.
rotate(value AS NUMBER) - Turn it to this many degrees (a pose).
rotate_origin(value AS COORDINATE) - The point it turns about, 0-1 across its extent.
scale(value) - Scale it: (sx, sy) (1 is actual size).
scale_to(value AS COORDINATE) - Scale it to (width, height) pixels.
shader(value AS STRING) - Run a shader over it.
shader_params(value) - Values for the shader’s @parameters, by name: a number for a USE NUMBER, three or four numbers from 0 to 1 for a USE COLOR, a picture’s name for a USE IMAGE. A name the shader doesn’t have is an error.
solid(value) - Give it a collider: on (a circle), or “circle”, “box” or “poly” (its real outline).
sprites(value AS ARRAY) - Tags it collides with, as SOLID SPRITES(...); [] clears them.
sync(on = TRUE) - Multiplayer: broadcast it to every player when on, or stop when off.
sync_room(value AS STRING) - Multiplayer: broadcast it only within this room.
tag(value AS STRING) - A name for the kind of thing it is (“wall”, “coin”), shared by as many sprites as you like: another sprite collides with it by listing this tag in its sprites, and collision handlers, spritetag, spritecollision and spritetouching give or match it.
texture(value AS STRING) - An image to texture the shape with.
uv(value AS ARRAY) - A shape whose points are per-vertex texture coordinates (0-1).
velocity(value AS COORDINATE) - Set its velocity: (vx, vy).
visible(on = TRUE) - Show it, or hide it when given off.
z_order(value AS NUMBER) - Draw order within the layer.

Example

SCREEN 320, 240
ship = MUTATION((0, 0), (20, 10), (0, 20))
SET POLYGON 0 !! bind(ship) color(15) fill(9) location((100, 100))
SET POLYGON 0 !! velocity((2, 0)) solid("poly")
YIELD
PRINT LEN(ship)

Notes

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

See also: BEHAVIOR, param, PATTERN

SET SCROLL

Scroll the current layer to an offset, preserving fractional pixels for layer content and sprites.

SET SCROLL x [, y]
set_scroll(x [, y])

Also documents: angle

Parameters

x - Horizontal offset, or the whole offset as (x, y).
y AS NUMBER = NULL - Vertical offset (with a number for x).

After !!

angle(value AS NUMBER) - Turn the layer by this many degrees.

Example

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET SCROLL 8, 4
scroll = getscroll()
SET SCROLL (0, 0) !! angle(15)
SET LAYER 3
PRINT scroll

Notes

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

SETFONT

Print at a size, in a font; with no name, the current font.

SETFONT size [, name]
setfont(size [, name])

Parameters

size AS NUMBER - The size.
name AS STRING = NULL - The font; omitted, the current one.

Example

SCREEN 320, 240
SETFONT 24
PRINT "bigger"
LOADFONT "font.ttf", "story"
SETFONT 12, "story"
PRINT "smaller, in another font"

Notes

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

SHADER

Defines a shader: USE lines for what it takes, then WHEN DRAWING … END WHEN.

USE NUMBER name is a number, with DEFAULT n if it can be left out. USE COLOR name is a color, with DEFAULT RGB(r, g, b) or DEFAULT RGBA(r, g, b, a), and opaque black without one; it is given as three or four numbers from 0 to 1, and with three its alpha is 1. USE IMAGE name is a picture, given by its name, and a shader takes up to four. Its settings have room for 64 numbers, and a color takes four of them. A DEFAULT can’t be negative: give the negative value when the shader is put on, or turn it round in the shader.

SCREEN is where the pixel is, in the game’s pixels from (0, 0) at its top left: the same pixels SCREEN_SIZE counts, whatever the size of the window.

A mistake stops the program where the shader is defined: a function given the wrong number of values, a name used before it is set, a setting assigned to, SAMPLE given something that isn’t a USE IMAGE, more settings than there’s room for, and a name the graphics chip keeps for itself (in, var, type, target) or one that starts with a built-in word (timer, uvs). Putting it on something checks its settings by name and kind, and stops at one it doesn’t have.

SHADER name
    ...
END SHADER

Parameters

name AS STRING - What the shader is called.

Example

SCREEN 320, 240
SHADER "dim"
    USE NUMBER amount DEFAULT 0.5
    WHEN DRAWING
        SET COLOR = RGBA(1, 1, 1, amount)
    END WHEN
END SHADER
CIRCLE (160, 120), 40, 12, 12
SET LAYER 0 !! shader("dim") shader_params({amount: 0.3})

Notes

Opens a block of text. I don’t read it: I hand it over just as you wrote it. It’s shader.

SHOW POLYGON

Show a bound polygon.

SHOW POLYGON id
show_polygon(id)

Parameters

id AS NUMBER - Polygon number.

Example

SCREEN 320, 240
box = MUTATION((0, 0), (30, 0), (30, 30), (0, 30))
SET POLYGON 0 !! bind(box) fill(4) location((50, 50))
HIDE POLYGON 0
SHOW POLYGON 0
PRINT "shown again"

Notes

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

TEXTTOIMAGE

Render text into a new image.

TEXTTOIMAGE text, name [, size, font]
texttoimage(text, name [, size, font])

Parameters

text AS STRING - The text.
name AS STRING - The image’s name.
size AS NUMBER = NULL - Font size.
font AS STRING = NULL - Font name.

Example

SCREEN 320, 240
LOADFONT "font.ttf", "story"
TEXTTOIMAGE "GAME OVER", "banner", 24, "story"
PUTIMAGE (80, 100), "banner"
PRINT imagewidth("banner") > 0

Notes

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

TOSPRITESHEET

Join images into one spritesheet, one frame each, in order.

TOSPRITESHEET name, images
tospritesheet(name, images)

Parameters

name AS STRING - The sheet’s name.
images AS ARRAY - The images, in frame order.

Example

SCREEN 320, 240
NEWIMAGE 8, 8, 4, "f0"
NEWIMAGE 8, 8, 12, "f1"
TOSPRITESHEET "blink", ["f0", "f1"]
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("blink") frame(1)
SHOW SPRITE 0
PRINT imagewidth("blink")

Notes

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

UPDATE MAP

Show what changed in a TILEMAP’s grids: all its layers, or the ones named.

UPDATE MAP name [, map_layers]
update_map(name [, map_layers])

Parameters

name AS STRING - The TILEMAP.
map_layers = NULL - Which of its layers: one, a run of them (a range, or a list of consecutive ones), or a layer’s name. Left out, every layer.

Example

SCREEN 320, 240
LOADIMG "greyscale.png", "tiles"
ground = [[0, 2, 0], [0, 0, 3]]
TILEMAP "level"
    TILESET "tiles"
    TILESIZE 32
    SIZE 3, 2
    TILES 0 !! from(ground) name("ground")
END TILEMAP
CREATE MAP "level" !! layer_to(0)
ground(0, 0) = 5
UPDATE MAP "level"
SET LAYER 3
PRINT maptile(0, 0, 0)

Notes

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

WINDOW

Keep print inside a rectangle of the current layer, or, with reset, the whole layer.

WINDOW [region]
window([region])

Also documents: reset

Parameters

region AS VECTOR = NULL - The rectangle: ((x1, y1), (x2, y2)).

After !!

reset(on = TRUE) - The whole layer again.

Example

SCREEN 320, 240
WINDOW (40, 40) -> (200, 120)
PRINT "This text starts at (40, 40) and wraps at x = 200."
WINDOW !! reset

Notes

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

getscroll

Returns the current scroll offset of a layer as a coordinate. If no layer is specified, returns the scroll offset of the current layer. The returned coordinate can be used directly or decomposed into X and Y components.

getscroll
getscroll(layer = NULL)

Parameters

layer = NULL - Optional layer number. Defaults to the current layer if omitted

Example

SCREEN 320, 240
SET SCROLL 40, 10
PRINT getscroll()
offset = getscroll(0)
PRINT offset.x, offset.y

imageheight

Returns the base height in pixels of a loaded image texture identified by its string handle (the name passed to LOADIMG, NEWIMAGE, TEXTTOIMAGE, BASE64TOIMG, etc.). The result is the texture’s intrinsic dimension, independent of any sprite that references it. Image handles are case-insensitive. Returns 0 if no image with that handle is loaded.

imageheight(name)

Parameters

name - String handle of a loaded image texture

Example

SCREEN 320, 240
LOADIMG "hero.png", "hero"
PRINT imageheight("hero")
PRINT imageheight("nobody")

imagewidth

Returns the base width in pixels of a loaded image texture identified by its string handle (the name passed to LOADIMG, NEWIMAGE, TEXTTOIMAGE, BASE64TOIMG, etc.). The result is the texture’s intrinsic dimension, independent of any sprite that references it. Image handles are case-insensitive. Returns 0 if no image with that handle is loaded.

imagewidth(name)

Parameters

name - String handle of a loaded image texture

Example

SCREEN 320, 240
NEWIMAGE 48, 16, 4, "bar"
PRINT imagewidth("bar")

maptile

Returns the 0-based tile index (the source Tiled tile id minus 1) at the given map coordinates. Defaults to the current screen layer if you omit screenLayer. Returns -1 if no tile exists at the position or the queried layer isn’t a map layer.

maptile(tile_x, tile_y, screen_layer = NULL)

Parameters

tile_x - Tile X coordinate (map space, not pixels)
tile_y - Tile Y coordinate (map space, not pixels)
screen_layer = NULL - Optional: screen layer to query (defaults to the current layer)

Example

SCREEN 320, 240
LOADIMG "greyscale.png", "tiles"
t = [[0, 0, 0, 0], [0, 0, 0, 0], [0, 1, 0, 0]]
CREATE MAP t !! layer_to(0) tileset("tiles") tilesize(32)
SET LAYER 3
PRINT maptile(1, 2, 0)
PRINT maptile(0, 0, 0)

maptilex

Converts a SCREEN pixel X coordinate to tile X coordinate by adding the layer’s scroll offset. This accounts for scrolling so the result maps to the correct tile even when the map has scrolled. Use this for MOUSEX(), TOUCHX(), and other screen-relative coordinates. For world coordinates like SPRITEX() that are already in map space, use MAPWORLDTILEX instead. Uses the current map layer if layerNum is omitted. Returns -1 if the layer is not a map layer. Quick rule: screen input (MOUSEX) → MAPTILEX, world position (SPRITEX) → MAPWORLDTILEX.

maptilex(screen_pixel_x, layer_num = NULL)

Parameters

screen_pixel_x - Screen pixel X coordinate (e.g., MOUSEX)
layer_num = NULL - Optional: Layer number to query (defaults to current layer)

Example

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET SCROLL 16, 0
SET LAYER 3
PRINT maptilex(20, 0)

maptiley

Converts a SCREEN pixel Y coordinate to tile Y coordinate by adding the layer’s scroll offset. This accounts for scrolling so the result maps to the correct tile even when the map has scrolled. Use this for MOUSEY(), TOUCHY(), and other screen-relative coordinates. For world coordinates like SPRITEY() that are already in map space, use MAPWORLDTILEY instead. Uses the current map layer if layerNum is omitted. Returns -1 if the layer is not a map layer. Quick rule: screen input (MOUSEY) → MAPTILEY, world position (SPRITEY) → MAPWORLDTILEY.

maptiley(screen_pixel_y, layer_num = NULL)

Parameters

screen_pixel_y - Screen pixel Y coordinate (e.g., MOUSEY)
layer_num = NULL - Optional: Layer number to query (defaults to current layer)

Example

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET SCROLL 0, 16
SET LAYER 3
PRINT maptiley(20, 0)

mapworldtilex

Converts a WORLD pixel X coordinate to tile X coordinate without adding scroll offset. Use this for SPRITEX() and other world/logical coordinates that are already in map space. For screen-relative coordinates like MOUSEX() that need scroll adjustment, use MAPTILEX instead. Uses the current map layer if layerNum is omitted. Returns -1 if the layer is not a map layer. Quick rule: world position (SPRITEX) → MAPWORLDTILEX, screen input (MOUSEX) → MAPTILEX.

mapworldtilex(world_pixel_x, layer_num = NULL)

Parameters

world_pixel_x - World pixel X coordinate (e.g., SPRITEX)
layer_num = NULL - Optional: Layer number to query (defaults to current layer)

Example

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET SCROLL 16, 0
SET LAYER 3
PRINT mapworldtilex(20, 0), maptilex(20, 0)

mapworldtiley

Converts a WORLD pixel Y coordinate to tile Y coordinate without adding scroll offset. Use this for SPRITEY() and other world/logical coordinates that are already in map space. For screen-relative coordinates like MOUSEY() that need scroll adjustment, use MAPTILEY instead. Uses the current map layer if layerNum is omitted. Returns -1 if the layer is not a map layer. Quick rule: world position (SPRITEY) → MAPWORLDTILEY, screen input (MOUSEY) → MAPTILEY.

mapworldtiley(world_pixel_y, layer_num = NULL)

Parameters

world_pixel_y - World pixel Y coordinate (e.g., SPRITEY)
layer_num = NULL - Optional: Layer number to query (defaults to current layer)

Example

SCREEN 320, 240
CREATE MAP "level.map.json" !! layer_to(0)
SET LAYER 3
PRINT mapworldtiley(40, 0)

mutation

A shape the engine keeps: an array of its points that the engine and the script share. Bound to a polygon and moved, its points are where the engine has them; change one, and the engine’s shape follows.

mutation(points...)

Parameters

points… - Its points, (x, y) each, or a list of them, or another shape.

Example

SCREEN 320, 240
ship = MUTATION((150, 100), (170, 100), (160, 120))
SET POLYGON 0 !! bind(ship) color(14)
ship(2) = (160, 130)
PRINT LEN(ship), ship(2)

point

Sample a pixel from a MEMORYBUFFER name !! from(...) source and return its palette index (0-255), or -1 if the pixel is transparent. It can be written point(x, y) or point(coord).

point(x, y = NULL)

Parameters

x - X coordinate in the source/buffer (same coordinate space as PSET)
y = NULL - Y coordinate in the source/buffer

Examples

SCREEN 320, 240
MEMORYBUFFER "blank", 8, 8
    c = point(2, 2)
END MEMORYBUFFER
PRINT c

SCREEN 320, 240
LOADIMG "hero.png", "hero"
MEMORYBUFFER "ghost" !! from("hero")
    FOR y = 0 ... 15
        FOR x = 0 ... 15
            IF point(x, y) >= 0 THEN PSET (x, y), 7
        NEXT
    NEXT
END MEMORYBUFFER
PUTIMAGE (100, 100), "ghost"
PRINT "a grey copy of the hero"

pointrgb

Sample a pixel from a MEMORYBUFFER name !! from(...) source and return its raw packed colour as 0xAARRGGBB (alpha in the high byte), or 0 if transparent. It can be written pointrgb(x, y) or pointrgb(coord).

pointrgb(x, y = NULL)

Parameters

x - X coordinate in the source/buffer (same coordinate space as PSET)
y = NULL - Y coordinate in the source/buffer

Example

SCREEN 320, 240
LOADIMG "hero.png", "hero"
MEMORYBUFFER "copy" !! from("hero")
    c = pointrgb((0, 0))
    outside = pointrgb(500, 500)
END MEMORYBUFFER
alpha = (c >> 24) AND 255
red = (c >> 16) AND 255
PRINT alpha >= 0, red >= 0, outside

realheight

Returns the height of the real area in pixels — the whole display your game is shown on, measured in your screen’s own units.

realheight

Example

SCREEN 320, 240
PRINT realheight >= screenheight

realstart

Returns the top-left corner of the real area as a coordinate, relative to your screen’s (0, 0). Each component is 0 or negative: the display extends that far above and to the left of your screen.

realstart

Example

SCREEN 320, 240
corner = realstart
PRINT corner.x <= 0, corner.y <= 0

realwidth

Returns the width of the real area in pixels — the whole display your game is shown on, measured in your screen’s own units.

realwidth

Example

SCREEN 320, 240
PRINT realwidth >= screenwidth

screenheight

Returns the current screen height in pixels. Useful for adaptive layouts, especially when using SCREEN NATIVE on mobile devices.

screenheight

Example

SCREEN 320, 240
LOCATE 1, 1 !! origin((0, screenheight - 16))
PRINT "bottom line", screenheight

screenwidth

Returns the current screen width in pixels. Useful for adaptive layouts, especially when using SCREEN NATIVE on mobile devices.

screenwidth

Example

SCREEN 320, 240
CIRCLE (screenwidth / 2, screenheight / 2), 20, 12
PRINT screenwidth

transition

Returns the name of the currently active screen transition effect on a layer, or an empty string if no transition is running. Use this to wait for CLS EFFECT transitions to complete. Each layer can have its own independent transition.

transition
transition(layer_id = NULL)

Parameters

layer_id = NULL - Optional layer number to check (default: current layer)

Examples

SCREEN 320, 240
CLS 0 !! effect("fade") speed(120)
PRINT transition()

SCREEN 320, 240
CLS 0 !! effect("dissolve") speed(240)
FOR i = 1 ... 100
    IF transition(0) = "" THEN BREAK
    YIELD
NEXT
PRINT "the dissolve is over"

transition_str

Returns the name of the transition effect currently running on a layer — "FADE", "MELT", "BLOCK", "DISSOLVE", "WIPE" — or an empty string if none is running.

transition_str
transition_str(layer = NULL)

Parameters

layer = NULL - Optional layer ID. Defaults to the current layer.

Example

SCREEN 320, 240
CLS 4 !! effect("wipex")
PRINT transition_str(0)

typing

Returns 1 if a PRINT RATE typewriter effect is currently in progress, 0 if complete. Use this to wait for typewriter text to finish before continuing or to allow the user to skip the effect.

typing

Example

SCREEN 320, 240
PRINT "Nothing is being typed out"
PRINT typing

Keyboard shortcuts

The Crash Library