Getting started

Tutorial

Let’s create your first own program! If you didn’t create a new program yet, go to the overview of all programs and tap the Plus button in the top-right corner. A new icon will appear at the end of the program list, called “Unnamed Program”. Tap on it!

You will see now an empty text editor. Write the following lines, but replace MY NAME with your own name (keep the quotation marks):

DO
COLOR RND*16
TEXT 31,29,"MY NAME",1
WAIT 0.1
LOOP

Now tap on the Play button and you should see your name flashing in random colors! If you see an error message instead, check if you wrote something wrong. When you have finished looking at your name, tap the Exit button (or the top-left corner).

We should give a name to this program. Tap on the Share/Action button and select “Rename / Settings…” from the menu. Change the name to “My Name” or whatever you like. You can also choose a nicer icon from the snapshots.

Share your work!

LowRes Coder has its own community. You can create a profile page to post your programs or status updates. Follow other programmers to try and discuss their works.

When you have created something and you are happy with it, you should share it! Tap on the Share button and select “Share with Community” to post your program on your profile page. We keep an eye on most of the activity, and if we like something, we will share it in the official LowRes Coder news!

Where to go from here?

You are ready now! Well, maybe you don’t know programming yet, so you should read some more chapters! Also try all the other included programs (especially from the “Simple Examples” folder) and learn from them! You can duplicate them and experiment with the copies.

Basic principles

Variables

Variables are the names used to refer to values stored in the memory of a computer. They are used to hold the results of calculations in a program. The contents of a variable can be changed at any time.
You can choose any variable names in your programs, with the following restrictions: Allowed characters are the letters A to Z, the numbers 0 to 9 and the underscore “_”, but no spaces. They must begin with a letter and cannot match with an existing LowRes Coder command or function name, but they can begin with one (see Reserved keywords chapter).
In LowRes Coder you don’t have to declare variables. They start to exist automatically when they appear the first time in your program.

Numbers

A variable without any special sign in its name can store numbers, like 10, -2 or 3.5. Examples of number variable names:

A, B2, X, Y, MY_SCORE, LIVES

To assign a number to a variable, you write for example:

A=10

Strings

String variables contain text rather than numbers. They are distinguished from number variables by the $ character at the end of their name. The $ is part of the variable name, so the variables A and A$ access different values. Examples of string variables:

A$, B2$, MY_NAME$, TXT$

You assign a text to a string variable like this:

A$="HELLO"

PERSIST

PERSIST x,y,z,...

The PERSIST command declares the given variables as persistent. Their values are automatically stored on program exit, and loaded when PERSIST is called. The variables must be still unused at the moment of calling this command, so it should be placed at the beginning of a program. Persistent variables are useful for highscores or to save the current level. The following example shows different results on every start:

PERSIST NUM,T$
NUM=NUM+1
T$=T$+"A"
PRINT NUM
PRINT T$

Arrays

An array is a group of values of the same type, referenced by a single variable name. The individual values in an array are called elements. Array elements are variables also. They can be used in any BASIC command or function that uses variables.

DIM

DIM [PERSIST] var(x,y,z,...)

DIM defines a table of variables in your program. These tables may have as many dimensions as you want and you define for each dimension the highest element index.

DIM TXT$(10),A(10,5),B(5,5,2)

In order to access an element in the array you simply type the array name followed by the index numbers. These numbers are separated by commas and are enclosed between round brackets. Note that the element numbers of these arrays always start from zero.

DIM ARR(10)
ARR(0)=2
ARR(10)=5
PRINT ARR(10)
PRINT ARR(0)

Include the PERSIST keyword to make the arrays persistent. Their values are automatically stored on program exit, and loaded when DIM PERSIST is called. If the size of an array changes, stored values get cleared.

Arithmetic operations

The following arithmetic operations can be used in a numeric expression:

Operator	Operation	Examples
–	Unary negation	-X
^	Power	X^Y
/ and *	Divide and multiply	X/Y, X*Y
MOD	Modulo (remainder of a devision)	X MOD Y
+ and –	Plus and minus	X+Y, X-Y

They are listed in the order of their priority how they are evaluated. Here is an example:

PRINT 10+2*5-8/4+5^2

This evaluates in the following order: 5^2, 2*5, 8/4 and then sums up the results to 43. If you want to change the order, you can enclose parts in round brackets:

PRINT (10+2)*(5-8/4+5)^2

Relational operations

Relational operators are used to compare two values. The result of the comparison is either TRUE (-1) or FALSE (0).

Operator	Relation tested	Expression
=	Equality	A=B
<>	Inequality	A<>B
<	Less than	A<B
>	Greater than	A>B
<=	Less than or equal to	A<=B
>=	Greater than or equal to	A>=B

LowRes Coder can not only compare numbers, but also strings. They are compared alphabetically (according to the characters’ ASCII values).

Logical operations

The results of the following operations are binary (bit by bit).

Operator	Value	Value	Result
NOT	X		NOT X
	true		false
	false		true
AND	X	Y	X AND Y
	true	true	true
	true	false	false
	false	true	false
	false	false	false
OR	X	Y	X OR Y
	true	true	true
	true	false	true
	false	true	true
	false	false	false
XOR	X	Y	X XOR Y
	true	true	false
	true	false	true
	false	true	true
	false	false	false

These operators can be used for logical expressions…

IF A=0 OR B=1 THEN PRINT "OK"

…but also for bit manipulations:

A=15 OR 256
PRINT A
REM >>271

String operations

You can concatenate strings with the plus operation.

A$="LOW"+"RES"+" CODER"
PRINT A$
REM >>LOWRES CODER

If you add together string and number variables or constants, the numbers get converted to strings automatically.

L=2
A$="LIVES: "+L
PRINT A$
REM >>LIVES: 2

Parameters

The values you enter into a LowRes Coder command are known as parameters, for example:

COLOR 2
TEXT X,Y,"HI"

