NextBASIC

From SpecNext official Wiki
Revision as of 02:04, 13 January 2024 by Orcmeal (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 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.

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