Differences

This shows you the differences between two versions of the page.

--- sd:sd-8516_stellar_basic [2026/03/27 05:01] – appledog
+++ sd:sd-8516_stellar_basic [2026/04/05 14:18] (current) – appledog
@@ Line 9: / Line 9: @@
 Stellar BASIC is a kind of 8 bit TinyBASIC, with a few improvements under the hood. It runs at 1800 lins per second at 4 MHz (1.28 MIPS). This is comparable to a C64 that can execute 150-200 lines of BASIC per second (at 1 MHz). The SD-8516 pulls ahead in speed because it has more registers available to hold temporary values, so it does not need to use memory as much as a C64 or other similar 80s microcomputer would need to. The extra registers, of course, were added precisely with BASIC execution speed in mind! No more register memory pressure, full speed ahead!
-== Graphics
+== Terminal Control
+There are some basic terminal interface commands you may wish to know. These will allow you to make character mode games; see next chapter for graphics mode.
+* STRXY X, Y, A$ -- print string at XY on the screen
+* CHARXY X, Y, C -- puts character C (0-255) on the screen at location (X,Y).
+* CHARFG X,Y,FG -- changes the foreground color of a single character on the screen
+* CHARBG X,Y,BG -- changes the background color of a single character on the screen
+* CHARAT$(X,Y) -- returns the character at X, Y
+As an example of these commands, the game [[sdb:ROBOTS]] uses CHARXY to draw the map.
+== Graphics
 === MODE
 One of the interesting commands you will come to use often is the MODE command.
@@ Line 230: / Line 241: @@
 VSTART will resume regular video chip scans of the framebuffer to video memory.