The parameters in these commands are 2, X, Y and “HI”.

Labels

Labels are a way of marking lines in your programs. They can have any names with the same restrictions as variable names have, and are followed by the “:” (colon) character.

TESTLABEL:
PRINT "HELLO"
GOTO TESTLABEL

Simple commands

PRINT

PRINT [value[;]]

PRINT writes value on the screen, where value can be also a string or any expression. By default the text cursor (invisible) jumps to the next line afterwards and the screen scrolls when the bottom is reached. If you append a semicolon, the cursor stays at the end of the printed text and following text appears in the same line. If the value parameter is omitted, PRINT outputs an empty line.

In graphics based programs you should prefer the TEXT command.

PRINT "HELLO"
PRINT 2+2
PRINT
PRINT "ONE ";
PRINT "LINE"

INPUT

INPUT ["prompt";]var

INPUT lets the user enter a text or number on the keyboard and stores it in the variable var. Optionally it can show a prompt text before (cannot be a variable). The keyboard will be activated automatically. If you want to hide it afterwards, you can call KEYBOARD OFF.

Note: There is no length limit for the input, but currently no line wrapping exists, so the user can write out of the screen.

INPUT "NAME:";N$
INPUT "AGE:";AGE
PRINT "HELLO "+N$+"!"
PRINT "IN ONE YEAR YOU ARE "+(AGE+1)

WAIT

WAIT seconds [TAP]

WAIT pauses the execution of the program for the time set by the seconds parameter. The shortes wait time is 0.04 seconds. If you add the TAP keyword, the waiting will be interrupted by any tap on a gamepad button (including the direction-pad). This is useful if you have a slow loop, but you want immediate reactions to user inputs.

This command has an important side effect: It updates the screen. If you draw something in a loop, you won’t see it until you call WAIT (or the program ends).

FOR X=0 TO 63
  PLOT X,31
  WAIT 0.1
NEXT X

WAIT BUTTON

WAIT BUTTON

Pauses the execution of the program until button A or B gets pressed and released (or it is already pressed and gets released). Use this for example after your game’s title screen or a menu, so that the program enters its next part without any button pressed.

GAMEPAD 1
PRINT "PRESS BUTTON!"
WAIT BUTTON
PRINT "THANKS!"

END

END

Stops the execution of the program. This can be called in any place of your program.

REM

REM comment

If a line starts with REM (remark), it’s completely ignored by the program, so you can write comments into your code.

REM THIS IS A TEST PROGRAM
REM WRITTEN BY TIMO KLOSS
PRINT "HELLO"
REM SHOW MORE TEXT...
PRINT "BYE"

=TRUE

v=TRUE

TRUE is equal to -1. It’s useful for assigning it to a variable.

A=TRUE
IF A THEN PRINT "IT'S TRUE"

=FALSE

v=FALSE

FALSE is equal to 0.

=DATE$

s$=DATE$

DATE$ returns the current date in the format yyyy-mm-dd.

PRINT DATE$

=TIME$

s$=TIME$

TIME$ returns the current time in the format hh:mm:ss.

PRINT TIME$

=TIMER

v=TIMER

TIMER returns the time passed since LowRes Coder was started in seconds. The value is a decimal, so time can be measured with high precision. Note that TIMER stops counting while you pause the program.

Graphics

LowRes Coder runs your programs on a virtual screen with 64×64 pixels (by default) and 16 colors. Check the chapter Screen layers for information about different resolutions and more options. With the following commands you can draw on LowRes Coder’s screen.

COLOR

COLOR [color],[background],[border]

COLOR sets the current drawing color (for most graphical commands), the background color (for CLS) and the border color (for TEXT). Any parameter can be omitted to keep the current value. Possible values are:

0	black	8	yellow
1	white	9	green
2	light gray	10	dark green
3	dark gray	11	cyan
4	red	12	blue
5	dark red	13	dark blue
6	brown	14	magenta
7	orange	15	purple

FOR I=1 TO 15
  COLOR I
  PRINT "COLOR "+I
NEXT I

These default colors can be changed with the PALETTE command.

CLS

CLS [color]

CLS clears and fills the whole screen with color. Check the color table of the COLOR command. If the parameter is omitted, the screen is cleared with the current background color.

FOR I=0 TO 15
  CLS I
  WAIT 0.1
NEXT I

PLOT

PLOT x,y

PLOT draws a pixel at the coordinates x,y.

DO
  COLOR RND*16
  PLOT RND*64,RND*64
  WAIT 0.1
LOOP

=POINT

v=POINT(x,y)

POINT returns the color index at the coordinates x,y.

COLOR 11
PLOT 63,0
PRINT POINT(63,0)
PRINT POINT(63,1)
REM >>11
REM >>0

LINE

LINE x1,y1 TO x2,y2

LINE draws a line from the coordinates x1,y1 to the coordinates x2,y2.

DO
  COLOR RND*16
  LINE RND*64,RND*64 TO RND*64,RND*64
  WAIT 0.1
LOOP

BOX

BOX x1,y1 TO x2,y2

BOX draws an unfilled rectangle with the diagonal corners at the coordinates x1,y1 and x2,y2.

BOX 0,0 TO 63,63

BAR

BAR x1,y1 TO x2,y2

BAR paints a filled rectangle with the diagonal corners at the coordinates x1,y1 and x2,y2.

BAR 2,20 TO 61,43

CIRCLE

CIRCLE x,y,radius [PAINT]

CIRCLE draws a circle with the coordinates x,y as center and the given radius. With the optional PAINT keyword, the circle gets filled.

COLOR 7
CIRCLE 32,32,24 PAINT
COLOR 8
CIRCLE 32,32,20

PAINT

PAINT x,y

PAINT flood fills a closed area, starting at the coordinates x,y.

COLOR 8
BOX 2,20 TO 61,43
LINE 2,20 TO 61,43
COLOR 7
PAINT 60,21
COLOR 9
PAINT 3,42

