NextBASIC

From SpecNext official Wiki
Jump to: navigation, search

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 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).
SPRITE CLEAR Reset all sprite attributes and global settings.

Tilemap support

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