This manual applies to BASIC Engine Next Generation platforms. 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 all random-access memory residing on the video controller chip.
-
Pixel memory refers to the parts of video 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
|
a numeric or string list variable |
|
a numeric or string expression |
CALL
Calls a procedure.
USAGE
CALL procedure[(argument[, argument ...])]
PARAMETERS
|
name of a procedure declared with |
|
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$().
CHAIN
Loads a new program and runs it, keeping the current set of variables.
USAGE
CHAIN file$[, line_num]
PARAMETERS
|
name of the BASIC program to be executed |
|
line number at which execution will start [default: first line] |
NOTES
Unlike EXEC, CHAIN does not allow returning to the original program.
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
DATA
Specifies values to be read by subsequent READ instructions.
USAGE
DATA expr[, expr...]
PARAMETERS
|
a numeric or string expression |
NOTES
When a DATA instruction is executed, nothing happens.
DELETE
Delete specified line(s) from the BASIC program in memory.
|
Warning
|
Do not confuse with REMOVE, which deletes files.
|
USAGE
DELETE range
PARAMETERS
|
a range of BASIC program lines |
NOTES
-
Using
DELETEdoes not affect variables. -
When called from a running program, execution will continue at the next program line, i.e. instructions following
DELETEon the same line are disregarded.
SEE ALSO
DIM
Declares an array.
USAGE
DIM variable(dimension[, ...]) [= [value, ...]]
PARAMETERS
|
an numeric or string array variable |
|
one or more dimensions of the array |
|
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
|
one or more instructions on one or more lines |
|
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
EXEC
Executes a BASIC program as a child process.
USAGE
EXEC program_file$
PARAMETERS
|
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
|
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.
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
|
a numeric variable used as the loop counter |
|
initial value of the loop counter |
|
amount the counter is changed each time through the loop |
|
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
|
a BASIC program line number |
|
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
GOTO
Branches to a specified line or label.
USAGE
GOTO <line_number|&label>
PARAMETERS
|
a BASIC program line number |
|
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
|
any numeric expression |
|
one or more instructions on one or more lines |
|
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
|
any variable |
|
any expression that is of the same type as |
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
|
name of the BASIC program |
|
font (encoding) used for UTF-8 conversion [ |
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
MERGE
Merge a program in a file with the program currently in memory.
USAGE
MERGE file$[, line_num]
PARAMETERS
|
name of the BASIC program to be merged |
|
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
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
|
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.
ON GOSUB
Call one of several subroutines, depending on the value of an expression.
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
|
any numeric expression |
|
a BASIC program line number |
|
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.
PREPEND
Adds an element to the start of a list.
USAGE
PREPEND list, value
PARAMETERS
|
a numeric or string list variable |
|
a numeric or string expression |
Prints data to the current output device (usually the screen) or to a given file.
USAGE
PRINT [#file_num, ][*expressions*][<;|,>]
PARAMETERS
|
file number to be printed to [ |
|
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 columnnum)
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.
PROC
Define a procedure or function.
USAGE
PROC name[(<num_arg|str_arg$>[, <num_arg|str_arg$> ...])]
PARAMETERS
|
procedure name |
|
name of a numeric argument variable |
|
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.
READ
Reads values specified in DATA instructions and assigns them to variables.
USAGE
READ var[, var...]
PARAMETERS
|
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.
RENUM
Renumber BASIC program in memory.
USAGE
RENUM [<start>[, <step>]]
PARAMETERS
|
new line number to start at [min |
|
line number increment [min |
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
|
a label or line number [default: start of program] |
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
|
numeric expression |
|
string expression |
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
|
name of the BASIC program to be loaded and run |
|
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. UseCHAINinstead.
SAVE
Saves the BASIC program in memory to a file.
USAGE
SAVE file$
PARAMETERS
|
name of file to be saved |
NOTES
BASIC programs are saved in plain text (UTF-8) format.
SEE ALSO
STOP
Halts the program.
A program stopped by a STOP command can be resumed using CONT.
USAGE
STOP
SEE ALSO
WHILE
Executes a series of instructions as long as a specified condition is "true".
USAGE
WHILE condition
PARAMETERS
|
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
|
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.
ARG()
Returns a numeric argument passed to a procedure.
USAGE
a = ARG(num)
PARAMETERS
|
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.
ARGC()
Returns the argument count for numeric and string variables passed to a procedure.
USAGE
cnt = ARGC(typ)
PARAMETERS
|
type of argument [ |
RETURN VALUE
Argument count.
NOTES
Returns 0 if called outside a procedure.
ASC()
Returns the Unicode codepoint for the first character in a string expression.
USAGE
val = ASC(s$)
PARAMETERS
|
string expression |
RETURN VALUE
Unicode codepoint of the first character.
ERRORS
Generates an error if s$ is empty.
NOTES
-
Unlike its counterparts in single-byte BASIC implementations, 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
|
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
|
any string expression |
|
number of bytes to return [min |
RETURN VALUE
Substring of num bytes or less.
NOTES
If l$ is shorter than num bytes, the return value is l$.
BLEN()
Returns the number of bytes in a byte string.
USAGE
sl = BLEN(string$)
PARAMETERS
|
any string expression |
RETURN VALUE
Length in bytes.
BMID$()
Returns part of a byte string.
USAGE
s$ = BMID$(m$, start[, len])
PARAMETERS
|
any string expression |
|
position of the first byte in the substring being returned |
|
number of bytes in the substring [default: |
RETURN VALUE
Substring of len bytes or less.
NOTES
-
If
m$is shorter thanlenbytes, the return value ism$. -
Unlike with other BASIC implementations,
startis 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
|
any string expression |
|
number of bytes to return [min |
RETURN VALUE
Substring of num bytes or less.
NOTES
If r$ is shorter than num bytes, the return value is r$.
CHR$()
Returns a string containing the UTF-8 encoding of the specified Unicode codepoint.
USAGE
char = CHR$(val)
PARAMETERS
|
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
|
error number [ |
RETURN VALUE
Error message.
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
|
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
|
string in which to search |
|
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
|
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
|
any string expression |
|
number of characters to return [min |
RETURN VALUE
Substring of num characters or less.
NOTES
If l$ is shorter than num characters, the return value is l$.
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
|
any string expression |
|
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
|
value to be re-mapped |
|
lower bound of the value’s current range |
|
upper bound of the value’s current range |
|
lower bound of the value’s target range |
|
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
|
any string expression |
|
position of the first character in the substring being returned |
|
number of characters in the substring [default: |
RETURN VALUE
Substring of len characters or less.
NOTES
-
If
m$is shorter thanlencharacters, the return value ism$. -
Unlike with other BASIC implementations,
startis 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.
POPB$()
Remove an element from the end of a string list.
USAGE
e$ = POPB$(~list$)
PARAMETERS
|
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
|
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
|
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
|
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
|
number of the string return value [ |
RETURN VALUE
String return value requested.
RET()
Returns one of the numeric return values of the last function call.
USAGE
rval = RET(num)
PARAMETERS
|
number of the numeric return value [ |
RETURN VALUE
Requested return value.
RIGHT$()
Returns a specified number of rightmost characters in a string.
USAGE
s$ = RIGHT$(r$, num)
PARAMETERS
|
any string expression |
|
number of characters to return [min |
RETURN VALUE
Substring of num characters or less.
NOTES
If r$ is shorter than num characters, the return value is r$.
STR$()
Returns a string representation of a number.
USAGE
s$ = STR$(num)
PARAMETERS
|
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
|
number of characters [at least |
|
any non-empty string expression |
NOTES
-
If
char$contains more than one character, only the first will be considered. -
If
countis0, 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
|
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
|
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
|
name of a procedure declared with |
|
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:
DEF FN f(x) = x * 2
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
|
any numeric expression |
RETURN VALUE
Absolute value of num.
ATN2()
Arc tangent function of two variables.
USAGE
a2 = ATN2(x, y)
PARAMETERS
|
any numeric expression |
|
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
|
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
|
an angle expressed in radians |
RETURN VALUE
Cosine of angle.
EXP()
Returns e raised to a specified power, where e is the base of natural logarithms.
USAGE
ex = EXP(pow)
PARAMETERS
|
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
|
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
|
any numeric expression |
RETURN VALUE
The natural logarithm of num.
RND()
Returns a random number.
USAGE
r = RND(mod)
PARAMETERS
|
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:
|
a random integer number between 0 and 2147483647 |
|
a random fractional number between 0 and 1 |
|
A random fractional number between 0 and 1. A specific
value of |
SGN()
Returns a value indicating the sign of a numeric expression.
USAGE
s = SGN(num)
PARAMETERS
|
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
|
an angle expressed in radians |
RETURN VALUE
Sine of angle.
SQR()
Square root function.
USAGE
s = SQR(num)
PARAMETERS
|
any numeric expression larger than or equal to |
RETURN VALUE
The nonnegative square root of num.
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 number [ |
|
pin number [ |
|
pin mode [ |
NOTES
-
This command is only implemented on the H3 platform.
-
A
modevalue of0or1configures the pin as a general-purpose input or output, respectively. A value of7disables 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.
GPOUT
Sets the state of a general-purpose I/O pin.
USAGE
GPOUT pin, value (ESP8266)
GPOUT port, pin, value (H3)
PARAMETERS
|
port number [ |
|
pin number [ |
|
pin state [ |
NOTES
-
This command is only implemented on the ESP8266 and H3 platforms.
-
On the ESP8266 platform,
GPOUTallows access to pins on the I2C I/O extender only.
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
|
number of the game controller [ |
|
a procedure defined with |
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 rate [ |
|
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
|
data bit order [ |
|
transfer frequency in Hz |
|
SPI mode [ |
SPIW
Sends data to an SPI device.
USAGE
SPIW out$
PARAMETERS
|
data to be transmitted |
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
|
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
|
port number [ |
|
pin number [ |
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.
I2CR()
Request data from I2C device.
USAGE
in$ = I2CR(i2c_addr, out_data, read_length)
PARAMETERS
|
I2C address [ |
|
data to be transmitted |
|
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 address [ |
|
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
|
Key code [ |
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
|
number of mouse button [ |
RETURN VALUE
1 if the mouse button is held, 0 if it is not.
BUTTONS
| Number | Mouse button |
|---|---|
|
Left button |
|
Right button |
|
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
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
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
MOUSEY()
Absolute vertical coordinate of the mouse cursor.
USAGE
y = MOUSEY
RETURN VALUE
Y coordinate of mouse cursor, from 0 to PSIZE(1)-1
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
|
Number of the game controller: |
|
|
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 |
|---|---|---|
|
◄ button |
Left key |
|
▼ button |
Down key |
|
► button |
Right key |
|
▲ button |
Up key |
|
Start button |
n/a |
|
Select button |
n/a |
|
□ button |
Z key |
|
✕ button |
X key |
|
○ button |
S key |
|
△ button |
A key |
|
R1 button |
n/a |
|
L1 button |
n/a |
|
R2 button |
n/a |
|
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.
|
SPIRW$()
Send and receive data to and from an SPI device.
USAGE
in$ = SPIRW$(out$)
PARAMETERS
|
data to be transmitted |
RETURN VALUE
Returns a string containing the received data that is of the same length as out$.
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
3.6. File System
BLOAD
Loads a binary file to memory.
USAGE
BLOAD file$ TO addr[, len]
PARAMETERS
|
name of binary file |
|
memory address to be loaded to |
|
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
|
name of binary file |
|
memory start address |
|
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
|
path to the new current directory |
SEE ALSO
CLOSE
Closes an open file or directory.
USAGE
CLOSE [#]file_num
PARAMETERS
|
number of an open file or directory [ |
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
|
number of an open file to redirect to [ |
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.
COPY
Copies a file.
USAGE
COPY file$ TO new_file$
PARAMETERS
|
file to be copied |
|
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
|
a filename or path, may include wildcard characters |
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
|
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
|
path to the new directory |
OPEN
Opens a file or directory.
USAGE
OPEN file$ [FOR <INPUT|OUTPUT|APPEND|DIRECTORY>] AS [#]file_num
PARAMETERS
|
name of the file or directory |
|
file number to be used [ |
MODES
-
INPUTopens the file for reading. (This is the default if no mode is specified.) -
OUTPUTempties the file and opens it for writing. -
APPENDopens the file for writing while keeping its content. -
DIRECTORYopensfile$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 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
|
current file name |
|
new file name |
BUGS
Does not support wildcard patterns.
RMDIR
Deletes a directory.
USAGE
RMDIR directory$
PARAMETERS
|
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
|
number of an open file [ |
|
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.
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
|
name of the file |
COMPARE()
Compares two files.
USAGE
result = COMPARE(file1$, file2$)
PARAMETERS
|
name of first file to compare |
|
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
|
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
|
number of an open file [ |
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
|
number of bytes to read |
|
number of an open file [ |
RETURN VALUE
Data read from file.
SEE ALSO
LOC()
Returns the current position within a file.
USAGE
l = LOC(file_num)
PARAMETERS
|
number of an open file [ |
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
|
number of an open file [ |
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
|
background number [ |
|
background map width, in tiles |
|
background map height, in tiles |
|
tile set X coordinate, pixels [ |
|
tile set Y coordinate, pixels [ |
|
tile width, pixels [ |
|
tile height, pixels [ |
|
window X coordinate, pixels [ |
|
window Y coordinate, pixels [ |
|
window width, pixels [ |
|
window height, pixels [ |
|
Background priority [ |
NOTES
-
The
BGcommand’s attributes can be specified in any order, but it is usually a good idea to place theONattribute at the end if used. -
A background cannot be turned on unless at least the
TILESattribute is set. In order to get sensible output, it will probably be necessary to specify thePATTERNattribute as well.
BUGS
If a background cannot be turned on, no error is generated.
SEE ALSO
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
|
number of frames to be skipped [ |
NOTES
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.
LOAD BG
Loads a background map from a file.
USAGE
LOAD BG bg, file$
PARAMETERS
|
background number. [ |
|
name of background map file |
SEE ALSO
LOAD FONT
Loads a TrueType font from a file.
USAGE
LOAD FONT file$
PARAMETERS
|
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
|
background number [ |
|
top/left corner offset horizontal, pixels |
|
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
MOVE SPRITE
Moves a sprite.
USAGE
MOVE SPRITE num TO pos_x, pos_y
PARAMETERS
|
Sprite number [ |
|
Sprite position X coordinate, pixels |
|
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
|
a procedure defined with |
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. |
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
|
background number [ |
|
tile number to remap [ |
|
tile number to map to [ |
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
|
background number [ |
|
tile X coordinate [ |
|
tile Y coordinate [ |
|
tile identifier [ |
|
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.
SAVE BG
Saves a background map to a file.
USAGE
SAVE BG bg TO file$
PARAMETERS
|
background number. [ |
|
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
|
X coordinate of the top/left sprite pattern, pixels |
|
Y coordinate of the top/left sprite pattern, pixels |
|
sprite width, pixels [ |
|
sprite height, pixels [ |
|
X coordinate of the pattern section to be used, in multiples of sprite width |
|
Y coordinate of the pattern section to be used, in multiples of sprite height |
|
special effect flags [ |
|
key color value to be used for transparency masking |
|
sprite priority in relation to background layers |
|
rotation angle in degrees [default |
|
horizontal scaling factor [default |
|
vertical scaling factor [default |
|
sprite opacity [ |
FLAGS
The FLAGS attribute is the sum of any of the following bit values:
| Bit value | Effect |
|---|---|
|
Sprite opacity (opaque if set) |
|
Horizontal flip |
|
Vertical flip |
NOTES
-
The
SPRITEcommand’s attributes can be specified in any order, but it is usually a good idea to place theONattribute at the end if used. -
The
ALPHAattribute 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.
SEE ALSO
BSCRX()
Returns the horizontal scrolling offset of a given background layer.
USAGE
p = BSCRX(bg)
PARAMETERS
|
background number [ |
RETURN VALUE
X scrolling offset of background bg.
BSCRY()
Returns the vertical scrolling offset of a given background layer.
USAGE
p = BSCRY(bg)
PARAMETERS
|
background number [ |
RETURN VALUE
Y scrolling offset of background bg.
SPRCOLL()
Checks if a sprite has collided with another sprite.
USAGE
res = SPRCOLL(spr1, spr2)
PARAMETERS
|
sprite number 1 [ |
|
sprite number 2 [ |
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 |
|---|---|
|
Sprite 2 is left of sprite 1. |
|
Sprite 2 is below sprite 1. |
|
Sprite 2 is right of sprite 1. |
|
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
|
sprite number [ |
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
|
sprite number [ |
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
|
sprite number [ |
RETURN VALUE
X coordinate of sprite spr.
SEE ALSO
SPRY()
Returns the vertical position of a given sprite.
USAGE
p = SPRY(spr)
PARAMETERS
|
sprite number [ |
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
|
sprite number [ |
|
background number [ |
|
tile number [ |
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 |
|---|---|
|
The tile is left of the sprite. |
|
The tile is below the sprite. |
|
The tile is right of the sprite. |
|
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
|
source area, X coordinate [ |
|
source area, Y coordinate [ |
|
destination area, X coordinate [ |
|
destination area, Y coordinate [ |
|
area width [ |
|
area height [ |
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 coordinate of the circle’s center |
|
Y coordinate of the circle’s center |
|
circle’s radius |
|
color of the circle’s outline [range depends on color space] |
|
color of the circle’s body |
BUGS
-
fill_colorcannot be omitted.
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
|
start point, X coordinate, pixels [ |
|
start point, Y coordinate, pixels [ |
|
|
NOTES
-
The expression list functions as it does in the
PRINTcommand. -
The "new line" character that is generally appended at the end of a
PRINTcommand is drawn literally byGPRINT, 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
|
start of the screen region, X coordinate, pixels [ |
|
start of the screen region, Y coordinate, pixels [ |
|
end of the screen region, X coordinate, pixels [ |
|
end of the screen region, Y coordinate, pixels [ |
|
direction |
DIRECTION
Valid values for direction are:
|
up |
|
down |
|
left |
|
right |
LINE
Draws a line.
USAGE
LINE x1_coord, y1_coord, x2_coord, y2_coord[, color]
PARAMETERS
|
X coordinate of the line’s starting point |
|
Y coordinate of the line’s starting point |
|
X coordinate of the line’s end point |
|
Y coordinate of the line’s end point |
|
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.
PSET
Draws a pixel.
USAGE
PSET x_coord, y_coord, color
PARAMETERS
|
X coordinate of the pixel |
|
Y coordinate of the pixel |
|
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
|
X coordinate of the rectangle’s top/left corner |
|
Y coordinate of the rectangle’s top/left corner |
|
X coordinate of the rectangle’s bottom/right corner |
|
Y coordinate of the rectangle’s bottom/right corner |
|
color of the rectangle’s outline |
|
color of the rectangle’s body |
BUGS
-
fill_colorcannot be omitted.
POINT()
Returns the color of the pixel at the given coordinates.
USAGE
px = POINT(x, y)
PARAMETERS
|
X coordinate, pixels [ |
|
Y coordinate, pixels [ |
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 component of the border color [ |
|
Y component of the border color [ |
|
first column to set [default: |
|
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 coordinate, characters [ |
|
Y coordinate, characters [ |
|
character [ |
NOTES
This command does nothing if the coordinates are outside the screen limits.
COLOR
Changes the foreground and background color for text output.
USAGE
COLOR fg_color[, bg_color [, cursor_color]]
PARAMETERS
|
foreground color [range depends on color space] |
|
background color [range depends on color space, default: |
|
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
|
start of the screen region, X coordinate, characters [ |
|
start of the screen region, Y coordinate, characters [ |
|
end of the screen region, X coordinate, characters [ |
|
end of the screen region, Y coordinate, characters [ |
|
direction |
DIRECTION
Valid values for direction are:
|
up |
|
down |
|
left |
|
right |
BUGS
Colors are lost when scrolling.
FONT
Sets the current text font.
USAGE
FONT font_num
FONT font_name$ SIZE width, height
PARAMETERS
|
font number |
|
font name |
|
font width (pixels) |
|
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
CONFIGcommand.
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
|
background number [ |
|
sprite range [limits between |
|
X-coordinate of destination, pixels |
|
Y-coordinate of destination, pixels |
|
offset within image file, X axis, pixels [default: |
|
offset within image file, Y axis, pixels [default: |
|
width of image portion to be loaded, pixels [default: image width] |
|
height of image portion to be loaded, pixels [default: image height] |
|
color key for transparency [default: no transparency] |
|
scaling factor [default: |
|
scaling factor [default: |
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
|
cursor X coordinate |
|
cursor Y coordinate |
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
|
colorspace number [ |
|
hue weight for color conversion [ |
|
saturation weight for color conversion [ |
|
value weight for color conversion [ |
|
conversion fix-ups enabled [ |
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.
REDRAW
Redraw the text screen.
DESCRIPTION
Overwrites anything displayed on-screen with the characters stored in the text buffer.
USAGE
REDRAW
SEE ALSO
SAVE IMAGE
Saves a portion of pixel memory as an image file.
USAGE
SAVE IMAGE image$ [POS x, y] [SIZE w, h]
PARAMETERS
|
name of image file to be created |
|
left of pixel memory section, pixels |
|
top of pixel memory section, pixels |
|
width of pixel memory section, pixels |
|
height of pixel memory section, pixels |
SEE ALSO
SCREEN
Change the screen resolution.
USAGE
SCREEN mode
PARAMETERS
|
screen mode [ |
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.) |
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,
SCREENclears the screen, resets the font and color space (palette) to their defaults, and disables sprites and tiled backgrounds.
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
|
video memory address [ |
|
numeric value [ |
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
|
video controller register number |
|
value [ |
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:
|
3 values |
|
no value |
|
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 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
-
This command will not wait if frame
f+1has 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
|
left boundary of the text window, in characters |
|
top boundary of the text window, in characters |
|
width of the text window, in characters |
|
height of the text window, in characters |
SEE ALSO
CHAR()
Returns the text character on screen at a given position.
USAGE
c = CHAR(x, y)
PARAMETERS
|
X coordinate, characters |
|
Y coordinate, characters |
RETURN VALUE
Character code.
NOTES
-
If the coordinates exceed the dimensions of the text screen,
0will 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.
CSIZE()
Returns the dimensions of the current screen mode in text characters.
USAGE
size = CSIZE(dimension)
PARAMETERS
|
requested screen dimension: |
RETURN VALUE
Size in characters.
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
|
requested axis: |
RETURN VALUE
Position in characters.
PSIZE()
Returns the dimensions of the current screen mode in pixels.
USAGE
size = PSIZE(dimension)
PARAMETERS
|
requested screen dimension: |
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 component [0 to 255] |
|
green component [0 to 255] |
|
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.
VPEEK()
Read a location in video memory.
USAGE
v = VPEEK(video_addr)
PARAMETERS
|
Byte address in video memory. [ |
RETURN VALUE
Memory content.
VREG()
Read a video controller register.
USAGE
v = VREG(reg)
PARAMETERS
|
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
|
tone cycle period in samples [ |
|
tone volume |
|
volume envelope
[characters from |
NOTES
The maximum value for period depends on the flavor of Engine BASIC;
it’s 320 for the gaming build, and 160 for the network build.
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
|
a sound channel [ |
|
a procedure defined with |
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.
PLAY
Plays a piece of music in Music Macro Language (MML) using the wavetable synthesizer.
USAGE
PLAY [ch, ]mml$
PARAMETERS
|
sound channel [ |
|
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
|
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
|
sound channel [ |
|
instrument number |
|
note pitch |
|
note duration, milliseconds [default: |
|
note velocity [ |
SEE ALSO
INST$()
Returns the name of the specified wavetable synthesizer instrument.
USAGE
name$ = INST$(num)
PARAMETERS
|
instrument number |
RETURN VALUE
Instrument name.
If an instrument is not defined in the current sound font, an empty string is returned.
SEE ALSO
3.11. System
#REQUIRE
Ensures that a given module is loaded.
USAGE
#REQUIRE "module_name"
PARAMETERS
|
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.
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
|
color code [ |
|
red component [0 to 255] |
|
green component [0 to 255] |
|
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
COLORcommand,CONFIG COLORrequires 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
|
configuration option to be set [ |
|
option value |
OPTIONS
The following options exist:
-
0: TV norm
Sets the TV norm to NTSC (0), PAL (1) or PAL60 (2).WarningThis 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) and4(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.WarningThe 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) to10]
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 [0to255]
Sets the cursor color the system defaults to at power-on. -
7: Beeper sound volume [0to15(default)]
Sets the volume of the "beeper" sound engine, which applies, among other things, to the start-up jingle. -
8: Screen line adjustment [-128to128, 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.WarningIt is not clear if this option is useful in practice, and it may be removed in future releases. -
9: Keyword separation optional [0(default) or1]
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) to6]
Sets the physical screen resolution:
0(1920x1080 HDMI),1(1280x1024 DVI),2(1280x720 HDMI),3
(1024x768 DVI),4(800x600 DVI),5(640x480 DVI) or6
(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).
NOTES
To restore the default configuration, run the command REMOVE
"/sd/config.ini" and restart the system.
BUGS
-
Changing the low-pass filter option (
3) only takes effect at the time of the next block move, which happens for instance when scrolling the screen. -
There is no way to override a saved configuration, which may make it difficult or even impossible to fix an system configured to an unusable state.
SEE ALSO
CPUSPEED
Sets the CPU clock frequency.
USAGE
CPUSPEED speed
PARAMETERS
|
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
speedis-1the 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
EDIT
Runs the ASCII text editor.
USAGE
EDIT [file$]
PARAMETERS
|
name of file to be edited [default: new file] |
GET DATE
Get the current date.
USAGE
GET DATE year, month, day, weekday
PARAMETERS
|
numeric variable |
|
numeric variable |
|
numeric variable |
|
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. |
GET TIME
Get the current time.
USAGE
GET TIME hour, minute, second
PARAMETERS
|
numeric variable |
|
numeric variable |
|
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
|
name of a packaged module file |
LOADMOD
Loads a module from the system module directory.
USAGE
LOADMOD module$
PARAMETERS
|
name of an installed module |
POKE$
Write a byte string to an address in memory.
USAGE
POKE$ addr, data$
PARAMETERS
|
memory address |
|
data to be written |
NOTES
-
addrmust 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.
POKE
Write a byte to an address in memory.
USAGE
POKE addr, value
PARAMETERS
|
memory address |
|
value to be written |
NOTES
addr must be mapped writable and must allow byte-wise access.
BUGS
Sanity checks for addr are insufficient.
POKED
Write a word (32 bits) to an address in memory.
USAGE
POKED addr, value
PARAMETERS
|
memory address |
|
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.
POKEW
Write a half-word (16 bits) to an address in memory.
USAGE
POKEW addr, value
PARAMETERS
|
memory address |
|
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.
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 under the name /flash/.config.
SEE ALSO
SET DATE
Sets the current date and time.
USAGE
SET DATE year, month, day, hour, minute, second
PARAMETERS
|
numeric expression [ |
|
numeric expression [ |
|
numeric expression [ |
|
numeric expression [ |
|
numeric expression [ |
|
numeric expression [ |
BUGS
It is unclear why the maximum value for second is 61 and not 59.
SYS
Call a machine language routine.
|
Warning
|
Using this command incorrectly may crash the system, or worse. |
USAGE
SYS addr
PARAMETERS
|
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
|
time in milliseconds |
SEE ALSO
XYZZY
Run Z-machine program.
USAGE
XYZZY file_name$
PARAMETERS
|
name of a z-code file |
ENVIRON$()
Returns the value of an environment variable.
USAGE
e$ = ENVIRON$(varname$)
PARAMETERS
|
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 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
|
memory address |
|
number of bytes to read, or 0 |
RETURN VALUE
Byte string containing length bytes of data starting at addr.
NOTES
-
Memory at
addrmust allow byte-wise access. -
When
lengthis0, data is read until a0-byte is encountered. Use this to read C-style strings.
BUGS
Sanity checks for addr are insufficient.
PEEK()
Read a byte of data from an address in memory.
USAGE
v = PEEK(addr)
PARAMETERS
|
memory address |
RETURN VALUE
Content of memory address.
NOTES
Memory at addr must allow byte-wise access.
BUGS
Sanity checks for addr are insufficient.
PEEKD()
Read a word (32 bits) of data from an address in memory.
USAGE
v = PEEKD(addr)
PARAMETERS
|
memory address |
RETURN VALUE
Content of memory address.
NOTES
addr must be 4-byte aligned.
BUGS
Sanity checks for addr are insufficient.
PEEKW()
Read a half-word (16 bits) of data from an address in memory.
USAGE
v = PEEKW(addr)
PARAMETERS
|
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.
SYS()
Retrieve internal system addresses and parameters.
USAGE
a = SYS(item)
PARAMETERS
|
number of the item of information to be retrieved |
RETURN VALUE
Requested information.
ITEMS
The following internal information can be retrieved using SYS():
|
memory address of BASIC program buffer |
|
memory address of current font |
|
system type; |
TICK()
Returns the elapsed time since power-on.
USAGE
tim = TICK([unit])
PARAMETERS
|
unit of time [ |
RETURN VALUE
Time elapsed.