The Commander X16 Launch SD Content Explained (and other X16 Usage Topics)

Last Revised 2024_05_25

Launch SD image archive here

TABLE OF CONTENTS

  • Introduction
  • A Note on Possible SD-Card Content Differences
  • Backing Up Your SD-Card and Notes about Read-Only Tab
  • Launch SD-Card Content Orientation
  • Some Startup Recovery Options
  • First Things First – AUTOBOOT.X16
  • Discussion About BASIC Tokenization
  • Back to AUTOBOOT.X16 (and Loading PRGs Explained)
  • Things To Do in AUTOBOOT.X16 (more examples)
  • More About the BOOT Command and Even More AUTOBOOT.X16 Examples
  • Some Final Words about AUTOBOOT.X16:
  • How //LAUNCH Works

(outline of some future topics)

Introduction

During an 8-week session from October through Novermber 2023, I helped organize the content for the “Launch SD” card for the Commander X16. While David and Kevin were preoccupied with the details of manufacturing the board (and coordinating the payment and storage of all the materials involved in that), I was asked to gather up a collection of the available X16 software (and to test and ensure those titles remained compatible with the current ROMs).

Along the way, AndyMT volunteered to produce a LAUNCHER program, essentially started from scratch using cc65. He developed a strategy for having both descriptions and image thumbnails. And the X16 community, across Discord and the Forum, offered up a wide variety of initial sample software.

I had hoped to prepare a video-walkthrough of this “Launch SD” content before the bulk of X16 deliveries. But around that time, I got bogged down dealing with a six-figure Breach of Contract by a bum contractor we had hired (for a completely unrelated project), then throughout March I got reminded and distracted about the total solar eclipse that came through in April. As an avid astronomer, I couldn’t pass that up! So for a compromise, I’ve started preparing written descriptions of what I would have liked to have covered in those walkthroughs.

Here are those total solar eclipse photos I took on April 8th, 2024 from my backyard in Texas (using an 80mm lens on a cooled CMOS sensor):

And yes, this is a full eclipse where the moon is photo-bombing the sun. In doing so, we get a brief opportunity to examine solar flares emanating from the sun.

A Note on Possible SD-Card Content Differences

Note that during the rollout of X16’s, there were some small changes in the SD card content over time. But for the most part, the Launch SD of the first 1000 systems should be fairly consistent. Here is an example of differences between an early PR16 and later PR900 SD-card:

To summarize these differences:

  • In APPS, the TERMINAL.PRG was added (which only works with a TexElec card that isn’t yet available)
  • In BASIC-GAMES, HANGMAN version was updated to the then-latest.
  • In DEMOS, KG3D was updated to the then-latest. For me, I always preferred the original two room version, if only to have as a reference years from now to show how far we had come in unleashing the potential of VERA FX.
  • EXPLORE\DOCS was relocated to the root folder. I didn’t do this originally since I didn’t want PDFs outside of the EXPLORE folder (and also didn’t want the DOCS folder showing up in the LAUNCHER, since there is nothing it can launch in there). More on that later.
  • GAMES had 8BG’s software updated (Planet X16, PETSCII Robots, Tetrads).
  • Apparently in addition to SD-card updates, there were also different ROM versions installed across that initial set of 1000. So now when providing support, we’ll need folks to type HELP and note the git commit version to verify which ROM build is being used.
  • Systems delivered after April 2024 may have additional differences, just based on who was packaging that next group of deliveries.

Because of these differences mentioned above, each X16 SD card can be considered as unique.

Backing Up Your SD-Card and Notes about Read-Only Tab

For me, I like to use a label-maker and put a small number on the SD card corresponding to the system. Obviously if you only have one X16 system this isn’t necessary, but it become helpful if you start using more SD-cards. The original X16 SD-card were consistently an 8GB card (which are getting harder to obtain, but very appropriate being “an 8-bit system” and just having that theme of “8” in it). Keep in mind that the X16 SMC firmware may have trouble supporting smaller SD cards than 8GB.

Be aware that the READ-ONLY tab on the SD-card does not really apply to the X16. Basically, the READ-ONLY tab is a software flag, so the Operating System or system as a whole must decide to honor that flag or not (which can cost some performance). The X16 file system does not support this flag (or at least, the SMC software does not, per my understanding). There had been thought on changing that, but for now that’s how it is: if you set the READ-ONLY TAB, don’t expect to be protected from the X16 making any changes to your high score tables or any other content on the SD-card.

For this reason, it is suggested to make a full backup of your SD-card (using a modern desktop PC or laptop) before using your SD-card.

HISTORICAL CONTEXT: Back when software was still delivered in boxes, they would include the “original factory disk.” A good habit was to never actually use those original disks, you would always make a backup first and use the software from that backup disks (of course, with an exception for copy-protected media). We hardly ever think of this today, since hardware is relatively so reliable now. But back then, disks drives would fail, or the disk might be your operating system (which you’d probably want to start making configuration changes to, but you wouldn’t want to do so on the original media disks). So just treating these modern SD cards in that context is part of the vintage experience.

Also, the original SD-card content isn’t maintained in any “official” archive. So don’t take it for granted that you can get your specific original back. The nearest “OG” (original) SD image can be found here:

X16 SD-card image “launch title” software – Commander X16 (cx16forum.com)

Which leads to here: https://www.dropbox.com/scl/fi/5ftf2r808w33mg9cy0e00/x16_sd_2023_12_14_RC3.zip

Here are the differences between that early RC3 (Release Candidate 3) and one of the earlier PR (Production) SD contents:

Summary:

  • BASIC folder was split into BASIC-GAMES and BASIC-DEMOS
  • 1160 was removed since it forced VGA output and we couldn’t get an updated build in time.
  • MEDEMO was removed due to possible licensing concerns (given that the PR boards are also a licensed commercial product)
  • KG3D was updated (excellent VERA FX demo, even though I still love the original)
  • CX16ASSEMBLER was updated with a few fixes
  • CALCA and TRAINYARD X16 were added
  • HANGMAN and LANDER were relocated to BASIC-GAMES (and version update)
  • X16ROBOTS changed to ROBOTS (note: this name change then broke the Launcher thumbnails, since the thumbnail support filenames were not changed to match the folder name change)
  • XBERT was removed due to licensing concerns after consulting with Sony
  • A few GAMES and DreamTracker updates
  • System ROM was updated (the system being launched with an alpha R47 rather than R46)
  • Version update on the FILEMANAGER PRG, and a note on using the Composite output was added in the INTRO folder.

Launch SD-Card Content Orientation

Due to a limitation in the LAUNCHER (and to have it ready by mid-December), the SD content was divided into two main categories – which I refer to as the “root” content and the “explore” content.

The main issue is that the LAUNCHER could not be configured to have “hidden folders.” And so, in that regard, it acts somewhat like a FileManager/Explorer type program. The real goal of a LAUNCHER is to help users quickly launch into the “best” or “most favorite” applications of the system. Originally the LAUNCHER was intended to focus just a handful of the most interesting and appealing software titles, so users could just jump in and enjoy something on the system very quickly. This was sort of like those walk-up Nintendo stations at Wal-Mart when that system was first released in the mid-1980s, and you could play a curated sample of their best titles. The main purpose being to showcase what the hardware could do and attract people to the system.

But the X16 is more than just a game-system, it is a full home-computer. So, the EXPLORE content was after users were done with the LAUNCHER content, and were ready to get more serious about learning the system (i.e. exploring using those DOS commands from command line, not explored via the LAUNCHER). So, within EXPLORE, that involved two main categories of content: (1) Incomplete (or work-in-progress) software that was still functional but needs more “hand-holding” to understand and use or to setup. (2) DEV tools, or software that required specifying a file or beyond just “gameplay” type input. Generally, things that more casual user wouldn’t get much enjoyment out of using the LAUNCHER for. For example, to fire up a complicated assembler that needs a lot of instruction before using.

Back in the 1980s, this might have been addressed by simply including two disks with the system (a kind of STARTER disk and ADVANCED disk). But since the 8GB SD card is so massive, it seemed silly to offer two different SD cards with the system. On this note, there is some philosophical debate about the SD card support on the X16: is it a “floppy drive” or a “hard drive”? Relative to the capacity of vintage floppy disks, the SD card is massive like a hard drive would have been then – you can “store everything” on it. But in operation, the SD card is like a floppy disks rather than a “fixed disks” – you can remove and re-insert the SD card at any time (other than when the activity LED is on).

Another way to address this “two disks” dilemma was to have multiple partitions on the SD-card. While technically that is supported, it was deemed too complicated to train users on how to mount up and reference the additional partition (plus imaging such a configuration, to make it easier to update and synchronize files within those images was also problematic). Hence, the compromise to just put the “less interesting” and “more work-in-progress” type stuff under EXPLORE (meaning, users would “explore” that content later using the X16 DOS commands). Another consideration here was one could just delete the EXPLORE folder, and you’d still have a viable and interesting Launch SD content.

There is some additional help and tutorial related docs in the EXPLORE folder. The HELP folder itself has nothing for the LAUNCHER to launch, so the most practical way to have it “hidden” from the launcher was to just move it into the EXPLORE folder.

There ended up 50 unique individual software contributors for the set of software chosen for the Launch SD card. This collection represented a good range of different software across both BASIC and 6502-machine code titles. These contributors are listed in the XINFO CREDIT file (as well as other contributors to the X16 project).

As some of the “ground rules” we decided for being in the LAUNCHER were:

  • Non-commercial, no licensed content (at least to the best of our knowledge)
  • “well-behaved” in that it didn’t freeze, lockup, crash, and in general performed whatever the purpose of the program was (that is, a “complete” software and not just a snippet). But we didn’t require the program to “exit gracefully” (and some in fact just reboot the system when they exit).
  • Work well on either modern flat panel or CRT output, in VGA and Composite mode. There are some who desire to exclusively use Composite mode, and numerous software titles would force VGA-out mode due to a one liner misuse of VERA registers.
  • “Family Friendly”, just for the sake of a broad audience.
  • Work also with 512KB RAM systems (i.e. not require a full 2MB).

As a “reward” for passing all those “quality checks,” we tried to ensure every title in the LAUNCHER had a description and thumbnail (we did miss a few, but did try our best). And to clarify, it wasn’t so much as a “reward” but just with the limited time and schedule, we focused on preparing the descriptions and thumbnails (making use of Aseprite) for those titles that would appear in the LAUNCHER.

The only “hidden folder” by LAUNCHER is the hard-coded LAUNDER.DATA folder. This folder contains the PRG descriptions and thumbnail files. They were split into two folders, since we found that hundreds of files within the same folder started to slow down the launcher performance when scrolling through titles. Some titles have multiple thumbnails, while some thumbnail files ended up becoming OBE (or changed to different filenames). The description NFO and thumbnail image filename need to exactly match the folder or file they refer to.