-For more information about how this works (for use in assembly language programming) please see the [[SD-8516 Programmer's Reference Guide]].
+=== Mode 4
+Mode 4 is a 256x224 "Famous Console" inspired mode. Here's a demo program:
-== Terminal Control
+<codify>
-* STRXY A$, X, Y -- print string at XY on the screen
+MODE 4
-* CHARXY X, Y, C -- puts character C (0-255) on the screen at location (X,Y).
+FOR C = 0 TO 15
-* CHARFG X,Y,FG -- changes the foreground color of a single character on the screen
+RECT C * 16, 0, C * 16 + 15, 223, C, 1
-* CHARBG X,Y,BG -- changes the background color of a single character on the screen
+NEXT C
-* CHARAT$(X,Y) -- returns the character at X, Y
+LINE 0, 0, 223, 223, 3
+INPUT "PRESS ENTER"; A$
+MODE 1
+</codify>
+As you can see, it's pretty much more of the same, but you may prefer the aspect ratio for classic 8bit and 16bit console games.
+=== Mode 8
+Mode 8 is a 128x128 "Ersatz-8" inspired mode.
+<codify>
+MODE 8
+FOR C = 0 TO 15
+RECT C * 8, 0, C * 8 + 7, 127, C, 1
+NEXT C
+LINE 0, 0, 127, 127, 3
+INPUT "PRESS ENTER"; A$
+MODE 1
+</codify>
+As you can see, it's pretty much more of the same, but you may prefer this aspect ratio for classic "ersatz retro" games.
+== Music
+Music and sound effects are an important part of any game. For many of us it is impossible to forget the iconic video game themes of yesteryear. Stellar BASIC honors this tradition with the PLAY command.
+=== Ode to Joy
+<codify BASIC>
+    PLAY "T120 O3 L4 E E F G G F E D C C D E E D2"
+</codify>
+The above PLAY statement plays a theme from "Ode to Joy". The structure of the PLAY statement is easy enough to understand: Tempo 120, Octave 3, Note Length 4 (Quarter notes), and then the music: E E F G, G F E D, and on, notes played in order.
+=== Jingle Bells
+<codify BASIC>
+    PLAY "T200 L4 O3 MN E E L2 E L4 E E L2 E L4 E G L3 C L8 D L1 E"
+    PLAY "L4 F F L3 F L8 F L4 F E L2 E L8 E E L4 E D D E L2 D G"
+    PLAY "L4 E E L2 E L4 E E L2 E L4 E G L3 C L8 D L1 E"
+    PLAY "L4 F F L3 F L8 F L4 F E L2 E L8 E F L4 G G F D L2 C"
+</codify>
+Here, we see the MN command and L commands used to great effect. MN means normal, and L# sets the length of the next notes. However, you can also write it like this:
+<codify BASIC>
+    PLAY "T200 L4 O3 MN"
+    PLAY "E E E2 E E E2 E G C3 D8 E1"
+    PLAY "F F F F8 F8 F E E E8 E8 E D D E D2 G2"
+    PLAY "E E E2 E E E2 E G C3 D8 E1"
+    PLAY "F F F F8 F8 F E E E8 F8 G G F D C2"
+</codify>
+Here, instead of using a lot of L commands, we just add the length to the end of the note for any note that is not the default length.
+=== FURELISE.BAS
+Let's take a closer look at the PLAY command by writing our first music program, FURELISE.BAS:
+<codify BASIC>
+REM FUR ELISE
+PLAY "XV1 W1 T140 L8 O5"
+PLAY "XV2 W1 T140 L8 O2"
+</codify>
+The commands here are easy to understand. This is the  voice setup. The first command in each PLAY line is XV0 or XV1. This sets the commands to use voice 0 or voice 1.
+    XV1            This sets the PLAY command to use voice 1.
+    XV2            This sets the PLAY command to use voice 2.
+Next, we have the W1 command. This sets waveform 1. The SD-450 gate register values are:
+* 0 = off
+* 1 = square
+* 2 = triangle
+* 3 = sawtooth
+* 4 = sine
+* 5 = pulse
+* 6 = noise
+Now, 1 (square) is the default, so you don't need to type it. But we included it here for edification.
+    W1             Set waveform to 1 (square).
+    W2             Set waveform to 2 (triangle).
+Next, we set tempo to 120, a standard value. Well, let's spice things up a little and choose 140 this time.
+    T120           Set tempo to 120
+    T140           Set tempo to 140
+Finally, we have the default note length, 8, which means eighth note, and the starting octave:
+    L8 O5          Set defaults to quarter note and octave 5 (mid-range/upper).
+    L8 O2          Set defaults to quarter note and octave 2 (lower).
+Next lets look at few bars of notes:
+<codify BASIC>
+PLAY "XV0 E D# E D# E O4 B O5 D C XW"
+PLAY "XV1 R4. R4. XW"
+</codify>
+There are two things going on here. One is the main line of notes for voice 1 containing the first 8 notes and an XW command. The second PLAY here contains information for voice 2. It starts with two rests and then an XW command. The other thing to note about the first PLAY is that it contains an O4 command which changes the octave to 4.
+    O4             Set default octave to 4
+This is just like above, You can set the octave any time to change it. But, what is XW?
+    XW             Wait for all other active voices to reach XW and then continue
+XW is the synchronize voice command. XW ensures that when the next lines of PLAY execute they will be perfectly synchronized with each other. There are other ways to synchronize music, such as using PLAY STOP, loading the music, then PLAY START; but XW is the way to do it inside a PLAY command.
+    PLAY STOP      Pause the player.
+    PLAY START     Start the player.
+When the player is stopped, you can add music and it won't start until you do PLAY START. But for our example we have plenty of time to enter the music before the first synchronization point is reached.
+Another way to do this is to do something like ''PLAY "W0 R1 XW"'' and this rest will give you enough time to load at least the first bar of music, then you can go on to load other bars in the background while the music plays.
+That's it! It's a very simple system.
+=== Program Listing
+Here is the complete program listing.
+<codify BASIC>
+REM FUR ELISE
+PLAY "XV1 W1 T140 L8 O5"
+PLAY "XV2 W1 T140 L8 O2"
+PLAY "XV1 E D# E D# E O4 B O5 D C XW"
+PLAY "XV2 R4. R4. XW"
+PLAY "XV1 O4 A4. L8 C E A XW"
+PLAY "XV2 A4. O3 E A XW"
+PLAY "XV1 O4 B4. L8 E G# B XW"
+PLAY "XV2 O2 E4. O3 E G# XW"
+PLAY "XV1 O5 C4. L8 O4 E O5 E D# E D# E O4 B O5 D C XW"
+PLAY "XV2 O2 A4. O3 E R O2 R4. R4. XW"
+PLAY "XV1 O4 A4. L8 C E A XW"
+PLAY "XV2 O2 A4. O3 E A XW"
+PLAY "XV1 O4 B4. L8 E O5 C O4 B XW"
+PLAY "XV2 O2 E4. O3 E A XW"
+PLAY "XV1 O4 A4."
+PLAY "XV2 O2 A4."
+</codify>
+=== MML COMMANDS
+This is 'Music Markup Language', used by many different implementations of BASIC. Our version, of course, is the best one -- but they are all very similar.
+    A-G             - play note (optional sharp/flat, length override, dot)
+    A#8 B-.         - Play A Sharp eighth note then B Flat with +1/2 length (i.e. dotted)
+    R               - rest
+    O n             - set octave (0-7)
+    > <             - octave up/down
+    L n             - set default note length (1=whole, 2=half, 4=quarter...)
+    T n             - tempo in BPM (32-255)
+    V n             - volume (0-15)
+    W n             - waveform (0=tri, 1=saw, 2=pulse, 3=noise)
+    P n             - pulse width (0-4095; PWM only)
+    MS / MN / ML    - staccato / normal / legato
+    XV n            - switch voice (0-7)
+    XC              - clear current voice queue
+    XW              - wait (sync point — all active voices must reach XW)
+=== Further Study
+If you wish to learn more about how the MML system works under the hood, please refer to the Programmer's Reference Guide [[Appendix 5 Sound System]].
+== Benchmarking your Code
+You might want to know how fast your code runs. This simple benchmarking program gives you an insight on how to create a simple timer:
+<codify BASIC>
+BANK 1
+LET T=PEEK($EF06)
+FOR I=1 TO 1000
+LET A=I*3+7
+LET B=A/2-1
+LET C=A+B
+LET S=S+C
+IF C>100 THEN LET P=P+1
+NEXT I
+LET U=PEEK($EF06)
+LET D=U-T
+PRINT D
+</codify>
+The memory location $EF06 is the second byte of the hardware clock, which ticks once every .256 seconds. it's a bit rough but if you need a simple timer you can do something like this. On my computer this returns 14, which indicates 7000/(14*.256) or 1,953 BASIC lines per second. Of course, we already have the WAIT command so this is not useful for waiting on time; but rather it can be used to measure approximately how long something took.
+== Dictionary
+=== FREE()
+This is like MEM in that it calculates the free space in bank 0 between the end of the BASIC program and VARTOP, however it returns it as an integer. Be careful because in BASIC integers are signed. So read the number like this; when it is negative, this shows how much space has been used (the zero page is reserved so it always shows -256 at start). When it is positive, then it shows how much space is left.
+Also see: MEM
+=== MEM
+This command calculates the free space in bank 0 between the end of the BASIC program and VARTOP, which roughly estimates how much free space you have left in bank 0 for BASIC.
+Also see: FREE()
+=== PRINT
+This command prints a number, expression, variable or string. Examples:
+    PRINT "HELLO WORLD!"
+    PRINT A$
+    PRINT ASC("*")
+    PRINT 5