This manual applies to BASIC Engine RX platforms. The BASIC Engine NG reference manual can be found here. The classic BASIC Engine reference manual can be found here.

1. How to Use this Manual

1.1. Syntax Conventions

  • KEYWORDS: Items in capital letters indicate BASIC keywords. Keywords are a required part of the statement syntax, unless they are enclosed in brackets. You must spell keywords correctly.

  • placeholders: Items in lowercase are placeholders for information you must supply in the statement, such as a filename.

  • [optional item]: Items inside square brackets do not need to be used in the statement.

  • <choice1|choice2>: Angle brackets and a vertical bar indicate a choice between two or more items. You must use one of the items in the statement unless the angle brackets are enclosed in square brackets, e.g. [<optional1|optional2>].

  • item, item, …​ means several of the preceding items can be used in a single-line statement.

Note
The uppercase and lowercase syntax notation conventions are used to help you read the syntax rules for a statement, and are not capitalization rules you must type in. Neither keywords nor variable and procedure names are case-sensitive.

1.2. Terminology

  • Video memory refers to the random-access memory that contains the visible screen image.

  • Pixel memory refers to the parts of random-access memory that represent pixels, including the visible screen and the off-screen area that can be accessed by graphics commands and functions.

  • A range is a way to specify a set of numbers by giving a start and/or an end. The following forms are allowed:

    num

    A single number.

    -num

    All numbers up to and including num

    num-

    All numbers from num.

    num1-num2

    All numbers between num1 and num2, inclusive.

2. Data Types

2.1. Arrays

Arrays must be dimensioned using the DIM command, which can also be used to resize and re-dimension them at any time. In the case of numeric arrays, the current values will be maintained. For string arrays, the existing values will be deleted.

If the DIM command is used to create a one-dimensional array, it can be followed by an = sign and a list of initial values separated by commas and enclosed in angular brackets ([ and ]).

2.1.1. Examples

Creating an uninitialized two-dimensional numeric array of size 4x6:

DIM A(4, 6)

Creating an initialized one-dimensional string array:

DIM A$(2) = ["one", "two", "three"]

Accessing an array element:

PRINT A$(0)
one

2.2. Lists

Similar to arrays, lists are data types that contain zero or more elements of a specific simple type (numbers or strings). List names start with the character ~.

Lists are more dynamic than arrays and allow items to be added and removed freely, using the POPB(), POPF(), POPB$() and POPF$() functions and the APPEND and PREPEND commands.

Individual elements can be accessed in the same way as array elements.

Lists are always one-dimensional. The current length of a list can be determined using the LEN() function.

2.2.1. Examples

Appending a list element:

APPEND ~A$, "Tom"

Accessing an element:

PRINT ~A$(0)
Tom
~A$(0) = "Jerry"

Removing a list element from the beginning of the list:

element$ = POPF$(~A$)
PRINT element$
Jerry

Creating a list with initial values:

~A = [1,2,3,4]

2.3. Strings as numeric buffers

Engine BASIC tries to make it easy to use strings as general-purpose buffers that have a lower overhead and use less memory than arrays or lists.

To create a string from a sequence of byte-sized numbers, a string initializer can be used:

A$ = [65, 66, 67]
PRINT A$
ABC

Individual characters can be set and retrieved as numbers:

PRINT A$[0]
65

3. Command and Function Reference

3.1. BASIC Core

APPEND

Appends an element to the end of a list.

USAGE
APPEND list, value
PARAMETERS

list

a numeric or string list variable

value

a numeric or string expression

CALL

Calls a procedure.

USAGE
CALL procedure[(argument[, argument ...])]
PARAMETERS

procedure

name of a procedure declared with PROC

argument

a string or numeric expression

NOTES

At least as many arguments must be given as defined in the procedure declaration. Additional arguments can be accessed using ARG() and ARG$().

SEE ALSO

CHAIN

Loads a new program and runs it, keeping the current set of variables.

USAGE
CHAIN file$[, line_num]
PARAMETERS

file$

name of the BASIC program to be executed

line_num

line number at which execution will start [default: first line]

NOTES

Unlike EXEC, CHAIN does not allow returning to the original program.

SEE ALSO

CLEAR

Deletes all variables.

USAGE
CLEAR
SEE ALSO

NEW

CONT

Continues an interrupted program.

DESCRIPTION

CONT can be used to resume a program run that has been interrupted by Ctrl+C or by the STOP command. It will reset text window and tiled background layouts if they have been automatically adjusted when the program was interrupted.

USAGE
CONT
SEE ALSO

DATA

Specifies values to be read by subsequent READ instructions.

USAGE
DATA expr[, expr...]
PARAMETERS

expr

a numeric or string expression

NOTES

When a DATA instruction is executed, nothing happens.

SEE ALSO

DELETE

Delete specified line(s) from the BASIC program in memory.

Warning
Do not confuse with REMOVE, which deletes files.
USAGE
DELETE range
PARAMETERS

range

a range of BASIC program lines

NOTES
  • Using DELETE does not affect variables.

  • When called from a running program, execution will continue at the next program line, i.e. instructions following DELETE on the same line are disregarded.

SEE ALSO

DIM

Declares an array.

USAGE
DIM variable(dimension[, ...]) [= [value, ...]]
PARAMETERS

variable

an numeric or string array variable

dimension

one or more dimensions of the array

value

initial value(s) for the array elements

NOTES

Initialization is only possible for one-dimensional arrays.

DO

Repeats a block of instructions while a condition is true or until a condition becomes true.

USAGE
DO
  instruction_block
LOOP [<WHILE|UNTIL> condition]
PARAMETERS

instruction_block

one or more instructions on one or more lines

condition

a numeric expression

NOTES

If condition is prefixed by WHILE, the loop will repeat if condition is "true" (non-zero). If condition is prefixed by UNTIL, the loop will continue if condition is "false" (zero). In any other case, the loop will be exited and execution will continue with the instruction following the LOOP command.

If no condition is specified, the loop will repeat forever.

EXAMPLES
i=0
PRINT "Value of i at beginning of loop is ";i
DO
  i=i+1
LOOP WHILE i<10
PRINT "Value of i at end of loop is ";i

ELSE

Introduces the ELSE branch of an IF instruction.

SEE ALSO

IF

END

Ends the program.

USAGE
END
SEE ALSO

ENDIF

Ends a multi-line IF instruction.

SEE ALSO

IF

ERROR

Triggers an error.

USAGE
ERROR code
PARAMETERS

code

error code

SEE ALSO

EXEC

Executes a BASIC program as a child process.

USAGE
EXEC program_file$
PARAMETERS

program_file$

name of the BASIC program file to be executed

NOTES

A program run via EXEC runs in its own program and variable space, and nothing it does affects the calling program or its variables, with the exception of the following:

  • Open files are shared between the parent and child program. Any changes will be visible to both programs.

  • Error handlers set in the parent program will be triggered by errors in the child program, unless they are handled by the child.

BUGS

There is no generalized way to share data between parent and child program.

SEE ALSO

EXIT

Exits a DO, FOR or WHILE loop.

USAGE
EXIT DO

EXIT FOR [loop_variable]
EXIT WHILE
PARAMETERS

loop_variable

the counter variable of a FOR loop

DESCRIPTION

Exits the top-most loop of the specified type, without regard for its loop condition, or the specified FOR loop if there is a loop_variable argument.

The matching loop is dropped from the loop stack, and execution resumes after the end of the loop (the nearest following LOOP, NEXT or WEND statement, or the nearest NEXT loop_variable statement).

NOTES

EXIT only works as intended in loops with a "single end", i.e. loops that are not iterated using more than one LOOP, NEXT or WEND statement.

SEE ALSO

FOR

Starts a loop repeating a block of instructions a specified number of times.

USAGE
FOR loop_variable = start TO end [STEP increment]
  instruction_block
NEXT [loop_variable]
PARAMETERS

loop_variable

a numeric variable used as the loop counter

start

initial value of the loop counter

increment

amount the counter is changed each time through the loop
[default: 1]

instruction_block

one or more instructions on one or more lines

NOTES

Both end and increment are only evaluated once, at the start of the loop. Any changes to these expressions afterwards will not have any effect on it.

If no loop variable is specified in the NEXT command, the top-most FOR loop on the loop stack (that is, the one started last) will be iterated. If it is specified, the FOR loop associated with the given variable will be iterated, and any nested loops below it will be discarded.

EXAMPLES
FOR i = 1 TO 15
  PRINT i
NEXT i
FOR i = 7 to -6 STEP -3
  PRINT i
NEXT i

GOSUB

Calls a subroutine.

DESCRIPTION

GOSUB puts the current position in the program on a stack and then jumps to the given location. It is then possible to return to the instruction after the GOSUB command by using RETURN.

USAGE
GOSUB <line_number|&label>
PARAMETERS

line_number

a BASIC program line number

&label

a BASIC program label

NOTES

It may be more convenient to use PROC procedures and the CALL command instead.

EXAMPLES
FOR i = 1 TO 20
  GOSUB &Square
NEXT i
END

&Square:
PRINT i, i * i
RETURN
SEE ALSO

GOTO

Branches to a specified line or label.

USAGE
GOTO <line_number|&label>
PARAMETERS

line_number

a BASIC program line number

&label

a BASIC program label

NOTES

Try not to use GOTO often as it tends to make programs more difficult to understand. If possible, use loop constructs and procedure calls instead.

SEE ALSO

IF

Executes a instruction or instruction block depending on specified conditions.

USAGE
IF condition THEN
  instruction_block
[ELSE IF condition THEN
  instruction_block]
...
[ELSE
  instruction_block]
ENDIF
IF condition THEN instructions [ELSE instructions]
PARAMETERS

condition

any numeric expression

instruction_block

one or more instructions on one or more lines

instructions

one or more instructions, separated by colons

NOTES

A condition is considered "false" if it is zero, and "true" in any other case.

Important
In many BASIC implementations, ENDIF is spelled END IF (that is, as two commands). If the sequence END IF is entered or loaded in a program, Engine BASIC will convert it to ENDIF.

LET

Assigns the value of an expression to a variable.

USAGE
LET variable = expression
PARAMETERS

variable

any variable

expression

any expression that is of the same type as variable

NOTES

The use of this command is optional; any variable assignment can be written as variable = expression, without prefixing it with LET.

It is provided solely as a compatibility feature with other BASIC dialects. Its use in new programs is not recommended, as it consumes additional memory and compute resources without providing any benefit.

LOAD

Load a program from a file.

USAGE
LOAD file$ [FONT n]
PARAMETERS

file$

name of the BASIC program

font

font (encoding) used for UTF-8 conversion [0 to -1]

NOTES

If you specify the FONT parameter, LOAD will convert the program from the single-byte encoding for that font to UTF-8. Use this to load programs written for the BASIC Engine ESP8266 platform on next-generation systems.

SEE ALSO

LOOP

Iterates a DO loop.

USAGE
LOOP [<UNTIL|WHILE> condition]
SEE ALSO

DO

MERGE

Merge a program in a file with the program currently in memory.

USAGE
MERGE file$[, line_num]
PARAMETERS

file$

name of the BASIC program to be merged

line_num

line number at which to contine execution [default: first line]

NOTES

If called from within a program, MERGE will continue execution from line line_num after the merge (or the beginning of the program if line_num is not specified).

BUGS

When called from within a program, MERGE resets all variables. This probably limits its usefulness.

SEE ALSO

NEW

Deletes the program in memory as well as all variables.

USAGE
NEW
SEE ALSO

NEXT

Increments and tests the counter in a FOR loop.

USAGE
NEXT [loop_variable]
SEE ALSO

FOR

ON ERROR

Enables error handling and, when a run-time error occurs, directs your program to branch to an error-handling routine.

Error handling can be disabled using ON ERROR OFF.

USAGE
ON ERROR GOTO location
ON ERROR OFF
PARAMETERS

location

a line number or a label

HANDLER

The error code is passed to the handler in RET(0), and the line number in RET(1).

When an error has been forwarded from a sub-program that has been started with EXEC, the line number of the sub-program in which the error has been triggered is passed in RET(2).

NOTES

Unlike other event handlers, ON ERROR does not call the error handler as a procedure, and it is not possible to use RETURN to resume execution. RESUME must be used instead.

When a program is executed using EXEC and does not define its own error handler, any errors occurring in the child program will be forwarded to the parent program’s error handler, if there is one.

SEE ALSO

