Entry for the PUR-80 category of the 2021 BASIC 10 Liner.

(For Mattel Aquarius - MattPilz.com - @MattPilz - YouTube)

FOREWARD

One of my earliest memories in video gaming history was playing Cosmic Ark for the Atari 2600. The sounds and visuals of that game are still etched in my mind all these decades later.

I recently became immersed in the world of Mattel Aquarius, a decidedly underpowered discount home computer system from 1983 that existed for mere months before being phased out. The lack of a dedicated graphics chip or programmable characters make this computer, in many ways, less programmable than the 2600 released six years prior.

Despite its shortcomings, I still find charm in the system. The old adage "limitations foster creativity" rings especially true for this platform. There still exists a small but passionate community of like-minded individuals who are taking the system to new levels with fresh software and hardware modifications.

To pay homage to the classic space shooter of my youth, while also celebrating the 10th anniversary of BASIC 10 Liner and my newfound admiration of Aquarius, I decided to develop the aptly titled Cosmic Aq.

There are some agonizing challenges in working for this platform especially within the scope of a 10 liner. Most notably,  each line can be a maximum of 72 characters and there is no abbreviated syntax for the commands. This gives Aquarius developers a hard limit of 720 characters instead of 800 characters allocated on other platforms in the PUR-80 category.

My original high ambitions for this project quickly diminished when I realized that I was nearing capacity of the code limit just in constructing the visuals for the ship and comet, which initially included a much more elegant design as well as dust trails and explosion effects. I had to refactor the design endlessly to squeeze enough game mechanics in to consider it a completed project. It is comparable to the meteor shower mode of the original Cosmic Ark.

Enjoy!

THE CODE

REM----------------EACH LINE IS 72 CHARACTERS IN LENGTH-----------------
0DIMB(22):D=12747:E=12347:T=50:L=53:M=14346:N=12774:Q=22:R=N:S=243:A=160
1B=1024:?CHR$(11):POKEE-59,46:FORI=0TOQ:Z=3-Z:POKEINT(960*RND(1)+E),46-Z
2READX:B(Q-I)=X:D=D+X*(I<13)*-1:POKED,S+Z:POKED+B,179+Z:SOUND(I,I):NEXTI
3SOUND(Q,S+S*F):IFL=48THENSOUND(Q*2,S*4):?TAB(53)"SCORE";:?P:INPUTA$:RUN
4G=INT(2*RND(1)+1)*SGN(RND(1)-0.5):U=E+460*ABS(G-1):H=40*G:K=9:F=2:V=-23
5POKEE+23,L:T=T+(G<=1):C=1-(T<-L):IFABS(G)=2THENU=N+(6.5*ABS(G-2)):H=G/2
6FORI=0TOKSTEPC:V=-V:POKEU+H*I,173+V:W=PEEK(M):O=I:IFW=B(G+2)THENF=1:O=K
7FORJ=0TOT:NEXTJ:R=B(G+7)+N:IFF=01THENPOKE(R),213:POKE(R+B),54:F=0:P=P+1
8POKEU+H*(I),A:I=O:NEXTI:POKE(M),A:POKE(R),A:POKE(R+B),22:IFF=2THENL=L-1
9GOTO3:DATA0,37,1,1,1,1,1,1,36,1,1,39,-498,9,-67,0,133,17,44,97,0,122,46
REM--10--||---20---||---30---||---40---||---50---||---60---||---70---|72

MATTEL AQUARIUS

The Mattel Aquarius has a fixed 256 character set and no GPU. It uses early version of Microsoft BASIC—1.7K usable RAM. It also only supports a maximum of 72 characters per line. The screen has a 40x24 grid of tile-like characters-16 colors.

STORY

The crew's latest interstellar effort aboard "Aquarius '83"  has gone dangerously astray. Caught in a shower of deadly and  increasingly violent meteors, the ship has already been hit. Now, it's a hard battle to the end; missiles against meteors!

