Introduction

What is Easy LowRes?

Easy LowRes is not a new platform, it's a new way to use LowRes NX. The idea was to remove all the complicated stuff from it and keep it at an easy to understand minimum, especially for beginners.

Specifications

Limitations

These are the limitations compared to the full LowRes NX platform. Keep in mind that these are soft limitations: You can still use all available LowRes NX commands from the normal manual, but then it wouldn't be pure Easy LowRes anymore.

Contents

Language Basics

Types and Variables

Available value types are strings and numbers (floating point).

Variable names can contain letters (A-Z), digits (0-9) and underscores (_), but cannot begin with a digit. Reserved keywords (commands, functions) cannot be used as variable names, but they can be part of them..

Examples of valid variable names:

X
A1
LONG_VARIABLE_NAME
PRINTER

Examples of invalid variable names:

2B
PRINT

String variable names end with a $ symbol, for example:

A$
NAME$

Variables are not explicitly declared, but they need to be initialized with a value before you can read from them. Values are assigned to variables using the equal symbol:

NAME$="LOWRES NX"
LIVES=3

Hexadecimal and binary notation can be used for number values:

$FF02
%11001011

Arrays

DIM

DIM [GLOBAL] var-list

Defines arrays with the highest index for each dimension:

DIM A(100)
DIM MAP(31,23,1),NAMES$(9),SCORES(9)

Access elements from arrays, indices start from 0:

DIM SCORES(9)
SCORES(0)=100
SCORES(9)=5
PRINT SCORES(0),SCORES(9)

All elements of arrays are automatically initialized, using zeros (0) or empty strings ("").

With the optional GLOBAL keyword the arrays will be accessable from all subprograms.

=UBOUND

UBOUND(var[,dimension])

Returns the upper bound (the highest index) of a dimension of the array var.

The dimension parameter is an optional number used when the array is multi-dimensional, and specifies the dimension of the array. The default value is 1.

DIM SCORES(9)
FOR I=0 TO UBOUND(SCORES)
  PRINT SCORES(I)
NEXT I

Labels

A label marks a position in a program and is used for commands like GOTO. It consists of a name, using the same rules as for variables, followed by a colon.

TESTLABEL:

Operators

Arithmetic

Symbol Example Purpose
- -B Negation
^ X^3 Exponentiation
* 2*Y Multiplication
/ X/2 Division
\ X\2 Integer Division
+ C+2 Addition
- 100-D Subtraction
MOD X MOD 2 Modulo

Operations are performed in mathematical order, for example multiplications and divisions are performed before additions and subtractions.

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

The order can be specified explicitly through the use of parentheses, for example:

PRINT (3+4)*5

Relational

Symbol Example Purpose
= A=10 Equal
<> A<>100 Not equal
> B>C Greater than
< 5<X Less than
>= X>=20 Greater than or equal
<= X<=30 Less than or equal

A relational operator expression returns the value true (-1) or false (0).

Logical/Bitwise

Symbol Example Purpose
NOT NOT (X=15)
NOT 0
"Not"
AND A=1 AND B=12
170 AND 15
"And"
OR X=10 OR Y=0
128 OR 2
"Or"
XOR A XOR B "Exclusive Or"

How to Use Operators

All operators are available for numbers. Relational and addition operators are usable with strings, too:

SUM=1+3
IF SUM<5 THEN PRINT "LESS THAN 5"
NAME$="LOWRES NX"
GREET$="HELLO "+NAME$+"!"
IF NAME$>"LOWRES" THEN PRINT GREET$
IF SUM=4 AND NAME$<>"" THEN PRINT "OK"

Program Flow Control

Basics

REM

REM remark
' remark

Allows you to put comments into your program. REM lines are not executed. You can use an apostrophe (') in place of the word REM.

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

IF...THEN...ELSE

IF expr THEN command [ELSE command]

Checks if the given expression is true or false. If it's true, the command after THEN is executed, otherwise the one after ELSE. The ELSE part is optional.

INPUT "NUMBER A:";A
INPUT "NUMBER B:";B
PRINT "SAME? ";
IF A=B THEN PRINT "YES" ELSE PRINT "NO"
IF A<B THEN PRINT "A LESS THAN B"
IF A>B THEN PRINT "A GREATER THAN B"

If you want to execute more than one command (or avoid long lines), you can use the block version of the IF command. It must be closed with the line END IF.

IF expression THEN
  commands
[ELSE IF expression THEN]
  commands
[ELSE]
  commands
END IF

Blocks can be nested like in this example:

PRINT "NUMBER OF PLAYERS"
INPUT "1-4: ";N

IF N<1 OR N>4 THEN
  PRINT "WRONG INPUT"
  PRINT "RESTART!"
ELSE IF N=1 THEN
  PRINT "SINGLE-PLAYER"
ELSE
  PRINT "MULTI-PLAYER"
  IF N=4 THEN
    PRINT "MAXIMUM"
  END IF
END IF

GOTO

GOTO label

Jumps to the given label and continues the program execution there.

PRINT "START"
GOTO GAMELEVEL

GAMEOVER:
PRINT "GAME OVER"
END

GAMELEVEL:
PRINT "PLAYING"
GOTO GAMEOVER

GOSUB

GOSUB label

Adds the current program position to a stack and jumps to the given label. The program after the label is called a subroutine and must be finished using RETURN.

FOR I=1 TO 5
  GOSUB SHOWNUMBER
NEXT I
END

SHOWNUMBER:
PRINT "NUMBER",I
RETURN

NOTE: Subroutines exist mostly for historical reasons. You should prefer the more powerful and safer subprograms.

RETURN

RETURN

Jumps back to the position of the last call of GOSUB and removes it from the stack.

RETURN label

Works like GOTO, but clears the whole stack. Use this to exit from a subroutine, if you want to continue your program somewhere else.

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"

END

END

Stops the program from any position. The program is also stopped automatically after the last line of code.

PRINT "THIS HAPPENS"
END
PRINT "THIS DOESN'T"

WAIT VBL

WAIT VBL

Waits for the next frame. This (or WAIT n) should be the last command in all loops which do animations and/or handle input, like the main game loop.

DO
  TEXT RND(19),RND(15),"*"
  WAIT VBL
LOOP

WAIT

WAIT n

Waits n frames (n/60 seconds), where the minimum for n is 1.

WAIT 1 is the same as WAIT VBL, so why is there WAIT VBL? Because it looks cooler and nerdier! A little guideline: Use WAIT VBL in loops for smooth animations and input handling, and WAIT n if you actually want to wait some time.

PRINT "INUTILIS"
PRINT "PRESENTS..."
WAIT 60
PRINT "THE WAIT PROGRAM!"

Loops

FOR...NEXT

FOR var=a TO b [STEP s]
  commands
NEXT var

Performs a series of commands in a loop a given number of times. The FOR command uses the variable var as a counter, starting with the value a. All commands until NEXT are executed, then the counter is increased by s (or 1 if STEP is omitted). A check is performed to see if the counter is now greater than b. If not, the process is repeated. If it is greater, the program continues with the lines after NEXT.

FOR I=1 TO 8
  PRINT I
NEXT I
FOR I=2 TO 16 STEP 2
  PRINT I
NEXT I

If STEP s is negative, the loop is executed until the counter is less than value b.

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

Loops can be placed inside of others:

FOR P=0 TO 3
  PRINT P
  FOR N=1 TO 4
    PRINT N
  NEXT N
NEXT P

DO...LOOP

DO
  commands
LOOP

Performs commands in an endless loop. You can use GOTO or EXIT to leave it.

DO
  PRINT "FOREVER",RND(100)
LOOP

REPEAT...UNTIL

REPEAT
  commands
UNTIL expression

Executes the commands in a loop until the given expression is true. The loop is executed at least once.

REPEAT
  A=RND(9)
  PRINT A
UNTIL A=0

WHILE...WEND

WHILE expression
  commands
WEND

Executes the commands in a loop as long as the given expression is true.

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

EXIT

EXIT

Exits immediately from a loop created with the FOR...NEXT, REPEAT...UNTIL, WHILE...WEND, or DO...LOOP commands.

DO
  INPUT "ENTER E TO EXIT:";A$
  IF A$="E" THEN EXIT
  PRINT "GOING ON..."
LOOP
PRINT "END"

Subprograms

SUB...END SUB

SUB name [(parameter-list)]
  commands
END SUB

Defines a subprogram with the given name. The optional parameter list can contain two types of entries: simple variables and array variables (followed by an empty parentheses pair). Entries are separated by commas. By default all variables inside the subprogram are local.

NOTE: Don't use GOTO or GOSUB to jump out of a subprogram!

CALL

CALL name [(argument-list)]

Executes the subprogram with the given name and returns to the current position after finishing it. The argument list must match the parameters of the SUB definition. Simple variables, single array elements and entire arrays (followed by an empty parentheses pair) are passed by reference to the subprogram. Other expressions are passed by value.

CALL GREET("LOWRES NX",3)
CALL GREET("YOU",1)
CALL BYE

SUB BYE
  PAL 1
  PRINT "BYE"
END SUB

SUB GREET(N$,A)
  FOR I=1 TO A
    PAL RND(3)
    PRINT "HELLO",N$
  NEXT I
END SUB

EXIT SUB

EXIT SUB

Exits a subprogram before END SUB is reached.

GLOBAL

GLOBAL variable-list

Makes variables from the main program available to all subprograms. The list can contain simple variables only. For arrays you should use DIM GLOBAL. This command cannot be used within a subprogram.

GLOBAL SCORE,TRIES

TRIES=3

CALL WIN(10)
CALL WIN(20)

SUB WIN(N)
  SCORE=SCORE+N
  PRINT "SCORE:",SCORE,"TRIES:",TRIES
END SUB

Text

PRINT

PRINT expression-list

Outputs text to the current window. Expressions can be strings or numbers, separated by commas or semicolons. A comma separates the output with a space, a semicolon outputs without space. End the list with a comma or semicolon to keep the cursor at the end of the output, otherwise a new line is started.

PRINT "HELLO WORLD"
PRINT 42
PRINT 1+3
PRINT "SCORE:",100
PRINT "ONE ";
PRINT "LINE"

INPUT

INPUT ["prompt";]var

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).

