Jump to content

Photo

[AQUARIUS] BASIC Programming on the Aquarius

mattel radofin aquarius programming homebrew BASIC

109 replies to this topic

#1 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Tue Nov 5, 2013 10:24 PM

A while back, I started a thread which was intended to be a place where interested programmers could go to find everything they needed to get started with assembly language programming on the Aquarius.  Since then, with the popularity of batari Basic for the Atari 2600 and other homebrew-oriented languages, there has been some interest in developing games for the Aquarius in BASIC, so ... here's another Aquarius thread, just for BASIC programmers!
 
Fortunately, the Aquarius already has its own version of BASIC, and it's built right in to the computer!  When you turn on your Aquarius (without a cartridge inserted), or start your favorite Aquarius emulator, you'll be presented with a startup screen for Microsoft BASIC.  This is the BASIC interpreter that is built in to the Aquarius OS ROM, and contrary to what you might have read elsewhere, it is a perfectly capable implementation of BASIC; it is not a "crippled" version that is missing such elementary features as the ability to do FOR-NEXT loops.  The Extended BASIC cartridge (released in very limited quantities, and available today as part of the Aquaricart) did add a few "missing" features, such as the ability to edit previously entered lines of code, but you can easily live without most of them, and as we'll see, there are even better ways of editing BASIC programs using the tools available today.
 
Speaking of tools, let me begin by posting a few.  First is the most recent version of the Virtual Aquarius emulator for Windows, version 0.72a:
 
Attached File  VirtualAquarius.zip   1.29MB   635 downloads
 
This distribution archive includes the emulator itself, the OS ROM, several cartridge and cassette images, and a few sample BASIC programs in ASCII text format to get you started (more on these later).  This is the primary emulator that I will be writing my instructions for in this thread, since it has a few features which are especially useful for BASIC programming but which other Aquarius emulators (such as MESS) presently lack.
 
(There is no "installer" for this emulator; just unpack the ZIP archive into a folder, move the folder to a convenient place, and open the "aquarius.exe" executable inside the folder to start the emulator.  It's a few years old now, but I've used Virtual Aquarius under every version of Windows from XP through Windows 8 (in Desktop mode), and it appeared to function perfectly.)
 
Next is a bootloader utility, generously provided by Martin v.d. Steenoven, which will convert completed BASIC programs of up to 16K into cartridge images.  You can use these images in Virtual Aquarius like any other cartridge binary, or even burn them to a 16K cartridge ROM for use with a real Aquarius.  In either case, your BASIC program will load and start automatically when the Aquarius is started; the users will not even see BASIC.  Here is a link to the most recent version of the bootloader from the assembly thread, along with Martin's usage instructions:
 
