First, if you have stumbled upon this page and you are not currently a beta tester but would like to be, please contact me by email and request to become a beta tester. A brief explanation of yourself and your background will help me decide if you're a good candidate.
I am only accepting a limited number of beta testers. A good beta tester is someone who is willing to go through every part of the operating system, and actually test it. A good beta tester is someone who will test C64 OS using many different hardware configurations, and try out many different combinations of its myriad configurable settings. When bugs are found, a good beta tester will try to reproduce the bug, try to narrow down what specific actions can lead to the bug being triggered, and will then report those bugs. If you don't have the time or inclination to do this, please don't request to be a beta tester. Beta testers who issue no reports may be dropped from the beta program.
1) The betas that are given to you are for your use only, for the purpose of testing and looking for bugs. Do not share the betas with anyone else, and do not upload the betas to anywhere on the internet. If I discover that you have shared the betas, you will be removed from the beta program, and will receive no further beta versions. I ask you to respect the insane number of hours that I have poured into this project.
2) If you know of an individual who wants to be a beta tester or who you think would make a good beta tester, send them to me or to this page. This page is not protected, however, I don't want it advertised either. Don't post the address to this page on social media or to your own site or on any other public forum.
3) Beta testers will be sent an email with a temporary link to download the latest beta as a .ZIP file.
4) Beta testers should take notes on the bugs and issues they find. Try to resolve the issues yourself and/or try to discover how to replicate the problem before reporting the bug. Include the Beta version number and the steps to replicate the bug in the report.
5) Ask questions about configuration or non–bug issues via email, or check in to the IRC channel to discuss. Read through the notes on this page for help with common issues.
6) In the notes below you'll find what is included, what is working, what is known to be not working and suggestions for what needs to be tested. The notes for Beta 0.1 are the most complete. Subsequent betas will have briefer notes that indicate what has changed or been fixed since the previous beta.
The official chat for beta testers is IRC. #c64osbetatesters on IRCNet.
If you have an IRC client, depending on your browser, this URL may open a link to the channel.
irc://irc.ircnet.com/c64osbetatesters
You can alternatively use the IRCNet webchat client:
https://webchat.ircnet.net
When a new beta is available, you'll get an email with a temporary link to download the .ZIP package. If the link expires, send me an email and I'll send you a new link.
Unzip the package on a PC/Mac. The ZIP file contains the 3 files listed below. You need to transfer these 3 files to a storage device accessible to your Commodore 64/128.
| File | Description |
|---|---|
| c64os |
This is the pre–booter with embedded configuration utility. This file must be in the root directory of the device/partition where C64 OS will be installed. |
| restore.car |
This is a C64 Archiver (.car) file that contains a complete copy of the C64 OS system
directory, with applications, utilities, drivers, etc. embedded within. This file must be in the root directory with the pre–booter, c64os. |
| c64restore |
This is a sub–program, loaded and run by the pre–booter when you answer "yes" to install from
restore.car. This file must be in the root directory with restore.car. |
Change current partition and directory to where the three installation files are stored. Load and run c64os. On its first run it will enter configuration mode automatically. On first run, the configuration utility asks only for the device number and the partition. You must enter the values for where those three values currently are. (The primary and default partition on an SD2IEC is 1).
After saving the device and partition numbers, it will ask if you want to install from restore.car. Choose "y" for yes.
Everything will be installed in a single directory called os. The system directory can be renamed at a later time.After installation, you can scratch restore.car and c64restore. These files are only needed for installation. But, you must keep the file c64os in the root directory.
After installation is complete, load and run c64os to boot into C64 OS.
IMPORTANT NOTE for SD2IEC: Before installing to an SD2IEC you must put it into File Extension Mode 2. This is "C64 compatibility" mode. When not in or using C64 OS, you can easily switch back to some other mode, if desired. (For a full explanation of what's going on with SD2IEC, please refer to the blog post, Understanding SD2IEC Filenaming.)
To change into File Extension Mode 2, use the following command:
open15,dev#,15,"xe2":close15 or with JiffyDOS @"xe2",dev#
Where dev# is the device number of your SD2IEC.
| Version | 0.3b |
|---|---|
| Release date | May 9, 2020 |
A few important changes were made to the KERNAL that should get us closer to supporting IDE64. There is less memory available in this build than there normally should be. That will be restored after getting IDE64 support hammered out.
Play around with the themes and drives utility. More to come.
| Version | 0.2b |
|---|---|
| Release date | April 13, 2020 |
If you change the installed location, for example, if you change the device number of the C64 OS system device, or if you rename the system directory (perhaps from "os" to "os v0.2b" or something like that) you need to update the pre–booter's configuration. Everytime you run c64os it displays "Press any key for configuration" for about half a second. Press any key while that message is displayed and it will re–enter the configuration mode.
When it asks for the device and partition numbers, they will be set to the previously saved values. You can adjust these to the new device and partition numbers. Further, because this is no longer the first run, and you already have a system directory, it will ask you for the name of the new system directory. The old name is prepopulated, if you haven't changed this just press return to proceed. Otherwise, you can put in the new name of the system directory.
It will then save the new settings. It will not offer to install again from restore.car, rather, just press a key and it will boot C64 OS using the new install location settings.
There is a new configuration program for changing all the other available system settings. If you are in C64 OS, quit back to BASIC, and change into //os/settings/ directory. Load and run configure.
Just answer each question with the available options. It won't allow you to enter an invalid value.
This walks through the date and time settings, including choosing an RTC driver. (I2C is not working in this build.) If you choose IEC it will ask you to specify the device number for the device that has the RTC. You can also choose auto detect. It will search through looking for the first IEC device that supports the RTC commands.
It then walks you through mouse input settings. You can choose your pointer style, tracking speed, double-click delay, pointer colors and left or right handedness. It also lets you choose the input device driver. (Koala Pad is not working in this build.) c128 keypad, if you're on a c128, uses 4,5,6,8 as an inverted T, and the enter key (beneath your pinky) as the primary mouse button.
Next it walks through global system settings. It will allow you to configure the 4 global keyboard shortcuts, for toggling visibility of the menu bar and status bar, toggling full GFX mode on and off (only works when GFX data is available, see Chess, NES Tester, and Gallery applications.) and taking screenshots.
To configure the keyboard shortcut settings first it wants a single unmodified key. If you press a key while a modifier is down it will not accept it. After you've picked a key, it will then ask for the modifier key combination to use with that key. Combinations are of COMMODORE, CONTROL and SHIFT keys. (SHIFT can be used in conjunction with one of the other modifiers but not on its own.)
Lastly it asks about the REU memory allocation settings. The REU api is new in beta 0.2. Fast app switching isn't available in this build, but it's coming. In order for applications to be fast switched an app needs a 64K slot into which main memory can be stored. You decide how many fast app slots you want to reserve in the REU. Remaining space is available for the current application to use.
| Version | 0.1b |
|---|---|
| Release date | March 1, 2020 |
The .ZIP package containing a beta release of C64 OS contains a single directory named os. This directory and all of its contents must be copied to the root directory of a partition on a supported boot device. See below for supported boot devices.
To boot C64 OS, set the current partition to the partition containing the system directory. Set the current directory to the system directory. (e.g., @cd//os). Load and run booter.o. Any device number from 8 to 30 can be used. JiffyDOS and its DOS wedge commands are fully supported, and recommended. Example:
load"booter.o",12 run
It is recommended to put the commands to load the booter into a small BASIC program, call it c64os and save it to the root directory of the boot partition. The device and partition numbers must be set according to your setup. For example:
10 @#12 :rem set curr. device# to 12 20 @cp1 :rem set curr. partition to 1 30 @cd//os :rem change to boot dir. 40 ↑booter.o :rem load & run booter.o
Included in the system directory is a BASIC program, backup2.5, that can be used to recursively copy the system directory between IEC devices. This can be used, for example, to copy the entire system from an SD2IEC device to a partition on a CMD HD, RAMLink, etc. This facilitates testing on other storage devices. NOTE: Backup2.5 requires JiffyDOS, as it uses JiffyDOS wedge commands and the built–in 2–drive copier.
All text files are in PETSCII, and I recommend using a PETSCII–based text editor to manually modify config files. Novatext is included in the system directory, however, it's not working on SD2IEC for some reason. Not sure why. Otherwise, you'll need some other way to edit PETSCII config files. In future betas, C64 OS utilities will become available to manage these settings with a proper user interface.
In lieu of a text editor you can use a BASIC to write a config file. I highly recommend backing up the config files, making copies of them, before modifying them. Here is an example BASIC program that can write a PETSCII-text file to disk.
10 open5,{dev#},5,"@:config.t,w,s" :rem overwrite config.t as seq file
20 print#5,"first config line"
30 print#5,"second config line"
40 print#5,"third config line"
50 print#5,"fourth config line" :rem and so on
60 close5
File references in C64 OS use a variant of the CMD (and SD2IEC) path notation. Two slashes means root directory, one slash begins from the current directory. All subsequent directories are separated by single slash. There must be a trailing slash on the last directory name. A full colon is used after the final slash before the filename. If no device or partition is specified then the device number and partition of the C64 OS installation is implied.
For example, assuming that the system directory has not been renamed, the path to the default input driver is: //os/drivers/:input.1351.r
Full C64 OS path notation is as follows:
dev#:partition#:path:filename
For example: 9:2://os/drivers/:input.1351.r
means IEC bus device #9, CMD-style partition #2, then the CMD-style path which requires
the trailing slash. Then the filename. On devices which do not have partitions, partition #0 is
used.
Most files throughout the system directory end with a single letter extension to identify the
type of data.
Files ending with .m or .t are designed to be editable manually with a text editor.
Files ending with .h or .s are human readable but must not be modified.
All other extensions are for files that are meant to be consumed programmatically only.
| Extension | File Data |
|---|---|
| .h | programming header data |
| .i | application binary data |
| .m | menu definitions data |
| .o | object code or executable |
| .p | PETSCII image data |
| .r | relocatable object code |
| .s | programming constants |
| .t | textual data |
Global settings are found in several files in //os/settings/
Applications and utilities save global settings to the system settings directory. Applications and utilities save app-specific settings to the inside of the bundle directory of the application that is running. If an application or utility starts misbehaving, deleting its settings file(s) may help resolve the issue.
Human editable settings are stored in a very simple flat text format. One setting per line. The line number defines which setting it is. If a setting is just one character, then only the first character is read. The following characters on that line are a note about what it does and its range of values.
The value range is typically some range of PETSCII that can be easily typed. For example, a range specified as a -> z means that you type in a single character from a to z, inclusive. This gives an effective value range from 0 to 25. Other PETSCII ranges are used depending on the target range. For example, ! -> ] gives an effective range from 0 to 60. The line notes specify the range of values for each setting. You can use a PETSCII table to find the appropriate setting value.
Some settings are a full string. These don't have notes following them, as the value is read from the start of the line, up until the carriage return. In some rare cases a setting will be more than one character, but a fixed number of characters. These can have notes following them.
The default main config file, //os/settings/:config.t, for example:
//os 1 0=CPUBusy Off,1=CPUBusy On _p System Key Values 4623 System Key Shortcuts 1->7 1 Status Bar Mode (drv/app/fil) 0->2
In the first line above, the setting is the full line. It's the name of the system directory preceded by two slashes. This will be discussed later. In the second line, only the first character is the setting, the rest of the line is a note about the values, 0 for CPUBusy Off, 1 for CPUBusy On. The next two lines, have a fixed set of 4 characters each. Everything after the first four characters are just notes. In the last line, only the first character is the setting, everything following it is just a note. In the last two lines you see 1->7 and 0->2, these are notes about the ranges of valid settings, in PETSCII.
One more example, //os/settings/:mouse.t, the mouse config file:
0 Mouse Pointer 0 a Mouse Speed a->z ? DblClik Jiffy Delay !->] 16ms->1s @ Inner Color @->o default: @ o Outer Color @->o default: o r l=Left Hand,r=Right Hand input.1351.r
All of these lines except the last use only the first character of the line as the setting. Everything else on the line is a note including the valid value range, again in PETSCII. The last line is a string, so the full line is the setting, and there is no note.
BASIC programs, config.bas, mouse.bas, and time.bas are included in //os/settings/ that, when run, recreate their corresponding config file. You can load one of these BASIC programs, list it, change the strings, notes are in REMarks on each line, and then run the BASIC program to update the config file.
Note: For an overview of the system directory layout and explanation of the files and sub–directories, see: C64 OS System Directory.
Booting from from 1541/1571/1581 is not supported.
The boot device number is auto-detected at boot time and used as the system device# from then on. The boot partition must be the current partition on that device at boot time. That partition number is auto-detected at boot time and used as the system partition from then on.
The relationship of the files and directories inside the C64 OS system directory must remain fixed. The entire C64 OS system must be found within a single sub–directory that is in the root directory of the partition. The name of the system directory can be customized. It is os by default (because it is very short.) If you change the name of the system directory, the first line of //os/settings/:config.t must be updated. It is in the format: //dirname and cannot have any notes following it, as it is read to the end of the line. Do not include a trailing slash.
TO TEST:All of the above listed devices should be tested. Different device numbers, and partition numbers should be tested. Different SD2IEC devices and CMD devices should be tested. On CMD devices only native partitions are supported. Customizing the system directory name should be tested. Booting with supported and unsupported devices on the IEC bus should be tested.
A Drive Detection routine is run during boot up. A detected devices table is constructed from:
$033C (device 8) to $0353 (device 30). Each address holds a device code for the device found
there.
See: //os/s/:drives.s for drive type definitions. From within C64 OS you can use the
Peek utility to inspect memory, and review the detected drives.
You can use backup2.5 to recursively copy the C64 OS system directory from one device to the root of another device.
From the READY. prompt, change into the C64 OS system directory on the source device. Load and run backup2.5. It will ask for a source device number, enter that. It will ask for a destination device number, enter the device number of the target device, which must be one of the supported boot devices listed above. It will then ask for the name of a target directory, enter a single directory name (16 characters or less). The target directory will be created in the root directory of the current partition of the target device. The recursive copy will be from the current partition and directory of the source device.
This was originally designed to allow you to copy the entire system directory, however, you can use it to copy any directory tree, including any subdirectory of the main C64 OS system directory. To do this, load backup2.5 but don't run it yet. You can then change the current partition and change directory on the source device. Then run. You specify the source device, but it always copies the current directory in the current partition.
Pointer Input Devices1351 mouse driver is configured by default.
Mouse settings are found in //os/settings/:mouse.t
The last line is the mouse driver to load. There is no note on that line, so the filename must match the complete line up to the carriage return. The driver filename from mouse.t is looked for within the drivers directory, //os/drivers/
The drivers directory holds more than just input drivers. All drivers are relocatable and end in .r. All mouse drivers begin with input. I.e. input.1351.r, input.joy1.r, etc.
TO TEST:All of the implemented input drivers should be tested. And all of the available settings in //os/settings/:mouse.t should be tested with every driver.
By default C64 OS will boot into the last used Homebase app. At present, app launcher is the only working homebase application. Applications that are essential services, that make up an essential part of the OS and cannot be (should not be) deleted, are found in: //os/services/ All other applications are found in, and can be installed to: //os/applications/
Applications may not be categorized into further sub-directories. Each application is contained within its own bundle. A bundle is simply a directory containing standardized components. The bundle directory name has no special extension. For example the App Launcher's bundle is found at: //os/services/app launcher/ The Gallery application is found at: //os/applications/Gallery/
App LauncherApp Launcher is like the launch screen of your smart phone. It has up to 5 desktops, and each desktop can support up to 32 aliases. The desktops are found at: //os/desktop/. Each desktop can have a PETSCII image background. The backgrounds do not contain color data, and are just 1000 bytes of SCREEN Codes. Each desktop's background is in a separate file, //os/desktop/:1.p for desktop 1 through //os/desktop/:5.p for desktop 5. To clear the background of a desktop, replace the background file for that desktop with a file containing all blank screencodes, like, 1000 bytes of value $20.
Within //os/desktop/ are 5 subdirectories, 1 through 5, for each of the 5 desktops. Each file within a desktop directory gets rendered as an alias on that desktop. The filename must match (case-sensitively) the name of either a Utility or an Application. The Application can be found either in //os/services/ or //os/applications/. The Utilities must be found in //os/utilities/.
The contents of an alias file are 4 bytes: X-Position, Y-Position, Color and Type. Positions are measured in text columns and rows. And, just like in settings files, the range values are offset to PETSCII so they can be easily human editable. X-Position is PETSCII "0" to "w", for 0 to 39, and Y-Position is PETSCII "0" to "h" for 0 to 24. Colors are from PETSCII "@" to "o" for 0 to 15. The value for type is PETSCII "u" for utility or "a" for application.
For example, the file //os/desktop/1/:Gallery will produce an alias named Gallery somewhere on desktop 1. If the contents of that alias file were like this...
12@a
... the alias would appear in the 1st column (zero based) and the 2nd row (one column of space between the left border and the start of the alias, and one row of space between the bottom of the menu bar and the top of the alias.) It'll have a black background, and the "a" indicates that it's an application. Therefore, when it is double clicked, App Launcher will try to launch an application named "Gallery".
At this time, aliases cannot be created by the App Launcher. They can be copied and moved from desktop to desktop. They can have their color set. Their position and color get saved. They can be deleted. To create new aliases, use a text editor (or some BASIC commands) and create them according to the format described above. For example, from the READY prompt, to create that Gallery alias:
@cd//os/desktop/1
open5,{dev#},5,"@:Gallery,s,w"
print#5"12@a"
close5
Aliases can be dragged and dropped. Selection boxes can be dragged around aliases. Selections can be extended, experiment with holding the shift and commodore keys as selections are drawn. Keyboard shortcuts exist to select and unselect all.
TO TEST:Everything the App Launcher can do. Moving aliases, changing their colors, double clicking them. Copying and moving between the desktops. Deleting aliases. Reloading and saving the desktops. Check that launching utilities and apps works. Test what happens if an alias goes to an app or utility that cannot be found. Try changing the data of a desktop background, etc.
Note: The current background PETSCII images look rough. They were originally converted using a PETSCII render, but only look right when used with the original character set. As the C64 OS character set has evolved, replacing PETSCII graphics characters with bits of UI and other essential symbols, the background images have gradually degraded. They need to be replaced with ones designed to work with the C64 OS character set.
Gallery is a fully baked app. It should work in all of the features that you can find in it. It tests the ability to use split screen. And has some controls. You can poke around at the inside of its application bundle to find the gallery files and the metadata files. You can test changing those and see how they work.
NESTesterNESTester is more or less fully baked. It tests the ability to load and unload joystick game controller drivers for 2 player and 4 player. The 4 player supports the 4–player joystick adapter. This should be tested. (A game controller driver is different than a mouse input driver. One game controller driver and one mouse input driver can be loaded simultaneously.)
The App's UI uses the split screen mode which can be tested. And has some interactable elements in the GFX half of the split. The toggle switch on the NES controller graphic is not working. The SELECT and START buttons are decoded by the drivers as combinations of LEFT+RIGHT and UP+DOWN simultaneously respectively.
ChessChess is openable. It's UI is almost 100% in the GFX split screen mode. You can drag pieces around the board. Many of the rules are not implemented, but movement constraint on many of the pieces is implemented. Of the menu options, only the reset the game is really working, and the ability to quit to home.
TestGroundThis is a very influx app, as I use it to test a variety of things. It is currently being used to test the build out of the Object Oriented Toolkit. If it crashes, it's not a big deal.
Every application bundle has a standardized set of components.
about.t is the metadata loaded in by the About This App utility. It has 4 lines: Title, Version, Copyright Year and Author. These can be tested, changed, and checked against the About This App utility. Things to test include, what happens if the lines are too long, or if a line is missing, or too many lines, etc. Example content from //os/applications/Gallery/:about.t
Gallery 1.0 2019 Greg Nacu
If you don't have a text editor, these can be created/overwritten with a simple BASIC program, or even BASIC direct mode commands.
open2,{dev#},2,"@:about.t,w,s"
print#2,"App Title"
print#2,"Version#"
print#2,"Year"
print#2,"Author Name"
close2
main.o is the app's main binary. An application bundle must have this file, or it will crash. You could test what would happen if the app is launched without this file being there. But, to be honest if it misbehaves, that's not too big a problem. It is required, so without it things will break. It would be nice if they broke gracefully, and returned to the Homebase app.
icon.charset is the app's 3x3 character icon. This contains 72 bytes of C64-format bitmap data. There is no associated color data. The icon is loaded and displayed by the About This App utility, and also is displayed by the loader when launching an app. Tests include, what happens if this is missing, if it is too short, too long (too much data, not enough data), etc.
Human configurable menu files
menu.m is the human editable menu definitions file. (Ordinary users would not be
required or expected to change these files, but hackers will be delighted that these exist.)
A menu.m file is in a hierarchical PETSCII-text format. It specifies the menu titles, as well as the
structure of nesting, the action code sent to the app, and the keyboard shortcut.
For more information about the menus, see these blog posts:
Menu System Comparison
Pointers in Practice, Menus
The menu definitions file structure is as follows:
Every line is a menu entry. The first content on the line is the menu item text. The menu item text is terminated by either a ":" or a ";" (colon or semi–colon.)
The semi-colon (;) indicates that this is a header node that opens a sub–menu. Following the semi-colon is one byte that indicates how many immediate children this header contains. (Not counting the children of those children.) The value is PETSCII–shifted so that "a" = 1, "b" = 2, "c" = 3 and so on. The actual number of children must exactly match the number specified or the parsing will fail.
The full–colon (:) indicates that this is a leaf node. Following the colon are three bytes. The first is a PETSCII number that is the bitwise ORing of the modifier keys for the shortcut. (See //os/s/:input.s) Shift = 1, Commodore = 2, Control = 4. The second byte is the key that is combined with the modifier keys. The third byte is the action code sent to the app.
An asterisk (*) alone on a line counts as a child item, but it leaves a blank organizational spacer in the menu.
The following is an example that defines 3 root menu items, each with its own submenu. And the last item of the first submenu contains its own submenu.
File;c Open:2oo Close:2wc Options;c Get Info:2i? * Quit:6qq Layers;b Bring Forward:00f Send Backward:00b Search;b Find:2fF Replace:2rr
Here's how this works. "File" is the title of the first root menu item. It ends with a ; indicating that it opens a submenu. After the ; is a "c", which means the submenu will contain 3 menu items. These 3 items follow immediately. The first child is "Open", it ends with a : which indicates it is a leaf node. After the colon is a 2, this is the bitwise OR that means COMMODORE key only. The two characters are o and o, so COMMODORE+o triggers this menu item, and o is sent to the application as the action code.
Close is the second child of the File submenu. It ends with a : so it too is a leaf node. Then a 2wc means COMMODORE+w to trigger it, and a "c" will be sent as the action code.
Options is the third and final child of the File submenu. It ends with ; however, indicating that it opens its own submenu. Its own children follow it immediately, but do not count towards the number of children that were specified for File in the first line. After the ; of Options is "c", so it has 3 immediate children.
Get Info is the first child of the Options submenu. It ends with : indicating a leaf node. 2i? means that COMMODORE+i is the keyboard shortcut, and "?" is sent as the action code.
Following Get Info is an asterisk alone on the line. This is the second child of the Options submenu, it has no other parameters, but it leaves a blank space in that submenu, for visual organizational purposes.
Quit is the third and final child of the Options submenu. It ends with a : to mean it's a leaf node. 6qq means the modifier key combination COMMODORE+CONTROL plus "q". The extra modifier key is to make it less likely to trigger by mistake. "q" will be sent as the action code.
The recursion at this point unwinds all the way back to the second root level menu item, Layers. This is terminated with ; so it has a submenu. The "b" indicates its submenu has 2 children that immediately follow. ... and so on until the end of the file.
You can visualize the tree hierarchy as follows, except that in the real file all the lines are flush left.
File;c Open:2oo Close:2wc Options;c Get Info:2i? * Quit:6qq Layers;b Bring Forward:00f Send Backward:00b Search;b Find:2fF Replace:2rr
This needs to be tested extensively. Rearranging menu items, making long menu item titles, creating collisions between shortcuts and action codes, deep nesting of menus, spacers in the root menu, etc, etc. Everything needs to be adversarially tested to suss out any issues.
One utility at a time can be opened concurrently with any application.
Utilities are simpler than applications and do not have a bundle directory. Every utility that is installed in the system is a PRG file found in //os/utilities/. The name of the utility file must match the name of an alias in the App Launcher for the App Launcher to open it.
Utilities save their current configuration, and or state information, to a file that is named for themselves with a .i extension. If the utility wishes for its state to be global, that is, consistent regardless of what application is running with it, it will save its state to the //os/settings/ directory. Other utilities are designed to have a custom saved state for each application they opened on top of. These utilities will read and write their config file inside the bundle directory of the application.
If a utility is suddenly misbehaving, try to delete its config file first, and see if that resolves the issue. You may have to look into the various application bundles to find those config files. The config files of utilities are always auto-generating. So it is always safe to delete a utility's config file, it will be generated with fresh default settings the next time the utility is run.
Utilities run from the same memory area that graphics data is loaded for split screen mode. This means that if a utility is opened, it will remove the graphics data, and any open split screen mode will be automatically closed. Applications that support split screen mode must (and do) support a way to re-install the graphics mode data. Reinstalling the graphics mode data while a utility is open should gracefully quit the utility first. This allows you to toggle back and forth quite easily.
This utility just opens up, shows information about C64 OS and its booter logo, and copyright info. It can be moved and closed and that's it.
About This AppThis utility contextually reads the about.t metadata from the current application's bundle, and the icon.charset from the current application. And displays them. Double clicking the icon should copy the icon data to the clipboard. This could be tested, but there is as of yet no way to paste the icon data from the clipboard. That's coming soon.
As mentioned earlier, other things to test is what happens if any of this data is missing or malformed.
CalculatorThis utility implements a scientific calculator. It has keyboard input as well as mouse. Test around to see if you can figure out which keys are usable for the keys on the UI. The math is backended on the BASIC ROM's implementation. Bugs in the BASIC ROM's floating point math are also present in this calculator. RAD/DEG can be clicked to toggle modes. The Memory features should be working. Double clicking the screen should copy the displayed value to the clipboard.
Order of operations is not implemented correctly. Each operation is performed immediately on the last value on the screen. This will be fixed in a future version of the calculator. All features of the calculator need to be tested.
ColorsThis utility implements a standard Color Picker. It is intended to communicate color information in two directions with the application running below it. From the App Launcher, when the color utility is open, selecting individual aliases should highlight that color in the utility. Picking a different color should change the color of the alias. When no alias is selected the utility should show the hint color of the current desktop. And picking a new color should change the hint color of that desktop. If multiple aliases of different colors are selected, the utility should show no colors highlighted. But if a color is picked, it should assign that color to all of the selected aliases.
The colors utility supports keyboard input. When it is open, it intercepts C= 1-8 and Control 1-8.
MemoryThis utility displays memory usage. It reads from the paged memory allocation table. Memory is divided into 6 types. Workspace, Application, Utility, System, Reserved and Free. Workspace memory is a fixed size, and occupies the lowest several pages. Reserved is a fixed size, and occupies all of the space behind the KERNAL ROM. System memory is partially fixed and partially allocated. Certain system processes may allocate from free memory, for example, a network driver may allocate input and output buffers. Application memory is divided and consumes free memory from both sides. The application's main binary is loaded at the bottom of free memory, and allocations are made from the top. Utility memory is divided. The utility's executable binary is loaded into reserved memory, but the utility may make allocations that come from the top of free memory.
The display of memory usage dynamically updates by rerendering from the memory allocation table periodically. The bottom UI row lets you adjust the update speed, fast or slow. The UI row above this can be clicked to toggle through a memory summary or detail on different types of memory usage. Each cell in the main display represents 2 pages. Double clicking a memory cell opens the Peek utility to that page.
Memory utility can be opened by double clicking the free memory indicator on the right end of the system status bar.
PeekThis utility displays the contents of one memory page at a time. The output is in hexadecimal, 16 columns by 16 rows. The controls at the bottom left indicate what page is currently being displayed and the arrows allow you to move sequentially through the pages. The Reload button will reload/redraw the current memory page. The Auto checkbox, if checked, will cause Peek to automatically reload the current page periodically. You can test this on memory pages that change frequently, such as Zero Page or Stack.
Double clicking a byte in the memory display will jump to the page number that that memory value holds. This allows you to follow vectors in memory very easily.
Peek is very useful for examining the contents of memory while C64 OS is running. If you explore
the programmatic includes in //os/s/ you will find the definitions for many system
addresses. For example:
//os/s/:drives.s defines the location and values for the detected drives map.
//os/s/:memory.s defines the location and values for the paged memory allocation map.
//os/s/:service.s defines the locations of the system fileref and current homebase.
All of these addresses and many more can be explored during runtime with Peek.
Today presents a calendar month view. The current date is indicated. An alternative day can be selected by clicking the date. Day of week is presented along the top, week of year along the left side. The selected date is shown in large characters at the top, along with the day of the week and month name and year. The controls let you move back and forwards through the months. Clicking the circle between the arrows takes you to the current month.
Today can be opened by double clicking the clock on the right end of the menu bar.
The system–wide utilities menu, left end of the menu bar, is configured from a standard menu definitions file, //os/settings/:utilities.m This menu can be customized like any other with keyboard shortcuts and nested hierarchy. However, it may only contain a single root menu. The Action Code is a zero byte. The menu system interprets a zero byte action code as a special code to launch a utility rather than pass the action code to the application. The title of the menu item must match the name of the Utility to open.
The position and configurable elements of utilities are saved automatically when the utility is closed, and restored automatically when it is reopened. This behavior needs to be tested for all utilities. Bear in mind that some utilities save their state on a per–application basis. Across two applications those utilities can have two different saved positions and configured settings.
There are global keyboard shortcuts for showing and hiding the menu and status bars, toggling between text or split screen mode and full screen graphics mode, and for taking a screenshot. These shortcuts are defined in //os/settings/:config.t The first row are keys to push, combined with the modifier key combinations specified in the config line below it. In //os/settings/:config.t for example:
//os 1 0=CPUBusy Off,1=CPUBusy On _p System Key Values 4623 System Key Shortcuts 1->7 1 Status Bar Mode (drv/app/fil) 0->2
The line 4623 those are 4 different modifier key bitwise OR'd values. The first is CONTROL, the second is COMMODORE+CONTROL, the third is COMMODORE, and the fourth is COMMODORE+SHIFT. These 4 key combinations correspond with the line above " _p". Those first 2 characters are spaces, because CONTROL+SPACE toggles the menu bar. And COMMODORE+CONTROL+SPACE toggles the status bar. The (_) underscore is the ← key, so COMMODORE+← toggles in and out of full screen graphics mode. The toggle only takes place if graphics mode is available. And lastly, COMMODORE+SHIFT+P takes a screenshot, by momentarily loading in the relocatable screenshot driver: //os/drivers/:screengrab.r, running it and then ejecting it from memory.
ScreenshotsScreenshots are saved to //os/:screen.pet and can be viewed, from BASIC, using the BASIC program //os/:petsciiview Note: the custom character set is not included in the screen capture, custom characters will be rendered with the default CHAR ROM's charset.
Status Bar ModesThe status bar can be toggled through three modes by single clicking its leftmost ~80%. All three modes are not always available in every application. The memory usage is not displayed while in application status mode. The default mode of the status bar at boot time is configurable in //os/settings/:config.t
CPU Busy IndicatorIf the main event loop is not executed for more than a brief period of time, a CPU Busy indicator will animate over the Utilities Menu icon at the left end of the menu bar. This indicator can be disabled in //os/settings/:config.t
Mouse PointersThe mouse pointer can be customized, by setting a numeric value for the pointer to load in //os/settings/:mouse.t The actual mouse pointers themselves are found in //os/pointers/, the files 0.o through 4.o. A pointer contains 128 bytes of data, which are two 64–byte hires sprite definitions back-to-back. The pointers are in PRG format with a 2–byte load address to $FF40. You can experiment with creating your own pointers, or modifying the existing ones. Other settings found in //os/settings/:mouse.t should be working and need to be tested.
Booter Components, Modules, ClassesIn //os/settings/ the files components.t, modules.t and tkclasses.t list the components, modules and toolkit classes that are loaded by the booter, and in what order. You can play with these, test them in different orders, but do not omit any, or that will almost certainly result in a broken system.
ClipboardData copied to the clipboard (for example, from the About This App utility, or the Calculator) will put their data and type information into //os/clipboard/:0.d and //os/clipboard/:0.t These can be explored and tested. The clipboard utility is not yet available. Quit from the App Launcher back to BASIC, and view these files from outside C64 OS.
RTC DriverThe system date and time are set by a configurable RTC driver that is loaded during boot time. There are two drivers available, rtc.cmd.r for CMD storage devices (HD/FD/RL) with an RTC. And rtc.uci.r for the 1541 Ultimate II/Ultimate 64's Ultimate Command Interface, which must be enabled in the menu system of those devices. The RTC driver to use is specified in //os/settings/:time.t If rtc.cmd.r is specified, the following line can be used to define the IEC device # of the CMD device to use, or a * will have the driver search through the detected drives map, and use the first CMD device found.
Clock SettingsThe menu bar clock can be disabled altogether, can be configured for 12 or 24 hour mode, and can blink or not blink the seconds indicator. All these are found in //os/settings/:time.t
Toolkit ColorsThe toolkit classes (and some elements manually) derive their colors by reference to the toolkit color map in workspace memory. See: //os/s/:ctxcolors.s for these definitions. The colors assigned to the values in this table come from //os/settings/:toolkit.t
The toolkit is in early development still, most elements in the utilities and apps that exist so far are not actually based upon the toolkit, and so they likely won't take their colors properly.