INPUT automatically enables the keyboard.

INPUT "NAME:";N$
INPUT "AGE:";AGE
PRINT "HELLO ";N$;"!"
PRINT "SOON YOU ARE ";AGE+1

LOCATE

LOCATE cx,cy

Moves the text cursor to column cx and row cy relative to the current window.

LOCATE 2,4
PRINT "HELLO"

=CURSOR.X/Y

CURSOR.X
CURSOR.Y

Returns the current column (X) or row (Y) of the text cursor relative to the current window.

WINDOW

WINDOW cx,cy,w,h,0

Sets the text output window to cell position cx,cy and sets the size to w columns and h rows.

WINDOW 6,4,8,4,0
PRINT "LONG TEXT IN A SMALL WINDOW"

CLW

CLW

Clears the window with spaces and resets the text cursor position.

PRINT "HELLO"
CLW
PRINT "BYE"

User Input

Gamepads

GAMEPAD

GAMEPAD n

Enables gamepads for n (1 or 2) players.

=UP/DOWN/LEFT/RIGHT

UP(p)
DOWN(p)
LEFT(p)
RIGHT(p)

Returns true if the given direction is currently pressed on the direction pad of player p (0/1).

UP TAP(p)
DOWN TAP(p)
LEFT TAP(p)
RIGHT TAP(p)

With the optional TAP keyword, this function returns true only for the first frame the button is pressed.

GAMEPAD 1
DO
  IF UP(0) THEN PRINT "UP"
  IF DOWN(0) THEN PRINT "DOWN"
  IF LEFT TAP(0) THEN PRINT "TAP <"
  IF RIGHT TAP(0) THEN PRINT "TAP >"
  WAIT VBL
LOOP

=BUTTON

BUTTON(p[,n])

Returns true if button A (n=0) or B (n=1) is currently pressed by player p (0/1). If the parameter n is omitted, both buttons (A and B) are checked.

BUTTON TAP(p[,n])

With the optional TAP keyword, this function returns true only for the first frame the button is pressed.

GAMEPAD 1
DO
  IF BUTTON(0,0) THEN PRINT "A"
  IF BUTTON TAP(0,1) THEN PRINT "TAP B"
  WAIT VBL
LOOP

PAUSE ON/OFF

PAUSE ON
PAUSE OFF

Enables or disables the automatic pause handling. By default it's enabled, so if you press the pause button, the program stops and shows "PAUSE" on the screen, until the button is pressed again.

