How To Program In GBASIC

GBASIC is truly the great unknown of the Tutor, as it is poorly documented (at least in the States), has truly bizarre syntax and operators, and has many inexplicable limitations and quirks. Nevertheless, it remains the sole supported way to directly leverage even part of the 9918A's powerful sprite and hi-resolution graphics capabilities, and on early Tutors and Pyuutas it's the only way of programming the unit at all! So dig in :-)

This document only covers the English-language GBASIC; early Pyuutas had a Japanese-language GBASIC which Junya Kubota has an excellent description of.

Updates and corrections are gratefully accepted. Last modify 1 January 2007.

GBASIC and MONitor Keywords

Back to "Programming the Tomy Tutor" | Back to the main page

[Tomy Tutor GBASIC]
Tomy GBASIC, as shown in the original Tutti.


First, let's clear up an intriguing historical mystery, which is of particular interest since the TI home computers and the Tutor are so close in heritage and architecture.

The TI 99/4A uses a curious middle-level programming language called GPL "Graphics Programming Language" in which TI BASIC and the high-level operating system are implemented (ouch, ouch, ouch! what a performance hit!), stored in "GROMs" which in turn are read out byte by agonizing byte through the GROM's "ports" and executed by a simple interpreter in the actual CPU ROM. Cartridges may also contain GROMs of their own for execution.

The Tutor, too, contains GPL, but GPL on the Tomy is implemented differently and runs much faster because there are no GROMs (just regular ROMs). GPL on the Tutor is responsible for running BASIC, but Tutor GPL has nothing to do with GBASIC. GBASIC is considerably more high-level than GPL, which is in most respects not unlike assembly in scope and function; the GPL instruction set (the TI GPL instruction set is well explained at is memory-access oriented and deals in low level VDP RAM ("GRAM") fetches and stores rather than the high level cell and sprite access of GBASIC; includes a richer set of bitwise and increment operators; and has advanced low and middle-level facilities for 9900 ML code execution, sub-interpreters and even BASIC interpreter access which GBASIC does not. By the same token, GBASIC provides high (or at least higher) level access to sprites, cells, integers and strings without having to deal in memory locations, stores or direct VDP port access.

Here's a more in-depth comparison of the TI and the Tomy.

GBASIC Overview

GBASIC is a very simple BASIC subset. It supports unsigned 16-bit integer math only (signed quantities are accepted, but are treated as if they were their unsigned equivalents), and simple string variables (up to eight characters long). There are no arrays and no floating point variables.

Most of the operations in GBASIC are oriented towards screen and sprite manipulation, and have particularly rich idioms and functions associated with them. By contrast, mathematical operations are merely perfunctory (*, +, / and -, as well as parentheses, are supported with standard operator precedence, but other than RAND, there are no other integer math functions of any kind), and string operations are very weak (no string manipulations other than assignment allowed).

The syntax is similarly simplified. While integer expressions may be fairly complex, not all keywords accept them as parameters. There is no way to put multiple statements on a line, and no REM or equivalent. Variables may only be four characters long (although all are significant). There are no keywords more than four characters long either, which makes for some amusing but non-standard abbreviations.

GBASIC operates in three distinct modes. In entry mode, you are in the GBASIC editor, and anything you type is parsed for syntax and any validity that can be confirmed at entry time. When you exit the editor with the END keyword (see below), GBASIC switches to compile mode where additional post-processing and optimization is performed, line numbers are checked and connected up, and other such housekeeping. Runtime mode refers to actual program execution after successful entry and compilation. These modes will be referred to in both the description below and in the list of keywords and commands.

At least two versions of GBASIC are known to exist: the earliest Japanese GBASIC found in the Pyuuta, and the later English dialect of the first generation UK Grandstand Tutors, the late model UK Tutors, the American Tutors, and the Pyuuta Mk II. We will only be discussing this latter keyword set and function here; Junya Kubota's page on GBASIC, if you can read Japanese, adroitly explains the major differences.

Getting Started With GBASIC

Make sure you turn off your Tutor and remove any cartridges that are installed. GBASIC is inaccessible if you have a cartridge in the cartridge port.

GBASIC is intimately tied with the system MONitor (part of GRAPHIC mode). To switch to the MONitor, enter GRAPHIC mode, press MOD three times to get to graphics mode 4 (so that you see both sprites and screen, but no colour palette), and press MON. The MONitor prompt will magically appear.

[MONitor screenshot]
The MONitor, as shown in the original Tutti.

To start a new GBASIC session, type GBASIC (or GBAS), which will move you into the interpreter and erase any program in memory. To keep a program already resident, type EDIT instead. Both commands will place you in entry mode.

There is no direct mode in GBASIC and all entries must be program lines, starting with a line number. Once you've entered a program line, you can scroll through the listing interactively using the arrow keys (counter to logical thought, down scrolls the listing up, and vice versa), although it seems you cannot edit program lines in place (darn).

GBASIC is an exceptionally terse beast and virtually all errors ranging from simple syntax errors to righteous moral outrage all elicit the ubiquitous complaint ERROR. We'll refer to this message as an entry error, and refers to any objection GBASIC makes to your program as you type it in. This is actually nicer than it feels because GBASIC does make an effort to trap common typos, integers that are too big (i.e., greater than 65535 -- integers are 16-bit only), strings that are too long (i.e., greater than eight characters), missed parentheses, outright syntax errors, etc., as you enter a command line and not a long way down the road. Blank lines give you entry errors too, by the way.

To get out of the GBASIC interpreter, enter a program line ending with the keyword END (a common idiom is 999 END) -- this is actually a program statement as well, so be careful not to overwrite a line of your program with this. GBASIC then shifts into compile mode; there will be a pause as the program is compiled and optimized, and then you will be dumped back into the MONitor. Theoretically errors may occur at this step, though I have not yet encountered any (however, there is a serious crash bug in GOTO, GSUB and THEN triggered at this step -- see the reference page).

To run your new work of art, type GRUN in the MONitor to put GBASIC into runtime mode. Your program will then execute; press MON to re-enter the MONitor or to break out of a program.

Certain errors, such as RTN-w/o-GSUB, can only be caught at runtime. These errors are simply flagged by displaying the offending line on the second-to-last screen line. We'll refer to these messages as runtime errors henceforth. Fortunately, they are comparatively uncommon.

Known GBASIC and MONitor Keywords

Here's a (so far) comprehensive list of keywords and commands in GBASIC and the MONitor.
Back to the top | Back to "Programming the Tomy Tutor" | Back to the main page