Loadstar 128 #10/q10.d81/t.gbasic demo

Text File | 1990-01-01 | 17.1 KB | 356 lines

                        G B A S I C   1 2 8   V 1 .  0

                                By Jon Mattson


When the C-128 first appeared on the scene with its greatly improved BASIC
7.0, general consensus was that it would be a boon to anyone who wanted to
program fast games but didn't have the knowledge to work with machine
language.  The interrupt-based movement commands, in particular, seemed
ideal for this.  For me, it became a challenge to see how few lines I could
use in the main loop of a game.  GANGSTER, on LOADSTAR 128 #4, was one of
the results of this experiment.  A new Renaissance in game programming
seemed inevitable.

Of course, as with so many things in life, BASIC 7.0 failed to live up to
expectations.  True, MOVSPR allows interrupt-driven movement, independent of
the main program, but the coding required to keep the little beggars fenced
in where you want them almost entirely negates the savings in time and
space.  True, SPRSAV allows relatively simple animation, but it is not very
fast (compared to ML) and must still be monitored from BASIC, since it is
not serviced by the interrupt.  True, BUMP(1) is easier to remember than
PEEK(53278), but that is the only real difference: it still doesn't tell you
which sprite hit which in a mass collision (ditto for COLLISION).  True, JOY
returns a more human-oriented result, but the computer still doesn't do
anything with it.

Clearly, what BASIC 7.0 needs is some sort of subset of commands designed to
deal with all of these shortcomings.  That is exactly what you now have at
your fingertips with GBASIC.

GBASIC actually began as an attempt to create a sort of "sprite shell" to
keep tabs on things in the background of a program.  Even in its initial
incarnation, it dealt with all of the problems noted above.  However, when I
noticed that I still had a little memory to play around with in the
4864-7168 range, I thought I might as well add a few more commands of use to
game programmers.  The end result is a collection of 14 commands and 2
functions, all of which operate harmoniously with your usual collection of
BASIC 7.0 tools.

Using GBASIC is simple.  Just BLOAD it into memory and SYS 4864, either in
direct mode or early on in your program.  If you are in direct mode, a
message will inform you that it is installed.  This message will not appear
from within a program, however, since it might ruin your screen
presentation.  Generally, a simple BLOAD will suffice, but, if you have been
playing around with BANKs and the like, you might want to use the full
syntax: BLOAD "GBASIC",B0,P4864.

Once GBASIC is installed, the new keywords can be used just like any other
BASIC commands.  You can even abbreviate them by shifting the second letter,
as usual.  Remember that GBASIC must be active (not just resident) while you
type in a program using its keywords, or they will not be tokenized
correctly, and you will end up with a jungle of syntax errors.  Note also
that GBASIC uses memory from 4864 to 7167 (only), so avoid POKEing around
this area.

Hitting the beloved STOP/RESTORE combination will not deactivate GBASIC, but
will turn off the interrupt-driven sprite shell.  Simple SYS 4864 again to
bring it back when you need it.  The QUIT command (previously unimplemented
on the 128) will shut off all facets of GBASIC, although SYS 4864 will bring
it back to life.  Resetting the computer will also turn it off; however, due
to its location, GBASIC will still be resident for later use as long as you
haven't POKEd over its memory space.

GBASIC has been designed primarily for use with the 40-column screen, since
sprites aren't supported in 80-column mode.  For this reason, very few of
the commands will have any visible effect in 80 columns, and STORE, in
particular, can have disastrous results to your screen presentation.

Now that we have the preamble out of the way, let's look at your new
resources.  Certain conventions have been followed in this listing.  Sprite
numbers are 1 to 8, as per BASIC 7.0.  Screen columns are numbered 0 to 39,
and screen rows/lines are numbered 0 to 24 (unless, of course, a smaller
window is in use).  In some cases, screen "zones" will be referred to: 0
indicates normal screen memory, 1 indicates color memory.  Most parameters
MUST be given for each command: those which are optional are noted in "< >"