TEXT

TEXT x,y,text$[,align[,outline]]

TEXT draws the string text$ at the coordinates x,y. Note that text$ can also be a number, it will be converted automatically into a string.

TEXT 0,0,"HELLO"

With the optional parameter align the text can be drawn in different ways:

0	Left aligned (default)
1	Centered
2	Right aligned

TEXT 32,0,"CENTERED TEXT",1

The are different modes to draw an outline with the current border color:

0	No outline (default)
1	Shadow
2	Normal outline
3	Strong outline

=TEXT WIDTH

v=TEXT WIDTH(text$)

TEXT WIDTH returns the width of text$ in pixels as it would be drawn with the TEXT command.

T$="HELLO"
W=TEXT WIDTH(T$)
WHILE X<63
  COLOR 1+RND*15
  TEXT X,0,T$
  X=X+W
WEND

FONT

FONT n

LowRes Coder includes 4 different fonts. FONT sets the current font for TEXT, TEXT WIDTH and PRINT. n must be a value from the following table:

0	6p proportional (default)
1	6p fixed-width (4×6)
2	8p proportional
3	8p fixed-width (8×8)

FOR I=0 TO 3
  FONT I
  PRINT "EXAMPLE " + I
NEXT I

SCROLL

SCROLL x1,y1 TO x2,y2,dx,dy [CLEAR]

SCROLL moves the rectangular screen area between x1,y1 and x2,y2 horizontally by dx and vertically by dy pixels. By default it will “smear” the colors from the borders. If the CLEAR keyword is added, new border areas are cleared with the current background color.

DO
  PLOT RND*63,1+RND*63
  SCROLL 0,0 TO 63,63,-2,1 CLEAR
  WAIT 0.04
LOOP

GET BLOCK

GET BLOCK number,x1,y1 TO x2,y2

Copies the rectangular screen area between x1,y1 and x2,y2 to a block buffer with the given number. Possible numbers range from 0 to 63. Use the PUT BLOCK command to draw it on the screen.

PUT BLOCK

PUT BLOCK number,x,y[,mask]

Draws a block buffer copied by the GET BLOCK command on the screen at the coordinates x,y. The optional mask parameter can have two values:

0	Block is drawn opaque (default)
1	Block is drawn with color 0 transparent

COLOR 7
CIRCLE 16,16,16 PAINT
COLOR 6
CIRCLE 16,16,16
GET BLOCK 0,0,0 TO 32,32
DO
  PUT BLOCK 0,RND*32,RND*32,1
  WAIT 0.1
LOOP

PALETTE

PALETTE index,value

Changes the value of color index in the palette. There are 64 possible color values, mixed with each 4 shades of red, green and blue. You can calculate value like this:

VALUE = RED * 16 + GREEN * 4 + BLUE

(RED, GREEN and BLUE are values from 0 to 3). When you call this command all pixels on the screen with that index in the palette will change their color.

PALETTE CLEAR

PALETTE CLEAR

Resets the palette to the default colors (see COLOR command).

=PALETTE

v=PALETTE(index)

This function returns the current value of the color index from the palette. You can get the RED, GREEN and BLUE values like this:

RED = INT(VALUE / 16)
GREEN = INT(VALUE / 4) MOD 4
BLUE = VALUE MOD 4

Control structures

LowRes Coder offers several commands to control the execution of your programs. You can repeat sequences of code, execute different code depending on decisions and jump between program parts.

IF … THEN … ELSE … END IF

IF condition THEN command [ELSE command]

IF condition THEN
commands
[ELSE
commands]
END IF

The IF command allows you to make decisions in a program. Depending on the result different commands are executed. The condition can be any list of tests including AND and OR. There is the single line version, which allows only one command after THEN and optionally one command after ELSE:

FOR I=1 TO 4
  IF I<3 THEN PRINT "SMALL" ELSE PRINT "BIG"
  IF I=4 THEN PRINT "END"
NEXT I

If you need to execute more than one command, an IF … END IF block can be used. ELSE blocks are optional.

A=1
IF A=0 THEN
  PRINT "A IS ZERO"
  PRINT "NO?"
ELSE IF A=1 THEN
  PRINT "A IS ONE"
  PRINT "NO?"
ELSE
  PRINT "A IS WHAT?"
END IF

GOTO

GOTO label

GOTO makes the program continue in the line marked with label. While it’s possible to jump out of a loop (WHILE/WEND, DO/LOOP,…) or out of an IF block, it’s an error to jump from outside to inside.

PRINT "START"
GOTO GAMELEVEL
GAMEOVER:
PRINT "GAME OVER"
END
GAMELEVEL:
PRINT "PLAYING"
GOTO GAMEOVER

GOSUB

GOSUB label

GOSUB is similar to GOTO, but it remembers the current execution position. When RETURN is called, the program jumps back to the line where GOSUB was called.

FOR I=1 TO 5
  GOSUB SHOWNUMBER
NEXT I
END
SHOWNUMBER:
PRINT "NUMBER "+I
RETURN

RETURN

RETURN [label]

The execution of the program returns to the last GOSUB call.

The label parameter may be included in the RETURN command to return to a specific label from the subroutine. This label must be accessible from the position of the previously called GOSUB command.

FOR I=1 TO 5
  GOSUB SHOWNUMBER
NEXT I
END
SHOWNUMBER:
IF I=4 THEN RETURN GAMEOVER
PRINT "NUMBER "+I
RETURN
GAMEOVER:
PRINT "GAME OVER"

FOR … NEXT

FOR index=first TO last [STEP increment]
commands
NEXT [index]

A FOR/NEXT command repeats a list of commands a specific number of times. index is a counter variable that will be incremented after each loop. At the start of the loop, this counter will be set to first. Now all commands until NEXT are performed. increment will be added to the counter every time NEXT is reached. If STEP is omitted, the increment will be 1. The loop repeats as long as the counter is not greater than last.