ON GOSUB

Call one of several subroutines, depending on the value of an expression.

SEE ALSO

ON GOTO

Branches to one of several locations, depending on the value of an expression.

USAGE
ON expression <GOTO|GOSUB> <line_number|&label>[, <line_number|&label> ...]
PARAMETERS

expression

any numeric expression

line_number

a BASIC program line number

&label

a BASIC program label

DESCRIPTION

ON GOTO and ON GOSUB will branch to the first given line number or label if expression is 1, to the second if expression is 2, and so forth. If expression is 0, it will do nothing, and execution will continue with the next instruction.

ON GOSUB calls the given location as a subroutine, while ON GOTO simply continues execution there.

SEE ALSO

PREPEND

Adds an element to the start of a list.

USAGE
PREPEND list, value
PARAMETERS

list

a numeric or string list variable

value

a numeric or string expression

PRINT

Prints data to the current output device (usually the screen) or to a given file.

USAGE
PRINT [#file_num, ][*expressions*][<;|,>]
PARAMETERS

file_num

file number to be printed to [0 to 255, default: current output device]

expressions

list of expressions specifying what to print

EXPRESSIONS

The following types of expressions can be used in a PRINT command expressions list:

  • Numeric expressions

  • String expressions

  • TAB(num) (inserts spaces until the cursor is at or beyond the column num)

You have to separate expressions by either a semicolon (;) or a comma (,). When you use a semicolon, the expressions are printed without separation. When you use a comma, spaces will be inserted until the next tabulator stop is reached.

BUGS

TAB() does not work when output is redirected to a file using CMD.

SEE ALSO

PROC

Define a procedure or function.

USAGE
PROC name[(<num_arg|str_arg$>[, <num_arg|str_arg$> ...])]
PARAMETERS

name

procedure name

num_arg

name of a numeric argument variable

str_arg$

name of a string argument variable

DESCRIPTION

PROC defines a procedure or function that can be called using CALL or FN. If a procedure or function has arguments, they can be referenced as local variables using the @ sigil.

Within a procedure or function, any numeric or string variable prefixed with the @ sigil will be treated as a local variable that is valid only within the scope of the procedure. Setting such a variable will not affect global variables or local variables in other procedures.

ERRORS

Procedures can only be called using CALL or FN. If a PROC instruction is encountered during normal program flow, an error is generated.

EXAMPLES
PROC foo(x, y)
  MOVE SPRITE 0 TO @x, @y
  RETURN
CALL foo(20, 30)
PROC sum(eins, zwei)
  RETURN @eins+@zwei
s = FN sum(1, 1)
BUGS

It is not currently possible to use complex data types (arrays and lists) as local variables or arguments.

SEE ALSO

READ

Reads values specified in DATA instructions and assigns them to variables.

USAGE
READ var[, var...]
PARAMETERS

var

numeric or string variable

NOTES

Data is read from the element that follows the current "data pointer". The data pointer points to the beginning of the program initially. With every element read it is forwarded to the next one. It can be set directly with the RESTORE command.

SEE ALSO

RENUM

Renumber BASIC program in memory.

USAGE
RENUM [<start>[, <step>]]
PARAMETERS

start

new line number to start at [min 0, default: 10]

step

line number increment [min 0, default: 10]

NOTES

Computed branches (GOTO and GOSUB commands with variable arguments) cannot be renumbered correctly.

RESTORE

Sets the data pointer to a given location.

USAGE
RESTORE [location]
PARAMETERS

location

a label or line number [default: start of program]

SEE ALSO

RESUME

Resume program execution after an error has been handled.

DESCRIPTION

When an error has been caught by a handler set up using ON ERROR, it is possible to resume execution after the instruction that caused the error using RESUME.

USAGE
RESUME
NOTES

In other BASIC implementations, RESUME will retry the instruction that has caused the error, and it is possible to continue after the error using RESUME NEXT. In Engine BASIC, RESUME will always skip the instruction that generated the error.

BUGS

It is not possible to repeat the instruction that has generated the error.

SEE ALSO

RETURN

Return from a subroutine or procedure.

Returns from a subroutine called by GOSUB or from a procedure defined by PROC and called with CALL or FN.

If specified, up to 4 return values of each type (numeric or string) can be returned to the caller.

USAGE
RETURN [<value|value$>[, <value|value$> ...]]
PARAMETERS

value

numeric expression

value$

string expression

SEE ALSO

RUN

Runs the progam in memory.

DESCRIPTION

If a file name is given, that program will be loaded to memory first. If a line number is given, execution will begin at the specified line. Otherwise, execution will start at the first line.

USAGE
RUN [line_num]
RUN file$
PARAMETERS

file$

name of the BASIC program to be loaded and run

line_num

line number at which execution will start [default: first line]

NOTES

RUN behaves slightly differently when executed from within a program than when used in direct mode.

In direct mode, RUN clears all variables, whereas within a program, it does not. The purpose of this is to allow a program to restart itself with all loop and subroutine stacks cleared, but with the variables still intact.

BUGS
  • The syntax RUN file$ does not work from within a program. Use CHAIN instead.

SEE ALSO

SAVE

Saves the BASIC program in memory to a file.

USAGE
SAVE file$ [LINE <ON|OFF>]
PARAMETERS

file$

name of file to be saved

NOTES
  • Programs are saved without line numbers if LINE OFF is specified.

  • Programs are saved with line numbers if LINE ON is specified.

  • If neither LINE OFF nor LINE ON are specified, line numbers are included if any were present when the program was loaded into memory. If a program has been entered entirely in direct mode, it will be saved with line numbers.

  • BASIC programs are saved in plain text (UTF-8) format.

STOP

Halts the program.

A program stopped by a STOP command can be resumed using CONT.

USAGE
STOP
SEE ALSO

WEND

Iterates a WHILE loop.

USAGE
WEND
SEE ALSO

WHILE

Executes a series of instructions as long as a specified condition is "true".

USAGE
WHILE condition
PARAMETERS

condition

any numeric expression

NOTES

condition is evaluated at the start of the loop. If it is "false", execution continues after the corresponding WEND instruction. (Note that all kinds of loops can be nested, so this may not be the nearest WEND instruction.)

If condition is "true", the instructions following the WHILE instruction will be executed, until the corresponding WEND instruction is reached, at which point condition will be evaluated again to determine whether to continue the loop.

The WHILE keyword can also form part of a LOOP command.

SEE ALSO

ARG$()

Returns a string argument passed to a procedure.

USAGE
a$ = ARG$(num)
PARAMETERS

num

number of the string argument

RETURN VALUE

Argument value.

ERRORS

An error is generated if no string arguments have been passed, num is equal to or larger than ARGC(1), or the function is evaluated outside a procedure.

SEE ALSO

ARG()

Returns a numeric argument passed to a procedure.

USAGE
a = ARG(num)
PARAMETERS

num

number of the numeric argument

RETURN VALUE

Argument value.

ERRORS

An error is generated if no numeric arguments have been passed, num is equal to or larger than ARGC(0), or the function is evaluated outside a procedure.

SEE ALSO

ARGC()

Returns the argument count for numeric and string variables passed to a procedure.

USAGE
cnt = ARGC(typ)
PARAMETERS

typ

type of argument [0 for numeric, 1 for string]

RETURN VALUE

Argument count.

NOTES

Returns 0 if called outside a procedure.

SEE ALSO

CALL, FN

ASC()

Returns the Unicode codepoint for the first character in a string expression.

USAGE
val = ASC(s$)
PARAMETERS

s$

string expression

RETURN VALUE

Unicode codepoint of the first character.

ERRORS

Generates an error if s$ is empty.

NOTES
  • Unlike its counterparts in BASIC implementations with single-byte strings, this function may return values larger than 255.

  • To get access to individual bytes without UTF-8 decoding, use the a$[num] syntax.

SEE ALSO

BIN$()

Returns a string containing the binary representation of a number.

USAGE
b$ = BIN$(num)
PARAMETERS

num

numeric expression

RETURN VALUE

Binary number as text.

NOTES

Numbers are converted to an unsigned 32-bit value first.

SEE ALSO

BLEFT$()

Returns a specified number of leftmost bytes in a byte string.

USAGE
s$ = BLEFT$(l$, num)
PARAMETERS

l$

any string expression

num

number of bytes to return [min 0]

RETURN VALUE

Substring of num bytes or less.

NOTES

If l$ is shorter than num bytes, the return value is l$.

SEE ALSO

BLEN()

Returns the number of bytes in a byte string.

USAGE
sl = BLEN(string$)
PARAMETERS

string$

any string expression

RETURN VALUE

Length in bytes.

BMID$()

Returns part of a byte string.

USAGE
s$ = BMID$(m$, start[, len])
PARAMETERS

m$

any string expression

start

position of the first byte in the substring being returned

len

number of bytes in the substring [default: BLEN(m$)-start]

RETURN VALUE

Substring of len bytes or less.

NOTES
  • If m$ is shorter than len bytes, the return value is m$.

  • Unlike with other BASIC implementations, start is zero-based, i.e. the first byte is 0, not 1.

BRIGHT$()

Returns a specified number of rightmost bytes in a byte string.

USAGE
s$ = RIGHT$(r$, num)
PARAMETERS

r$

any string expression

num

number of bytes to return [min 0]

RETURN VALUE

Substring of num bytes or less.

NOTES

If r$ is shorter than num bytes, the return value is r$.

SEE ALSO

CHR$()

Returns a string containing the UTF-8 encoding of the specified Unicode codepoint.

USAGE
char = CHR$(val)
PARAMETERS

val

Unicode codepoint

RETURN VALUE

Single-character string.

NOTES
  • To construct string from a byte value without UTF-8 encoding, use the a$ = [byte] syntax.

SEE ALSO

ERROR$()

Returns the error message associated with a given error number.

USAGE
msg$ = ERROR$(num)
PARAMETERS

num

error number [0 to 69]

RETURN VALUE

Error message.

SEE ALSO

FREE()

Get free memory size.

USAGE
bytes = FREE
RETURN VALUE

Number of bytes free.

NOTES

The alternative syntax FREE() is supported for backwards compatibility with earlier versions of Engine BASIC.

HEX$()

Returns a string containing the hexadecimal representation of a number.

USAGE
h$ = HEX$(num)
PARAMETERS

num

numeric expression

RETURN VALUE

Hexadecimal number as text.

SEE ALSO

INSTR()

Get the position of the first occurrence of a string in another string.

USAGE
p = INSTR(haystack$, needle$)
PARAMETERS

haystack$

string in which to search

needle$

string to search for

RETURN VALUE

Position of first occurence of needle$ (starting with 0), or -1 if it could not be found.

Note
The meaning of the return value differs from other BASIC implementations, in which 0 usually indicates that the string has not been found, and locations found start at 1.

LCASE$()

Converts string to all-lowercase letters.

USAGE
s$ = LCASE$(s$)
PARAMETERS

s$

string to convert

RETURN VALUE

Value of s$ with all letters replaced with their lowercase equivalents.

SEE ALSO

LEFT$()

Returns a specified number of leftmost characters in a string.

USAGE
s$ = LEFT$(l$, num)
PARAMETERS

l$

any string expression

num

number of characters to return [min 0]

RETURN VALUE

Substring of num characters or less.

NOTES

If l$ is shorter than num characters, the return value is l$.

SEE ALSO

LEN()

Returns the number of characters in a string or the number of elements in a list.

USAGE
sl = LEN(string$)
ll = LEN(~list)
PARAMETERS

string$

any string expression

~list

reference to a numeric or string list

RETURN VALUE

Length in characters (string) or elements (list).

MAP()

Re-maps a value from one range to another

USAGE
mval = MAP(val, l1, h1, l2, h2)
PARAMETERS

val

value to be re-mapped

l1

lower bound of the value’s current range

h1

upper bound of the value’s current range

l2

lower bound of the value’s target range

h2

upper bound of the value’s target range

RETURN VALUE

Re-mapped value.

BUGS

Restricts value to the range l1-h1, which is arbitrary.

MID$()

Returns part of a string (a substring).

USAGE
s$ = MID$(m$, start[, len])
PARAMETERS

m$

any string expression

start

position of the first character in the substring being returned

len

number of characters in the substring [default: LEN(m$)-start]

RETURN VALUE

Substring of len characters or less.

NOTES
  • If m$ is shorter than len characters, the return value is m$.

  • Unlike with other BASIC implementations, start is zero-based, i.e. the first character is 0, not 1.

BUGS

You cannot assign values to MID$(), which is possible in some other BASIC implementations.

SEE ALSO

POPB$()

Remove an element from the end of a string list.

USAGE
e$ = POPB$(~list$)
PARAMETERS

~list$

reference to a string list

RETURN VALUE

Value of the element removed.

ERRORS

An error is generated if ~list$ is empty.

SEE ALSO

POPB()

Remove an element from the end of a numeric list.

USAGE
e = POPB(~list)
PARAMETERS

~list

reference to a numeric list

RETURN VALUE

Value of the element removed.

ERRORS

An error is generated if ~list is empty.

SEE ALSO

POPF$()

Remove an element from the beginning of a string list.

USAGE
e$ = POPF$(~list$)
PARAMETERS

~list$

reference to a string list

RETURN VALUE

Value of the element removed.

ERRORS

An error is generated if ~list$ is empty.

SEE ALSO

POPF()

Remove an element from the beginning of a numeric list.

USAGE
e = POPF(~list)
PARAMETERS

~list

reference to a numeric list

RETURN VALUE

Value of the element removed.

ERRORS

An error is generated if ~list is empty.

SEE ALSO

RET$()

Returns one of the string return values returned by the last function call.

USAGE
rval$ = RET$(num)
PARAMETERS

num

number of the string return value [0 to 3]

RETURN VALUE

String return value requested.

SEE ALSO

RET()

Returns one of the numeric return values of the last function call.

USAGE
rval = RET(num)
PARAMETERS

num

number of the numeric return value [0 to 3]

RETURN VALUE

Requested return value.

SEE ALSO

RIGHT$()

Returns a specified number of rightmost characters in a string.

USAGE
s$ = RIGHT$(r$, num)
PARAMETERS

r$

any string expression

num

number of characters to return [min 0]

RETURN VALUE

Substring of num characters or less.

NOTES

If r$ is shorter than num characters, the return value is r$.

SEE ALSO

STR$()

Returns a string representation of a number.

USAGE
s$ = STR$(num)
PARAMETERS

num

any numeric expression

RETURN VALUE

String representation of num.

SEE ALSO

STRING$()

Returns a string of a specified length made up of a repeating character.

USAGE
s$ = STRING$(count, char$)
PARAMETERS

count

number of characters [at least 0]

char$

any non-empty string expression

NOTES
  • If char$ contains more than one character, only the first will be considered.

  • If count is 0, an empty string will be returned.

EXAMPLES
PRINT STRING$(5, "-");
PRINT "Hello";
PRINT STRING$(5, "-")

UCASE$()

Converts string to all-uppercase letters.

USAGE
s$ = UCASE$(s$)
PARAMETERS

s$

string to convert

RETURN VALUE

Value of s$ with all letters replaced with their uppercase equivalents.

SEE ALSO

VAL()

Converts a number contained in a string to a numeric value.

USAGE
v = VAL(num$)
PARAMETERS

num$

a string expression containing the text representation of a number

RETURN VALUE

Numeric value of num$.

SEE ALSO

FN

Call a procedure and get its return value.

Evaluates to the first return value of a procedure.

USAGE
v = FN procedure[(argument[, argument ...])]
PARAMETERS

procedure

name of a procedure declared with PROC

argument

a string or numeric expression

RETURN VALUE

First return value of called procedure.

NOTES

Most implementations of BASIC allow declaration of functions using DEF FN, a syntax that is not supported by Engine BASIC. To achieve the same result, you will have to rewrite the function declaration:

Example 1. Standard BASIC
DEF FN f(x) = x * 2
Example 2. Engine BASIC
PROC f(x): RETURN @x * 2
SEE ALSO

INKEY$

Reads a character from the keyboard.

USAGE
c$ = INKEY$
RETURN VALUE

Returns either

  • an empty string if there is no keyboard input,

  • a single-character string for regular keys,

  • a two-character string for extended keys.

An "extended key" is a key that does not have a common ASCII representation, such as cursor or function keys.

SEE ALSO

3.2. Math Functions

ABS()

Returns the absolute value of a number.

USAGE
a = ABS(num)
PARAMETERS

num

any numeric expression

RETURN VALUE

Absolute value of num.

ATN2()

Arc tangent function of two variables.

USAGE
a2 = ATN2(x, y)
PARAMETERS

x

any numeric expression

y

any numeric expression

DESCRIPTION

Calculates the principal value of the arc tangent of y/x, using the signs of the two arguments to determine the quadrant of the result.

RETURN VALUE

Arc tangent of y/x.

SEE ALSO

ATN()

Arc tangent function.

USAGE
a = ATN(x)
PARAMETERS

x

any numeric expression

DESCRIPTION

ATN() calculates the principal value of the arc tangent of x; that is the value whose tangent is x.

RETURN VALUE

The principal value of the arc tangent of x in radians.

SEE ALSO

COS()

Returns the cosine of a specified angle.

USAGE
c = COS(angle)
PARAMETERS

angle

an angle expressed in radians

RETURN VALUE

Cosine of angle.

SEE ALSO

EXP()

Returns e raised to a specified power, where e is the base of natural logarithms.

USAGE
ex = EXP(pow)
PARAMETERS

pow

Power to raise e to.

RETURN VALUE

Exponential value of pow.

INT()

Returns the largest integer less than or equal to a numeric expression.

USAGE
i = INT(num)
PARAMETERS

num

any numeric expression

RETURN VALUE

num rounded down to the nearest integer.

LOG()

Returns the natural logarithm of a numeric expression.

USAGE
l = LOG(num)
PARAMETERS

num

any numeric expression

RETURN VALUE

The natural logarithm of num.

RND()

Returns a random number.

USAGE
r = RND(mod)
PARAMETERS

mod

modifier determining the type of random number to generate

RETURN VALUE

A random number of the selected type.

TYPES

The following types of random numbers are generated depending on the value of mod:

mod > 1

a random integer number between 0 and 2147483647

mod between 0 and 1

a random fractional number between 0 and 1

mod < 0

A random fractional number between 0 and 1. A specific value of mod will always yield the same random number.

SGN()

Returns a value indicating the sign of a numeric expression.

USAGE
s = SGN(num)
PARAMETERS

num

any numeric expression

RETURN VALUE

1 if the expression is positive, 0 if it is zero, or -1 if it is negative.

SIN()

Returns the sine of a specified angle.

USAGE
s = SIN(angle)
PARAMETERS

angle

an angle expressed in radians

RETURN VALUE

Sine of angle.

SEE ALSO

SQR()

Square root function.

USAGE
s = SQR(num)
PARAMETERS

num

any numeric expression larger than or equal to 0

RETURN VALUE

The nonnegative square root of num.

TAN()

Returns the tangent of a specified angle.

USAGE
t = TAN(angle)
PARAMETERS

angle

an angle expressed in radians

RETURN VALUE

Tangent of angle.

SEE ALSO

3.3. Numeric Operators

*

Multiplication operator.

USAGE
a * b
RESULT

Product of a and b.

PRECEDENCE

3

+ (unary)

Identity operator.

USAGE
+a
RESULT

a.

NOTES

This operator serves decorative purposes only.

PRECEDENCE

2

+

Numeric addition operator.

USAGE
a + b
RESULT

Sum of a and b.

PRECEDENCE

4

- (unary)

Negation operator.

USAGE
-a
RESULT

The negative of a.

PRECEDENCE

2

-

Numeric subtraction operator.

USAGE
a - b
RESULT

Difference of a and b.

PRECEDENCE

4

/

Division operator.

USAGE
a / b
RESULT

Quotient of a and b.

PRECEDENCE

3

< (strings)

String less-than operator.

USAGE
a$ < b$
RESULT

-1 if the value of a$ precedes the value of b$ when sorted alphabetically, 0 otherwise.

PRECEDENCE

5

<<

Bit-shift operator, left.

USAGE
a << b
RESULT

a converted to an unsigned integer and shifted left by b bits.

PRECEDENCE

3

<

Less-than operator.

USAGE
a < b
RESULT

-1 if a is less than b, 0 otherwise.

PRECEDENCE

6

<> (strings)

String inequality operator.

USAGE
a$ <> b$
a$ >< b$
RESULT

-1 if the value of a$ is different from the value of b$, 0 otherwise.

PRECEDENCE

5

<>

Inequality operator.

USAGE
a <> b
a >< b
RESULT

-1 if a and b are not equal, 0 otherwise.

PRECEDENCE

6

= (strings)

String equality operator.

USAGE
a$ = b$
RESULT

-1 if the value of a$ is identical to the value of b$, 0 otherwise.

PRECEDENCE

5

=

Equality operator.

USAGE
a = b
RESULT

-1 if a and b are equal, 0 otherwise.

PRECEDENCE

6

> (strings)

String greater-than operator.

USAGE
a$ > b$
RESULT

-1 if the value of a$ succeeds the value of b$ when sorted alphabetically, 0 otherwise.

PRECEDENCE

5

>=

Greater-than-or-equal operator.

USAGE
a >= b
RESULT

-1 if a is greater than or equal to b, 0 otherwise.

PRECEDENCE

6

>

Greater-than operator.

USAGE
a > b
RESULT

-1 if a is greater than b, 0 otherwise.

PRECEDENCE

6

>>

Bit-shift operator, right.

USAGE
a >> b
RESULT

a converted to an unsigned integer and shifted right by b bits.

PRECEDENCE

3

AND

Bitwise AND operator.

USAGE
a AND b
RESULT

Bitwise conjunction of a and b.

PRECEDENCE

7

NOTES

Like most BASIC implementations, Engine BASIC does not have a dedicated "logical AND" operator; instead, the bitwise operator is used.

EOR

Bitwise exclusive-OR operator.

USAGE
a EOR b
RESULT

Bitwise exclusive disjunction of a and b.

PRECEDENCE

8

MOD

Modulus operator.

USAGE
a MOD b
RESULT

Remainder of division of a and b.

PRECEDENCE

3

NOT

Bitwise inversion operator.

USAGE
NOT a
RESULT

Bitwise inversion of a.

PRECEDENCE

7

NOTES

Like most BASIC implementations, Engine BASIC does not have a dedicated "logical NOT" operator; instead, the bitwise operator is used.

OR

Bitwise OR operator.

USAGE
a OR b
RESULT

Bitwise inclusive disjunction of a and b.

PRECEDENCE

8

NOTES

Like most BASIC implementations, Engine BASIC does not have a dedicated "logical OR" operator; instead, the bitwise operator is used.

<=

Less-than-or-equal operator.

USAGE
a <= b
RESULT

-1 if a is less than or equal to b, 0 otherwise.

PRECEDENCE

6

^

Exponentiation operator.

USAGE
a ^ b
RESULT

a raised to the power of b.

PRECEDENCE

1

3.4. String Operators

+ (strings)

String concatenation operator.

USAGE
a$ + b$
RESULT

Concatenation of a$ and b$.

3.5. Input/Output

GPMODE

Sets the mode of a general-purpose I/O pin.

USAGE
GPMODE port, pin, value
PARAMETERS

port

port number [0 to 7]

pin

pin number [0 to 31]

mode

pin mode [0 to 7]

NOTES
  • This command is only implemented on the H3 platform.

  • A mode value of 0 or 1 configures the pin as a general-purpose input or output, respectively. A value of 7 disables the pin.

  • For the functions of other modes, consult the Allwinner H3 datasheet, chapter 3.2 ("GPIO Multiplexing Functions").

  • WARNING: Improper use of this command can cause permanent damage to the system and/or attached devices.

SEE ALSO

GPOUT

Sets the state of a general-purpose I/O pin.

USAGE
GPOUT pin, value (ESP8266)
GPOUT port, pin, value (H3)
PARAMETERS

port

port number [0 to 7]

pin

pin number [0 to 15 (ESP8266) or 31 (H3)]

value

pin state [0 for "low", anything else for "high"]

NOTES
  • This command is only implemented on the ESP8266 and H3 platforms.

  • On the ESP8266 platform, GPOUT allows access to pins on the I2C I/O extender only.

SEE ALSO

ON PAD

Defines a game controller input handler triggered by changes in the state of the buttons of a given controller.

Game controller input event handling can be disabled using ON PAD OFF.

USAGE
ON PAD num CALL handler
ON PAD OFF
PARAMETERS

num

number of the game controller [0 to 2]

handler

a procedure defined with PROC

HANDLER

The event handler will receive two numeric arguments: the number of the game controller that has changed state, and a bit pattern indicating which buttons have changed.

NOTES

Unlike some other event handlers, the game controller handler remains enabled after an event has been processed and does not have to be re-armed.

BUGS
Warning
This command has never been tested.
SEE ALSO

SMODE

Changes the serial port configuration.

Warning
This command is likely to be renamed in the future to reduce namespace pollution.
USAGE
SMODE baud[, flags]
PARAMETERS

baud

baud rate [0 to 921600]

flags

serial port flags

BUGS

The meaning of flags is determined by enum values in the Arduino core and cannot be relied on to remain stable.

SEE ALSO

SPICONFIG

Configures the SPI controller.

USAGE
SPICONFIG bit_order, freq, mode
PARAMETERS

bit_order

data bit order [0 = LSB first, 1 = MSB first]

freq

transfer frequency in Hz

mode

SPI mode [0 to 3]

SEE ALSO

SPIDEV

Selects a SPI device.

USAGE
SPIDEV major, minor
PARAMETERS

major

Major device number

minor

Minor device number

NOTES

This command is only implemented on Linux-based platforms.

SEE ALSO

SPIW

Sends data to an SPI device.

USAGE
SPIW out$
PARAMETERS

out$

data to be transmitted

SEE ALSO

SWRITE

Writes a byte to the serial port.

Warning
This command may be renamed in the future to reduce namespace pollution.
USAGE
SWRITE c
PARAMETERS

c

byte to be written

SEE ALSO

ANA()

Reads value from the analog input pin.

USAGE
v = ANA()
RETURN VALUE

Analog value read.

GPIN()

Reads the state of a general-purpose I/O pin.

USAGE
s = GPIN(pin)
PARAMETERS

portno

port number [0 to 7]

pin

pin number [0 to 15]

RETURN VALUE

State of pin: 0 for low, 1 for high.

NOTES
  • This function is only implemented on the ESP8266 and H3 platforms.

  • On the ESP8266 platform, GPIN() allows access to pins on the I2C I/O extender only.

SEE ALSO

I2CBUS()

Selects the I2C bus to use.

USAGE
I2CBUS bus
PARAMETERS

bus

I2C bus number [0 to 255]

NOTES

This command is only implemented on Linux-based platforms.

SEE ALSO

I2CR()

Request data from I2C device.

USAGE
in$ = I2CR(i2c_addr, out_data, read_length)
PARAMETERS

i2c_addr

I2C address [0 to $7F]

out_data

data to be transmitted

read_length

number of bytes to be received

RETURN VALUE

Returns the received data as the value of the function call.

Also returns the status code of the outward transmission in RET(0).

NOTES

If out_data is an empty string, no data is sent before the read request.

SEE ALSO

I2CW()

Sends data to an I2C device.

USAGE
res = I2CW(i2c_addr, out_data)
PARAMETERS

i2c_addr

I2C address [0 to $7F]

out_data

data to be transmitted

RETURN VALUE

Status code of the transmission.

SEE ALSO

INKEY()

Reads a character from the keyboard and returns its numeric value.

USAGE
c = INKEY
RETURN VALUE

Key code [0 to 65535]

NOTES

The alternative syntax INKEY() is supported for backwards compatibility with earlier versions of Engine BASIC.

SEE ALSO

KEY()

Get the state of the specified keyboard key.

USAGE
state = KEY(num)
PARAMETERS

num

Key code [0 to 255]

RETURN VALUE

1 if the key is held, 0 if it is not.

The key codes are detailed in the table below. Availability of each key depends on the Engine BASIC platform.

Key Key code Notes

Left Alt

1

Left Shift

2

Left Ctrl

3

Right Shift

4

Right Alt

5

Right Ctrl

6

Left GUI

7

Right GUI

8

NumLock

9

Scroll Lock

10

Caps Lock

11

Print Screen

12

`

13

Insert

14

Home

15

Pause

16

Romaji

17

Japanese keyboard, not available on SDL

App

18

Japanese keyboard, not available on SDL

Henkan

19

Japanese keyboard, not available on SDL

Muhenkan

20

Japanese keyboard, not available on SDL

Page Up

21

Page Down

22

End

23

Left Arrow

24

Up_Arrow

25

Right Arrow

26

Down Arrow

27

ESC

30

Tab

31

Enter

32

Backspace

33

Delete

34

Space

35

'

36

:

37

,

38

-

39

.

40

/

41

[

42

]

43

\

44

]

45

Japanese keyboard, not available on SDL

=

46

Ro

47

Japanese keyboard, not available on SDL

0

48

1

49

2

50

3

51

4

52

5

53

6

54

7

55

8

56

9

57

Pipe2

58

not well defined, not available on SDL

A

65

B

66

C

67

D

68

E

69

F

70

G

71

H

72

I

73

J

74

K

75

L

76

M

77

N

78

O

79

P

80

Q

81

R

82

S

83

T

84

U

85

V

86

W

87

X

88

Y

89

Z

90

Keypad =

94

Keypad Enter

95

Keypad 0

96

Keypad 1

97

Keypad 2

98

Keypad 3

99

Keypad 4

100

Keypad 5

101

Keypad 6

102

Keypad 7

103

Keypad 8

104

Keypad 9

105

Keypad *

106

Keypad +

107

Keypad ,

108

Brazilian keyboard, not available on SDL

Keypad -

109

Keypad .

110

Keypad /

111

F1

112

F2

113

F3

114

F4

115

F5

116

F6

117

F7

118

F8

119

F9

120

F10

121

F11

122

F12

123

Power

145

NOTES

Key codes are fixed and do not change with the configured keyboard layout.

BUGS
  • Not all keys available on international (especially Japanese) keyboard are correctly mapped on all platforms.

  • Some key definitions are not well-defined. The Pipe2 key is documented as belonging to a US layout keyboard, but US layouts do not have a separate | key.

  • There is currently no keyboard event handling similar to ON PAD for game pad input.

SEE ALSO

MOUSEBUTTON()

State of the specified mouse button.

USAGE
state = MOUSEBUTTON(n)
PARAMETERS

n

number of mouse button [1 to 32]

RETURN VALUE

1 if the mouse button is held, 0 if it is not.

BUTTONS
Number Mouse button

1

Left button

2

Right button

3

Middle button

NOTES

Other buttons than the ones specified above may be available if the mouse connected has more than three buttons.

SEE ALSO

MOUSEDX()

Horizontal movement of the mouse.

DESCRIPTION

Returns a value representing the amount of horizontal movement of the mouse since the last call to MOUSEDX.

USAGE
x = MOUSEDX
RETURN VALUE

relative horizontal movement of mouse, pixels

SEE ALSO

MOUSEDY()

Vertical movement of the mouse.

DESCRIPTION

Returns a value representing the amount of vertical movement of the mouse since the last call to MOUSEDY.

USAGE
y = MOUSEDY
RETURN VALUE

relative vertical movement of mouse, pixels

SEE ALSO

MOUSEWHEEL()

Movement of the mouse wheel.

DESCRIPTION

Returns a value representing the movement of the mouse wheel since the last call to MOUSEWHEEL.

USAGE
wheel = MOUSEWHEEL
RETURN VALUE

movement of mouse wheel, clicks

BUGS

This function is not implemented on SDL platforms.

SEE ALSO

MOUSEX()

Absolute horizontal coordinate of the mouse cursor.

USAGE
x = MOUSEX
RETURN VALUE

X coordinate of mouse cursor, from 0 to PSIZE(0)-1

SEE ALSO

MOUSEY()

Absolute vertical coordinate of the mouse cursor.

USAGE
y = MOUSEY
RETURN VALUE

Y coordinate of mouse cursor, from 0 to PSIZE(1)-1

SEE ALSO

PAD()

Get the state of the game controller(s) and cursor pad.

DESCRIPTION

PAD() can be used to query actual game controllers, or a "virtual" controller simulated with cursor and letter keys on the keyboard.

The special controller number 0 returns the combined state of all (real and virtual) controllers, making it easier to write programs that work with and without a game controller.

USAGE
state = PAD(num[, state])
PARAMETERS

num

Number of the game controller:
0: all controllers combined
1: cursor pad
2: Joystick/joypad controller

state

0: current button state (default)
1: button-change events

RETURN VALUE

Bit field representing the button states of the requested controller(s). The value is the sum of any of the following bit values:

Bit value Joystick/joypad Controller Keyboard

1 (aka LEFT)

button

Left key

2 (aka DOWN)

button

Down key

4 (aka RIGHT)

button

Right key

8 (aka UP)

button

Up key

16

Start button

n/a

32

Select button

n/a

256

button

Z key

512

button

X key

1024

button

S key

2048

button

A key

4096

R1 button

n/a

8192

L1 button

n/a

16384

R2 button

n/a

32768

L2 button

n/a

Depending on state, these bit values are set if the respective buttons are currently pressed (0) or newly pressed (1).

If state is 1, additional values are returned:

  • RET(1) contains buttons that are newly released,

  • RET(2) contains the current button state.

NOTES
Warning
Using PAD() to retrieve button events (state is not 0) interacts with the event handling via ON PAD. It is not recommended to use both at the same time.
SEE ALSO

SPIRW$()

Send and receive data to and from an SPI device.

USAGE
in$ = SPIRW$(out$)
PARAMETERS

out$

data to be transmitted

RETURN VALUE

Returns a string containing the received data that is of the same length as out$.

SEE ALSO

SREAD()

Reads bytes from the serial port.

Warning
This function is currently useless because the serial port receive pin is used for sound output in the BASIC Engine. It may be removed in the future if it turns out that there is no viable way to support serial input.
USAGE
b = SREAD
RETURN VALUE

Byte of data read, or -1 if there was no data available.

NOTES

The alternative syntax SREAD() is supported for backwards compatibility with earlier versions of Engine BASIC.

SEE ALSO

SREADY()

Checks for available bytes on the serial port.

Warning
This function is currently useless because the serial port receive pin is used for sound output in the BASIC Engine. It may be removed in the future if it turns out that there is no viable way to support serial input.
USAGE
n = SREADY
RETURN VALUE

Number of bytes available to read.

NOTES

The alternative syntax SREADY() is supported for backwards compatibility with earlier versions of Engine BASIC.

SEE ALSO

DOWN

Value of the "down" direction for input devices.

SEE ALSO

LEFT

Value of the "left" direction for input devices.

SEE ALSO

RIGHT

Value of the "right" direction for input devices.

SEE ALSO

UP

Value of the "up" direction for input devices.

SEE ALSO

3.6. File System

BLOAD

Loads a binary file to memory.

USAGE
BLOAD file$ TO addr[, len]
PARAMETERS

file$

name of binary file

addr

memory address to be loaded to

len

number of bytes to be loaded [default: whole file]

NOTES

BLOAD will use 32-bit memory accesses if addr and len are multiples of 4, and 8-bit accesses otherwise.

While the BLOAD command does a basic sanity check of the given parameters, it cannot predict any system malfunctions resulting from its use. Use with caution.

SEE ALSO

BSAVE

Saves an area of memory to a file.

USAGE
BSAVE file$, addr, len
PARAMETERS

file$

name of binary file

addr

memory start address

len

number of bytes to be saved

NOTES

BSAVE will use 32-bit memory accesses if addr and len are multiples of 4, and 8-bit accesses otherwise.

While the BSAVE command does a basic sanity check of the given parameters, it cannot predict any system malfunctions resulting from its use. Use with caution.

SEE ALSO

CHDIR

Changes the current directory.

USAGE
CHDIR directory$
PARAMETERS

directory$

path to the new current directory

SEE ALSO

CLOSE

Closes an open file or directory.

USAGE
CLOSE [#]file_num
PARAMETERS

file_num

number of an open file or directory [0 to 255]

SEE ALSO

CMD

Redirect screen I/O to a file.

DESCRIPTION

CMD allows to redirect standard text output or input operations to files.

Redirection can be disabled by replacing the file number with OFF. CMD OFF turns off both input and output redirection.

USAGE
CMD <INPUT|OUTPUT> file_num
CMD <INPUT|OUTPUT> OFF
CMD OFF
PARAMETERS

file_num

number of an open file to redirect to [0 to 255]

NOTES
  • Redirection will automatically be reset if a file redirected to is closed (either explicitly or implicitly, by opening a new file using the currently used file number), or when returning to the command prompt.

  • If -1 is used as file_num, redirection is turned off.

SEE ALSO

COPY

Copies a file.

USAGE
COPY file$ TO new_file$
PARAMETERS

file$

file to be copied

new_file$

copy of the file to be created

BUGS

Does not support wildcard patterns.

FILES

Displays the contents of the current or a specified directory.

USAGE
FILES [filespec$]
PARAMETERS

filespec$

a filename or path, may include wildcard characters
[default: all files in the current directory]

SEE ALSO

FORMAT

Formats the specified file system.

Warning
This command will erase any files stored on the formatted file system, including system files and the saved configuration, if any.
Important
Formatting the SD card file system does not currently work.
USAGE
FORMAT <"/flash"|"/sd">
BUGS

SD card formatting is currently broken; use another device to format SD cards for use with the BASIC Engine.

IMGINFO

Returns dimensions and component count of an image file.

USAGE
IMGINFO file$
PARAMETERS

file$

name of the file

RETURN VALUE

Returns the width in pixels in RET(0), the height in RET(1) and the number of components in RET(2).

BUGS

This command does not work with PCX files.

MKDIR

Creates a directory.

USAGE
MKDIR directory$
PARAMETERS

directory$

path to the new directory

OPEN

Opens a file or directory.

USAGE
OPEN file$ [FOR <INPUT|OUTPUT|APPEND|DIRECTORY>] AS [#]file_num
PARAMETERS

file$

name of the file or directory

file_num

file number to be used [0 to 255]

MODES
  • INPUT opens the file for reading. (This is the default if no mode is specified.)

  • OUTPUT empties the file and opens it for writing.

  • APPEND opens the file for writing while keeping its content.

  • DIRECTORY opens file$ as a directory.

REMOVE

Deletes a file.

Warning
REMOVE does not ask for confirmation before deleting the specified file.
Warning
Do not confuse with DELETE, which deletes lines from the program in memory.
USAGE
REMOVE file$
PARAMETERS

file$

file to be deleted

BUGS

Does not support wildcard patterns.

SEE ALSO

RENAME

Changes the name of a file or directory.

USAGE
RENAME old$ TO new$
PARAMETERS

old$

current file name

new$

new file name

BUGS

Does not support wildcard patterns.

RMDIR

Deletes a directory.

USAGE
RMDIR directory$
PARAMETERS

directory$

name of directory to be deleted

BUGS

Does not support wildcard patterns.

SEE ALSO

SEEK

Sets the file position for the next read or write.

USAGE
SEEK file_num, position
PARAMETERS

file_num

number of an open file [0 to 255]

position

position where the next read or write should occur

ERRORS

The command will generate an error if file_num is not open or the operation is unsuccessful.

SEE ALSO

TYPE

Writes the contents of a file to the screen. When a screen’s worth of text has been printed, it pauses and waits for a key press.

USAGE
TYPE file$
PARAMETERS

file$

name of the file

CMD()

Returns the current file number for screen I/O redirection to a file.

USAGE
file_num = CMD(which)
PARAMETERS

which

0 for OUTPUT, 1 for INPUT

RETURN VALUE

File number, or -1 for screen output

SEE ALSO

CMD

COMPARE()

Compares two files.

USAGE
result = COMPARE(file1$, file2$)
PARAMETERS

file1$

name of first file to compare

file2$

name of second file to compare

RETURN VALUE

If both files are equal, the return value is 0. Otherwise, the return value is -1 or 1.

If the files are not equal, the sign of the result is determined by the sign of the difference between the first pair of bytes that differ in file1$ and file2$.

CWD$()

Returns the current working directory.

USAGE
dir$ = CWD$
RETURN VALUE

Current working directory.

NOTES

The alternative syntax CWD$() is supported for backwards compatibility with earlier versions of Engine BASIC.

SEE ALSO

DIR$()

Returns the next entry of an open directory.

USAGE
d$ = DIR$(dir_num)
PARAMETERS

dir_num

number of an open directory

RETURN VALUE

Returns the directory entry as the value of the function.

Returns an empty string if the end of the directory has been reached.

Also returns the entry’s size in RET(0) and 0 or 1 in RET(1) depending on whether the entry is a directory itself.

ERRORS

An error is generated if dir_num is not open or not a directory.

EOF()

Checks whether the end of a file has been reached.

USAGE
e = EOF(file_num)
PARAMETERS

file_num

number of an open file [0 to 255]

RETURN VALUE

-1 if the end of the file has been reached, 0 otherwise.

INPUT$()

Returns a string of characters read from a specified file.

USAGE
dat$ = INPUT$(len, [#]file_num)
PARAMETERS

len

number of bytes to read

file_num

number of an open file [0 to 255]

RETURN VALUE

Data read from file.

SEE ALSO

LOC()

Returns the current position within a file.

USAGE
l = LOC(file_num)
PARAMETERS

file_num

number of an open file [0 to 255]

RETURN VALUE

Position at which the next byte will be read or written.

LOF()

Returns the length of a file in bytes.

USAGE
l = LOF(file_num)
PARAMETERS

file_num

number of an open file [0 to 255]

RETURN VALUE

Length of file.

3.7. Sprite/Background Engine

BG

Defines a tiled background’s properties.

DESCRIPTION

Using BG, you can define a tiled background’s map and tile size, tile set, window size and position, and priority, as well as turn it on or off.

BG OFF turns off all backgrounds.

USAGE
BG bg [TILES w, h] [PATTERN px, py, pw] [SIZE tx, ty] [WINDOW wx, wy, ww, wh]
      [PRIO priority] [<ON|OFF>]
BG OFF
PARAMETERS

bg

background number [0 to 15]

w

background map width, in tiles

h

background map height, in tiles

px

tile set’s X coordinate, pixels [0 to PSIZE(0)-1]

py

tile set’s Y coordinate, pixels [0 to PSIZE(2)-1]

tx

tile width, pixels [8 (default) to 255]

ty

tile height, pixels [8 (default) to 255]

wx

window X coordinate, pixels [0 (default) to PSIZE(0)-1]

wy

window Y coordinate, pixels [0 (default) to PSIZE(1)-1]

ww

window width, pixels [9 to PSIZE(0)-wx (default)]

wh

window height, pixels [0 to PSIZE(1)-wy (default)]

priority

Background priority [0 to 15, default: bg]

NOTES
  • The BG command’s attributes can be specified in any order, but it is usually a good idea to place the ON attribute at the end if used.

  • A background cannot be turned on unless at least the TILES attribute is set. In order to get sensible output, it will probably be necessary to specify the PATTERN attribute as well.

BUGS

If a background cannot be turned on, no error is generated.

FRAMESKIP

Sets the number of frames that should be skipped before a new frame is rendered by the BG/sprite engine.

This serves to increase the available CPU power to BASIC by reducing the load imposed by the graphics subsystem.

USAGE
FRAMESKIP frm
PARAMETERS

frm

number of frames to be skipped [0 (default) to 59]

LOAD BG

Loads a background map from a file.

USAGE
LOAD BG bg, file$
PARAMETERS

bg

background number. [0 to 15]

file$

name of background map file

SEE ALSO

LOAD FONT

Loads a TrueType font from a file.

USAGE
LOAD FONT file$
PARAMETERS

file$

name of TrueType font file

BUGS

Proportional fonts and fonts that are not specifically designed for use on low-resolution screens will not look very good.

SEE ALSO

MOVE BG

Scrolls a tiled background.

USAGE
MOVE BG bg TO pos_x, pos_y
PARAMETERS

bg

background number [0 to 15]

pos_x

top/left corner offset horizontal, pixels

pos_y

top/left corner offset vertical, pixels

NOTES

There are no restrictions on the coordinates that can be used; backgrounds maps wrap around if the display window extends beyond the map boundaries.

SEE ALSO

BG

MOVE SPRITE

Moves a sprite.

USAGE
MOVE SPRITE num TO pos_x, pos_y
PARAMETERS

num

Sprite number [0 to 127]

pos_x

Sprite position X coordinate, pixels

pos_y

Sprite position X coordinate, pixels

NOTES

There are no restrictions on the coordinates that can be used; sprites that are placed completely outside the dimensions of the current screen mode will not be drawn.

SEE ALSO

ON SPRITE

Defines an event handler for sprite collisions.

The handler is called once for each collision between two sprites. The handler can be disabled using ON SPRITE OFF.

USAGE
ON SPRITE CALL handler
ON SPRITE OFF
PARAMETERS

handler

a procedure defined with PROC

HANDLER

The event handler will be passed three numeric arguments: The sprite IDs of the involved sprites, and the direction of the collision, as would be returned by SPRCOLL().

NOTES

The handler will be called once for each sprite collision, but it has to be re-enabled using ON SPRITE CALL each time to prevent event storms.

BUGS
Warning
This command has never been tested.
SEE ALSO

PLOT MAP

Creates a mapping from one tile to another.

DESCRIPTION

Tile numbers depend on the locations of graphics data in memory and do not usually represent printable characters, often making it difficult to handle them in program text. By remapping a printable character to a tile as represented by the graphics data, it is possible to use that human-readable character in your program, making it easier to write and to understand.

USAGE
PLOT bg MAP from TO to
PARAMETERS

bg

background number [0 to 15]

from

tile number to remap [0 to 255]

to

tile number to map to [0 to 255]

EXAMPLES
PLOT 0 MAP ASC("X") TO 1
PLOT 0 MAP ASC("O") TO 3
...
PLOT 0,5,10,"XOOOXXOO"
SEE ALSO

PLOT

Sets the value of one or more background tiles.

USAGE
PLOT bg, x, y, <tile|tile$>
PARAMETERS

bg

background number [0 to 15]

x

tile X coordinate [0 to background width in tiles]

y

tile Y coordinate [0 to background height in tiles]

tile

tile identifier [0 to 255]

tile$

tile identifiers

NOTES

If the numeric tile argument is given, a single tile will be set. If a string of tiles (tile$) is passed, a tile will be set for each of the elements of the string, starting from the specified tile coordinates and proceeding horizontally.

SEE ALSO

SAVE BG

Saves a background map to a file.

USAGE
SAVE BG bg TO file$
PARAMETERS

bg

background number. [0 to 15]

file$

name of background map file

BUGS

Does not check if the specified background is properly defined.

SEE ALSO

SPRITE

Defines a sprite’s properties.

DESCRIPTION

Using SPRITE, you can define a sprite’s appearance, size, animation frame, color key, prority, special effects, and turn it on and off.

SPRITE OFF turns all sprites off.

USAGE
SPRITE num [PATTERN pat_x, pat_y][SIZE w, h][FRAME frame_x, frame_y]
           [FLAGS flags][KEY key][PRIO priority][ANGLE angle]
           [SCALE scale_x[,scale_y]][ALPHA alpha][<ON|OFF>]
SPRITE OFF
PARAMETERS

pat_x

X coordinate of the top/left sprite pattern, pixels

pat_y

Y coordinate of the top/left sprite pattern, pixels

w

sprite width, pixels [0 to 1023]

h

sprite height, pixels [0 to 1023]

frame_x

X coordinate of the pattern section to be used, in multiples of sprite width

frame_y

Y coordinate of the pattern section to be used, in multiples of sprite height

flags

special effect flags [0 to 7]

key

key color value to be used for transparency masking

priority

sprite priority in relation to background layers
[0 to 15]

angle

rotation angle in degrees [default 0]

scale_x

horizontal scaling factor [default 1]

scale_y

vertical scaling factor [default 1]

alpha

sprite opacity [0 to 255, default 255]

FLAGS

The FLAGS attribute is the sum of any of the following bit values:

Bit value Effect

1

Sprite opacity (opaque if set)

2

Horizontal flip

4

Vertical flip

NOTES
  • The SPRITE command’s attributes can be specified in any order, but it is usually a good idea to place the ON attribute at the end if used.

  • The ALPHA attribute is only available on true-color platforms.

BUGS

Having to specify the rotation angle in degrees is cumbersome when using other trigonometric operations to calculate it.

BSCRX()

Returns the horizontal scrolling offset of a given background layer.

USAGE
p = BSCRX(bg)
PARAMETERS

bg

background number [0 to 15]

RETURN VALUE

X scrolling offset of background bg.

SEE ALSO

BSCRY()

Returns the vertical scrolling offset of a given background layer.

USAGE
p = BSCRY(bg)
PARAMETERS

bg

background number [0 to 15]

RETURN VALUE

Y scrolling offset of background bg.

SEE ALSO

SPRCOLL()

Checks if a sprite has collided with another sprite.

USAGE
res = SPRCOLL(spr1, spr2)
PARAMETERS

spr1

sprite number 1 [0 to 127]

spr2

sprite number 2 [0 to 127]

RETURN VALUE

If the return value is 0, no collision has taken place. Otherwise the return value is the sum of 64 and any of the following bit values:

Bit value Meaning

1 (aka LEFT)

Sprite 2 is left of sprite 1.

2 (aka DOWN)

Sprite 2 is below sprite 1.

4 (aka RIGHT)

Sprite 2 is right of sprite 1.

8 (aka UP)

Sprite 2 is above sprite 1.

It is possible that none of these bits are set even if a collision has taken place (i.e., the return value is 64) if sprite 1 is larger than sprite 2 and covers it completely.

NOTES
  • Collisions are only detected if both sprites are enabled.

  • Sprite/sprite collision detection is pixel-accurate, i.e. a collision is only detected if visible pixels of two sprites overlap.

BUGS

Does not return an intuitive direction indication if sprite 2 is larger than sprite 1 and covers it completely. (It will indicate that sprite 2 is up/left of sprite 1.)

SEE ALSO

SPRH()

Returns the height of a given sprite.

USAGE
p = SPRH(spr)
PARAMETERS

spr

sprite number [0 to 127]

RETURN VALUE

Height of sprite spr.

NOTES

On platforms with rotozoom support, the function returns the dimension after transformations have been applied.

BUGS

When rotation and/or scale are changed, the new dimensions may not be reflected here until the next video frame is rendered.

SEE ALSO

SPRW()

Returns the width of a given sprite.

USAGE
p = SPRW(spr)
PARAMETERS

spr

sprite number [0 to 127]

RETURN VALUE

Width of sprite spr.

NOTES

On platforms with rotozoom support, the function returns the dimension after transformations have been applied.

BUGS

When rotation and/or scale are changed, the new dimensions may not be reflected here until the next video frame is rendered.

SEE ALSO

SPRX()

Returns the horizontal position of a given sprite.

USAGE
p = SPRX(spr)
PARAMETERS

spr

sprite number [0 to 127]

RETURN VALUE

X coordinate of sprite spr.

SEE ALSO

SPRY()

Returns the vertical position of a given sprite.

USAGE
p = SPRY(spr)
PARAMETERS

spr

sprite number [0 to 127]

RETURN VALUE

Y coordinate of sprite spr.

SEE ALSO

TILECOLL()

Checks if a sprite has collided with a background tile.

USAGE
res = TILECOLL(spr, bg, tile)
PARAMETERS

spr

sprite number [0 to 127]

bg

background number [0 to 15]

tile

tile number [0 to 255]

RETURN VALUE

If the return value is 0, no collision has taken place. Otherwise the return value is the sum of 64 and any of the following bit values:

Bit value Meaning

1 (aka LEFT)

The tile is left of the sprite.

2 (aka DOWN)

The tile is below the sprite.

4 (aka RIGHT)

The tile is right of the sprite.

8 (aka UP)

The tile is above the sprite.

Note that it is possible that none of these bits are set even if a collision has taken place (i.e., the return value is 64) if the sprite’s size is larger than the tile size of the given background layer, and the sprite covers the tile completely.

BUGS
Warning
This function has never been tested.

Unlike SPRCOLL(), tile collision detection is not pixel-accurate.

SEE ALSO

3.8. Pixel Graphics

BLIT

Copies a rectangular area of pixel memory to another area.

USAGE
BLIT x, y TO dest_x, dest_y SIZE width, height [ALPHA]
PARAMETERS

x

source area, X coordinate [0 to PSIZE(0)-1]

y

source area, Y coordinate [0 to PSIZE(2)-1]

dest_x

destination area, X coordinate [0 to PSIZE(0)-1]

dest_y

destination area, Y coordinate [0 to PSIZE(2)-1]

width

area width [0 to PSIZE(0)-x]

height

area height [0 to PSIZE(2)-y]

NOTES

By default an opaque blit is performed, ignoring the alpha channel of the source area. To enable alpha-blending, ALPHA must be appended at the end.

SEE ALSO

CIRCLE

Draws a circle.

USAGE
CIRCLE x_coord, y_coord, radius, color[, fill_color]
PARAMETERS

x_coord

X coordinate of the circle’s center
[0 to PSIZE(0)-1]

y_coord

Y coordinate of the circle’s center
[0 to PSIZE(2)-1]

radius

circle’s radius

color

color of the circle’s outline [range depends on color space]

fill_color

color of the circle’s body
[range depends on color space, 0 for an unfilled circle]

SEE ALSO

GPRINT

Prints a string of characters at the specified pixel position.

DESCRIPTION

GPRINT allows printing characters outside the fixed text grid, including off-screen pixel memory.

USAGE
GPRINT x, y, *expressions*
PARAMETERS

x

start point, X coordinate, pixels [0 to PSIZE(0)-1]

y

start point, Y coordinate, pixels [0 to PSIZE(2)-1]

expressions

PRINT-format list of expressions specifying what to draw

NOTES
  • The expression list functions as it does in the PRINT command.

  • The "new line" character that is generally appended at the end of a PRINT command is drawn literally by GPRINT, showing up as a funny character at the end of the drawn text. This can be avoided by appending a semicolon (;) to the print parameters.

SEE ALSO

GSCROLL

Scroll a portion screen contents in the given direction.

USAGE
GSCROLL x1, y1, x2, y2, direction
PARAMETERS

x1

start of the screen region, X coordinate, pixels [0 to PSIZE(0)-1]

y1

start of the screen region, Y coordinate, pixels [0 to PSIZE(2)-1]

x2

end of the screen region, X coordinate, pixels [x1+1 to PSIZE(0)-1]

y2

end of the screen region, Y coordinate, pixels [y1+1 to PSIZE(2)-1]

direction

direction

DIRECTION

Valid values for direction are:

0

up

1

down

2

left

3

right

SEE ALSO

LINE

Draws a line.

USAGE
LINE x1_coord, y1_coord, x2_coord, y2_coord[, color]
PARAMETERS

x1_coord

X coordinate of the line’s starting point
[0 to PSIZE(0)-1]

y1_coord

Y coordinate of the line’s starting point
[0 to PSIZE(2)-1]

x2_coord

X coordinate of the line’s end point
[0 to PSIZE(0)-1]

y2_coord

Y coordinate of the line’s end point
[0 to PSIZE(2)-1]

color

color of the line [default: text foreground color]

BUGS

Coordinates that exceed the valid pixel memory area will be clamped. This can change the slope of the line and is not the behavior one would expect.

SEE ALSO

PSET

Draws a pixel.

USAGE
PSET x_coord, y_coord, color
PARAMETERS

x_coord

X coordinate of the pixel

y_coord

Y coordinate of the pixel

color

color of the pixel [range depends on color space]

SEE ALSO

RECT

Draws a rectangle.

USAGE
RECT x1_coord, y1_coord, x2_coord, y2_coord, color[, fill_color]
PARAMETERS

x1_coord

X coordinate of the rectangle’s top/left corner
[0 to PSIZE(0)-1]

y1_coord

Y coordinate of the rectangle’s top/left corner
[0 to PSIZE(2)-1]

x2_coord

X coordinate of the rectangle’s bottom/right corner
[0 to PSIZE(0)-1]

y2_coord

Y coordinate of the rectangle’s bottom/right corner
[0 to PSIZE(2)-1]

color

color of the rectangle’s outline

fill_color

color of the rectangle’s body
[range depends on color space, 0 for an unfilled rectangle]

SEE ALSO

POINT()

Returns the color of the pixel at the given coordinates.

USAGE
px = POINT(x, y)
PARAMETERS

x

X coordinate, pixels [0 to PSIZE(0)-1]

y

Y coordinate, pixels [0 to PSIZE(2)-1]

RETURN VALUE

Pixel color [0 to 255]

NOTES

If the coordinates exceed the dimensions of the pixel memory area, 0 will be returned.

3.9. Screen Handling

BORDER

Sets the color of the screen border.

The color can be set individually for each screen column.

USAGE
BORDER uv, y[, x, w]
PARAMETERS

uv

UV component of the border color [0 to 255]

y

Y component of the border color [0 to 255]

x

first column to set [default: 0]

w

number of columns to set [default: all]

NOTES

There is no direct correspondence between border and screen color values.

BUGS

There is no way to find the allowed range of values for x and w without trial and error.

CHAR

Prints a single character to the screen.

USAGE
CHAR x, y, c
PARAMETERS

x

X coordinate, characters [0 to CSIZE(0)]

y

Y coordinate, characters [0 to CSIZE(1)]

c

character [0 to 255]

NOTES

This command does nothing if the coordinates are outside the screen limits.

CLS

Clears the current text window.

USAGE
CLS
SEE ALSO

COLOR

Changes the foreground and background color for text output.

USAGE
COLOR fg_color[, bg_color [, cursor_color]]
PARAMETERS

fg_color

foreground color [range depends on color space]

bg_color

background color [range depends on color space, default: 0]

cursor_color

cursor color [range depends on color space]

SEE ALSO

CSCROLL

Scrolls the text screen contents in the given direction.

USAGE
CSCROLL x1, y1, x2, y2, direction
PARAMETERS

x1

start of the screen region, X coordinate, characters [0 to CSIZE(0)-1]

y1

start of the screen region, Y coordinate, characters [0 to CSIZE(1)-1]

x2

end of the screen region, X coordinate, characters [x1+1 to CSIZE(0)-1]

y2

end of the screen region, Y coordinate, characters [y1+1 to CSIZE(1)-1]

direction

direction

DIRECTION

Valid values for direction are:

0

up

1

down

2

left

3

right

BUGS

Colors are lost when scrolling.

SEE ALSO

FONT

Sets the current text font.

USAGE
FONT font_num
FONT font_name$ SIZE width, height
PARAMETERS

font_num

font number

font_name$

font name

width

font width (pixels)

height

font height (pixels)

RETURN VALUE

Returns the index of the selected font in RET(0).

FONTS

The following fonts are built-in:

0

"lexis"

Lexis font, 6x8 pixels (default)

1

"cpc"

CPC font, 8x8 pixels

2

"bescii"

PETSCII-style font, 8x8 pixels

3

"tt"

Japanese font, 8x8 pixels

4

"hp100lx"

HP 100 LX font, 8x8 pixels

NOTES
  • Additional fonts will be assigned consecutive font indices.

  • The font set at power-on can be set using the CONFIG command.

SEE ALSO

LISTFONTS

Lists installed fonts.

USAGE
LISTFONTS
DESCRIPTION

Prints a tab-separated list of the indices, names and sizes of the fonts currently loaded.

SEE ALSO

LOAD IMAGE

Loads an image file in whole or in parts to pixel memory.

USAGE
LOAD IMAGE image$ [AS <BG bg|SPRITE *range*>] [TO dest_x, dest_y] [OFF x, y]
           [SIZE width, height] [KEY col] [SCALE scale_x, scale_y]
PARAMETERS

bg

background number [0 to 15]

range

sprite range [limits between 0 and 127]

dest_x

X-coordinate of destination, pixels
[0 (default) to PSIZE(0)-w]

dest_y

Y-coordinate of destination, pixels
[0 (default) to PSIZE(2)-h]

x

offset within image file, X axis, pixels [default: 0]

y

offset within image file, Y axis, pixels [default: 0]

width

width of image portion to be loaded, pixels [default: image width]

height

height of image portion to be loaded, pixels [default: image height]

col

color key for transparency [default: no transparency]

scale_x

scaling factor [default: 1]

scale_y

scaling factor [default: 1]

RETURN VALUE

Returns the destination coordinates in RET(0) and RET(1), as well as width and height in RET(2) and RET(3), respectively.

NOTES

If no destination is specified, an area of off-screen memory will be allocated automatically.

If AS BG is used, the loaded image portion will be assigned to the specified background as its tile set.

If AS SPRITE is used, the loaded image portion will be assigned to the specified range of sprites as their sprite patterns.

If a color key is specified, pixels of the given color will not be drawn.

If the scaling factor for a dimension is -1, it will be resized to the screen size. If it is -2, it will be resized so that the aspect ratio is preserved.

If the scaling factor for both dimensions is -2, the image will be fit to the screen while preserving the aspect ratio.

Important
Resizing is not supported for images in PCX format.
SEE ALSO

LOCATE

Moves the text cursor to the specified position.

USAGE
LOCATE x_pos, y_pos
PARAMETERS

x_pos

cursor X coordinate
[0 to CSIZE(0)-1]

y_pos

cursor Y coordinate
[0 to CSIZE(1)-1]

SEE ALSO

PALETTE

Sets the color space ("palette") for the current screen mode, as well as coefficients for the color conversion function RGB().

USAGE
PALETTE pal[, hw, sw, vw, f]
PARAMETERS

pal

colorspace number [0 or 1]

hw

hue weight for color conversion [0 to 7]

sw

saturation weight for color conversion [0 to 7]

vw

value weight for color conversion [0 to 7]

f

conversion fix-ups enabled [0 or 1]

NOTES

The default component weights depend on the color space. They are:

Color space H S V

0

7

3

6

1

7

4

7

Conversion fix-ups are enabled by default.

SEE ALSO

REDRAW

Redraw the text screen.

DESCRIPTION

Overwrites anything displayed on-screen with the characters stored in the text buffer.

USAGE
REDRAW
SEE ALSO

CLS

SAVE IMAGE

Saves a portion of pixel memory as an image file.

USAGE
SAVE IMAGE image$ [POS x, y] [SIZE w, h]
PARAMETERS

image$

name of image file to be created

x

left of pixel memory section, pixels
[0 (default) to PSIZE(0)-1]

y

top of pixel memory section, pixels
[0 (default) to PSIZE(2)-1]

w

width of pixel memory section, pixels
[0 to PSIZE(0)-x-1, default: PSIZE(0)]

h

height of pixel memory section, pixels
[0 to PSIZE(2)-y-1, default: PSIZE(1)]

SEE ALSO

SCREEN

Change the screen resolution.

USAGE
SCREEN mode
PARAMETERS

mode

screen mode [1 to 20]

MODES

The following modes are available:

Mode Resolution Comment

1

460x224

Maximum usable resolution in NTSC mode.

2

436x216

Slightly smaller than mode 1; helpful if the display does not show the entirety of mode 1.

3

320x216

4

320x200

Common resolution on many home computer systems.

5

256x224

Compatible with the SNES system.

6

256x192

Common resolution used by MSX, ZX Spectrum and others.

7

160x200

Common low-resolution mode on several home computer systems.

8

352x240

PC Engine-compatible overscan mode

9

282x240

PC Engine-compatible overscan mode

10

508x240

Maximum usable resolution in PAL mode. (Overscan on NTSC systems.)

11

320x256

12

320x240

IBM PC VGA "Mode X"

13

640x256

14

480x270

1/8 HD, 16:9, default mode on SDL platforms

15

640x480

IBM PC VGA

16

800x600

IBM PC SVGA

17

1024x768

IBM PC XGA

18

1280x720

HD, 16:9

19

1280x1024

IBM PC SXGA, 5:4

20

1920x1080

Full HD, 1080p, 16:9

NOTES
  • While the resolutions are the same for NTSC and PAL configurations, the actual sizes and aspect ratios vary depending on the TV system.

  • Resolutions have been chosen to match those used in other systems to facilitate porting of existing programs.

  • Apart from changing the mode, SCREEN clears the screen, resets the font and color space (palette) to their defaults, and disables sprites and tiled backgrounds.

SEE ALSO

VPOKE

Write data to video memory.

Warning
Incorrect use of this command can configure the video controller to produce invalid output, with may cause damage to older CRT displays.
USAGE
VPOKE addr, val
PARAMETERS

addr

video memory address [0 to 131071]

val

numeric value [0 to 255] or string expression

SEE ALSO

VREG

Writes to a video controller register.

Warning
Incorrect use of this command can configure the video controller to produce invalid output, with may cause damage to older CRT displays.
USAGE
VREG reg[, val[, val ...]]
PARAMETERS

reg

video controller register number

val

value [0 to 65535]

NOTES

Valid registers numbers are: $01, $28 to $30, $34 to $36, $82 and $B8

The number of values required depends on the register accessed:

$34, $35

3 values

$36

no value

$30

2 values

all others

1 value

SEE ALSO

VSYNC

Synchronize with video output.

DESCRIPTION

Waits until the video frame counter has reached or exceeded a given value, or until the next frame if none is specified.

USAGE
VSYNC [frame]
PARAMETERS

frame

frame number to be waited for

NOTES

Specifying a frame number helps avoid slowdowns by continuing immediately if the program is "late", and not wait for another frame.

f = FRAME
DO
  ' stuff that may take longer than expected
  VSYNC f+1	// (1)
  f = f + 1
LOOP
  1. This command will not wait if frame f+1 has already passed.

SEE ALSO

WINDOW

Sets the text screen window.

WINDOW OFF resets the text window to cover the entire screen.

USAGE
WINDOW x, y, w, h
WINDOW OFF
PARAMETERS

x

left boundary of the text window, in characters
[0 to CSIZE(0)-1]

y

top boundary of the text window, in characters
[0 to CSIZE(1)-1]

w

width of the text window, in characters
[1 to CSIZE(0)-x]

h

height of the text window, in characters
[1 to CSIZE(1)-y]

SEE ALSO

CHAR()

Returns the text character on screen at a given position.

USAGE
c = CHAR(x, y)
PARAMETERS

x

X coordinate, characters

y

Y coordinate, characters

RETURN VALUE

Character code.

NOTES
  • If the coordinates exceed the dimensions of the text screen, 0 will be returned.

  • The value returned represents the current character in text screen memory. It may not represent what is actually visible on screen if it has been manipulated using pixel graphics functions, such as GPRINT.

SEE ALSO

CSIZE()

Returns the dimensions of the current screen mode in text characters.

USAGE
size = CSIZE(dimension)
PARAMETERS

dimension

requested screen dimension:
0: text screen width
1: text screen height

RETURN VALUE

Size in characters.

SEE ALSO

FRAME()

Returns the number of video frames since power-on.

USAGE
fr = FRAME
RETURN VALUE

Frame count.

NOTES

The alternative syntax FRAME() is supported for backwards compatibility with earlier versions of Engine BASIC.

SEE ALSO

POS()

Returns the text cursor position.

USAGE
position = POS(axis)
PARAMETERS

axis

requested axis:
0: horizontal
1: vertical

RETURN VALUE

Position in characters.

PSIZE()

Returns the dimensions of the current screen mode in pixels.

USAGE
size = PSIZE(dimension)
PARAMETERS

dimension

requested screen dimension:
0: screen width
1: visible screen height
2: total screen height

RETURN VALUE

Size in pixels.

SEE ALSO

RGB()

Converts RGB value to hardware color value.

DESCRIPTION

All Engine BASIC commands that require a color value expect that value to be in the video controller’s format, which depends on the PALETTE setting.

RGB() can be used to calculate hardware color values from the more easily understood RGB format, and can also help with programs that need to work with different color palettes.

USAGE
color = RGB(red, green, blue)
PARAMETERS

red

red component [0 to 255]

green

green component [0 to 255]

blue

blue component [0 to 255]

RETURN VALUE

YUV color value

NOTES

The color conversion method used is optimized for use with pixel art. Its results can be tweaked by setting conversion coefficients with the PALETTE command.

Component values that are out of range will be silently clamped.

SEE ALSO

VPEEK()

Read a location in video memory.

USAGE
v = VPEEK(video_addr)
PARAMETERS

video_addr

Byte address in video memory. [0 to 131071]

RETURN VALUE

Memory content.

SEE ALSO

VREG()

Read a video controller register.

USAGE
v = VREG(reg)
PARAMETERS

reg

video controller register number

RETURN VALUE

Register contents.

NOTES

Valid register numbers are: $05, $53, $84, $86, $9F and $B7.

SEE ALSO

3.10. Sound

BEEP

Produces a sound using the "beeper" sound engine.

USAGE
BEEP period[, volume [, env$]]
PARAMETERS

period

tone cycle period in samples [0 (off) to 480/512/2048]

volume

tone volume
[0 to 15, default: as set in system configuration]

env$

volume envelope [characters from CHR$(0) to CHR$(15), default: constant volume]

NOTES

The maximum value for period varies depending on the platform: * H3: 480 * SDL: 512 * DOS: 2048

SEE ALSO

ON PLAY

Defines an event handler triggered by the end of the current MML pattern.

The handler is called when the MML pattern of any sound channel has finished playing. It can be disabled using ON PLAY …​ OFF.

USAGE
ON PLAY channel CALL handler
ON PLAY channel OFF
PARAMETERS

channel

a sound channel [0 to 2]

handler

a procedure defined with PROC

HANDLER

The event handler will receive the number of the channel that has ended as a numeric argument.

NOTES

All end-of-music handlers will be disabled when one of them is called, and they therefore have to be re-enabled using ON PLAY CALL if so desired.

BUGS
Warning
This command has never been tested.

An event on one channel will disable handling on all channels. That is stupid.

SEE ALSO

PLAY

Plays a piece of music in Music Macro Language (MML) using the wavetable synthesizer.

USAGE
PLAY [ch, ]mml$
PARAMETERS

ch

sound channel [0 to 2, default: 0]

mml$

score in MML format

BUGS
  • MML syntax undocumented.

  • Fails silently if the synthesizer could not be initialized.

SOUND FONT

Sets the sound font to be used by the wavetable synthesizer.

USAGE
SOUND FONT file$
PARAMETERS

file$

name of the SF2 sound font file

NOTES

If a relative path is specified, Engine BASIC will first attempt to load the sound font from /sd, then from /flash.

The default sound font name is 1mgm.sf2.

BUGS

No sanity checks are performed before setting the sound font.

SEE ALSO

SOUND

Generates a sound using the wavetable synthesizer.

USAGE
SOUND ch, inst, note[, len[, vel]]
PARAMETERS

ch

sound channel [0 to 2]

inst

instrument number

note

note pitch

len

note duration, milliseconds [default: 1000]

vel

note velocity [0 to 1 (default)]

SEE ALSO

INST$()

Returns the name of the specified wavetable synthesizer instrument.

USAGE
name$ = INST$(num)
PARAMETERS

num

instrument number

RETURN VALUE

Instrument name.

If an instrument is not defined in the current sound font, an empty string is returned.

SEE ALSO

PLAY()

Checks if a sound is playing a on wavetable synthesizer channel.

USAGE
p = PLAY(channel)
PARAMETERS

channel

sound channel
[0 to 2, or -1 to check all channels]

RETURN VALUE

1 if sound is playing, 0 otherwise.

SEE ALSO

3.11. System

#REQUIRE

Ensures that a given module is loaded.

USAGE
#REQUIRE "module_name"
PARAMETERS

"module_name"

module name

DESCRIPTION

Checks if a module called module_name has alredy been loaded. If not, it will search for the module in /sys/modules/module_name and load it. If no module is found, it will generate an error.

NOTES

The behavior of #REQUIRE differs from that of other BASIC commands. It is executed as soon as it is spotted by the interpreter, for instance when loading a program.

This means that #REQUIRE will already generate an error when loading a program if the specified module cannot be found.

When executed during normal program flow, #REQUIRE will not do anything.

SEE ALSO

BOOT

Reboots the system.

USAGE
BOOT
NOTES

Only implemented on the H3 platform.

CONFIG COLOR

Changes the color scheme.

DESCRIPTION

The color scheme is a set of colors that are used to print system messages and BASIC program listings. It also contains the default foreground and background colors.

USAGE
CONFIG COLOR col, red, green, blue
PARAMETERS

col

color code [0 to 11]

red

red component [0 to 255]

green

green component [0 to 255]

blue

blue component [0 to 255]

COLOR CODES

0

Default background

1

Default foreground

2

Syntax: BASIC keywords

3

Syntax: line numbers

4

Syntax: numbers

5

Syntax: global variables

6

Syntax: local variables and arguments

7

Syntax: operands

8

Syntax: string constants

9

Syntax: procedure names

10

Syntax: comments

11

Default border color

NOTES
  • Unlike the COLOR command, CONFIG COLOR requires the colors to be given in RGB format; this is to ensure that the color scheme works with all YUV colorspaces.

  • To set the current color scheme as the default, use SAVE CONFIG.

BUGS

The default border color is not used.

SEE ALSO

CONFIG

Changes configuration options.

DESCRIPTION

The options will be reset to their defaults on system startup unless they have been saved using SAVE CONFIG. Changing power-on default options does not affect the system until the options are saved and the system is restarted.

USAGE
CONFIG option, value
PARAMETERS

option

configuration option to be set [0 to 13]

value

option value

OPTIONS

The following options exist:

  • 0: TV norm
    Sets the TV norm to NTSC (0), PAL (1) or PAL60 (2).

    Warning
    This configuration option does not make much sense; the available TV norm depends on the installed color burst crystal and is automatically detected; PAL60 mode is not currently implemented.
    The semantics of this option are therefore likely to change in the future.
  • 1: Keyboard layout
    Four different keyboard layouts are supported:
    0 (Japanese), 1 (US English, default), 2 (German), 3 (French) and 4 (Spanish).

  • 2: Interlacing
    Sets the video output to progressive (0) or interlaced (1). A change in this option will become effective on the next screen mode change.

    Warning
    The intention of this option is to provide an interlaced signal to TVs that do not handle a progressive signal well. So far, no displays have turned up that require it, so it may be removed and/or replaced with a different option in future releases.
  • 3: Luminance low-pass filter
    This option enables (1) or disables (0, default) the video luminance low-pass filter. The recommended setting depends on the properties of the display device used.

    Many recent TVs are able to handle high resolutions well; with such devices, it is recommended to turn the low-pass filter off to achieve a more crisp display.

    On other (usually older) TVs, high-resolution images may cause excessive color artifacting (a "rainbow" effect) or flicker; with such devices, it is recommended to turn the low-pass filter on to reduce these effects, at the expense of sharpness.

  • 4: Power-on screen mode [1 (default) to 10]
    Sets the screen mode the system defaults to at power-on.

  • 5: Power-on screen font [0 (default) to -1]
    Sets the screen font the system defaults to at power-on.

  • 6: Power-on cursor color [0 to 255]
    Sets the cursor color the system defaults to at power-on.

  • 7: Beeper sound volume [0 to 15 (default)]
    Sets the volume of the "beeper" sound engine, which applies, among other things, to the start-up jingle.

  • 8: Screen line adjustment [-128 to 128, default: 0] Adjusts the number of screen lines. A positive value adds lines, a negative value subtracts them.
    This option may be useful to mitigate issues with color artifacting and flicker on some devices.

    Warning
    It is not clear if this option is useful in practice, and it may be removed in future releases.
  • 9: Keyword separation optional [0 (default) or 1]
    Controls if BASIC keywords need to be separated from other language elements containing alphanumeric characters with a space (0), or if they can be adjacent to those like in traditional BASIC dialects (1).

  • 10: Physical screen mode (H3 platform only) [0 (default) to 6]
    Sets the physical screen resolution:
    0 (1920x1080 HDMI), 1 (1280x1024 DVI), 2 (1280x720 HDMI), 3
    (1024x768 DVI), 4 (800x600 DVI), 5 (640x480 DVI) or 6
    (1920x1200 HDMI).
    It is necessary to save the configuration and reboot the system for this option to take effect.

  • 11: Language
    The following languages are supported for system messages:
    0 (US English, default), 1 (German), 2 (French), 3 (Spanish), 4 (Japanese), 5 (Russian).

  • 12: Start screen recording immediately.
    When enabled, screen recording will start as soon as Engine BASIC boots.
    (Only available on platforms that support screen recording.)
    0 enabled, 1 disabled.

  • 13: Name of audio device to be used.
    When set to "default" (which is, unsurprisingly, the default), an appropriate audio device will be chosen automatically. Otherwise, the specified audio device will be used. To find out what audio devices are available you can use the SYS$(1, index) function.

NOTES

To restore the default configuration, run the command REMOVE "/sd/config.ini" and restart the system.

SEE ALSO

CPUSPEED

Sets the CPU clock frequency.

USAGE
CPUSPEED speed
PARAMETERS

speed

CPU speed in percent of maximum.

NOTES
  • Only implemented on the H3 platform.

  • Will not generate an error on platforms that do not support it.

  • When speed is -1 the CPU speed will be reset to the power-on default.

CREDITS

Prints information on Engine BASIC’s components, its authors and licensing conditions.

USAGE
CREDITS

DATE

Prints the current date and time.

Warning
The semantics of this command are not consistent with other BASIC implementations and may be changed in future releases.
USAGE
DATE
SEE ALSO

EDIT

Runs the ASCII text editor.

USAGE
EDIT [file$]
PARAMETERS

file$

name of file to be edited [default: new file]

GET DATE

Get the current date.

USAGE
GET DATE year, month, day, weekday
PARAMETERS

year

numeric variable

month

numeric variable

day

numeric variable

weekday

numeric variable

RETURN VALUE

The current date in the given numeric variables.

BUGS

Only supports scalar variables, not array or list members.

Warning
The syntax and semantics of this command are not consistent with other BASIC implementations and may be changed in future releases.
SEE ALSO

GET TIME

Get the current time.

USAGE
GET TIME hour, minute, second
PARAMETERS

hour

numeric variable

minute

numeric variable

second

numeric variable

RETURN VALUE

The current time in the given numeric variables.

BUGS

Only supports scalar variables, not array or list members.

Warning
The syntax and semantics of this command are not consistent with other BASIC implementations and may be changed in future releases.
SEE ALSO

INSTALL

Installs a packaged module to the system module directory.

USAGE
INSTALL filename$
PARAMETERS

filename$

name of a packaged module file

SEE ALSO

LISTMOD

Shows the names of all modules currently loaded.

USAGE
LISTMOD
SEE ALSO

LOADMOD

Loads a module from the system module directory.

USAGE
LOADMOD module$
PARAMETERS

module$

name of an installed module

SEE ALSO

POKE$

Write a byte string to an address in memory.

USAGE
POKE$ addr, data$
PARAMETERS

addr

memory address

data$

data to be written

NOTES
  • addr must be mapped writable and must allow byte-wise access.

  • When writing a string that is to be used by a C function you have to make sure to add a 0-byte at the end, e.g. "text" + CHR$(0).

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

POKE

Write a byte to an address in memory.

USAGE
POKE addr, value
PARAMETERS

addr

memory address

value

value to be written

NOTES

addr must be mapped writable and must allow byte-wise access.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

POKED

Write a word (32 bits) to an address in memory.

USAGE
POKED addr, value
PARAMETERS

addr

memory address

value

value to be written

NOTES

addr must be mapped writable and must allow half-word-wise access. It must be 4-byte aligned.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

POKEW

Write a half-word (16 bits) to an address in memory.

USAGE
POKEW addr, value
PARAMETERS

addr

memory address

value

value to be written

NOTES

addr must be mapped writable and must allow half-word-wise access. It must be 2-byte aligned.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

PROFILE

Enables or disables the system and procedure profiler.

DESCRIPTION

The system profiler shows a bar in the border of the screen indicating how much CPU time is spent on the various tasks of the grahpics and sound subsystems. It helps in determining the cause of system overloads that lead to graphics and/or sound glitches.

PROFILE ON enables the profiler, PROFILE OFF disables it.

PROFILE ON also enables the procedure profiler that helps determine the number of CPU cycles used in each BASIC procedure. After the program has been run, the results can be viewed using PROFILE LIST.

USAGE
PROFILE <ON|OFF|LIST>
BUGS

It is not possible to switch the system and procedure profiling on and off independently.

SAVE CONFIG

Saves the current set of configuration options as default.

USAGE
SAVE CONFIG
NOTES

The configuration will be saved as a file in the Engine BASIC root directory under the name config.ini.

SEE ALSO

SET DATE

Sets the current date and time.

USAGE
SET DATE year, month, day, hour, minute, second
PARAMETERS

year

numeric expression [1900 to 2036]

month

numeric expression [1 to 12]

day

numeric expression [1 to 31]

hour

numeric expression [0 to 23]

minute

numeric expression [0 to 59]

second

numeric expression [0 to 61]

BUGS

The maximum value for second is 61 and not 59 to accommodate a leap second.

SEE ALSO

SHELL

Runs operating system commands.

USAGE
SHELL [<command>[, <argument> ...]] [OFF]
PARAMETERS

command

command to run

argument

argument to pass to the command

DESCRIPTION

Runs command, or an interactive shell if command is not specified.

command is executed by the operating system shell if there are no argument parameters, allowing shell syntax constructs to be used.

If one or more argument parameters are specified, the command will be executed directly.

If the OFF keyword is added, Engine BASIC will shut down its graphics, sound and input system to allow the executed program to use these facilities.

NOTES
  • command-only commands are executed using execl("/bin/sh", "sh", …​).

  • Commands with argument parameters are executed using execvp("<command>", "<command>", "<argument">, …​).

SYS

Call a machine language routine.

Warning
Using this command incorrectly may crash the system, or worse.
USAGE
SYS addr
PARAMETERS

addr

a memory address mapped as executable

BUGS

No sanity checks are performed on the address.

SYSINFO

Displays internal information about the system.

Warning
This command may be renamed in the future to reduce namespace pollution.
USAGE
SYSINFO
DESCRIPTION

SYSINFO displays the following information:

  • Program size,

  • statistics on scalar, array and list variables, both numeric and string,

  • loop and return stack depths,

  • CPU stack pointer address,

  • free memory size and

  • video timing information (nominal and actual cycles per frame).

WAIT

Pause for a specific amount of time.

USAGE
WAIT ms
PARAMETERS

ms

time in milliseconds

SEE ALSO

XYZZY

Run Z-machine program.

USAGE
XYZZY file_name$
PARAMETERS

file_name$

name of a z-code file

ENVIRON$()

Returns the value of an environment variable.

USAGE
e$ = ENVIRON$(varname$)
PARAMETERS

varname$

name of environment variable

RETURN VALUE

Value of the specified environment variable.

GETSYM()

Returns a pointer to a native symbol.

USAGE
ptr = GETSYM(name$)
PARAMETERS

name$

name of a native symbol

RETURN VALUE

Pointer to requested symbol, or 0 if not found.

PEEK$()

Reads a byte string of data from an address in memory.

USAGE
data$ = PEEK$(addr, length)
PARAMETERS

addr

memory address

length

number of bytes to read, or 0

RETURN VALUE

Byte string containing length bytes of data starting at addr.

NOTES
  • Memory at addr must allow byte-wise access.

  • When length is 0, data is read until a 0-byte is encountered. Use this to read C-style strings.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

PEEK()

Read a byte of data from an address in memory.

USAGE
v = PEEK(addr)
PARAMETERS

addr

memory address

RETURN VALUE

Content of memory address.

NOTES

Memory at addr must allow byte-wise access.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

PEEKD()

Read a word (32 bits) of data from an address in memory.

USAGE
v = PEEKD(addr)
PARAMETERS

addr

memory address

RETURN VALUE

Content of memory address.

NOTES

addr must be 4-byte aligned.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

PEEKW()

Read a half-word (16 bits) of data from an address in memory.

USAGE
v = PEEKW(addr)
PARAMETERS

addr

memory address

RETURN VALUE

Content of memory address.

NOTES

Memory at addr must allow byte-wise access, and addr must be 2-byte aligned.

BUGS

Sanity checks for addr are insufficient.

SEE ALSO

SYS$()

Retrieve internal system addresses and parameters.

USAGE
a = SYS$(item[, index])
PARAMETERS

item

number of the item of information to be retrieved

index

number of the subitem to be retrieved

RETURN VALUE

Requested information.

ITEMS

The following internal information can be retrieved using SYS$():

0

audio device currently used

1

name of the audio device index

NOTES
  • The audio device names provided are only meaningful on LT platforms. Other platforms always return the string "default".

SEE ALSO

SYS

SYS()

Retrieve internal system addresses and parameters.

USAGE
a = SYS(item)
PARAMETERS

item

number of the item of information to be retrieved

RETURN VALUE

Requested information.

ITEMS

The following internal information can be retrieved using SYS():

0

memory address of BASIC program buffer

1

memory address of current font

2

system type; 0 for original (ESP8266), 1 for Shuttle (ESP32), 2 for NG (H3 bare-metal), 3 for LT (Linux/SDL-based), 4 for RX (Linux/bare-metal hybrid), 5 for Windows, 6 for MacOS.

SEE ALSO

TICK()

Returns the elapsed time since power-on.

USAGE
tim = TICK([unit])
PARAMETERS

unit

unit of time [0 for milliseconds, 1 for seconds, default: 0]

RETURN VALUE

Time elapsed.