FUNCTIONS
---------

BANG(sprite)

Allows you to check for collisions between sprites and operates in a manner
similar to BUMP (1).  However, the parameter specified is the number of the
sprite in question, and the result will indicate only those collisions which
affect that specific sprite.  For example, BANG(3) would check for
collisions with sprite 3 ONLY and would return a 0 if none were occurring.
If sprite 3 was in contact with 5 and 7, this function would return 80 (16 +
64), even if other sprites were colliding on the screen.  Naturally, a
sprite must be on to have a collision.  Note that this command is based on
the position of the sprite and so may give unforgiving readings with sprite
pictures that are much smaller than the actual possible sprite area.  For
best results with small sprites, use the following formula:

B = BANG(x) AND BUMP(2)

This will only indicate a collision if the picture portion of the indicated
sprite is touching another sprite, AND it will indicate exactly which
sprites are involved in the tangle.

DICE(range)

Generates random numbers within a specified range of 2 to 128.  For example,
D=DICE(6) would be the equivalent of rolling a six-sided dice and putting
the result in D.  If the "range" parameter is 0 or 1, a new random seed is
generated to begin a new sequence of random numbers - the equivalent of
putting D=RND(-TI) at the beginning of your program.  It also generates a
random number between 0 and 255.  Note that this command does not use the
SID chip in any way, so you need not worry about tinkering with VOICE 3.


COMMANDS
--------

ANIMATE sprite, base, blocks, speed

This command animates the indicated sprite by shifting it through each shape
in a sequence.  Since this action is controlled by the GBASIC interrupt, it
will continue independent of program control.  The "base" is the first
64-byte block of the sequence, from 0 to 255: use 56 to start the sequence
in the area reserved for sprites on the C-128 - memory location 3584.  The
sprite will be shifted along the sequence a number of times indicated by
"blocks" (1-255) before it returns to "base" and starts the sequence over
again.  Thus, a "base" of 56 with 2 "blocks" would run 56, 57, 58, 56, 57...
 ad infinitum.  "Speed" (0-255) controls how fast this animation occurs: low
numbers are fast and high numbers are slow.  A "speed" of 5 to 8 generally
works best.  Entering 0 for either "blocks" or "speed" will turn off the
animation sequence for that sprite.  Entering ANIMATE by itself, with no
parameters at all, will turn off animation for ALL sprites.

DEFAULT

This command allows you to quickly change the various sprite parameters
without issuing several commands for each sprite.  It has the following
effects:

 1) Sprite 1 is LINKed to joystick 2 with a speed of 2; all other LINKs are
turned off.  This is the equivalent of issuing a LINK x,0,0,for every sprite
except 1, and a LINK 1,2,2 for it.  See LINK.

 2) All sprites are FENCEd by the screen borders and will bounce off them
without disappearing.  This is the equivalent of issuing a FENCa
x,1,24,65,50,229 for every single sarite.  See FENCE.

 3) Animation is unaffected.

Essentially, this command is a quick way to set up the sprite parameters
most commonly used in arcade games.

FENCE sprite, action, < x-left, x-right, y-top, y-bottom >

This command rides shotgun over your sprites, making sure that they stay
within the boundaries you specify, regardless of MOVSPR and the like.
"Action" indicates what should happen when a sprite goes out of bounds:

 0 - Nothing (FENCE off)
 1 - Stop
 2 - Disappear (good for removing shots that go off-screen)

Note that a "stopped" sprite is only prevented from moving in the blocked
direction (x or y).  If it is moving at an odd angle with both x and y
vectors, it can still "crawl" along the border in the unblocked direction.
The "x-left", "x-right", "y-top" and "y-bottom" parameters specify the
boundary zone.  For example, XL=24, XR=65, YT=50 and YB=229 would set the
boundary exactly at the edges of the screen (the default value).  Note that
the X-MSB is assumed for the right boundary, giving you the full width of
the screen if you so desire it.

FILL zone, value

