NextBASIC

NextBASIC is an extended version of the classic Spectrum BASIC which adds extra commands supporting the new features of the NEXT.

? after parameters indicate they are optional. Square brackets [] indicate scope of optional or repeated areas (parenthesis are not used for this because they are part of the BASIC language). Bracketed sections in the effects only apply if the optional parameters are specified.

Basic Interaction Commands

Command	Effect
BANK b LINE x,y	Copies lines x,y into bank b. Once this is done, these lines cannot be edited except by overwriting them with another BANK..LINE command. Cannot be used in a program.
BANK b LIST x?	Lists source code in bank b (from line x)
BANK b MERGE	Adds all basic lines in bank b to main program
CONTINUE	Repeats last command or restarts from error location
CLEAR x?	Resets variables, clears screen, resets plot cursor (and sets ramtop to X)
ERASE f, l	Deletes all program lines between f and l. Cannot be used in a program.
LIST x?	Lists source code (from line x)
LLIST x?	Lists source code to printer (from line x)
NEW	Clear stored program
RUN x?	CLEAR then run program (from line x)

Control Flow

Command	Effect
BANK b GO TO x	Jump execution to line x stored in bank b. b=-1 for main program
BANK b GO SUB x	Jump execution to line x stored in bank b, storing current location on gosub stack. b=-1 for main program
DEF FN func(param[,param..])=expr	Creates a user defined function based on a parameterised expression. Will not work if moved into any bank other than the main program
DIM a(x[,y]..)	Defines a as an array of length x (and second dimension length y, etc..)
FOR var = start TO end [STEP step]?	Starts FOR loop between given numeric values (with given step)
GO TO x	Jump execution to line X in the same bank
GO SUB x	Jump execution to line X in the same bank, storing current location (and bank) on gosub stack
IF c THEN statements..	Run statements only if expression c is true
LET var = expr	Sets variable var to expr
NEXT var	Marks end of FOR loop regarding VAR
REM comment	Code comment, ignored
RETURN	Restore execution location (line and bank) from gosub stack

Console I/O

Command	Effect
COPY	Prints screen
INKEY$	Returns currently pressed key
INPUT specifier [connector specifier]..	Output expression(s) and read a variable
INVERSE x	Enable or disable switching ink/paper color when printing (x=0 or 1)
LPRINT specifier [connector specifier]..	Output expression(s) to printer
OVER x	Enable or disable overprinting (x=0 or 1)
PAUSE x	Waits x frames or until a key is pressed
PRINT specifier [connector specifier]..	Output expression(s)

Possible specifiers for PRINT and INPUT statements are:

Specifier	Effect
var	In PRINT, shows contents of var; in INPUT, inputs into this var
(var)	Shows contents of var (in both PRINT and INPUT)
AT x,y	Moves text cursor to the given text cell
TAB x	Inserts spaces until text cursor is in column x
INK x, PAPER x	Changes the appropriate color for the duration of the print/input statement
LINE x$	INPUT only, reads a string without the prompting quotes
#x	Selects input/output channel number

And the connectors between these are:

Specifier	Effect
,	Separate with a tab
'	Separate with a newline
;	Use no separator

File I/O

Command	Effect
CAT	Displays disk/tape catalogue
FORMAT	Prepares inserted disk for usage, erasing it
LOAD fn	Load BASIC program from file named fn
LOAD fn DATA x()	Load data from fn into array x()
LOAD fn CODE addr	Load data from fn into memory at address addr
LOAD fn SCREEN$	Load data from fn onto standard ULA screen
LOAD fn BANK b,addr	Load data from fn into memory bank b at addr
LOAD fn LAYER	Load data from fn onto current layer
MERGE fn	Loads BASIC lines from file named fn and integrates them with current program
SAVE fn (LINE l)?	Save BASIC program to file named fn (and set up autorun at line l)
SAVE fn (DATA/CODE/SCREEN$/BANK/LAYER..)	Save data as specified; CODE and BANK have an extra "length" parameter
VERIFY fn	Checks loaded basic program matches fn
VERIFY fn (DATA/CODE/BANK)	Checks data in memory/array matches contents of fn; does not work with SCREEN$/LAYER because the screen is inevitably changed during the verify operation

Inline data

Command	Effect
BANK b RESTORE x	Sets DATA read point to start of line x in bank b
DATA x[,y]..	Stores data in program for later READing
READ var	Read next value from DATA statement into variable
RESTORE x	Sets DATA read point to start of line x

Graphics

Command	Effect
BORDER n	Set ULA border to color N
BRIGHT n	Enable or disable bright colors. n must be 0 or 1. Not legal on non-ULA layers or if Enhanced ULA is enabled.
CIRCLE x,y,r	Draw circle centered at x, y with radius r
CLS	Clears screen
DRAW [modifier or x,y]..	Draw line from plot cursor to given coordinate
FLASH n	Enable or disable ink/paper cycling. n must be 0 or 1. Not legal on non-ULA layers or if Enhanced ULA is enabled.
INK c	Set ink (foreground) color for print and graphics commands. If Enhanced ULA is enabled, this can use any legal palette value. On layer 2, it can use any value 0-255.
LAYER x	Selects active layer for graphics operations. LAYER 0 is an unenhanced ULA screen. LAYER 1 is the ULA screen but with enhancements and with the origin at the top left (not the bottom left). LAYER 2 is, well, Layer 2.
LAYER 1,x	Sets mode for layer 1 based on x. 1 = Standard Spectrum, 2 = Timex hires, 3 = Timex hicolour, 0 = Lores Layer.
LAYER 2,x	Selects Layer 2 and determines if it is displayed or not (x must be 0 or 1)
LAYER AT x, y	Sets the scroll display offset for the current layer.
LAYER BANK f, b	Only when Layer 2 is selected, selects the first bank for layer 2 (f) and shadow layer 2 (b). Note that a layer 2 screen occupies 3 banks.
LAYER CLEAR	Resets all layer settings
LAYER DIM left, top, right, bottom	Sets visible area for current layer
LAYER ERASE x, y, w, h [,f]?	Fills a region at x,y, of size w,h, with palette index f (or the transparent value)
LAYER OVER	Sets layer ordering
LAYER PALETTE x	Choose which of the two palettes is used for the active layer (x must be 0 or 1)
LAYER PALETTE n, i, v	Sets palette index i in palette in to color value v. V is always 9 bit, even if PALETTE DIM 8 is set.
LAYER PALETTE n BANK b, offset	Loads current layer's palette n (0 or 1) from bytes starting at offset in bank b. If PALETTE DIM 8 is set, each byte is one color. If PALETTE DIM 9 is set, each color needs two bytes, but only one bit of the second is used.
PALETTE CLEAR	Resets all palettes and palette settings
PALETTE DIM x	Sets number of color bits in the active palette; x must be 8 or 9
PALETTE FORMAT x	Enables Enhanced ULA colors with x inks. X must be a bitmask which masks off bits on the right of a value (1, 3, 7, 15, 31, 63, 127 or 255)
PALETTE OVER x	Sets the global transparency color to x
PAPER c	Set paper (background) color for print and graphics commands. Follows the same rules as INK.
PLOT [modifier or x,y]..	Plot listed points as single pixels on current layer
POINT x, y, var	Stores the color at point x, y on the ULA screen in variable var
POINT x, y	Returns the color at point x, y on the ULA screen

Modifiers for graphics commands can be inline INK, PAPER, INVERSE, and OVER. INVERSE 1 causes drawing to be in the paper color. OVER 1 causes pixels in the line to be flipped.

Sprites

Command	Effect
SPRITE BANK x	Populates all 64 sprite patterns from bank b, taking 256 bytes per sprite and thus using all data in bank b.
SPRITE BANK b, o, p, n	Define n sprite patterns, starting with p, with data from bank b starting at offset o.
SPRITE PALETTE x	Choose the first or second palette for sprites. X must be 0 or 1.
SPRITE PALETTE x BANK b, o	Load sprite palette x (0 or 1) from bank b at offset o. Data is read as with LAYER PALETTE.
SPRITE PALETTE n, i, v	Set sprite palette n, index i, to color v. V is always 9-bit, even if PALETTE DIM 8 is in effect.
SPRITE PRINT x	Enable or disable sprites. X must be 0 (disable) or 1 (enable).
SPRITE BORDER x	Enable or disable sprites crossing the border. X must be 0 (disable) or 1 (enable).
SPRITE s, x, y, i, f	Set sprite f to image i at position x,y with flags f. f is bitmapped as byte 3 of data packets sent to Sprite Attribute Upload ($xx57 / 87).
SPRITE CLEAR	Reset all sprite attributes and global settings.

Sprites

Command	Effect
TILE [AT x,y]?	Draw the entire screen from the tilemap (from tile offset (x,y))
TILE w,h [AT x,y]? [TO x2,y2]?	Draw a section of the tilemap w,h wide (from tile offset x,y in the tilemap) (to tile offset x2,y2 on the screen)
TILE BANK n	Set bank n as the root of tile graphics (which may occupy up to 4 banks in the case of 16x16 tiles).
TILE DIM n, o, v, t	Set bank n offset o as the root of tilemap data, with tilemap width v and tile size t (t must be 8 or 16 for 8x8 or 16x16 tiles)

Memory and Port Access

Command	Effect
BANK 1346 FORMAT	Re-enable RAMdisk having been disabled by previous BANK 1346 USR
BANK 1346 USR	Disable RAMdisk, allowing banks 1, 3, 4, and 6 to be used
BANK b COPY TO c	Copy entire bank b to bank c
BANK b COPY start, len TO c, start	Copy len bytes from start in bank b, to start in bank c
BANK b ERASE x?	Erase all data in bank by overwriting with zeros (or x)
BANK b ERASE off, len, value	Overwrite len bytes of data at off in bank b with value
BANK b PEEK addr	Returns value at given address in bank b (address is from start of bank)
BANK b POKE addr, value	Sets address in bank b to value (address is from start of bank)
IN port	Returns current value at port
PEEK addr	Returns value at given address
POKE addr, value	Sets address to value
OUT port, value	Sends value to port

Functions/Expressions

Command	Effect
+ - * / ^	Standard arithmetic operators
= < > <= >= <>	Standard comparison operators (arithmetic for numbers, alphabetic for strings)
a(x)	Returns x'th element of array/string a
s(x? TO y?)	Return substring of s; if x or y are omitted, start or end is assumed
AND OR NOT	Standard boolean conjunctives
ABS x	Gets unsigned magnitude of x
ASN x, ACS x, ATN x	Returns inverse trigonometric ratio (arcsin, arccos, arctan)
ATTR x,y	Returns attribute cell value at cell x,y
BIN x	Converts binary number x to decimal
CHR$ x	Gets character for an ASCII code
CODE x	Gets ASCII code for a character
INT x	Rounds x down to integer
LEN x	Gets length of string
PI	Returns approximation of pi
RND	Returns a random number between 0 and 1
SCREEN$ x,y	Returns text character in text cell x,y
SIGN x	Divides x by its magnitude
SIN x, COS x, TAN x	Returns standard trigonometric ratio
SQR x	Returns square of x
STR$ x	Converts number into a string
USR x	If x is a string, gets the address of the first byte of the user defined graphic for the character. If x is a number, runs a machine code routine at address x and returns the value of BC after it exits.
VAL x	Converts string number or expression into a number