FOR I=1 TO 10 STEP 2
  PRINT I
NEXT I

Note that increment can be negative to count backwards. In this case the loop will be finished when the counter is less than last.

FOR I=5 TO 1 STEP -1
  PRINT I
NEXT I

As all other loops, FOR/NEXT loops can be placed inside of others.

FOR X=0 TO 5
  FOR Y=0 TO 5
    CLS
    PLOT X,Y
    WAIT 0.1
  NEXT Y
NEXT X

REPEAT … UNTIL

REPEAT
commands
UNTIL condition

A REPEAT/UNTIL command repeats a list of commands until condition is true.

REPEAT
  A=INT(RND*10)
  PRINT A
UNTIL A=0

WHILE … WEND

WHILE condition
commands
WEND

A WHILE/WEND command repeats a list of commands as long as condition is true.

WHILE A<10
  PRINT A
  A=A+1
WEND

DO … LOOP

DO
commands
LOOP

A DO/LOOP command repeats a list of commands forever. You can still exit from the loop by calling EXIT.

DO
  COLOR RND*16
  PRINT "FOREVER"
LOOP

EXIT

EXIT

EXIT makes the program jump out of the current loop (WHILE/WEND, DO/LOOP,…).

DO
  C=INT(RND*16)
  COLOR C
  PRINT "LOOPING"
  IF C=15 THEN EXIT
LOOP
PRINT "DONE"

ON END GOTO

ON END GOTO label

ON END

This command adds special handling for the moment the user taps the exit button. Instead of just quitting the program, it will jump to label. The program has 2 seconds then to do something before calling END. You can use this for example to transfer data with WRITE.

ON END GOTO FIN
DO
  PRINT "EXIT PROGRAM!"
  WAIT 1
LOOP
FIN:
PRINT "BYE!"
WAIT 2

ON END (without GOTO) clears the label and activates the normal behavior again.

ON PAUSE GOTO

ON PAUSE GOTO label

ON PAUSE

This command adds special handling for the moment the user taps the pause button. Instead of pausing the program, it will jump to label.

GAMEPAD 1
GAME:
ON PAUSE GOTO GAMEMENU
CLS
DO
  COLOR RND*16
  TEXT 0,20,"PLAYING..."
  TEXT 0,26,"PRESS PAUSE"
  WAIT 0.1
LOOP
GAMEMENU:
ON PAUSE GOTO GAME
CLS
DO
  COLOR RND*16
  TEXT 0,20,"PAUSED"
  TEXT 0,26,"PRESS PAUSE"
  TEXT 0,32,"TO CONTINUE"
  WAIT 0.1
LOOP

ON PAUSE (without GOTO) clears the label and activates the normal behavior again.

User input

LowRes Coder can show a virtual game pad and a keyboard. Use these commands to handle the user input.

GAMEPAD

GAMEPAD players

GAMEPAD shows game controls (a direction pad and two buttons) for the given number of players. Currently only one player is supported. If players is 0, the controls will be hidden and the complete screen works like button A.

=UP

v=UP(player)

Returns TRUE if up is currently pressed on the direction pad of the given player. player starts with 0 for the first one.

=DOWN

v=DOWN(player)

Returns TRUE if down is currently pressed on the direction pad of the given player. player starts with 0 for the first one.

=LEFT

v=LEFT(player)

Returns TRUE if left is currently pressed on the direction pad of the given player. player starts with 0 for the first one.

=RIGHT

v=RIGHT(player)

Returns TRUE if right is currently pressed on the direction pad of the given player. player starts with 0 for the first one.

=BUTTON

v=BUTTON [TAP](player[,button])

Returns TRUE if the A or B button of the given player is currently pressed. player starts with 0 for the first one. If button is omitted or 0, any button (A and B) is checked. 1 checks only the A button, 2 checks only the B button.

With the optional TAP keyword the function returns TRUE only once for one tap on the button, and not as long as the button is pressed.

KEYBOARD ON/OFF

KEYBOARD ON

KEYBOARD OFF

Activates or deactivates the keyboard.

=INKEY$

s$=INKEY$

INKEY$ returns the last pressed key as a string. If no key was pressed, it returns an empty string (“”). After calling this function its value is cleared, so it returns each pressed key only once.

KEYBOARD ON
DO
  I$=INKEY$
  IF I$<>"" THEN PRINT "PRESSED "+I$
LOOP

Sound

LowRes Coder has three independent sound generators, called voices. Each of them has a queue which can store and reproduce sound sequences without blocking the execution of the program.

SOUND

SOUND voice,pitch,duration[,instr]

Plays a sound through the given voice (a value from 0 to 2). pitch sets the tone to play:

Note	Pitch (with different octaves)
C	1	13	25	37	49	61	73	85
C#	2	14	26	38	50	62	74	86
D	3	15	27	39	51	63	75	87
D#	4	16	28	40	52	64	76	88
E	5	17	29	41	53	65	77	89
F	6	18	30	42	54	66	78	90
F#	7	19	31	43	55	67	79	91
G	8	20	32	44	56	68	80	92
G#	9	21	33	45	57	69	81	93
A	10	22	34	46	58	70	82	94
A#	11	23	35	47	59	71	83	95
B	12	24	36	48	60	72	84	96

A sound with pitch 0 is silent and can be used as a pause.

The duration of the note is set in 1/24 seconds. Each voice has an own queue, so sounds are played one after another without blocking the program. A maximum of 1023 sounds can be queued in each voice. If duration is 0, the queue is cleared and the sound will start immediately and won’t stop until the voice starts another sound or SOUND OFF is called.

You can set an instrument with the instr parameter (see DEF SOUND), otherwise the last instrument of the voice will be kept. By default the instruments are already set up with different waveforms.

SOUND 0,49,12,1
SOUND 0,53,12
SOUND 0,56,12
SOUND 0,61,24,0