GAMEPLAY

You control the tattered Aquarius spacecraft, hovering in space and with minimal protection against the meteors. By chance, the ship still has functional four-way missles and these can be fired upward, downward, to the left or right. Use this weaponry to obliterate all the incoming meteors!

The game ends when you've been hit more than 5 times. At the end, your score will be shown. Press [ENTER] to start a new game, or [CTRL]+[C] to exit.

CONTROLS

These are the essential controls you'll need to succeed:

• [<] = FIRE LEFT
  [>] = FIRE RIGHT
• [A] = FIRE UP
• [Z] = FIRE DOWN
• [ENTER] = NEW GAME
• [CTRL]+[C] = EXIT GAME

LAUNCH GUIDE

The game can be played on a real or emulated Aquarius using the factory system base.

EMULATION

The code should work in any Aquarius emulator. The longest standing one is Virtual Aquarius 0.72a. Others include AquaLite and AquaWX from the Mattel Aquarius Computer Group on Facebook. These instructions are for Virtual Aquarius, which is readily available.

(For any emulator, you should be able to simply insert/paste the 10 lines of source code and then type RUN.)

VIRTUAL AQUARIUS: QUICK TYPE

EMULATOR: http://zophar.net/aquarius/virtual-aquarius.html

1. Launch Virtual Aquarius or do hard reset if already running.
2. Select File → Quick Type...
3. Browse to "cosmic_src.txt" and double-click to load and run.

VIRTUAL AQUARIUS: CASSETTE LOAD

1. Launch Virtual Aquarius or do hard reset if already running.
2. Type: CLOAD and then press [ENTER]. 
3. Press [ENTER] again to begin the cassette load operation. 
4. Select File → Play Cassette File...
5. Browse to "cosmic_tape.caq" and double-click to load.
6. Type: RUN and then press [ENTER].

PHYSICAL DEVICE

For maximum authenticity, you can run this code on a stock model of the Mattel Aquarius. 

DEVICE: CASSETTE LOAD

REQUIREMENTS: Aquarius with Compatible Cassette Player & Cable.

Note: This process is sensitive and I only recommend it if you  have previous experience transferring cassette data to  Aquarius. Each sound system and output process will vary.

1. Transfer "cosmic_tape.wav" to cassette tape via line-out.
2. Place the cassette into the tape player and rewind it.
3. Power on the Aquarius and press [ENTER] to launch BASIC.
4. Type: CLOAD and then press [ENTER].
5. Press [ENTER] again to begin the cassette load operation.
6. Press [PLAY] on the cassette player, you should see "Found: Cosmic."
7. Once the prompt reads "Ok" type: RUN and then press [ENTER].

DEVICE: MANUAL TYPE-IN CODE

To experience the thrilling art of 1980s type-in coding books, or if you just feel like an absolute madman, you can manually enter the source code into Aquarius, letter-by-letter.

1. Power on the Aquarius and press [ENTER] to launch BASIC.
2. Carefully type all 10 source lines from "cosmic_src.txt" as seen.
3. Type: RUN and press [ENTER]..

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

LINE EXPLANATION:  HIGH LEVEL OVERVIEW

Below is a basic summary of what each of the 10 lines achieves. To more fully understand each line, refer to line-by-line breakdowns instead.

• LINE 0: Declares the main variables and array and sets defaults.
• LINE 1: Initializes display, generates stars & begins draw loop. 
• LINE 2: Reads data into array and draws the on-screen spaceship.
• LINE 3: Starts main game loop, handles sound, game over & reset.
• LINE 4: Calculates direction of meteor and sets base properties.
• LINE 5: Updates lives and sets properties for horizontal meteor.
• LINE 6: Handles meteor movement display and checks player input.
• LINE 7: Controls meteor speed and sets flag if player won round.
• LINE 8: Cleans up visuals for next round and handles round loss.
• LINE 9: Jumps to start of loop and stores values for game array. 

LINE EXPLANATION: DETAILED EXPLANATION

This section contains extremely technical details of how each line is constructed and the many intricacies required to fit it all in 720 characters of data across 10 lines. Useful for programmers, not so much for general enthusiasts.

LINE 0: Variable Declarations

0DIMB(22):D=12747:E=12347:T=50:L=53:M=14346:N=12774:Q=22:R=N:S=243:A=160 

• B: Array that stores 23 integers from DATA (Ship, Controls, Misc.).
• D: Topmost screen location of the ship visuals (Row 10, Col 19).
• E: Default screen location of incoming meteor (Row 0, Col 19).
• T: Delay duration of approaching meteor; gets faster every turn.
• L: Total number of lives as a character value (53=5 . . . 48=0).
• M: Storage location of last pressed key for checking keyboard input.
• N: Screen offset used when calculating meteor direction and display.
• Q: Matches "B" array length, used for iteration and sound effects.
• R: Calculated location for the firing edge of ship, defaults to N.
• S: Base character value for drawing the ship, also used for sounds.
• A: Character value for an empty tile, 32 and 160 are equivalent.

Line 1:  Display Initialization

1B=1024:?CHR$(11):POKEE-59,46:FORI=0TOQ:Z=3-Z:POKEINT(960*RND(1)+E),46-Z 

• Clears the screen, initializes data loop and draws basic HUD and bg.
• The value Z is assigned an alternating value of 3 or 0 for effects.
• The random starfield draws "." or "+" (46/43) to screen, based on Z.
• The far top-left tile 12288 (E-59) creates border from character 46.
• B: Stores 1024, the offset needed to add COLOR to POKED characters.
• I: Begins the loop from 0 to 22, used to load DATA, draw ship, etc.

LINE 2: Data Storage and Ship Generation

2READX:B(Q-I)=X:D=D+X*(I<13)*-1:POKED,S+Z:POKED+B,179+Z:SOUND(I,I):NEXTI

• Stores DATA values into array B for ship design, controls and more.
• The array order is inversed to save a few characters on input check.
• For the first 13 elements, draws to screen to construct the ship.
• POKE command uses data values to draw ship from offset D (12747).
• Z value is used to alternate ship char 243/246 and colors 179/182.
• The result of the alternating character/color is a "run-down" look.
• Plays a small tune while the game is initializing, repeats loop.

LINE 3: Start of Game Loop

3SOUND(Q,S+S*F):IFL=48THENSOUND(Q*2,S*4):?TAB(53)"SCORE";:?P:INPUTA$:RUN 

• Called at end of each "round" when meteor reaches ship or is shot.
• It plays a unique sound effect based on whether user survived round.
• If the lives are 0 (character value 48), an end sequence occurs.
• At game over, a final death sound is made and the score displayed.
• The program then waits for user input, on [ENTER] will start over.
• Pressing [CTRL]+[C] will break out of the program and exit game.

LINE 4: Calculate Direction of Meteor

4G=INT(2*RND(1)+1)*SGN(RND(1)-0.5):U=E+460*ABS(G-1):H=40*G:K=9:F=2:V=-23 

• The direction of the next meteor is determined by this unusual line.
• It generates a value of -2 (RIGHT) -1 (BOTTOM) 1 (TOP) or 2 (LEFT).
• In this way, the value can be passed to an array for input handling
• as well as visual updates to the appropriate ship side and so forth.
• The variables defined and updated on this line are given defaults
• applicable for BOTTOM (-1) and TOP (1) meteor directions.
• G: Direction of the next meteor, as described above (-2, -1, 1, 2).
• U: Calculated vertical movement vector and location of the meteor.
• H: Calculated horizontal movement vector and location of the meteor.
• K: Total number of moves the meteor has before reaching the ship. 
• F: Resets flag that indicates if player loses (2) or wins (1) round.
• V: Offsets meteor character value to provide animated effect [O o].

LINE 5: HUD Update and Meteor Initialization