For those more experienced with these types of systems, the EXPLORE folder hierarchy can tend to make things harder to remember where things are (when exploring things from the CMDR-DOS prompt). In earlier packaging of the SD Card, we had this approach flipped from what ended up in the Launch SD – that is, EXPLORE-type stuff was all in the root, and the LAUNCHER content was in its own sub-folder. This was a way to keep only the desired content within the LAUNCHER menu, to avoid it being cluttered with “random” software titles that hadn’t yet been vetted. But the desired approach is a philosophy between starting the system up in a more FileManager type utility (and also having a more “flat” directory hierarchy) versus a more pure “focus only on these titles” type LAUNCHER like many other systems have. A better compromise would have been to have the LAUNCHER.INI contain a list of just the titles to be presented (as opposed to the LAUNCHER listing all content from the folder it is started in), but we just couldn’t finish the code for that in time.

Some Startup Recovery Options

In the /SYSTEM/SYSTEM-BOOT folder, we placed a feature to help adjust the startup method of your X16 more conveniently. Or this can also be used to recover your startup, if something unexpected has happened or perhaps it has gone missing. All this feature does is copy an archived backup copy of versions of the AUTOBOOT.X16 back to your root folder.

From the //LAUNCH menu you would go to SYSTEM then SYSTEM-BOOT and then choose the startup option you prefer:

  • (1) the “standard” startup with the text,
  • (2) just BASIC (essential no AUTOBOOT.X16),
  • (3) start with the actual FileManager,
  • (4) startup directly in the LAUNCHER,
  • (5) startup with the SHELL (that is similar to a Linux style command line shell).

If you are having trouble with the LAUNCHER, then the command-line way to get these options would be as follows:

@CD:/SYSTEM/SYSTEM-BOOT
LOAD "BOOT-BASIC-HELPER.PRG"
RUN

First Things First – AUTOBOOT.X16

During startup, the standard X16 System ROM will look for this file in the root folder of the SD file system. If found, then the System ROM effectively invokes these two BASIC commands:

LOAD "AUTOBOOT.X16"
RUN

Likewise, if you type the “BOOT” command, the above two commands are also issued. The difference is BOOT command will look for an AUTOBOOT.X16 within the CWD (current working directory) you are in, as opposed to only using the one in the root folder.

If you aren’t familiar with BASIC or file types in the Commodore system, then some of this will be a little confusing. I also didn’t come from a Commodore background (I used Tandy and IBM systems), so I can understand that initial confusion.

So, for this discussion, we’ll do a complete walkthrough of the Launch SD AUTOBOOT.X16 file. Even if you aren’t so interested about modifying what the system does during startup, the discussion will also introduce various concepts about BASIC at the same time.

Ok, to begin: when you startup your X16 with the SD-card inserted, you will see something like this:

If you want to follow in the emulator, it was started like this:

x16emu -ram 2048 -rom ROM.BIN -joy1

If you don’t see the above, double check that your SD-card is fully inserted. Or, perhaps you inadvertently overwrote the AUTOBOOT.X16 file (which can happen when using the MENU command and accidentally doing “SAVE SETTINGS” to AUTOBOOT.X16). In these cases, maybe try to restore your SD card from one of the available images.

So, in the normal case, where you are seeing something like the above, there is a lot to go over. The display of the X16 logo and the information to the right of that is called “the BANNER” because you get all that by typing the “BANNER” command at the BASIC prompt. More than just looking pretty, this is telling quite a bit of useful information:

  • (1) a reminder that you are using a tailored version of BASIC for the Commander X16 system, derived from Commodore BASIC V2 but is not exactly the same,
  • (2) that your system has 512KB or 2048MB (or some increment in between of 512KB), (3) the “git” checksum code of the specific System ROM build you are using. The “+” at the end means it is a pre-release (that wasn’t intended for general public release). The checksum value is supposed to let you go back into github and rebuild (or re-download) that specific System ROM, but sometimes (especially for pre-release variants) those options aren’t always available. Typically you would go to the X16 Technical Ref, go to “Releases” and stick to “official” builds.
  • (3) BASIC reserves some amount of System RAM for its own purposes, and so this reports how much remaining RAM is available for your use when writing a BASIC program. If you type “? FRE(0)” the system will display approximately the same number (typically -2 byte because the immediate mode parsing of ? and FRE took away two bytes momentarily). The “standard number” should be 38655 bytes remaining – if it is different than that, then some future System ROM update has made changes to BASIC that has caused it to consume (or free up) some available System RAM.

Next, there is a bunch of introduction text. Where did all that come from? It’s not part of the System ROM. I wrote this Introduction Text, to help orient those very new to these kinds of systems. The text was limited to not more than 40 columns, and to keep the full startup screen to less than 20 rows – in case anyone elects to startup on a CRT or a lower text mode resolution (which is possible in the MENU and saving those settings to NVRAM).

There was a lot of thought put into the Intro Text (or more specifically, what not to include), plus debate on whether to have any Intro Text at all (some felt it contradicted the fashion of all other “boots up to BASIC” systems). My thought was this is a new system and has this wonderful AUTOBOOT.X16 feature, what better way to showcase that feature than to show how some custom startup can be performed beyond what is “baked into” the System ROM. But there is another view that users should be “forced” to learn how to use the system by other off-system resources (the included user guide and the X16 technical reference website).

The first four lines I felt were important, since: (1) many vintage systems did not have a MENU-like command, which has settings stored in a small NVRAM. Or many vintage systems didn’t have a RTC (real-time clock) or 80 vs 40 mode, so I felt it was important to let users be aware that MENU exist to adjust these kinds of settings. (2) Showing the EDIT command was also important, as most vintage systems also did not come with such an excellent editor tool built into ROM. Out of the box, you could replicate the Doogie Howser Journal experience – a TV series starting in 1989, often ending with the main actor typing a journal in his computer). (3) HELP was important since if users eventually needed supported, they should be aware that HELP shows the version number of all the system software. (4) And unlike Apple or Commodore systems, this system doesn’t use CATALOG or DIRECTORY to list files in the current folder (or on IBM PC this was the FILES keyword). Instead, it is a DOS”$” command, that got shortened into “@$” in later System ROMS (which reminds me of the fall-off text in Q-Bert). It’s not intuitive or easy to remember, so when away from the system for a while, this is helpful on how to view directories on this system.