SOUND OFF

SOUND OFF [voice]

Stops the sound of voice and clears its queue. If the voice parameter is omitted, all voices will be stopped.

SOUND WAIT

SOUND WAIT

Causes the sound queues to be paused until SOUND RESUME is called. This can be used to synchronize the sounds coming from the three voices.

SOUND RESUME

SOUND RESUME

Lets the sound queues play again after a call to SOUND WAIT.

SOUND WAIT
SOUND 0,49,12
SOUND 0,53,12
SOUND 0,56,12
SOUND 0,61,24
SOUND 1,41,36
SOUND 1,44,24
PRINT "TAP SCREEN"
WAIT BUTTON
SOUND RESUME

=SOUND LEN

v=SOUND LEN[(voice)]

This function returns the number of notes in the queue of the given voice. The currently playing sound is already removed from the queue. If the parameter is omitted, all voices are checked and the highest value is returned.

DO
  IF SOUND LEN=0 THEN
    SOUND 0,49,12
    SOUND 0,53,12
    SOUND 0,56,12
    SOUND 0,61,24
  END IF
  CLS
  TEXT 0,0,SOUND LEN
  WAIT 0.1
LOOP

DEF SOUND

DEF SOUND instr,wave[,pulse[,time]]

Defines one of up to 64 different instruments which can be used with SOUND, so instr can be a value from 0 to 63.

The base of an instrument is the waveform, which is set with the wave parameter:

0	sawtooth wave
1	triangle wave
2	pulse wave
3	noise

If the waveform is “pulse wave” (2), you can set a pulse width between 0.0 and 1.0 with the pulse parameter. A value of 0.5 results in a square wave. For other waveforms this parameter is ignored.

The time parameter defines the maximum duration of the sound in seconds. If a SOUND command sets a longer duration, the voice will play the maximum duration and then it will be silent until the next sound in the queue. Omit the parameter to play sounds always in full duration.

DEF SOUND LINE

DEF SOUND LINE instr,time,pitch,pulse

Sets additional values for the instrument number instr. It makes sounds change over the given time (in seconds). Call this command (if needed) always after the DEF SOUND of the same instrument, otherwise the values will be reset.

The sound will start with pitch added to the note’s original value (or subtracted if pitch is negative). The pulse value is added to pulse width of the original sound (only if the waveform is “pulse”).

Pitch and pulse width will return in the given time to its original values.

DEF SOUND 0,2,0,0.2
DEF SOUND LINE 0,0.1,12,0
SOUND 0,30,12,0
SOUND 0,42,12
SOUND 0,54,12

Sprites

Sprites are graphical objects with 8×8 pixels and 3 colors (plus a transparent background color). They are shown on an own layer and don’t affect the normal graphic layers used for drawing. They can be moved and animated very easily, that’s why they are perfect for game objects. Sprites are not designed with the normal graphic commands, but they are defined by bitmaps. LowRes Coder can show up to 64 sprites at once.

DEF SPRITE

DEF SPRITE image,data[,c1,c2,c3]

Defines a sprite image and stores it as number image. Possible values range from 0 to 63. data is the name of an array (without index numbers) which has 16 elements and contains the bitmap data. The optional parameters c1, c2 and c3 are used to set the default color palette for the given sprite. If these parameters are omitted, the colors are: 1, 2, 3. Usually the data array and colors are loaded from DATA lines, like this:

DIM ARR(15)
FOR I=0 TO 15
  READ ARR(I)
NEXT I
READ C0,C1,C2,C3
DEF SPRITE 0,ARR,C1,C2,C3
SPRITE 0,10,10,0
SPRITE 1,20,20,0
SPRITE 2,30,30,0
DATA 5,80,21,84,105,105,105,105
DATA 85,85,127,253,31,244,5,80
DATA 0,8,11,6

Don’t be scared of the numbers, you can use the included program Easy Sprite Designer to draw your images and transfer them to source code.

Here is a little explanation of the format: The numbers in the data array are bytes. A sprite has 8×8 pixels and each pixel has two bits to define the color, that makes two bytes per line. Lines are stored from top to bottom, so in the end we have 16 bytes. The following 4 values are simply the used colors. The first one is read but not used, as the sprite background is always transparent.

SPRITE

SPRITE number,[x],[y],[image]

Shows a sprite or changes the position or the image. number is the identification number of the sprite and can have a value from 0 to 63. The sprite will be shown at the screen coordinates x,y with the given image. See the example of DEF SPRITE.

If a sprite is already visible, it is possible to change only specific parameters and keeping others. Just omit the parameters you don’t want to change, but don’t remove the commas!

REM SHOW SPRITE
SPRITE 0,10,10,0
REM CHANGE Y POSITION
SPRITE 0,,15,
REM CHANGE IMAGE
SPRITE 0,,,1

SPRITE OFF

SPRITE OFF [number]

Removes the sprite with the given number from the screen. If the parameter is omitted, all sprites are removed.

SPRITE PALETTE

SPRITE PALETTE number,[c1],[c2],[c3]

By default a sprite will appear in its standard colors set by DEF SPRITE. With SPRITE PALETTE you can change the colors for each visible sprite separately. See the available color numbers of the COLOR command. Single color parameters can be omitted to keep the current values of the sprite. If a color is set to -1, the sprite’s default color is used.

REM ORANGE, WHITE, RED
SPRITE PALETTE 0,7,1,4
REM CHANGE ONLY COLOR 3
SPRITE PALETTE 0,,,5

SPRITE ZOOM

SPRITE ZOOM number,x,y

Changes the zoom of the sprite with the given number. x is the horizontal zoom, and y the vertical. Possible values are:

0	Original size
1	2x zoom
2	4x zoom

=SPRITE X/Y/I

x=SPRITE X(number)

y=SPRITE Y(number)

i=SPRITE I(number)