5POKEE+23,L:T=T+(G<=1):C=1-(T<-L):IFABS(G)=2THENU=N+(6.5*ABS(G-2)):H=G/2 

• Updates the total number of lives and space ship icon for HUD.
• 75% chance of decreasing the meteor delay T by 1 so it progresses in speed.
• If the user is extraordinary and gets 73+, it will double the step (hyper speed).
• Checks to see if the meteor direction is LEFT or RIGHT (2, -2).
• If so, updates the variables to support horizontal movement instead.
• The position is recalculated so it can accommodates both directions.

LINE 6: Meteor Movement and User Input

6FORI=0TOKSTEPC:V=-V:POKEU+H*I,173+V:W=PEEK(M):O=I:IFW=B(G+2)THENF=1:O=K 

• Creates a loop based on defined meteor direction properties.
• Draws the meteor to screen based on the current loop index and data.
• 16|-16 is added to the character base of 95 to animate meteor look.
• Data cell containing last pressed key is read and compared.
• If the pressed key matches the meteor direction, player wins round.
• I: Iterator that traverses the meteor from edge of screen to ship.
• C: Step value for loop/speed. If alive after 100 turns, is set to 2 (hyperspeed!).
• W: Stores the last pressed user key to compare input.
• F: Flag is set to 1 to indicate the user has won the round.
• O: If user has won, sets value to end of for loop for an early exit.

LINE 7: Time Delay and Round Win 

7FORJ=0TOT:NEXTJ:R=B(G+7)+N:IFF=01THENPOKE(R),213:POKE(R+B),54:F=0:P=P+1 

• In Aquarius, delays are created using simple loops like CPU cycles.
• An empty loop is iterated based on duration value to slow meteors.
• Each successful attack against a meteor reduces the delay 1 cycle.
• If the user fires in same direction as meteor, it displays gunshot.
• A point is awarded for a successful hit against the meteor.
• The win flag gets set to 0 specifically for sound reasons in line 3.

LINE 8: Cleanup and Round Loss 

8POKEU+H*(I),A:I=O:NEXTI:POKE(M),A:POKE(R),A:POKE(R+B),22:IFF=2THENL=L-1 

• Overwrites last meteor and gunshot locations to clear the graphics.
• Resets input value so it doesn't match any of the four directions.
• Sets the color of the ship edge area to red (for visual collisions).
• If the round has been lost, decrease player lives by one.

LINE 9: Loop End and Data Structure 

9GOTO3:DATA0,37,1,1,1,1,1,1,36,1,1,39,-498,9,-67,0,133,17,44,97,0,122,46 

Sends the program back to line 3 to begin the next round. Contains 23 different data elements used throughout the program. The data is stored in the array in REVERSE-ORDER for some reductions.

[0-4] : 46,122,0,97,44

• Stores the character codes that correspond to input.
• 46 = FIRE RIGHT (-2), 122 = FIRE DOWN (-1)
• 97 = FIRE UP (1), 44 = FIRE LEFT (2)
• The middle value 0 is the base point referenced in game.
• To its index gets added the direction value (-2,-1,1,2).
• This allows condensed checking if user has shot meteor.
• The middle value is arbitrary and is not actively used.

[5-9] : 17,133,0,-67,9

• Stores the values of the ship edges as offsets from N.
• Used to alter colors/designs on fire or collision.
• The middle value 0 is the base point referenced in game.
• To its index gets added the direction value (-2,-1,1,2).
• The middle value is arbitrary and is not actively used.

[10] : -498

•  Traverses back to top of screen during ship generation.
• This is to override the default black cursor at the top.
• In the game, this tile gets replaced with the lives icon.

 [11-22] : 39,1,1,36,1,1,1,1,1,1,37,0

• Stores offsets from D-12747 for the ship's construction.
• The ship is built as data is read & stored as part of it.
• Could be useful in-game to make parts of ship destruct.
• Not actively called in-game due to no coding space left!