So, how does all this work? Let’s walk through where this comes from: start by doing the following commands:

@CD:/
LOAD "AUTOBOOT.X16"
LIST

You should see something like the following:

@CD:/ just ensures you are back at the SD-card root folder. LOAD is loading the AUTOBOOT.X16 which is a regular Commodore-style PRG file. Those types of files can be either BASIC tokenized code, or a machine code sequence that has a small BASIC program loader at the front. That will make more sense later, but for now just know that the AUTOBOOT.X16 is a regular X16 BASIC program.

Now that won’t mean much if you aren’t familiar with BASIC yet. But as you see from LISTing the program, there are few straightforward things: the BANNER is retained like the normal startup because this BASIC program calls the BANNER command on its very first line. It then simply PRINT’s the text that appears during startup. Some of the text has “weird characters” in them that correspond to PETSCII codes for console actions (in these cases, to change the color of the text). Commodore systems have a thing called “quote mode” that is started whenever you first type a double-quote symbol. When in quote mode, control-keys show up as “funny weird characters” instead of performing whatever they normally do. More on this later.

Further on in the program it is doing some “PEEK-magic.” Don’t be too intimidated by this. What it is doing is checking the version of the System ROM. There was a time just before Release that support for the “//” shortcut wasn’t yet supported, so as an exercise we put this example in the AUTOBOOT.X16 as a reminder to users on how to they can also check for ROM versions.

When using an “official” System ROM build (like R46 in the example below), you can use that same PEEK code in the immediate mode to also verify the ROM version. Just type:

A=PEEK($FF80):? A

This assigns variable A to the single-byte value at hex-address $FF80 (where the System ROM has decided to repeat its version number in RAM). The “:” is a “command-divider” that lets you put multiple BASIC statements on the same row. The “? A” is shorthand to PRINT the stored value of variable A, which in this case matches the BANNER ROM version of R46.

The last important thing to note is the last line of the default AUTOBOOT.X16 program which is “NEW” on lines 130 and 1030. What is that for? In this case, NEW is sort of like END, in that it does end the program. But it also removed the loaded AUTOBOOT.X16 from memory. This is why on startup, if you do a LIST you won’t see the AUTOBOOT.X16 content (and so you have to LOAD it yourself, and then do LIST before you do a RUN). This was just a clever way to mask how the startup screen of the system was working, with the additional introduction text.

So now with that knowledge in mind, maybe you want to adjust the AUTOBOOT.X16. Even if you don’t want to adjust the startup sequence, going through this discussion will introduce a lot of related concepts, so it is a good exercise to go through if you’re not familiar with BASIC or these types of systems.

First, you may want to make a backup of your AUTOBOOT.X16 file (if you don’t have a complete backup of the SD-card already). One way to do this is:

LOAD"AUTOBOOT.X16"
SAVE"@:BOOTBACKUP.X16"

Note that the @: in the SAVE command is to force overwrite if the file already exists. The X16 won’t prompt you if the file already exists, so pay attention to the status message returned to make sure the copy was made correctly. Another way is to rename the AUTOBOOT.X16, if you’re going to create a new one from scratch. That command is like this:

@R:BOOTBACKUP.X16=AUTOBOOT.X16

@R for “rename” with the new name first, then the old filename.

If you ever forget “CMDR-DOS” commands, what I do is @CD:INTRO and BOOT, and load the text file there that has a list of the most common DOS commands. The INTRO folder is a good tutorial introduction to the system (and learning how to use the on-system EDIT feature).

So, speaking of EDIT, you will notice that you cannot EDIT the AUTOBOOT.X16 file. Doing so will look something like this:

This is not a PETSCII vs ASCII issue or anything like that. All BASIC programs are saved essentially exactly like they are represented in RAM, which means they are saved in a “tokenized” form. Now I see a lot of people throw that term around as if everyone in the world understands what that means. Well, many people who never worked with BASIC before won’t know what that means. So, let’s dig into what “stored in tokenized form” actually means.

Discussion About BASIC Tokenization

To conserve memory, BASIC doesn’t store your program in “plain text.” Each keyword (such as FOR) ends up stored as a corresponding token. The exact set of tokens varies across the different systems that use BASIC. You can experiment with this on your own, like this:

You can type “? FRE(0)” to show the current amount of memory remaining available to BASIC. So as you type in lines of BASIC code, you can monitor this by typing ? FRE(0) now and then.

And that’s the neat thing about boot-to-BASIC systems, you can just “code whenever” (limited to the available RAM, which we’ll get to BANKing a bit later). In this way, “boot to BASIC” systems are sort of like exotic programmable calculators, which is appropriate given the history of how they evolved. In fact, “immediate mode” is a term where you can invoke BASIC code without using a line number (behind the scenes it uses a kind of “privately reserved line numbers”, generally either 0 or the last possible BASIC line number depending on the implementation). So you can do things like “? (5*A)+COS(B)” and the system will compute and show that result right away without a RUN command

NEW clears any current program in BASIC’s workspace of RAM. “? FRE(0)” shows the available workspace RAM (minus two bytes to process the immediate mode command; recall question-mark “?” is shorthand for the keyword PRINT). From the above example, the line of code “10 A=5” is stored in RAM as a tokenized sequence of 8 bytes.