PAUSE

PAUSE

Pauses the program and shows the default "PAUSE" screen, even if automatic pause handling is disabled.

=PAUSE

PAUSE

Returns true if the pause button was pressed, otherwise false. After calling this function its value is cleared, so it returns each button tap only once. The automatic pause handling needs to be disabled for this function.

GAMEPAD 1
PAUSE OFF
DO
  IF PAUSE THEN PRINT "PAUSE PRESSED"
  WAIT VBL
LOOP

Keyboard

KEYBOARD ON/OFF

KEYBOARD ON
KEYBOARD OFF

Enables or disables the keyboard. While the keyboard is enabled, gamepads don't work.

=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. The keyboard needs to be enabled for this function.

KEYBOARD ON
DO
  I$=INKEY$
  IF I$<>"" THEN PRINT I$
  WAIT VBL
LOOP

Graphics

All graphics in LowRes NX are based on characters. A character is an 8x8-pixel image with 4 colors.

The screen is usually called background. The background is a map of 20x16 character cells and is used for text and tile based maps or images. Each cell has the information of which character it contains.

Use the tool "Easy Designer" to create characters and backgrounds.

CLS

CLS

Clears the background with character 0 and resets the current window to the default one.

CELL

CELL cx,cy,c

Sets the cell at position cx,cy to character c.

CELL 1,1,225
CELL 2,1,226
CELL 3,1,227

=CELL.C

CELL.C(cx,cy)

Returns the character of the cell at position cx,cy.

BG FILL

BG FILL cx1,cy1 TO cx2,cy2 CHAR c

Sets all cells in the area from cx1,cy1 to cx2,cy2 to character c.

BG FILL 2,2 TO 17,13 CHAR 225
BG FILL 10,8 TO 17,13 CHAR 226

BG COPY

BG COPY cx1,cy1,w,h TO cx2,cy2

Copies a two-dimensional part of the map from Easy Designer to the background.

'SHOW SCREEN FROM EASY DESIGNER
BG COPY 0,0,20,16 TO 0,0

BG SCROLL

BG SCROLL cx1,cy1 TO cx2,cy2 STEP dx,dy

Moves the content of all cells in the area from cx1,cy1 to cx2,cy2 horizontally by dx and vertically by dy cells.

DO
  BG SCROLL 0,0 TO 19,15 STEP -1,0
  CELL 18,RND(15),193+RND(62)
  WAIT 5
LOOP

TEXT

TEXT cx,cy,s$

Outputs the string s$ at cell position cx,cy.

TEXT 15,15,"HELLO"

NUMBER

NUMBER cx,cy,n,d

Outputs the number n at cell position cx,cy. The number is formatted to show always d digits. This command is preferred over TEXT to show numbers, as it doesn't need to convert numbers to strings.

NUMBER 15,0,321,5

=TIMER

TIMER

Returns the number of frames shown since LowRes NX was started. The value wraps to 0 when 5184000 is reached, which is about 24 hours.

Sound

LowRes NX has four independent sound generators (voices) with pulse and noise waveforms.

PLAY

PLAY v,p[,len] [SOUND s]

Plays a sound on voice v (0-3). p is the pitch:

NotePitch (with different octaves)
C113253749617385
C#214263850627486
D315273951637587
D#416284052647688
E517294153657789
F618304254667890
F#719314355677991
G820324456688092
G#921334557698193
A1022344658708294
A#1123354759718395
B1224364860728496

The optional parameter len is the length in 1/60 seconds, the maximum is 255. 0 means, that the the sound won't stop automatically. If the parameter is omitted, the current value of the voice is kept.

By default the current sound settings of the voice are used. Add the SOUND parameter to use the sound number s from the presets:

PulseNoise
Hard08
Soft19
Short210
Long311
Down412
Up513
Boing614
Random715
PLAY 0,49,20 SOUND 1
WAIT 40
PLAY 0,53,20
WAIT 40
PLAY 0,56,40
WAIT 80

STOP

STOP [v]

Stops the current sound on voice v. If the parameter is omitted, all voices are stopped. Some sound presets won't stop immediately, but fade out.

Data

DATA

DATA constant-list

Stores comma separated 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.

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.

READ

READ var-list