This command will fill either screen (zone 0) or color (zone 1) memory with
the given "value" (0-255).  Note that only the current window is filled:
this may or may not be the entire screen, depending on how you have
specified any WINDOWs (BASIC 7.0) or FRAMEs (GBASIC).

FRAME top left column, top left row, bottom right column, bottom right row,
frame character, frame color

Note: With the exception of the last two parameters, this syntax is as per
the WINDOW command.

This command opens a cleared window anywhere on the screen, as per WINDOW.
However, it puts a frame around the window of the specified character
(0-255) and color (0-15).  Note that the actual window size will be two less
in width and length to accomodate the frame.  Parameters which do not allow
for this will generate an ILLEGAL QUANTITY error.  This command can be
combined with STORE and RECALL to create true "pop up" windows which
disappear without a trace when closed.

HOME

Homes the cursor within the current window.

LCLEAR first line, last line

This command clears the indicated lines (0-24).  Naturally, the last line
must be higher in value than the first.  Note that lines are only cleared
within the boundaries of the current window, and the line values will be
offset by the position of the window from the real top of the screen.

LINK sprite, port, speed

This command links the indicated "sprite" to the indicated joystick "port"
(1-2), so that it moves in the appropriate direction when the stick is
pushed.  The "speed" can also be changed from 1 (slow) to 16 (too fast for
most purposes).  Entering 0 for "port" or "speed" will severe the LINK.
Since this routine is part of the sprite shell interrupt, it will operate
independently from the BASIC program.  As with all sprite-moving commands,
it is subject to FENCE limits, however.  Note that more than one sprite can
be LINKed to the same stick to create giant-sized objects that move
seamlessly together.

MCOPY bytes, from address, from bank, to address, to bank

This command copies chunks of memory from one location to another.  "Bytes"
(1-65536) indicates the number of bytes to copy.  "Address" and "bank"
ranges are as per usual, 0-65536 and 0-15 respectively.  Since it can move
data from one bank to another, this command has many uses.  For example,
MCOPY 2048,53248,14,14336,0 will almost instantly copy the character set to
bank 0, address 14336, allowing you to alter it to suit your tastes.  POKE
2604,30 to see the new set.  As with all commands that alter memory
directly, you should be VERY careful with MCOPY.

RECALL screen

This command allows you to RECALL a screen which has been previously STOREd.
See below.

STORE screen

This command and its companion, RECALL, allow you to save and load full
screens (including color) in memory.  You can have up to 8 screens, numbered
0 to 7, STOREd at a time.  The uses for these commands are infinite.  For
example, you could STORE one or more "help windows" to be RECALLed as needed
- also STOREing the current screen before the help window is called up so
that it can be retrieved afterwards.  By preceding a FRAME or WINDOW command
with STORE, you can RECALL the original screen later to create "pop up"
windows which later vanish, leaving the first screen intact.  This
versatility has one price: the screens are stored in 8563 RAM, making full
use of the 80-column screen difficult, if not impossible, unless you stick
to only screens 2 and 3, which cover normally unused 8563 RAM.  If this
situation is intolerable, remember that MCOPY can also be used to save and
load screens in other areas of memory.

TRANS from zone, from value, to zone, to value

TRANS (short for "TRANSMUTE") scans the entire screen and alters only the
portions of it which you specify.  It will look through either screen or
color memory (zone 0 or 1) for every occurrence of the noted "from value"
(0-255), and then alter it, in the appropriate "to zone" (0-1), to the new
"to value" (0-255).  A few examples will make this more clear.  Remembering
that the screen codes 1 and 2 are "A" and "B" respectively, and the color
codes 3 and 4 are cyan and purple respectively:

 TRANS 0,1,0,2: Change every "A" on the screen to a "B"
 TRANS 1,3,1,4: Paint every cyan character on the screen purple.
 TRANS 0,1,1,4: Paint every "A" on the screen purple.
 TRANS 1,3,0,2: Change every cyan character on the screen to a "B"