These functions return current values of the given sprite number. X and Y are the coordinates, I is the image. If the sprite is currently not visible, SPRITE I will return -1.

=SPRITE HIT

v=SPRITE HIT(number[,other [TO last]])

Returns TRUE if sprite number collides with another sprite (which means that pixels overlap). If no more parameters are given, it will check with all other visible sprites. If the other parameter is added, it will check only with that sprite number. If all parameters are given, it will check with all sprites between number other and last.

REM COLL. SPRITE 0 WITH ANY
IF SPRITE HIT(0) THEN PRINT "HIT"
REM COLL. BETWEEN SPRITES 1 AND 10
IF SPRITE HIT(1,10) THEN PRINT "HIT"
REM COLL. 1 WITH ANY FROM 5 TO 10
IF SPRITE HIT(1,5 TO 10) THEN PRINT "HIT"

=HIT

v=HIT

Returns the number of the sprite which collided with the sprite of the last call of SPRITE HIT.

IF SPRITE HIT(0) THEN
  PRINT "0 COLLIDED WITH "+HIT
END IF

Screen layers

LowRes Coder can show up to 4 screen layers at once! Each layer can have its own size, and they can even be bigger than the actual screen and you can scroll their content easily. There is a mode to show a layer with a transparent background color, so you can create impressive parallax scrolling effects. Also each layer can have its own color palette, so for example you can use different colors for the background and for the foreground.

By default LowRes Coder creates two layers with a resolution of 64×64 pixels and a shared color palette. Layer 0 is in the background and usually the main layer. Layer 1 is in the foreground and is transparent in all pixels with color 0.

DISPLAY

DISPLAY mode [SHARED]

DISPLAY sets the screen resolution. When you call it all currently opened layers get closed (including the two default layers), so you will have to open any needed layer with LAYER OPEN. Available options for mode are:

Mode	Screen Resolution
0	8×8
1	16×16
2	32×32
3	64×64
4	128×128

By adding the SHARED keyword, all layers will share the same color palette. Otherwise each layer will have its own.

LAYER OPEN

LAYER OPEN number,width,height,mode

Creates a layer which will be used as the destination of all subsequent graphical commands. number is used to identify this layer, possible values range from 0-3. Layers with higher numbers cover lower ones. If this layer is already open, it will be replaced with the new one. width and height hold the size of your layer in pixels. The maximum size is 512×512, so it can be larger than the actual screen resolution. With the LAYER OFFSET command you can manipulate the currently visible area. mode can be one of these options:

0	Standard (opaque)
1	Transparent for pixels with color 0

DISPLAY 4
LAYER OPEN 0,128,128,0
TEXT 64,64,"THIS IS HI-RES!",1

LAYER CLOSE

LAYER CLOSE number

Deletes the layer with the given number. If it was the current layer, following graphical commands won’t have any effect until you open or set another current layer.

LAYER

LAYER number

Use this command to select the current layer. This layer will be used as the destination of all subsequent graphical commands. Each layer will even hold its own current colors and font.

By default LowRes Coder opens two layers: Layer 0 is in the background and usually the main layer. Layer 1 is in the foreground and is transparent in all pixels with color 0.

LAYER 1
LINE 0,0 TO 63,63
LAYER 0
DO
  COLOR RND*16
  BAR 0,26 TO 63,36
  WAIT 0.1
LOOP

LAYER DISPLAY

LAYER DISPLAY number,[x],[y],[w],[h]

LAYER DISPLAY sets where a layer should be shown on the screen. x and y hold the position of the top left corner of the layer. You can even move it around like a sprite! w (width) and h (height) are not related to the actual size of the layer, but they set the visible size. If the layer is larger than its visible size, you can manipulate the current visible section with LAYER OFFSET. Parameters can be omitted to keep the layer’s current values.

LINE 0,0 TO 63,63
LAYER OPEN 1,60,7,0
LAYER DISPLAY 1,2,0
CLS 14
TEXT 1,1,"I AM A LAYER"
DO
  FOR Y=-7 TO 64
    LAYER DISPLAY 1,,Y
    WAIT 0.04
  NEXT Y
LOOP

LAYER OFFSET

LAYER OFFSET number,[x],[y]

LAYER OFFSET sets the visible section of a layer. x and y measure the offset from the top left
corner of the layer to the starting point for your section. By creating a layer larger than the screen resolution and moving its offset, you can produce scrolling in a very simple way. Parameters can be omitted to keep the layer’s current values.

LAYER OPEN 0,256,64,0
FOR I=0 TO 20
  COLOR RND*16
  BAR RND*256,RND*64 TO RND*256,RND*64
NEXT I
DO
  FOR X=0 TO 191
    LAYER OFFSET 0,X,0
    WAIT 0.04
  NEXT X
LOOP

LAYER OFF

LAYER OFF number

Hides the given layer without losing its contents. It’s still possible to draw on it and it can be shown again with LAYER ON.

LAYER ON

LAYER ON number

Shows a layer which was previously hidden by the LAYER OFF command.

SPRITE LAYER

SPRITE LAYER layer[,sprite [TO last]]

By default all sprites are shown on layer 0. This means they use the colors of that layer and they will be covered by all layers with higher numbers. However, positions of sprites are always independent from the layer position and offset. With the command SPRITE LAYER you can set the layer for each sprite.

REM ASSIGN ALL SPRITES TO LAYER 1
SPRITE LAYER 1
REM ASSIGN ONLY SPRITE 7 TO LAYER 1
SPRITE LAYER 1,7
REM ASSIGN SPRITES 0 TO 7 TO LAYER 1
SPRITE LAYER 1,0 TO 7

=LAYER HIT

v=LAYER HIT(layer,sprite)

Returns TRUE if layer collides with sprite. A collision happens when a non-transparent pixel of the sprite hits a layer pixel with a color different from 0.

String functions

The following functions allow you to modify and analyze strings.

=LEFT$=

s$=LEFT$(string$,number)

LEFT$(string$,number)=s$

The LEFT$ function returns a new string with the first number characters of string$.

PRINT LEFT$("LOWRES CODER",3)
REM >>LOW

The command variant of LEFT$ overwrites the first characters in the variable string$ with the first number characters of s$.

A$="FOORES CODER"
LEFT$(A$,3)="LOWER"
PRINT A$
REM >>LOWRES CODER

=RIGHT$=

s$=RIGHT$(string$,number)

RIGHT$(string$,number)=s$

The RIGHT$ function returns a new string with the last number characters of string$.

PRINT RIGHT$("LOWRES CODER",5)
REM >>CODER

The command variant of RIGHT$ overwrites the last characters in the variable string$ with the last number characters of s$.

A$="LOWRES COFOO"
RIGHT$(A$,3)="UNDER"
PRINT A$
REM >>LOWRES CODER

=MID$=

s$=MID$(string$,position,number)

MID$(string$,position,number)=s$

The MID$ function returns a new string with number characters of string$, starting at character position. The first character has the position 1.

PRINT MID$("LOWRES CODER",4,3)
REM >>RES

The command variant of MID$ overwrites the given text range in the variable string$ with the first number characters of s$.

A$="LOWFOO CODER"
MID$(A$,4,3)="RESTAURANT"
PRINT A$
REM >>LOWRES CODER

=INSTR

v=INSTR(string$,search$[,position])

INSTR searches the first occurrence of search$ inside of string$ and returns its start position. If it’s not found, the function returns 0.

PRINT INSTR("LOWRES CODER","RES")
REM >>4

Usually the function starts searching at the beginning of the string. Optionally it can start searching at position.

PRINT INSTR("LOWRES CODER","E",6)
REM >>11

=CHR$

s$=CHR$(ascii)

CHR$ returns a string containing one character with ASCII code ascii. Note that LowRes Coder’s font has only a limited range of characters (english capital letters, numbers and some symbols).

FOR I=32 TO 90
  PRINT CHR$(I)
NEXT I

=ASC

v=ASC(string$)

ASC supplies you with the ASCII code of the first character of string$.

PRINT ASC("L")
REM >>76

=LEN

v=LEN(string$)

LEN returns the number of characters in string$.

PRINT LEN("LOWRES CODER")
REM >>12

=VAL

v=VAL(string$)

VAL converts a number written in string$ into a numeric value.

X=VAL("123.5")
X=X+1
PRINT X
REM >>124.5

=STR$

s$=STR$(number)

STR$ converts a number value into a string. Usually this function is not neccessary, because numbers are converted automatically to strings where needed.

PRINT STR$(255)
REM >>255

=HEX$

s$=HEX$(number)

HEX$ converts a number value into a hexadecimal string.

PRINT HEX$(255)
REM >>FF

Maths functions

LowRes Coder has all maths functions of the classic BASIC programming language, and some more.

Trigonometric functions

=PI

v=PI

PI is the ratio of the circumference of a circle to its diameter: 3.1415926535…

=SIN

v=SIN(x)

The sine of x, where x is in radians.

=COS

v=COS(x)

The cosine of x, where x is in radians.

=TAN

v=TAN(x)

The tangent of x, where x is in radians.

=ATN

v=ATN(x)

The arctangent of x in radians, i.e. the angle whose tangent is x. The range of the function is -(PI/2) < ATN(X) < (PI/2).

Standard mathematical functions

=ABS

v=ABS(x)

The absolute value of x.

=SGN

v=SGN(x)

The sign of x: -1 if x < 0, 0 if x = 0 and +1 if x > 0.

=INT

v=INT(x)

The largest integer not greater than x; e.g. INT(1.3) = 1 and INT(-1.3) = -2.

=EXP

v=EXP(x)

The exponential of x, i.e. the value of the base of natural logarithms (e = 2,71828…) raised to the power x.

=LOG

v=LOG(x)

The natural logarithm of x; x must be greater than zero.

=SQR

v=SQR(x)

The nonnegative square root of x; x must be nonnegative.

Manipulating numbers

=MIN

v=MIN(x,y)

The MIN function returns the smallest value of two expressions.

=MAX

v=MAX(x,y)

The MAX function returns the largest value of two expressions.

SWAP

SWAP x,y

Swaps the data between any two variables of the same type (string or number).

A=10
B=40
SWAP A,B
PRINT A
PRINT B

Note: If you want to swap values from arrays randomly, don’t use RND for indices in the line of SWAP, but store the random values in variables before.

Creating random sequences

=RND

v=RND

The next number in a sequence of random numbers uniformly distributed in the range 0 <= RND < 1. A typical use for integer numbers looks like this:

V=INT(RND*16)

This will return an integer number from 0 to 15 (INT rounds down and RND is always less than 1.0).

RANDOMIZE

RANDOMIZE seed

In practice, the numbers produced by the RND function are not really random. They’re computed internally using a complex mathematical formula. The starting point for this calculation is taken from a number known as the seed. This seed is set to 0 whenever you run a program, so the sequence of numbers generated by RND will be exactly the same every time!

With the RANDOMIZE command you can set your own seed. Each seed generates its own individual sequence of numbers. In order to generate true random numbers you should use the TIMER function for seed. Calling RANDOMIZE TIMER once at the beginning of your program will give different results depending on the time the program starts.

RANDOMIZE TIMER
FOR I=1 TO 8
  PRINT RND
NEXT I

Data and transfer

LowRes Coder cannot load data from files, everything a program needs must be included in its source code. With the following commands you can write big lists of data and assign them easily to variables and arrays.

This system also allows you to transfer data between a program and the source code editor. In addition to the “Copy” and “Paste” actions in the text edit menu, there is “Copy to Transfer” and “Paste from Transfer”. By selecting lines of DATA and copying them to the transfer memory, a program can read their values. And the other way around a program can write values to the transfer memory, which can be pasted as DATA commands into your source code.