To back up a little bit, if you’ve never-ever programmed in BASIC: Each line of code in BASIC must first start with a user-defined line number. It is a bit lengthy to explain why (involving historical reasons related to line printers, used before CRTs became affordable). I’ll defer to that to a different section. But for now, understand that to “enter a program” means to type exactly what you see in the screenshot or printed example (of those portions that start with numbers, like 10, 20, 30, etc.). While not as sophisticated as a modern Linux shell, the blinking-cursor of the X16 is a prompt to a kind of command-line driven operating system (whose main job is to interpret BASIC keywords).

So, to understand tokens and how a BASIC program is stored in memory, it is good to go through that process at least once to gain an appreciation of how that works. Along the way we’ll introduce a few other neat features about the X16. So, type NEW and then type in the following program:

Here is a text-version of the same code, if you want to paste it into the emulator:

10 A=5
20 FOR I = 1 TO A
30 PRINT I
40 NEXT I
50 REM STOP

This is a simple program, intentionally kept short and simple to make it easier to explore the tokenized equivalent. You can RUN the program if you’d like, to verify you have typed it correctly. We’ll walk through more examples of BASIC in later sections. For now, type MENU and use arrow keys to select HEXEDIT.

Press a key to pass its intro instructions (use H to show that help again). Use G command to go to 0801 (hex), and use F3 to switch to PETSCII mode as needed. For the standard System ROM, all BASIC programs on the X16 start at $0801 (same convention as used all the way to the original Commodore PET). That BASIC program could SYS into a pre-loaded program that are somewhere else in memory, but the BASIC program itself will start at $0801 (note that I use $ to indicate a hex value, other conventions are 0x or some use “h” or the “&” symbol – we’re all meaning the same thing).

If the G command in HEXEDIT isn’t working for you, you can also PGUP/PGDN manually to the address offset (along the left) to where you want ($0801). If you’re in 80 columns and things are hard to read, you can exit the HEXEDIT, enter the command “SCREEN 11” and then return to the HEXEDIT (it will adjust to the mode you start it in). The screen should look like this:

Welcome to the 1980’s version of The Matrix! If you’ve never seen anything like this or have no idea what is going on, don’t be intimidated. Keep reading through the sample, absorb the lingo and enjoy the experience. No one learned this stuff their first time either, and as you gain experience down the road, you’ll come back on this, and it will make more sense (which will then be confirmation that you are learning!).

Ok, to break down what you are seeing: to conserve memory, the code you have typed is encoded into a series of “tokens.” When you type “FOR”, those three unique letters/symbols don’t need to be stored literally, but becomes represented as a single token (and typically a “non-printable” character). But, in BASIC, there is a certain amount of “metadata” (or just “supporting information”) that needs to also be stored for each line of code: the address of the next line of code and a hex representation of the user-defined line number. In the diagram below, the addresses are enclosed in LIGHT BLUE below, and the line numbers are enclosed in YELLOW boxes. The corresponding tokens for that line of code are enclosed in RED boxes.

I won’t go far into bytes and hex vs decimal here, but just be aware that this HEXEDIT utility is showing all values in hex (and each column along the center is a single byte). Also be aware that a clever usage of custom fonts is involved here in order to be more compact and show this much information at once. Lastly, if you know nothing else about PETSCII, memorize that Display Code 0 is the “@” symbol (more on Display Codes versus Keyboard Codes at another time).

For those a little more experience, or just dusting off old knowledge, the chart below might be appreciated. It is a re-arrangement of essentially the same information highlighted in the HEXEDIT tool above, but clarifies the 1:1 relationship between the original BASIC program that was typed in and the tokens used to represent that program in System RAM:

From the above: the keyword PRINT, for example, is stored as a single byte token value of 99 in hex. The three-letter keyword REM is identified as value 8F in hex. The main point here is just to show that what appears as “plain text” to users (when you type in a lot of BASIC code), it ends up “compressed” into this token representation. There are a lot of other details here, to summarize a few aspects (which may be particular to X16 or Commodore BASIC and might not apply to other implementations of BASIC):

  • On the X16, the POINTER keyword is added to get the address of variables. (e.g. “? HEX$(POINTER(A))” to see the hex address value of variable A.
  • ROM Bank 4 address $C13A has a “dictionary” of keyword to token mappings. That address could change in future ROM builds, but the point is that an inventory of valid BASIC tokens exists in the System ROM.
  • All numeric variables (integer or float) are stored as 5 bytes (starting with the exponent), at the address refer to by the POINTER result.
  • The “next line address” is in “reverse byte order” (when viewed linearly in a HEXEDIT)
  • Variables are allocated at the end of the BASIC code, in the order initialized (except that string arrays are always last).
  • The order of declared variables can impact program performance.
  • The VARTAB (variable table) is in System RAM bank 0, $03E1. Again this address could change over time across System ROM builds, but that the concept of a VARTAB exists is the main point.
  • Although “STOP” is a BASIC keyword, in the above example it is not stored as a token in this particular case because it is part of a REM (reminder) string which get stored as-is (which is why many BASIC programs from those days lacked comments, because they took up valuable System RAM space).
  • Thanks to MarkTheStrange and MooingLemur on clarifying a lot of these details for the X16!

Back to AUTOBOOT.X16 (and Loading PRGs Explained)

So, the above was to explain why you can’t “plain text” EDIT the AUTOBOOT.X16. That is because the AUTOBOOT.X16 is a PRG – a tokenized LOADable program (that is, you can load it into System RAM using the LOAD keyword command). For those with IBM PC/MS-DOS background, the AUTOBOOT.X16 is most similar to the AUTOEXEC.BAT that PC-DOS would run during startup. On that system, the AUTOEXEC.BAT (or any .BAT file) was a plain-text (ASCII) file interpreted as a list of commands, ran at startup in the order they appear in the file. This was to automate, or “script” a set of commonly used commands (like setting up the style of the command prompt, “prompt $p$g” for those that remember). Note that IBM had this concept also in their very first IBM 5100 in 1975, called Processing Files.

But always keep in mind that file extensions have no real specific meaning. A file just has a name, and it can coincidentally contain a “.” and some more text after that, but all that is optional. If present, these “extensions” have no influence on how CMDR-DOS treats the file. And that’s largely still true today – a filename “just is” and the “extension” is not stored as a line-item attribute of that file record (unlike say the original IBM 5100, the file record did have a specific byte in its header to convey “file type” – but that idea got abandoned since no one can track a type for each application in the world). Still, in the modern day, we often do associate meaning or “program associations” based on “extensions.” But this is also why you can still “pass zip files” by just renaming them, because the only way to truly know a file-type is to make a guess based on the file content itself.

This is a round-about way of explaining that the “.X16” extension to AUTOBOOT has no specific meaning, other than it does suggest “it is a PRG specific to the X16 system.” Well, then you might ask, “what is a PRG?” which is a term we have mentioned earlier. As a convention, “runnable programs” on C64 (and VIC-20) systems generally do have a .PRG added to their filenames. So if you’re looking for something to LOAD and RUN, it is probably a .PRG file. But there is a bit more to it than that (or said another way, it’s not always that simple as some PRG’s can’t be loaded).

When you do F7, then CMDR-DOS will list files at the current folder. It will categorize those files as either “DIR” (sub-directory) or “PRG.” This then makes it confusing to know what files you can LOAD and which you cannot – there just isn’t a universal correct answer to that (for example, some developers prefer to have no extension as part of their filenames – such as raw data files, but doing F7 will still categorize that file as a PRG file).

For performance reasons, CMDR-DOS doesn’t peek into each file during a folder listing and try to judge whether it is actually loadable or not (such as a raw data binary or text file, versus an actual executable). Although it would be possible to write a custom version of a directory listing utility that would do that (i.e. it might “simulate” or predict what a LOAD on that file would do). Modern systems are the same way – if the extension is .EXE then we just “have faith” it is an executable (or that a .PDF is a document in an Adobe standard format, etc.). The interpretation is really up to the software that loads or executes the given file.

On the X16 that software is the LOAD command, which provides a consistent set of “rules” on how a given file is loaded into memory. The first main rule is that the first two bytes of the file are interpreted to indicate what RAM address the remaining content of the file is to be loaded into. At least, that’s the general default behavior of LOAD. There are some parameters that can be used to override that with LOAD, but 99% of the use-cases will be to refer to the first two bytes of the file.

So, this is why if you LOAD a wrong file (such as a plain-text document), you can quickly “corrupt main memory” and confuse the system and cause it to “freeze” or lock-up. There is a reason BASIC programs are loaded at $0801, which is to deconflict with other addresses the system is using to maintain the operational state. Generally, this memory corruption won’t do any lasting damage, but you will have to reset the system and try again with a correct filename.

If the program you are loading is not a traditional BASIC program (such as “raw machine code” instead), most such programs will have a brief BASIC header that will SYS to the appropriate machine-code address (since the entire PRG file content will be loaded). This makes the program compatible with the RUN command, but you can also just SYS the program startup yourself.

To visualize this, below is a couple different perspectives of an AUTOBOOT.X16 loaded into X16HXD and the ROM HEXEDIT. The first two bytes are “01 08” which get swapped and the loader interprets that as the standard BASIC starting address of $0801.

HXD is located in /EXPLORE/APPS/X16HXD (use V to change video resolution). One feature of HXD is that the bytes are in alternating colors to help visually separate them, modifies bytes are in red until the changes are saved, and bytes past the end of the file are in dark gray to show that end of file position.

When using the built in ROM HEXEDIT for files, be sure to use F1 to change to MODE:FILE first before doing SHIFT+L to load the file. This HEXEDIT has no real smarts on the size of the file or its end-of-file marker, it presents it as a 0000 to FFFF range of data. When saving, you have to highlight/select just the desired portion (so you have to remember how many bytes the original file was). As with most things, each tool has its pros and cons.

Things To Do in AUTOBOOT.X16 (more examples)

Because the root-folder AUTOBOOT.X16 is loaded (at startup) using the LOAD command, it does mean that this file must contain line numbers like regular BASIC programs. But what might not be obvious is that within BASIC programs, you can also invoke BASIC commands. For example, you can add LIST into your program, it is perfectly valid for a program to LIST itself. Like this:

In the above, the program runs, and then executes line 60 which LISTs itself automatically. You can also issue DOS (file system) commands from within BASIC, such as changing directories. However, be aware that if you issue a LOAD command from within your BASIC program, it will overwrite the current program, clear all variable state values, and RUN that loaded program. Also be aware that the “@” and “/” prefix commands are not supported from within BASIC programs (which is mainly why the DOS commands are still present in the System ROM). On the original Launch SD card, you can go to the INTRO folder to get a brief reminder about the most common DOS commands (just you have to remember to type @CD:INTRO and then BOOT to open up that INTRO information, which is why the default startup screen reminds about that, as not everyone always remembers even how to change directories on a system like this).

Now with all this background information, you may want to go back and LOAD”AUTOBOOT.X16″ and review that program for ideas on things you can do in BASIC. It will take some time to get familiar with quote mode and screen control characters and things like that. But as one simple idea, suppose you want to start up your system with a different background color. You can LOAD”AUTOBOOT.X16″ Then, you can insert a line number such as “1 COLOR 1.0” (that is, force the very first line number to adjust the text-mode color). Or you can use SCREEN keyword to adjust to a different screen resolution (as an alternative to messing with MENU and NVRAM settings).

If there already is a Line number 1, or you want to add a few lines in-between some existing lines, that a good situation to use the REN command which will automatically renumber all the BASIC line numbers into increments of 10.

But just remember before “testing” your changes to the program, you have to re-save your file using SAVE “@:AUTOBOOT.X16” (the @: is important, to overwrite the existing file).

More About the BOOT Command and Even More AUTOBOOT.X16 Examples

What BOOT does is looks for an AUTOBOOT.X16 file within whatever current working directory you are in.

When preparing the SD card, I tried to add an AUTOBOOT.X16 to most of the software titles, so that when exploring using CMDR-DOS command line you can just type BOOT to get things going. And also to try to encourage this as a habit as others prepare their software releases for the system. In some cases, the AUTOBOOT.X16 was rather necessary to correct some startup aspect about the software (for example, if you started it in while in the 20×15 mode, some software still obliged and ran in that mode even though they didn’t correctly support it).

Sometimes it is not always obvious which PRG to start with a program (especially if it is a cross-platform program that has multiple PRG files, such as one for a VIC-20 or C64). And to be clear, BOOT will also automatically RUN the loaded AUTOBOOT.X16 file (which is why all current BASIC program state information is lost, as a normal action of invoking RUN).

The INTRO folder is a good starter for learning more about the BOOT command and what kinds of things you can do in an AUTOBOOT.X16 file. If you go to that folder and do LOAD “AUTOBOOT.X16” it should look like the following:

What the first few lines of the program is doing is storing the current screen text-mode. For any “well behaved” software system, this is the more “polite” way to operate – to try to return the system state back to the state that the users had it before running your program (or called “exiting gracefully”, as opposed to “just rebooting”). That system state is the text-mode they were using (PETSCII vs ISO), screen resolution and colors, things like that. As-is, BASIC doesn’t provide keywords for all those aspects, so we can work around that by doing our own system calls with POKE and SYS.

Sometimes “exiting gracefully” isn’t possible, if an exotic program “takes over” the system by writing into the pagefile, system reserved memory spaces, or BASIC’s reserved memory. For advanced timing requirements, that is just sometimes necessary by those extreme programs. The system reboots so quickly, it is generally fine to just end your program by just rebooting the system. The only real downfall is that you then revert back to the root folder, rather than whatever sub-folder you were in when starting that software.

As mentioned, at the time it was developed, the system BASIC had no utility to get the currently active display mode. But you can make KERNAL (or any loaded system code) calls by using the SYS keyword. There is a tad more to it: SYS not only invokes any address, but SYS also has a convention used as a way to read/write actual CPU registers while interacting with those System ROM calls. That is, the parameters passed to system calls is through various direct register settings within the CPU. And so SYS refers to specific RAM addresses to facilitate doing that from BASIC. See the X16 Technical Reference manual BASIC SYS call for more information on how this is used.

In the above example, AUTOBOOT.X16 saves the current video mode, then issues an EDIT (another valid BASIC command) with appropriate parameter to show a text file. Note that “control of the system” is handed over to the EDIT program (but it does not count as a LOAD since EDIT is in ROM, so your AUTOBOOT.X16 stays resident). Your BASIC program is sort of “suspended” at that time. When you exit from EDIT, then note that the SCREEN keyword is used to revert the system back to the original screen mode that was stored in variable A.

For an even more exotic example of an AUTOBOOT.X16, go to the following folder:

@CD:/EXPLORE/GAMES/JIMBO 
LOAD"AUTOBOOT.X16"
LIST

This AUTOBOOT.X16 prompts the user, to ask which PRG within the folder to load. It should look something like this:

In this case, the original screen mode isn’t saved as was done in the prior example (it was done in the prior example because it was known that EDIT would exit gracefully). In this example, SCREEN 3 is forced as a choice for a kind of menu selection. One could get fancy and show sprites, play audio, or support arrow keys to cycle through choices. This example just polls the keyboard, and lets the user choose multiple LOAD choices. The “IF A=0” means the prompt waits for some key to be pressed. If no valid choice is made, the program does the NEW and clears itself (so they have to type BOOT again to then go again and make a valid choice).

HISTORICAL NOTE: Jim Orlando is famous for his PETSCII games for the Commodore PET, typically done during weekend game challenges (and then refined a bit in weeks after). Jim graciously ported some of these to the X16 system, where PORTAL16 was one of the newest arrivals as the final Launch SD was being prepared. Even soon after, he released yet great game TRAINYARD16 (one of his software titles to make use of overlay sprites and color). These “last minute additions” were why some of this content ended up in EXPLORE instead of the LAUNCHER, just since sufficient “prep time” hadn’t been done to verify the programs satisfied all the expectations of LAUNCHER titles.

Another good example of AUTOBOOT.X16 is in the VERA FX demo folder (“@CD:/DEMOS/VERAFX“). This example also has a “choose by number” type menu, but the difference is the reason for this menu. Recall we didn’t want software in the LAUNCHER that required over 512KB, which the Mario Kart demo sampler does require a full 2MB. So, for this reason, the Mario sampler is still present, but “hidden” via this BOOT menu.

Some Final Words About AUTOBOOT.X16:

Sometimes a program doesn’t appear to be “well-behaved” because it expects a certain settings prior to startup. And some developers might not really be aware of that, if they always test in their “normal expected mode.” An AUTOBOOT.X16 file can be a way to compensate for those expectations. One common example was if the program supported mouse operation, then the mouse cursor has to be enabled by the program. Some programs forget to do this, so you can issue a “MOUSE 1” in your AUTOBOOT.X16 file to have this done automatically.

Other similar “prep” commands can be switching to a specific SCREEN mode (1, 3, 9, 11 are common ones), or to enable/disable PETSCII vs ISO mode, or maybe you want to scratch (erase) a score file before each load (or check for a certain Day of Week before doing so). All of these can be issued in an AUTOBOOT.X16 file, which can be customized to each specific folder (but only the one located in the root folder is invoked during startup).

How //LAUNCH Works

When you do F7 on the Launch SD from the root folder, you will notice these files (amongst others):

It is a couple DIR (sub-folders/directories) and a few PRG‘s. So right here we can see that the “PRG” category is misleading, because LAUNCHER.INI is actually a “plain-text” (ASCII) file. You can enter the command EDIT “LAUNCHER.INI” (and after doing so, then press CTRL+E until the content “looks right,” which should be about like this:

I won’t go into all these settings here, this is just to verify that this is a plain-text file with CRLF line endings (notice CRLF at the bottom left, as X16EDIT has detected this file having that convention). The “green bar thing” at the center of the screen is the mouse cursor. Do CTRL+X to exit back out of EDIT (and say NO if you accidentally made any changes).

Now, the two other PRG files are LAUNCH and LAUNCHER (with no extension). Both of these files are identical. When first introducing David to the LAUNCHER, I had noticed he had typed LOAD “LAUNCHER” (this was with a ROM before // was supported, but the startup text did say to type LOAD “LAUNCH” instead of “LAUNCHER”). So based on that, I figured it might become a common mistake that many people would do, and so from then I decided to just prepare that file using both filenames (though it does somewhat clutter up that root folder, but that really is the only reason both filenames exist).

As the startup instruction say, type //LAUNCH then RUN to activate the LAUNCHER. So how does that work? Type LOAD “LAUNCH” (or LOAD “LAUNCHER” if you prefer), then do LIST. You will see that both are identical: they are a “helper loader” that first ensures the CWD is the root folder (by doing DOS”CD:/”), then LOADs the actual LAUNCHER.PRG located in the APPS sub-folder. This is also an example of how you can LOAD programs that are in other files, but run them from the current folder (in this case, so LAUNCHER uses the LAUNCHER.INI that is in the root folder). If you launch it from the APPS folder, at least in the earlier version the LAUNCHER would not let you go UP from the folder you started it from (unsure if this ever changed in later builds).

What “//LAUNCH” is doing is that the first “/” is a shortcut to mean LOAD. The second “/” indicates to load a file that is at the root folder of the disk. So “//LAUNCH” is like doing the following commands:

LOAD "/LAUNCH"

But there is no way to automatically invoked the file that was just loaded, you still have to type RUN yourself (you could use BOOT, but at least by default we didn’t want to force usage of the LAUNCHER). And you saw earlier what this program does after running (which is to do a couple steps need to start the LAUNCHER program).

And that’s all there is to it, //LAUNCH is just a convenient (easier to remember) way to load the LAUNCHER. Note that after typing //LAUNCH you could issue a LIST command, to double check what it will do when you RUN it. And if you are in the root folder already, yes just “/LAUNCH” would work, but I felt it was better for the Intro Text to use “//LAUNCH” since that would always work from any folder.

Additional Topics under consideration. I think better to make these a PART 2 as this page has gotten so long already. TBD:

  • Overview of the LAUNCHER – also explain the arrangement of Description text files and Thumbnail images
  • More details about Quote Mode and Control Codes (incorporated into BASLOAD tutorial)
  • PETSCII vs DisplayCodes vs Upper/Grx vs ISO (incorporated into BASLOAD tutorial)
  • BASLOAD Explained (DONE, and intro usage HERE)
  • Overview of the BASIC Examples in EXPLORE/BASIC/TUTORIAL and content in EXPLORE/HELP
  • XINFO Explained (and pointing out the CREDITS file) HERE
  • A Machine Code Example (and RUN vs SYS pass-thru in/out of register values) 6502 on X16 playlist
  • Bloopers (some known mistakes in the Launch SD content)
  • EXAMPLE: Using BASIC to write the System ROM to a file HERE
  • EXAMPLE: Doing “inline-assembly” from BASIC (example using serial card, see here)
  • EXAMPLE: ISR Revealed! (keyboard ISR, C-language HERE and BASIC HERE; for VIA and main ISR, see here)

My Favorite Things in LAUNCHER

  • MELODIUS / SCUMBOTRON / QUARX (all very excellent at what they do!)
  • VINDICATOR / X16MINES (both fun in different ways)
  • MONTEZUMA (just some great sound FX’s!)
  • KG3D / VERAFX DEMO (awesome and inspiring work!)
  • X16-TRIBUTE (thanks badmai for helping put this together!)
  • LANDER (CRAZYLANDER) (just one of the most impressive BASIC games on the system)
  • HANGMAN + SLIDESHOW (relaxing fun stuff, the sun animated when you win!)
  • X16CLOCK (has an hourly chime option)
  • (and of course Planet X16 and PETSCII Robots!)

My Favorite Things in EXPLORE

  • X16HXD (/EXPLORE/APPS) (focused on file editing in hex)
  • BIG FONT SEMI (/EXPLORE/BASIC/TUTORIAL)
  • GAME-OF-LIFE (/EXPLORE/GAMES)
  • TRAINYARD X16 (/EXPLORE/GAMES)
  • BMXVIEWER (/EXPLORE/BASIC/TONY)

Leave a Reply