Obviously, this command is of particular use in creating interesting
animation effects.

QUIT

This command simply turns off GBASIC.  SYS 4864 to reactivate it.

MINE

This is perhaps the most unusual command of all and is aimed mainly at
machine language programmers.  Normally, issuing MINE will give an
UNIMPLEMENTED COMMAND error.  However, by POKEing an address into memory
locations 7166-7167 (low byte/high byte format), you will cause the MINE
command to execute a machine language routine of your creation at this
location.  A good place to put this routine is in the mostly unused area
from $B00 to $BFF, since it is in common RAM and will allow you to avoid
banking hassles.  "POKE 7166,0: POKE 7167,11" will set this up.  The demo
program (see below) uses a short routine of this sort to place the comet and
get it moving at the chosen speed.

For really large routines, you can use the area from 7168 to 16383(!), but
this will necessitate setting up the graphic area without actually using it
(GRAPHIC1: GRAPHIC0).  This has the advantage that you can then BSAVE a new
version of GBASIC with your routine permanently added on.  BSAVE "GBASIC",
B0, P4864 TO P(x+1), where "x" is the end address of your routine, will
accomplish this.

If you would like the MINE command to take in parameters, the following
coding will usually do the trick:

 JSR $0386
 JSR $AF96
 JSR $AF0C

Place this in your code to retrieve each parameter.  It will return the low
byte in the Y-Register and the high byte in the Accumulator (i.e.  "MINE
1026" would return 2 in YREG and 4 in ACC).  Commas are automatically dealt
with by the built-in routines.  If you want to save some space, the second
two commands are built into a subroutine in GBASIC itself at $1697, i.e.
the three can be replaced with: JSR $0386 : JSR $1697.  If you want to limit
input to one byte (numbers from 0-255), there is also a built-in routine for
this: JSR $0386 : JSR $16A0.  Single byte parameters will show up in YREG;
multi-byte inputs (256+) will generate an ILLEGAL QUANTITY error.

I have included a demo program to get you used to the capabilities of the
new commands.  Of course, it is more of a game portion than a full program,
but it will give you some idea of what you can now accomplish.  In
particular, you should list the program and study how each command is used.
See if you can find the game's main loop: you may be amazed at how short it
is, since virtually all movement is controlled with the GBASIC and C-128
interrupts.

There is one final trick that you might find handy to have in your arsenal.
As previously noted the GBASIC module must naturally be active to run a
program using its commands.  With a little careful coding, you can link it
permanently to your program so that the two files LOAD and SAVE together -
in effect, a GBASIC runtime module.  Here's how to do it:

 1) Design your program using the GBASIC commands as usual.  Don't bother
having it BLOAD GBASIC - this won't be necessary once they are linked
together.  Just make sure that the first line has SYS 4864.

 2) When you are happy with the results, make sure that both GBASIC and your
program are in memory.  Be certain that your program is in the normal area
reserved for BASIC and not pushed up above the graphics area.  A GRAPHICCLR
command will do this.

 3) In direct mode, lower the start of BASIC by entering the following:

POKE45,0:POKE46,19

then DSAVE your program normally.  Don't forget to push BASIC back to its
normal location afterwards with:

POKE45,1:POKE46,28

If you study the block count of your program, you'll notice that it is now
longer: the GBASIC module is attached to it.

There are only two catches to this trick:

 1) Your program will not work properly if the graphics area is in use when
it is first loaded, since GBASIC will end up in the wrong place.  It WILL
work all right if the graphics area is set up afterwards, however.

 2) You must use the LOAD "filename",8,1 syntax to LOAD the program from now
on.  DLOAD will assume that GBASIC is a normal BASIC program itself and
place it in the wrong area, with your program crammed on top.

That's about all there is to it.  Once you get the syntax down, the commands
are very easy to use and will perform many tasks in the background that you
would normally have to code yourself.  Now you can create that epic arcader
you've been dreaming about, and maybe even get it published on LOADSTAR!

JM
                             **** End of Text ****