Getting Started
The complete source code and binary ROM for NucBasic is included in the
Rom2Cart package
. Download the NucBasic.gb ROM file to a GatesBoy™ / Game
Boy or load this file in a Game Boy Emulator.
| Game Boy | NucBasic™ | NOCASH Emulator |
| B | Input | Tab |
| START | Backspace | Enter |
| A | Enter | Space |
| SELECT | CapsToggle | Left Ctrl |
| SELECT & START | Break | Left Ctrl / Enter |
Hello World
Switch on the Game Boy. If "Ok" is not displayed at the bottom of the screen,
you must stop the program that is running. Do this by pressing two keys
together to send the Break signal (Left Control and Enter on the PC, or Select
and Start on the Game Boy). See above for key
assignments.
You should now erase any existing program in RAM memory prior to starting to write your new program. Type in "NEW" Enter, as follows: use the cursor keys to select "N" on the onscreen keyboard and press the Input key (Tab key on the PC, or "A" on the Game Boy). Then move the cursor to "E" on the onscreen keyboard and press the Input key. Move the cursor to the letter "W" and press the Input key. Now press the Enter key (space on the PC or "A" on the Game Boy). NucBasic™ should respond with "Ok".
You are now ready to write your first program. "Type" the following:
1 PRINT "HELLO WORLD"
Tips: "Space" is found to the right of the digit 9 on the onscreen keyboard.
If you make a mess typing
in a line you can cancel the line
by typing
@
Now press the Enter key (space on the PC or "A" on the Game Boy). NucBasic™ will respond with "Ok". You have just written your first program! Run the program by typing "RUN" Enter. NucBasic™ will type "HELLO WORLD" on the screen, then "Ok" on the next line (because it's waiting for your next command).
Downloading your NucBasic™ Program to ROM
See
NucMorse.bas
below for an example of a NucBasic™ program. This program
autoruns because of the RUN command on the last line.
The MergNucB.bat file uses the MergNucB.com utility to merge a
NucBasic™ program at the end of the ROM.
Statements
Most statements can be used in "direct input" mode. For Example: RUN, LIST,
PRINT Z. Statements which form part of a program, however, require a line
number. A space after the number is optional.
Multi statement lines are allowed. The separator is
:
For Example:
10 L = 4
:
REM set Loop count
or, the equivalent:
10 L = 4
: '
set Loop count
Variables
String variables are
not
supported.
Variable names may be a letter, or a letter and a number. For example:
A , B , C , and C1 are all valid variable names.
Variables are not case sensitive. For example, c1 and C1 are equivalent.
Variables can be assigned a value with or without the LET keyword. For example:
A=10 and LET A=10 are equivalent.
Single dimension arrays are supported, with or without an explicit statement of their size.
DIM(20) A, and DIM B, will set up an array of size 20 for the variable "A", and an array of default size 10 for variable "B".
&H may be used for entering hex values. (e.g: POKE &HFF00,&HFF)
DATA / READ / RESTORE / INPUT
The DATA statement can be used to introduce one or more of a series of
constants into a program. READ statements will read these values.
The RESTORE statement will "recycle" the data contained in DATA statements, and read by subsequent READ statements, starting from the specified line number, or from the beginning of the program if this line number is omitted.
The INPUT (I.) statement prints
?
and waits for the input of a floating point number from the user. It is
normally
used in conjunction with the PRINT command to prompt the user. For Example:
PRINT "What is your age";
INPUT A
FOR / NEXT loops
FOR / NEXT loops cause the program to execute a group of statements a certain
number of times. For Example:
10 FOR I=1 TO 10
20 PRINT I
30 NEXT I
will cause 1 - 10 to be printed on the screen. An optional STEP parameter can be used if you wish to decrement the loop counter or to assign an increment other than 1. For Example:
10 FOR I=1 TO 10 STEP 2
20 PRINT I
30 NEXT I
will cause 1, 3, 5, 7 and 9 to be printed on the screen.
IF / THEN branches
IF / THEN conditional branches are implemented as single statements. For
Example:
10 IF A=4 THEN GOTO 100
GOSUB Subroutines
Subroutines are implemented and must end with the RETURN statement. For
Example:
10 IF A=4 THEN GOSUB 100
20 PRINT "A can = 4 - or not"
30 END
100 PRINT "A=4"
110 RETURN
Functions / Keywords
ABS
AUTO
CLEAR
COLOR
COS
DELAY
END
FREE
GOTO
INT
KEYPAD
LET
LINE
LINK
LIST
LOAD
LOCATE
MEMTOP
NEW
PEEK
POINT
POKE
PRINT
REG
REM
RENUM
RND
RUN
SAVE
SCREEN
SERVO
SGN
SIN
SINIT
SOUT
SOUND
SPEED
SQR
STEP
STOP
TAB
TAN
USR
ABS(x) Return the absolute value of x.
AUTO(x) Not used.
CLEAR(x) Clear all variables.
COLOR (x)
Set drawing color to x. 0=Black, 1=Dark Gray, 2=Light Gray, 3=White, & 4=XOR.
(Defaults to XOR on program execution.)
COS(x) Return the cosine of x given in radians.
DELAY(x) (D.) Delay from 10ms to 655 seconds. (Delay length = x * 10ms)
END End program.
FREE Display remaining amount of free memory.
GOTO n
(G.) Go to line
n
.
INT(x) Returns the integer part of x.
KEYPAD(x)
If x=0, the following bits are returned if that button is pressed.
128 - Start 8 - Down
64 - Select 4 - Up
32 - B 2 - Left
16 - A 1 - Right
If x>0, then x is ANDed with the bits above.
If the result = zero, 0 is returned.
If result >< zero, a 1 is returned.
LET Assign a value to a variable (optional).
LINE x1,y1,x2,y2
Draw a line on the screen using COLOR. (0<=x<=127,0<=y<=119)
LINK Not Used.
LIST [x][-][x]
(L.) List lines of the program. Starting and/or ending line numbers are
optional. The two speeds for the LIST function are controlled by the UP /
DOWN keypad. LIST starts in fast speed.
LOAD Not Used.
LOCATE y,x Position cursor with coordinates y,x.
MEMTOP x
Set last address of RAM for NucBasic™ to use.
On power up or reset this defaults to $dfff.
Lowering this value reserves memory (for USR, for example).
Note: All variables are CLEARed when this instruction is executed.
NEW Erase all program lines in memory.
PEEK(x)
Returns value of a memory location x.
POINT x,y
Draw a point on the screen using COLOR. (0<=x<=127,0<=y<=119)
POKE x,y
Write value y to a memory location x.
PRINT
(P. or ?) Prints to screen and then prints a carriage return. This carriage
return can be surpressed if a
;
is added at the end of the PRINT
statement. For example:
10 PRINT 1
20 PRINT 2
will print 1 and 2 on separate lines and
10 PRINT 1
;
20 PRINT 2
will print 1 and 2 on the same line.
REG x,y
Sets value of cpu BC register (x) and cpu DE register (y). Normally called
just prior to USR.
REM
(
'
) Remark.
RENUM Renumber program.
RND(x)
Returns a random number between 0 and 1. x is ignored.
RUN (R.) Execute program.
SAVE Not Used.
SCREEN x
If x=0, set text mode. If x=1, set graphics mode.
SERVO x,y Not Used.
SGN(x) Returns 1 if x>or=0. Else returns value -1.
SIN(x) Returns the sine of x given in radians.
SINIT x,y Not Used.
SOUT x Not Used.
SOUND x,y
Generate a sound of frequency x for y * 10 milli-seconds. If y=65535, sound
will stay on infinitely. If y=0, sound is turned off.
SPEED x
x=0, Set single speed mode. (Default on powerup.) x=1, Set double speed mode.
(Only has an effect on GB Colo(u)r.
SQR(x) Returns the square root of x.
STEP Not Used.
STOP
Same as end but displays line number last executed.
TAB(x)
Used with PRINT command for moving cursor to column x.
TAN(x) Returns the tangent of x radians.
USR(x)
This function is normally called just after REG, and calls an assembly
language routine at address x. It returns the value in HL. In this way, you
can extend the language.
Error Messages
Argument error
- no variable name following DIM statement
Control Stack error
- missing index after FOR statement; missing NEXT; improper
nesting (i.e. overlapping) FOR loops; Control Stack empty
Direct Input error
- Some statements e.g. REM or DATA are not legal when you are typing commands
directly e.g. RUN or LIST for immediate execution. Perhaps you have forgotten
the line number?
Divide by 0 error
- variable or expression is divided by 0
Duplicate error
- variable name already defined
Floating point error
- more than 6 digits of precision for floating point
calculations?
Illegal function call error
- square root of a negative number?
Input error
- error in floating point input
Line too long error
- maximum input line = 80 characters (including CR)
Out of DATA error
- there are more READs than DATA values
Out of memory error
- memory allocation would go beyond MEMTOP
Out of range error
- POKE value greater than 255; index out of bounds for a
dimensioned variable (e.g. index greater than defined dimension size; greater
than 10 if no dimension specified; negative index for a floating point number).
Overflow error
- number overflow
SINtax error
- you have probably misspelled a key word
Undefined line number error
- cannot find requested line number e.g. the line number specified by a GOSUB or
GOTO statement.
Sample Code
Example NucBasic™ Program
NucMorse.bas
1 REM NucBasic Program NucMorse.bas
2 ' dnathan@gatesboy.com 14 November 2001
3 ' Example program for GatesBoy™ cartridge
4 ' Demonstrates use of a switch and LED connected to DB25 connector
5 ' Connect a normally open switch between Pin 16 and Pin 11
6 ' Connect a LED between Pin 15 and Pin 10 via a 10 KOhm resistor
7 ' You can specify the number of times SOS is sent
8 ' And the time period in 1/100 sec for a single DIT
9 ' A countdown timer waits for the switch to be closed
10 GOSUB 100 : ' Initialise
15 T = 100 : ' Timeout in cycles
20 GOSUB 200 : ' Check switch
21 PRINT T;: ' Timeout
22 IF T
< 0 THEN GOTO 95
24 IF S1 = 1 THEN GOTO 20 : ' S1 = 1 = Switch not pressed
26 FOR N1 = 1 TO N : ' N = Number of SOS
28 PRINT "SOS number " ; N1
32 F = 3 : D = 1
36 GOSUB 300 : ' Send F Flashes, D Duration 1*P = DIT, 3*DIT = 'S'
38 DELAY 5*P : ' Time between letters is 5*Period
40 F = 3 : D = 4
44 GOSUB 300 : ' Send F Flashes, D Duration 3*P = DAH, 3*DAH = 'O'
46 DELAY 5*P : ' Time between letters is 5*Period
48 F = 3 : D = 1
60 GOSUB 300 : ' Send F Flashes, D Duration 1*P = DIT, 3*DIT = 'S'
62 DELAY 10*P : ' Time betweem SOSs is 10*Period
65 NEXT N1
70 PRINT "": ' New line
80 PRINT N1 - 1 ; "SOS completed"
85 PRINT "MORSE ENDED"
90 END
95 PRINT "": ' New Line
96 PRINT "Switch timeout"
98 GOTO 26
99 END
100 ' Initialise
102 POKE &HB015,2 : ' Set Pin 15 out, Pin 16 In
105 POKE &HB017,0 : ' DRIVE_D bit 1 = 0 for Low Slew rate
110 ' DATAOUT_D bit 1 = 1 for Pin 15 High = LED Off
115 POKE &HB013,2 : ' Turn Off LED = High at Pin 15
120 PRINT "MORSE"
125 PRINT "Connect Switch"
130 PRINT "Between Pin 16"
135 PRINT "and Pin 11"
140 PRINT "Connect LED"
145 PRINT "Between Pin 15"
150 PRINT "and Pin 10 via a "
155 PRINT "10 KOhm resistor"
160 PRINT "No of times to send SOS";
165 INPUT N
170 PRINT "Period for DIT in 1/100 sec";
175 INPUT P
198 ' End of Initialise
199 RETURN
200 ' Read Switch - Read Port D
210 S1 = PEEK(&HB011)
220 'PRINT "PEEK =";S1
230 S1 = S1 - 2 * INT(S1/2) : ' Extract Bit 0
240 T = T - 1 : ' Decrement Timeout
250 'PRINT "Switch =";S1 : ' S1 = 0 when switch closed
299 RETURN : ' End of Read Switch
300 FOR F1 = 1 TO F : ' Send F flashes
310 POKE &HB013,0 : PRINT "ON ";
320 SOUND 1000, D*P
330 DELAY D*P : ' DELAY 1 = 10 ms
340 POKE &HB013,2 : PRINT "Off ";
350 DELAY P : ' Time between flashes is = Period
360 NEXT F1
399 RETURN : ' End F flashes
CLS
RUN
Feedback
This is a
FeedbackFriendly
site. Feedback to
NucBasic@gatesboy.com
Version History
Version 1.02 20 November 2001.
Rom2Cart package
now includes the MergNucB.com utility so that writing and merging a
NucBasic™ program with the NucBasic.gb Interpreter ROM is a snap.
Version 1.00 13 November 2001
- Original Release