Reads values from DATA commands and assigns them to the comma separated variables in var-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=0 TO 3
  READ TYPE$,POWER
  PRINT TYPE$;":",POWER
NEXT I
DATA "LASER",10,"BLASTER",15
DATA "PLASMA",20,"FUSION",30

RESTORE

RESTORE [label]

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 SHIELDS
FOR I=0 TO 1
  READ TYPE$,POWER
  PRINT TYPE$;":",POWER
NEXT I
DATA "LASER",10,"BLASTER",15
SHIELDS:
DATA "SIMPLE",30,"ADVANCED",60

Math Functions

Trigonometric

=PI

PI

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

=SIN

SIN(x)

The sine of x, where x is in radians.

=COS

COS(x)

The cosine of x, where x is in radians.

=TAN

TAN(x)

The tangent of x, where x is in radians.

=ASIN

ASIN(x)

The arc sine of x, where x must be in the range of -1 to +1. The range of the function is -(PI/2) <= ASIN(x) <= (PI/2).

=ACOS

ACOS(x)

The arc cosine of x, where x must be in the range of -1 to +1. The range of the function is 0 <= ACOS(x) <= PI.

=ATAN

ATAN(x)

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

=HSIN

HSIN(x)

The hyperbolic sine of x.

=HCOS

HCOS(x)

The hyperbolic cosine of x.

=HTAN

HTAN(x)

The hyperbolic tangent of x.

Standard Math

=ABS

ABS(x)

The absolute value of x.

=SGN

SGN(x)

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

=INT

INT(x)

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

=EXP

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

LOG(x)

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

=SQR

SQR(x)

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

Random Sequences

=RND

RND

The next number in a sequence of random numbers uniformly distributed in the range 0 <= RND < 1.

RND(n)

The second syntax generates a random integer between 0 and n inclusive.

RANDOMIZE

RANDOMIZE x

Sets the seed for random numbers to x, which should be an integer value. By default a program starts with seed 0, so the sequence of random numbers is always the same.

RANDOMIZE TIMER

If you want different random numbers each time you run your program, you should insert this line at the beginning.

RANDOMIZE TIMER
FOR I=1 TO 16
  PRINT RND(1000)
NEXT I

Manipulating Numbers

=MIN

MIN(x,y)

The MIN function returns the smallest value of two expressions.

=MAX

MAX(x,y)

The MAX function returns the largest value of two expressions.

SWAP

SWAP var1,var2

Swaps the data between any two variables of the same type.

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

String Functions

=LEFT$=

LEFT$(s$,n)

Returns a new string with the first n characters of s$.

PRINT LEFT$("LOWRES NX",3)
LEFT$(s$,n)=a$

Overwrites the first characters in the variable s$ with the first n characters of a$.

A$="FOORES NX"
LEFT$(A$,3)="LOWER"
PRINT A$

=RIGHT$=

RIGHT$(s$,n)

Returns a new string with the last n characters of s$.

RIGHT$(s$,n)=a$

Overwrites the last characters in the variable s$ with the last n characters of a$.

=MID$=

MID$(s$,p,n)

Returns a new string with n characters of s$, starting at character p. The first character has the position 1.

PRINT MID$("LOWRES NX",4,3)
MID$(s$,p,n)=a$

Overwrites the given text range in the variable s$ with the first n characters of a$.

A$="LOWFOO NX"
MID$(A$,4,3)="RESTAURANT"
PRINT A$

=INSTR

INSTR(d$,s$[,p])

Searches the first occurrence of s$ inside of d$ and returns its start position. If it's not found, the function returns 0. Usually the function starts searching at the beginning of the string. Optionally it can start searching at position p.

PRINT INSTR("LOWRES NX","RES")

=CHR$

CHR$(n)

Returns a string containing one character with ASCII code n.

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

=ASC

ASC(a$)

Supplies you with the ASCII code of the first character of a$.

PRINT ASC("L")

=LEN

LEN(a$)

Returns the number of characters in a$.

=VAL

VAL(a$)

Converts a number written in a$ into a numeric value.

=STR$

STR$(n)

Converts the number n into a string.

=BIN$

BIN$(n[,len])

Converts the number n into a binary string with at least len digits.

=HEX$

HEX$(n[,len])

Converts the number n into a hexadecimal string with at least len digits.