[AQUARIUS] Machine Language Programming on the Aquarius (Post #52)
 
(Note that it is not necessary to use this bootloader utility until after you have completed your BASIC program.  While you are writing your program, you would load it into BASIC for testing, using the procedure I will outline in my next post.  If you are interested in putting your first completed program onto a real cartridge, send me a PM; I'll be offering a cartridge publishing service in the near future.)
 
Finally, here is a dump of the original Aquarius Character Generator ROM, containing the default Aquarius character set.  This replaces the "reconstructed" character set used by Virtual Aquarius:
 
Attached File  AquariusCharacterSet.zip   1.18KB   198 downloads
 
To explain why this is important, and how to use the replacement ROM in Virtual Aquarius, I'll quote from the assembly thread:
 

For a long time, this character set posed a problem for emulation authors: the contents of the original ROM are not directly accessible, so most emulators (including Virtual Aquarius) have used "approximations" of the original Aquarius characters. For complete character sets that were drawn by hand, they were remarkably close, but several of them included subtle but noticeable discrepancies.

You can use the replacement ROM with the Virtual Aquarius emulator, but the current version has a bug: it provides a "Browse" button to choose a different character set, but this button doesn't seem to do anything. Here is a workaround:

Once you have unzipped the Virtual Aquarius archive into its own folder, look for a subfolder inside it called "ROM". This contains several cartridge dumps, as well as a dump of the Aquarius operating system. Copy this character ROM into this folder and rename it to "CHARS.BIN". Then, open Virtual Aquarius, open the "Configure" menu, select "Memory ...", and toward the bottom of the dialog box, select the "Load 2K Character ROM from disk" radio button and click the "Browse" button. Click OK to reset the emulator.

You should now be using the correct character set. To check, press ENTER to start BASIC, type the following line of code, and press ENTER again:
 

PRINT CHR$(215)
If you are using the correct character set, the simulated Aquarius should have printed a character which looks like this:

post-3819-129297632198.png

You're still using the built-in character set if you see this instead:

post-3819-129297633195.png

(I've enlarged both of these so you can more clearly see the difference).
 

The only other tool you will need is a text editor. Note that a text editor is not the same thing as a word processor: both are writing tools, but the text editor saves your files as plain text, without any formatting information or metadata. Microsoft Windows comes with Notepad, but since this is a very simple editor, many developers choose to use editors which offer more features, such as macros and syntax highlighting. The editor that I usually use on Windows systems is VEDIT by Greenview Data, but just about any editor will do. Even plain old Notepad is a much better alternative than typing a lengthy BASIC program on a real Aquarius!

#2 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Tue Nov 5, 2013 10:25 PM

So, now that you have the tools, how do you develop BASIC programs for the Aquarius on a modern PC?
 
Using a modern PC for development offers many conveniences over an original Aquarius: you can write your programs using any text editor you choose (and a much more comfortable keyboard!), and you can save your programs to plain text files on your PC instead of cassettes.
 
Since the Aquarius uses its own built-in version of Microsoft BASIC, there is no BASIC compiler or interpreter that you will need to install on your PC; you will be loading and testing your programs in the emulator instead.  Fortunately, thanks to a feature of Virtual Aquarius called "Quick Type", this is a very easy process: once you've saved your program to a file, you're only a few steps away from loading and testing it in the emulator.
 
Let's see how "Quick Type" works by trying it with one of the sample programs.  Start Virtual Aquarius (using the procedure described in the first post), and you should see a startup screen of changing colors containing a "Press RETURN key to start" prompt.  Press ENTER on your keyboard, and you'll see the following:
 
start.png
 
The prompt shown on this screen (the black cursor) is where you would normally begin typing your BASIC program at the keyboard.  But, using the "Quick Type" feature, we will instead use the emulator to read a program from a text file, line by line, and "type" it into the simulated Aquarius, just as if it was being entered at the keyboard.

Open the "File" menu in Virtual Aquarius, and choose the "Quick Type ..." option.  An "Open" dialog box will appear, in which you will choose the text file to be "quick typed" into the emulator.  The default location should be the Virtual Aquarius folder; if it is not, browse your file system until you find the folder in which you unpacked the Virtual Aquarius emulator.  In this folder, you should see a subfolder called "QUICKTYP", and inside this folder, another subfolder called "GraphicFun".  This contains a few sample programs, in the form of BASIC program listings stored in text files.  Choose one of these files (such as "KALEIDO.TXT") and click the "OK" button, and you should see a series of BASIC program lines scroll rapidly on the screen.  This is the emulator "quick typing" the program into the simulated Aquarius's memory, and it should be able to complete even the largest BASIC program within a few seconds:
 
listing.png
 
Once the program lines stop scrolling on the screen, the "quick type" process is complete.  Some of the sample BASIC programs will start automatically at this point; others will return control of the keyboard to you, and you will have to type "RUN" followed by the ENTER key to start the program.  The "KALEIDO.TXT" program will draw a simple kaleidoscopic color pattern on the screen:
 
kaleido.png
 
To get an idea of how to use "Quick Type" with your own programs, close Virtual Aquarius and take a look inside one of the sample program files.  Using the Windows Explorer file manager from the Windows desktop, open the Virtual Aquarius folder, and then the "QUICKTYP" subfolder, and then the "GraphicFun" folder.  Double-click the "KALEIDO.TXT" program file, and it should open in your default text editor (Windows Notepad, unless you've installed a different editor).
 
editor.png
 
Look at the contents of this file in the editor, and notice that it contains the exact lines of text that you would ordinarily type at the keyboard on a real Aquarius, including the line numbers and any "immediate mode" commands such as "NEW" or "RUN".  In fact, it's a good idea to do what the author of this program did and put "NEW" in the first line of your program files, to clear the memory and make room for your new program before it is loaded.  To make your program run automatically after it is "quick typed", put "RUN" in the last line of your file.  Since Microsoft BASIC is an interpreted language, there is no need to compile your program; just save it to a text file, and after the program is loaded into the emulator using the "Quick Type" feature, it will be read and executed line by line by the interpreter.

This is the general procedure that I recommend for writing your own programs in BASIC: enter your program in the editor, save it to a text file, and then load it into Virtual Aquarius using "Quick Type".  If you find that you need to make a change to your program, don't make the change within Virtual Aquarius; instead, go back to your text editor, make your changes there, save your revised file, and "quick type" it into your emulator again.  You may also need to reset the emulator (choose "Hard Reset" from the "File" menu) before "quick typing" your program.  Just remember: don't use "Quick Type" unless the BASIC prompt is visible and awaiting input!  This means that, if the startup screen is visible, you must remember to press ENTER first.  If the emulated Aquarius is in a state in which it isn't ready to accept keystrokes, it won't be ready to accept your "quick typed" text, either!

That should be enough to get you started.  Let me know what you think, and of course, I invite questions or additional ideas!



#3 Gemintronic OFFLINE  

Gemintronic

    Jason S. - Lead Developer & CEO

  • 9,172 posts

Posted Wed Nov 6, 2013 12:14 AM

This is bookmarked!  Thank you very much for explaining things and consolidating sometimes hard to locate information.

 

I'd like to make or customize an existing tile editor to aid in building Aquarius game art.  Is there any chance the simulated Aquarius font is out there in bitmap format?



#4 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Wed Nov 6, 2013 8:37 AM

Got it.  Im on the virtual AQ now going over the guidebook. 

 

Thanks!



#5 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Wed Nov 6, 2013 10:49 AM

I'd like to make or customize an existing tile editor to aid in building Aquarius game art.  Is there any chance the simulated Aquarius font is out there in bitmap format?

Do you mean the replacement character set built in to Virtual Aquarius?  There is a "quick type" program provided with Virtual Aquarius called "showchars.txt" (it's in the "ForNerds" folder, inside "QUICKTYP") which simply displays all the characters on the screen.  The easiest way to get these characters in bitmap format would be to "quick type" this program into Virtual Aquarius and run it, and then capture a screenshot:

 

chars.png

 

I'm using the default Virtual Aquarius characters here instead of my replacement ROM, so there are some inaccuracies.  If you want to use these characters for other purposes, you can crop them out of this screenshot as 8x8 tiles using your favorite graphics program.  I'll see what I can do about putting together a quick program to "slice" this into tiles programmatically.  (EDIT: I converted these to individual bitmaps already; see my next post.)

 

I already have an Aquarius Screen Editor, albeit in a half-completed state (I posted a screenshot in the original Aquaricart thread).  When it is finished, it will make designing nice-looking Aquarius screens much easier.  I'll try to add the ability to save them in a format that can be used inside BASIC programs as well.



#6 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Wed Nov 6, 2013 3:14 PM

Thanks Jay, this thread makes clear that basic programming on the Aquarius is very entertaining to achieve fast programming results of ideas someone may have. 

 



#7 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Wed Nov 6, 2013 3:55 PM

Its coming back gradually, programing in basic. I started today reading the guidebook, and i shoild be done with the book tonight. :)

#8 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Wed Nov 6, 2013 4:48 PM

Okay, I've split the Virtual Aquarius "character map" screenshot from my last post into individual bitmaps.  The attached archive contains 256 image files, corresponding to the 256 characters in the Virtual Aquarius character set.  Each file is in PNG format, 8x8 pixels in size, with the file names corresponding to the original character codes:

 

Attached File  VirtualAquariusCharacterBitmaps.zip   44.34KB   190 downloads

 

I also converted the original Aquarius character set (from the ROM that I posted) into bitmaps in the same way:

 

Attached File  OriginalAquariusCharacterBitmaps.zip   44.34KB   179 downloads

 

In case anyone is wondering, here is a list of the character codes which differ between these two sets:

 

017

052

064

148

153

191

215

224



#9 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Thu Nov 7, 2013 4:36 PM

Day Two of Studying Aquarius basic.  Here is a dumb little video I made. 

 

 



#10 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Thu Nov 7, 2013 4:39 PM

I have been going based on the book, and I am wondering is there a second book, or someplace where I can find more advance programs than what is in  the guide to home computing?  The reason I ask is because the programs are mostly text based, and im wondering what the commands are for something more complex, lets say I wanted running man to shot down the jet. 


Edited by voltron, Thu Nov 7, 2013 4:43 PM.


#11 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Thu Nov 7, 2013 4:48 PM

I just realized I gave running man some stealth powers as well.  :)



#12 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Thu Nov 7, 2013 9:07 PM

I have been going based on the book, and I am wondering is there a second book, or someplace where I can find more advance programs than what is in  the guide to home computing?  The reason I ask is because the programs are mostly text based, and im wondering what the commands are for something more complex, lets say I wanted running man to shot down the jet.

The Guide to Home Computing is a good reference for Aquarius BASIC, but unfortunately it doesn't have very many sample programs. There were a great many third-party programming guides and collections of type-in BASIC programs published in the 80s, so that might be the next logical step. I remember learning a lot from studying how other programmers solved the kinds of problems I couldn't quite figure out on my own.

Given its short lifespan, I don't think very many of those books were written specifically for the Aquarius, but it wouldn't be much work to adapt BASIC programs written for other systems: the kaleidoscope program that I mentioned earlier, for example, was evidently written for the CoCo. A book for the Sinclair ZX81 (the Timex/Sinclair 1000 in the US) might be your best bet: that machine was similar in specifications to the Aquarius (Z80 processor, character-oriented graphics, a comparable amount of RAM, etc), and it used a similar dialect of BASIC. It was also a much more successful machine, having been introduced a few years earlier, so it got lots of books which are still easy to find on the used market.

Here's a good one that I remember spending a lot of time with:
 
51gameprogs.jpg
51 Game Programs for the Timex Sinclair 1000 and 1500 (by Tim Hartnell, 1983)
 
Amazon has almost no information about it, but it's a collection of different types of games, most of which are relatively short and simple.  I remember a Tic-Tac-Toe game, a couple of card and strategy games, some simple action games, etc.  You're bound to find something instructive in it.  I haven't found a scanned copy anywhere, but there are several Amazon sellers who have inexpensive used copies available.



#13 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Thu Nov 7, 2013 10:14 PM

Im going to get the book. .yeah the Guide to home comouting is excellent, but i finished reading it, and doing the programs, so imready for intermediate training. :) Im curious are there more commands and functions that are not listed in the book. I remember when I was a kid, there were a few command that the computer to identify a color change, for example when i made the game as a kid the missile was one color, the plane a different color so if the missile touched the planed the point where it touched would produced a mixture color of the two and that would count as a hit.


But today was productive. :) I know the video shows a simple program, but for me it showed me i understood what i read, bc i wrote it from memory, except for the character set, i had to peak at the graph to see which one i wanted to use.


Im becoming an aquarius junkie. :)

