Engine BASIC Reference Manual

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

ARG(), ARG$(), ARGC(), FN, PROC

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

EXEC, LOAD

NEW

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.

BG, STOP, WINDOW

When a DATA statement is executed, nothing happens.

READ, RESTORE

REMOVE

Initialization is only possible for one-dimensional arrays.

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 statement following the LOOP command.

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

IF

ENDIF

IF

ON ERROR

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:

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

CHAIN

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.

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

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

CALL, ON GOSUB, PROC, RETURN

It is recommended to use GOTO sparingly as it tends to make programs more difficult to understand. If possible, use loop constructs and procedure calls instead.

ON GOTO

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

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 BG, LOAD PCX, SAVE

DO

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

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

CHAIN

CLEAR, DELETE

FOR

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 run with EXEC, the line number of the sub-program in which the error has been triggered is passed in RET(2).

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 there will be forwarded to the calling program’s error handler, if there is one.

EXEC, RESUME

ON GOTO, GOSUB

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

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

GOTO, GOSUB

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

Expressions have to be separated by either a semicolon (;) or a comma (,). The former concatenates expressions directly, while the later inserts spaces until the next tabulator stop is reached.

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

CMD, GPRINT

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.

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

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

CALL, FN, RETURN

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.

DATA, RESTORE

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

DATA, READ

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

In other BASIC implementations, RESUME will retry the statement that has caused the error, while continuing after the error is possible using RESUME NEXT. In Engine BASIC, RESUME will always skip the statement that generated the error.

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

ON ERROR

CALL, FN, GOSUB, PROC

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.

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.

CHAIN, CLEAR, EXEC, GOTO, LOAD

BASIC programs are saved in plain text (ASCII) format.

SAVE BG, SAVE CONFIG, SAVE PCX

CONT

WHILE

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

If condition is "true", the statements following the WHILE statement will be executed, until the corresponding WEND statement 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.

LOOP

Argument value.

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.

ARG(), ARGC()

Argument value.

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.

ARG$(), ARGC()

Argument count.

Returns 0 if called outside a procedure.

CALL, FN

ASCII code of the first character.

Generates an error if s$ is empty.

CHR$()

Binary number as text.

HEX$()

Single-character string.

ASC()

Error message.

ON ERROR, RET()

Number of bytes free.

Hexadecimal number as text.

BIN$()

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

Substring of at most the length specified in num.

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

MID$(), RIGHT$()

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

Re-mapped value.

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

Substring of at most len characters.

MID$() cannot be used as the target of an assignment, as is possible in other BASIC implementations.

LEFT$(), LEN(), RIGHT$()

Value of the element removed.

An error is generated if ~list$ is empty.

POPF$()

Value of the element removed.

An error is generated if ~list is empty.

POPF()

Value of the element removed.

An error is generated if ~list$ is empty.

POPB$()

Value of the element removed.

An error is generated if ~list is empty.

POPB()

String return value requested.

RET(), RETURN

Requested return value.

RETURN, RET$()

Substring of at most num characters.

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

LEFT$(), MID$()

String representation of num.

VAL()

Numeric value of num$.

STR$()

First return value of called procedure.

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:

CALL

Returns either

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

INKEY$ is not consistent with the Engine BASIC convention of following functions with parentheses to distinguish them from constants and variables in order to remain compatible with other BASIC implementations.

INKEY()

Absolute value of num.

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.

Arc tangent of y/x.

ATN()

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

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

ATN2()

Cosine of angle.

SIN(), TAN()

Exponential value of pow.

num rounded down to the nearest integer.

The natural logarithm of num.

A random number of the selected type.

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

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

Sine of angle.

COS(), TAN()

The nonnegative square root of num.

Tangent of angle.

COS(), SIN()

Product of a and b.

3

a.

This operator serves decorative purposes only.

2

Sum of a and b.

4

The negative of a.

2

Difference of a and b.

4

Quotient of a and b.

3

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

5

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

3

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

6

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

5

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

6

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

5

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

6

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

5

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

6

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

6

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

3

Bitwise conjunction of a and b.

7

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

Bitwise exclusive disjunction of a and b.

8

Remainder of division of a and b.

3

Bitwise inversion of a.

7

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

Bitwise inclusive disjunction of a and b.

8

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

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

6

a raised to the power of b.

1

Concatenation of a$ and b$.

GPOUT allows access to pins on the I2C I/O extender only.

GPIN()

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.

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.

PAD()

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

SWRITE

SMODE

Analog value read.

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

GPIN() allows access to pins on the I2C I/O extender only.

GPOUT

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

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

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

I2CW()

Status code of the transmission.

I2CR()

Key code [0 to 65535]

INKEY$

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 codes are fixed and do not change with the configured keyboard layout.

PAD()

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.

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

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:

ON PAD, KEY(), UP, DOWN, LEFT, RIGHT

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

SREADY()

Number of bytes available to read.

SREAD()

PAD(), UP, LEFT, RIGHT

PAD(), UP, DOWN, RIGHT

PAD(), UP, DOWN, LEFT

PAD(), DOWN, LEFT, RIGHT

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.

BSAVE

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.

BLOAD

CWD$()

OPEN

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.

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.

OPEN, CLOSE

Does not support wildcard patterns.

CHDIR, CWD$()

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

CLOSE, DIR$(), [INPUT], INPUT$(), PRINT, SEEK

Does not support wildcard patterns.

DELETE

Does not support wildcard patterns.

Does not support wildcard patterns.

MKDIR

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

[INPUT], INPUT$(), PRINT

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

Current working directory.

CHDIR

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.

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

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

Data read from file.

[INPUT]

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

Length of file.

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.

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

LOAD BG, LOAD PCX, MOVE BG, SAVE BG

It is not possible to mitigate flickering caused by overloading the graphics engine using FRAMESKIP because each frame that is actually rendered must be so within a single TV frame.

SAVE BG

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

BG

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.

SPRITE

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

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.

PROC, SPRCOLL()

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.

PLOT

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.

BG, PLOT MAP

Does not check if the specified background is properly defined.

LOAD BG

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.

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

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.

LOAD PCX, MOVE SPRITE

X scrolling offset of background bg.

BG, BSCRY()

Y scrolling offset of background bg.

BG, BSCRX()

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:

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.

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

TILECOLL()

X coordinate of sprite spr.

MOVE SPRITE, SPRY()

Y coordinate of sprite spr.

MOVE SPRITE, SPRX()

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:

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.

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

SPRCOLL()

GSCROLL

Coordinates that exceed the valid pixel memory area will be clamped.

fill_color cannot be omitted.

PSIZE(), RGB()

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

PRINT

Valid values for direction are: