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 (parentheses 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 parametrised 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 [ELSE statements]	Run statements only if expression c is true
LET var = expr	Sets variable var to expr
LOCAL var	Declares local variable
NEXT var	Marks end of FOR loop regarding VAR
REM comment	Code comment, ignored
REPEAT	Begin of loop
REPEAT UNTIL condition	Marks the end of REPEAT loop
RETURN	Restore execution location (line and bank) from gosub stack
WHILE condition	Condition for staying in loop

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
REG r [, v]?	Return the value in NextReg register r (or set it to value v if provided)

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

Basic Tokens

Value (hex)	Token
0x87	PEEK$
0x88	REG
0x89	DPOKE
0x8a	DPEEK
0x8b	MOD
0x8c	<<
0x8d	>>
0x8e	UNTIL
0x8f	ERROR
0x90	ON
0x91	DEFPROC
0x92	ENDPROC
0x93	PROC
0x94	LOCAL
0x95	DRIVER
0x96	WHILE
0x97	REPEAT
0x98	ELSE
0x99	REMOUNT
0x9a	BANK
0x9b	TILE
0x9c	LAYER
0x9d	PALETTE
0x9e	SPRITE
0x9f	PWD
0xa0	CD
0xa1	MKDIR
0xa2	RMDIR
0xA3	SPECTRUM
0xA4	PLAY
0xA5	RND
0xA6	INKEY$
0xA7	PI
0xA8	FN
0xA9	POINT
0xAA	SCREEN$
0xAB	ATTR
0xAC	AT
0xAD	TAB
0xAE	VAL$
0xAF	CODE
0xB0	VAL
0xB1	LEN
0xB2	SIN
0xB3	COS
0xB4	TAN
0xB5	ASN
0xB6	ACS
0xB7	ATN
0xB8	LN
0xB9	EXP
0xBA	INT
0xBB	SQR
0xBC	SGN
0xBD	ABS
0xBE	PEEK
0xBF	IN
0xC0	USR
0xC1	STR$
0xC2	CHR$
0xC3	NOT
0xC4	BIN
0xC5	OR
0xC6	AND
0xC7	<=
0xC8	>=
0xC9	<>
0xCA	LINE
0xCB	THEN
0xCC	TO
0xCD	STEP
0xCE	DEF FN
0xCF	CAT
0xD0	FORMAT
0xD1	MOVE
0xD2	ERASE
0xD3	OPEN #
0xD4	CLOSE #
0xD5	MERGE
0xD6	VERIFY
0xD7	BEEP
0xD8	CIRCLE
0xD9	INK
0xDA	PAPER
0xDB	FLASH
0xDC	BRIGHT
0xDD	INVERSE
0xDE	OVER
0xDF	OUT
0xE0	LPRINT
0xE1	LLIST
0xE2	STOP
0xE3	READ
0xE4	DATA
0xE5	RESTORE
0xE6	NEW
0xE7	BORDER
0xE8	CONTINUE
0xE9	DIM
0xEA	REM
0xEB	FOR
0xEC	GO TO
0xED	GO SUB
0xEE	INPUT
0xEF	LOAD
0xF0	LIST
0xF1	LET
0xF2	PAUSE
0xF3	NEXT
0xF4	POKE
0xF5	PRINT
0xF6	PLOT
0xF7	RUN
0xF8	SAVE
0xF9	RANDOMIZE
0xFA	IF
0xFB	CLS
0xFC	DRAW
0xFD	CLEAR
0xFE	RETURN
0xFF	COPY