#14 voltron OFFLINE  

voltron

    River Patroller

  • 3,204 posts
  • INTELLINATI
  • Location:Far Universe playing Intellivision

Posted Thu Nov 7, 2013 10:15 PM

holi moli the book is only a penny. :) just shipping

#15 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Thu Nov 7, 2013 10:26 PM

Im becoming an aquarius junkie. :)

Glad to hear it! That odd little machine has a way of growing on you, as I've found out the "hard" way. :)
 
You could detect collisions in several ways.  In a game where you're shooting down a plane with a missile, for example, you'd probably use one character for the moving missile and several characters to make up the plane body.  You could program your game to move the missile up the screen one character cell at a time, checking each new cell to see if it is empty or if it has a piece of plane in it (the latter would indicate a hit).  That would be an example of detecting a collision using characters, but you could certainly do the same with colors.  Using either method in BASIC would involve using PEEK statements to return the contents of a memory address, either in the character matrix or the color matrix; both are described in the Guide to Home Computing.
 
(I can't view your video from the computer I'm on right now, but I'll look at it as soon as I can!)

#16 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Thu Nov 7, 2013 10:31 PM

holi moli the book is only a penny. :) just shipping

I'm pretty sure I still have my copy of that book as well (somewhere in my stacks of stuff), so if you have trouble "translating" any of the programs in it, let me know which one you're working on and I'm sure I can help you figure it out.  Aside for differences in the character sets, the only differences that I can imagine between the two versions of BASIC would be slight changes in syntax, or perhaps different methods of clearing the screen or checking a memory location for a character.  Adapting these for the Aquarius would be relatively simple.

#17 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 9:26 AM

I have been going based on the book, and I am wondering is there a second book, or someplace where I can find more advance programs than what is in  the guide to home computing?  The reason I ask is because the programs are mostly text based, and im wondering what the commands are for something more complex, lets say I wanted running man to shot down the jet.

Indeed there are a few books available. At the time I got my Aquarius in the earlie eighties I didn't have more than the basic manual, but at this point I have the follwoing in my collection: "The Aquarius and how to get the most of it" by Ian Sinclair, "30 Dynamic Games for the Aquarius by Tim hardwell" and finally "The Aquarius program book" by Peter Goode. There should be one out there named "Mattel Aquarius Ideabook" by David H. Ahl, but I have never seen anyone having it? I have a scanned version of the first book "The Aquarius and how to get the most of it" for you if you want, but because of the size I cannot post it here. So if you want it I can send it to you by general E-mail. Furthermore I would recommend you to become a member of the Mattel Aquarius Yahoo user group, because in the file segment, there is also a lot to be found which may come in handy!

#18 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 9:37 AM

I have been going based on the book, and I am wondering is there a second book, or someplace where I can find more advance programs than what is in  the guide to home computing?  The reason I ask is because the programs are mostly text based, and im wondering what the commands are for something more complex, lets say I wanted running man to shot down the jet.

Also there is of course the "Extended Basic" which covers some more commands also on the graphical side and if you use the 1541 version you also have some more sound and joystick control. PS the best version is the 1541V2 debugged by Martin see the thread 1541OS Aquarius Extended Basic issue within this forum. If you want a scanned version of this manual I also need a general E-mail address due to the size.

#19 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 9:43 AM

holi moli the book is only a penny. :) just shipping

Here is something to get you started (from an Aquarius User magazine).

Attached Files


Edited by Aquaman, Fri Nov 8, 2013 9:44 AM.


#20 Gemintronic OFFLINE  

Gemintronic

    Jason S. - Lead Developer & CEO

  • 9,172 posts

Posted Fri Nov 8, 2013 9:47 AM

I'm guessing I can't target Extended BASIC because of the way I need to make a physical game: .CAS -> ROM -> Cart. 

 

Another quandary might be like the situation with converting Family BASIC programs into an .NES ROM: You end up sucking in code from companies other than Yourself Ltd.



#21 jaybird3rd OFFLINE  

jaybird3rd

    Quadrunner

  • Topic Starter
  • 8,998 posts
  • "Excuse me, sir? I have a question ..."
  • Location:806.4616.0110

Posted Fri Nov 8, 2013 9:58 AM

I'm guessing I can't target Extended BASIC because of the way I need to make a physical game: .CAS -> ROM -> Cart. 

Correct.  Martin's tool will create a ROM which includes only your own BASIC program, except for a small bootstrap routine.  It will not include the Extended BASIC extensions, so if you plan to make your program into a cartridge, you can't use any of the Extended BASIC commands.  Fortunately, most of them are easy to live without, as I said earlier (unless you really need to compute arctangents).

 

Thanks to Aquaman for listing those Aquarius books.  I've love to see scans made of these books, since printed copies are few and far between, and the last time I checked, are very expensive as well.



#22 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 10:04 AM

I'm guessing I can't target Extended BASIC because of the way I need to make a physical game: .CAS -> ROM -> Cart.

Of course the people you reach would be even more restricted. They would need the Extended Basic cartridge or The Aquaricart for that matter (good for sales of the Aquaricart) and the Mini-expander to hold two cartridges. Otherwise I see no real problems of converting it, but that's something Martin can better answer! Oh, I just see that Jay already did answer this, and it is not possible! PS I only use extended basic 1541V2 to test my programming out (Joypad, sound) and afterwards I want to replace those particular functions with assembly! That makes me wonder, if the conversion still would work when parts of the programming is being done in assembly? (Martin could you please answer this?)

Edited by Aquaman, Fri Nov 8, 2013 10:08 AM.


#23 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 10:17 AM

Thanks to Aquaman for listing those Aquarius books.  I've love to see scans made of these books, since printed copies are few and far between, and the last time I checked, are very expensive as well.

Unfortunately the 2 books with listings are difficult to scan without ruining them, the other two I will gladly send you by E-mail!

Edited by Aquaman, Fri Nov 8, 2013 10:21 AM.


#24 Gemintronic OFFLINE  

Gemintronic

    Jason S. - Lead Developer & CEO

  • 9,172 posts

Posted Fri Nov 8, 2013 10:23 AM

Can you inject assembly routines from BASIC?



#25 Aquaman OFFLINE  

Aquaman

    Moonsweeper

  • 374 posts
  • Location:the Netherlands

Posted Fri Nov 8, 2013 10:33 AM

Look for example at the website of Martin to get the general idea http://www.vdsteenov...us/psgprog.html





Also tagged with one or more of these keywords: mattel, radofin, aquarius, programming, homebrew, BASIC

0 user(s) are browsing this forum

0 members, 0 guests, 0 anonymous users