DATA

DATA list

Stores numeric and string constants (values, but no variables or expressions) that are accessed by the READ command. DATA commands are not executed and may be placed anywhere in the program. list can contain any number of constants, separated by commas.

READ commands access DATA in order, from the top of a program until the bottom. All constants of all DATA commands are read as one continuous list of items.

DATA 10,20,30,40,50

…is exactly the same as:

DATA 10,20,30
DATA 40,50

READ

READ list

Reads values from DATA commands and assigns them to the variables in list. The program has an internal pointer to the current DATA value. With each value read, the pointer will move to the next DATA value.

FOR I=1 TO 3
  READ A,B$
  PRINT A+" "+B$
NEXT I 
DATA 10,"A",20
DATA "B",30,"C"

RESTORE

RESTORE [label]

RESTORE TRANSFER

Changes the internal read pointer to another position. This allows to reread data or to select specific data. If the label parameter is omitted, READ will start again from the top of the program. Otherwise the pointer will be set to the jump label.

RESTORE SECOND
READ A$
PRINT A$
FIRST:
DATA "ONE","TWO"
DATA "THREE"
SECOND:
DATA "FOUR","FIVE"
DATA "SIX"

RESTORE TRANSFER has a special meaning: It sets the read pointer to the beginning of the transfer memory. This is the text you can copy from your source code with the “Copy to Transfer” action in the edit menu.

WRITE

WRITE list

Writes values to the transfer memory, which can be pasted into your source code. list can be any number of values or expressions, separated by commas. Each call to WRITE will add one DATA command with all its values to the transfer memory (can be changed with WRITE WIDTH).

FOR A=1 TO 5
  WRITE A,"HI",A*5
NEXT A

After running this example program, the transfer memory will contain 5 DATA commands each with three constants.

WRITE DIM

WRITE DIM array[,columns]

Writes all elements of an array to the transfer memory. array is the name of a variable (without index numbers). This command adds several DATA commands to the transfer memory, each with a maximum number of columns values. columns can be a number from 0 to 16. If the parameter is omitted or 0, the default value of 8 is used.

DIM ARR(3,7)
FOR I=0 TO 3
  FOR J=0 TO 7
    ARR(I,J)=I*100+J
  NEXT J
NEXT I
WRITE DIM ARR,4

After running this example program, the transfer memory will contain 8 DATA commands each with 4 constants.

WRITE CLEAR

WRITE CLEAR

Clears the transfer memory.

WRITE WIDTH

WRITE WIDTH columns

Changes the number of values per DATA line for the WRITE command (not WRITE DIM) to columns. The maximum value is 16. If columns is 0 (default), each WRITE command creates one DATA command.

WRITE WIDTH 6
FOR I=1 TO 30
  WRITE I
NEXT I

After running this example program, the transfer memory will contain 5 DATA commands each with 6 constants.

Obsolete Commands

These commands are still available for compatibility with older programs, but they should be avoided in new programs. Use the recommended alternatives instead.

GET

GET x1,y1 TO x2,y2

Copies the rectangular screen area between x1,y1 and x2,y2 to a buffer. Use the PUT command to draw it on the screen.

This command is obsolete. Use GET BLOCK and PUT BLOCK instead.

PUT

PUT x,y[,sx,sy,sw,sh[,transparency]]

PUT x,y[,transparency]

Draws the screen area copied by the GET command on the screen at the coordinates x,y. By default the complete copied area will be drawn. With the additional parameters you can draw a smaller part of the source image. With sx and sy you specify the top left corner of the source image, sw is the width and sh the height. If transparency is given and different from -1, the image is drawn with transparency as transparent color.

This command is obsolete. Use GET BLOCK and PUT BLOCK instead.

=SOUND END

v=SOUND END[(voice)]

This function returns TRUE, if the queue of the given voice is empty. A queue is already empty when its last sound is still playing. If the parameter is omitted, all voices are checked.

This function is obsolete. Use SOUND LEN instead.

Reserved keywords

This is a list of all reserved keywords. They cannot be used as variable or label names.

* Keywords with an asterisk have no function yet, but are reserved for future versions of LowRes Coder.

ABS,
AND,
ASC,
ATN,
BANK*,
BAR,
BLOCK,
BOX,
BUTTON,
CALL*,
CHR$,
CIRCLE,
CLEAR,
CLOSE,
CLS,
COLOR,
COS,
DATA,
DATE$,
DEF,
DIM,
DISPLAY,
DO,
DOWN,
ELSE,
END,
EXIT,
EXP,
FALSE,
FONT,
FOR,
GAMEPAD,
GET,
GOSUB,
GOTO,
HEIGHT*,
HEX$,
HIT,
IF,
INKEY$,
INPUT,
INSTR,
INT,
KEYBOARD,
LAYER,
LEFT,
LEFT$,
LEN,
LET,
LINE,
LOG,
LOOP,
MAX,
MID$,
MIN,
MOD,
NEXT,
NOT,
OFF,
OFFSET,
ON,
OPEN,
OR,
PAINT,
PALETTE,
PAUSE,
PEEK*,
PERSIST,
PI,
PLOT,
POINT,
POKE*,
PRINT,
PUT,
RANDOMIZE,
READ,
REM,
REPEAT,
RESTORE,
RESUME,
RETURN,
RIGHT,
RIGHT$,
RND,
SCROLL,
SGN,
SHARED,
SIN,
SOUND,
SPRITE,
SQR,
STEP,
STR$,
SUB*,
SWAP,
TAN,
TAP,
TEMPO*,
TEXT,
THEN,
TILE*,
TIME$,
TIMER,
TO,
TRACE*,
TRUE,
UBOUND*,
UNTIL,
UP,
VAL,
WAIT,
WEND,
WHILE,
WIDTH,
WRITE,
XOR,
ZOOM