Hi65 version 9.1 (c) 2013-2023 Simone Gremmo (Devil Master)


============
= Abstract =
============

Hi65 is a high-level Commodore 65 emulator.

In order to understand what "high-level" means, let's first consider what a "low-level" emulator does. It implements a software version of the whole machine, including a virtual processor that executes machine language commands. When any software for the target platform is loaded into the virtual RAM, the virtual processor executes it instruction by instruction.

However, the Commodore 65 is not the ideal platform for a low-level approach: each of the few units around has a different implementation of its ROM software, the implementations themselves are buggy and there is no commercial software around.
The authors of MESS want to emulate the Commodore 65 with a low-level approach, but that has been a failure: the C65 driver of MESS has had the same bugs for over a decade, bugs that do *not* appear in the actual C65 prototypes. Emulating the Commodore 65 with a low-level approach is not "accurate" and it's more than pedantic: it's a self-defeating task.

Enter Hi65.

Hi65 does not implement a virtual version of the 4510 CPU (used in the physical Commodore 65), nor does it execute machine code software: it executes tokenized BASIC 10 programs directly, as if the various BASIC tokens were machine code instructions for its own virtual processor. Thus, the execution is much faster because it's not limited to the clock speed of the 4510 (but the timing is still accurate) and it's not limited by the scarce knowledge of the inner workings of the Commodore 65, because all instructions are made to do what the manual says they should do, not what they actually do on a physical machine (which may be buggy and inconsistent between individual machines).

Hi65 (the emulator), Hi65CFG (the command line configuration software) and Hi65 Edit and Launch Tool (the graphical frontend) are released under version 3 of the GPL (GNU General Public License). If you do not have a copy of the license, go to http://www.gnu.org/licenses/gpl.html to read it.


====================
= Current features =
====================

Version 9:
* Implemented the RND instruction, which initializes the pseudorandom number generator with the current timer value and returns a result if its parameter is zero, returns a new result with the current initialization if the parameter is positive, and initializes the pseudorandom number generator with its parameter if it's negative.
* Fixed a bug in the function that transforms expressions into a format MuParser can understand, which used to work incorrectly with negative numbers being multiplied, divided or elevated to power.
* Added a feature in the default expression evaluator, to make it accept negative numbers or variables as parameters for mathematical functions.
* Added checks in the If, Input and Print functions to prevent the user from using variables called DO, FN, GO, IF, ON, OR, TO (which would be tokenized as commands and work incorrectly on a C65). * Fixed a bug in the Next function, which used to make it exit loops after a single iteration if a colon was present after the corresponding FOR instruction
* Extended the Dim function so that multiple arrays, separated by commas, can be declared with a single instruction.
* Fixed a bug in the function that transforms expressions into a format MuParser can understand, which used to work incorrectly with negative variables being multiplied, divided or elevated to power.
* Fixed a bug in the keyboard input routine, that used to make the character display sluggish on Windows 10.
UPDATE 9.1: Fixed a related bug, only apparent on Windows 10, that sometimes prevented the application to release the screen after quitting. Fixed the proportions in the alternative screen layouts (GOPET, GO20, GO16, GO64, GO128) and sped up their creation. Implemented font and color selection in the frontend.

Version 8:
* Added support for additional resolutions (1360*768 and 1440*900).
* Rewrote the zoom routines for the instructions BOX, CIRCLE, DRAW, ELLIPSE and LINE, to make them more compact and have them accept more zoom values (for running the emulator at different resolutions) up to 6x.
* Implemented the GOSUB instruction.
* Added a partial implementation of the ASC instruction (to return the ASCII value of the first character of a string, with no string operations for now).
* Extended the PRINT instruction to support string chaining (with the operator + ) and the CHR$ parameter (to turn an ASCII code into a character).
* Fixed a bug in the frontend that used to corrupt the status of the MuParser flag.
* Fixed a bug that used to crash the program if a pixel is drawn beyond the edge of the current resolution.
UPDATE 8.1: fixed a bug in the string array that used to hang the emulator when a file with a name shorter than 16 characters was opened. Removed leftover debug code.
UPDATE 8.2: redefined the Gosub stack as an unsigned integer array to let it accept addresses greater than 255. Fixed a bug in the default (=non-MuParser) expression evaluator for a correct evaluation of multiple variable assigns separated by colons.

Version 7:
* Changed the types of the program counter, data counter and expression counter from unsigned integer to unsigned long to allow for longer programs.
* Modified the keyboard handling functions so that they yield CPU time every time they are called
* Fixed a bug in the INPUT# instruction that used to leave the file open after the program terminates for attempting to read past EOF.
* Added a check in the LET instruction that stops the execution of a program if a string is over 255 characters long.
* Implemented string chaining with the operator + , with an arbitrary number of strings (up to the limit of 255 characters).
* Fixed a bug in the PRINT instruction that prevented the cursor from going to the next line when a single instruction displays more characters than a line can fit.
* Implemented the LEN instruction, to know the length of a string or chain of strings.
* Implemented the RESTORE instruction, to move the data counter to the desired line or to the beginning of the data section.
* Added checks in both the frontend and the main executable to force the emulator to run in full screen when launched from the frontend, to avoid an "invalid video mode" error.
* Added a check that recognizes attempts to execute an empty program file and skips them.

Version 6:
* Included a fix for a COMDLG32.OCX error that happens on certain Windows systems when attempting to run Hi65 Edit and Launch Tool. Note that the fix must be installed manually, following the included instructions.
* Fixed a bug in the text wraparound check that used to crash Hi65 if text reached the bottom of the screen in certain resolutions.
* Implemented the CLR instruction, to clear all variables, loop stacks, open streams and data pointer during the course of a program.
* Implemented the EXP mathematical function (the mathematical expression exp(x) equals to e^x).
* Implemented the HELP instruction (only as an immediate command, to display the line that returned an error during the execution).
* Implemented the CHR$, HEX$, LEFT$, MID$ and RIGHT$ string operations (note: for now, they only work in variable assigns, not as part of a PRINT command).

Version 5:
* Incorporated Ingo Berg's MuParser routines into Hi65. They form an open source evaluator of mathematical expressions, that enables Hi65 to evaluate and calculate expressions (e.g. for variable assigns) with an even higher complexity than what a physical Commodore 65 could do. However, they are disabled by default in Hi65 for speed reasons (the native Hi65 expression evaluator is limited to expressions with at most two operands, but is over 275 times faster to evaluate them). The MuParser routines can be toggled on or off with the Hi65cfg utility, from the Hi65 Edit and Launch Tool, or directly from Hi65 with the MUPARSER pseudocommand (see below).
* Implemented a pseudocommand to enable, disable or verify the status of MuParser within Hi65. The syntax is: MUPARSER 0 to disable it, MUPARSER 1 to enable it, and just MUPARSER to display a message telling you whether it's currently on or off. It works either from the command line or from within a BASIC 10 program.
* Added 36 new error messages that do not appear in the physical Commodore 65, that are triggered whenever MuParser fails to evaluate an expression for some reason. This does not affect compatibility and makes debugging programs easier because they are more specific than a generic "SYNTAX ERROR" could ever be. 

Version 4:

* Implemented the SPC and TAB parameters in the PRINT function (respectively, to display the specified amount of spaces and move the cursor to the specified column).
* Fixed a bug in the LOCATE function that used to add the screen border twice instead of once to the cursor position.
* Fixed a bug in the DLOAD function that used to hang the emulator if a syntax error was made when entering the command.
* Fixed a bug in the LET function that used to leave residual characters of a previous string initialization, if the new value was shorter than the older one.
* Implemented the system timer. This counts the 60ths of a second elapsed since the C65 was switched on (or, in this case, since the emulator was launched) and stores the value into the numeric variable TI. Instead, the string variable TI$ contains the system time, like it would in a C65 with a real-time clock.
* Implemented the SCNCLR function.
* Implemented the support of sequential files, with the functions DOPEN, APPEND, DCLOSE, INPUT# and PRINT#. This makes it possible to read and write files from within a BASIC 10 program.
* Added a new feature to the Windows frontend: a menu called Paths, from which you can now tell the frontend where the Hi65 and VICE executables are located. The default is that both are located in the same directory as the frontend, which is true for Hi65, but if you want to use the frontend with VICE without moving files around, you'll have to use the appropriate option of the Paths menu to specify the VICE directory.
* Fixed a bug in the frontend: now, if you load a .txt file, make some modifications and click on the "Launch with current program" button, the frontend will actually launch the correct program.

UPDATE 4.1: Optimized and debugged the INPUT function, to prevent it from corrupting the data when reading a negative non-integer.

Version 3:

* Fixed a bug in the function that loads the configuration: if a configuration file was not found, the program used to crash; now instead it creates a default configuration file.
* Rewrote the part of the PRINT function that deals with numbers, to make it display non-integers correctly.
* Modified the functions that work on non-integers so that they use doubles instead of floats, to increase precision.
* Made a major overhaul to the Windows frontend, which now allows you to write and modify BASIC 10 programs directly, instead of relying on an external text editor. The GUI of the frontend is now different too, more complete and professional. To reflect the change, the name of the frontend is now Hi65 Edit and Launch Tool.

UPDATE 3.1: Fixed a resizing bug in the frontend. Corrected the icons when another version of Commodore BASIC is selected. 

Version 2:

* Fixed a bug in the expression evaluator, so that goniometric functions also accept variables (only numeric, of course).
* Fixed a bug in the CHAR function, so that it also accepts variables (only strings - a limitation of the original instruction on the C65).
* Fixed a bug in the function that reads the instruction end address, so that it is also read correctly whenever its least significant byte happens to be zero.
* Added the support for more HD resolutions.
* Added the support for windowed mode. Note that running Hi65 from the edit and launch tool will modify the configuration file to force it to full screen anyway, because launching it in windowed mode from the frontend would cause it to crash. Instead, configuring it to any mode (windowed or full screen) with hi65cfg.exe and then running hi65.exe will run it correctly in whatever mode you select.
* Added a flashing cursor whenever Hi65 is accepting keyboard input.
* Added a wraparound check that returns the text cursor to the top of the screen whenever the bottom of the screen is reached.
* Implemented 1-dimensional arrays for numbers and strings, with a maximum number of 256 elements (from 0 to 255). This also includes the ability to use an element of an array as an index in a FOR cycle, which was not possible in an actual C65.
* Just for fun, added alternative interfaces to the emulator, resembling screens of other Commodore computers. To try them, use the following commands: GO64, GO128, GO16, GO20, GOPET. To return to the classic interface: GO65. Note that the changes are merely aesthetical, with no difference in functionality or scope of the emulator.

Version 1:

* It can load programs at launch time, by specifying the name of the program as a parameter in the command line
* It can load programs at run time, by using the DLOAD command
* It can run a consistent subset of BASIC 10 instructions
* It can perform extremely fast graphical operations, with an accuracy and speed exceeding those on MESS. In particular, the speed is several *ORDERS OF MAGNITUDE* greater than on MESS.


==============
= To-do list =
==============

* It does not yet support nested multiline IF statements (meaning you can create multiline IF statements, but you cannot put one inside another)
* The INPUT function cannot yet process multiple inputs if separated by commas
* Audio and sprite emulation are not yet supported
* It cannot yet tokenize and run a program that has been written within the emulator
* Direct command mode is still incomplete


=========================
= What it will never do =
=========================

* Run Commodore 64 software
* Emulate the known bugs of Commodore 65


=======================
= System requirements =
=======================

* Any version of Windows, from Windows 95 to Windows 11 (or, if you have a Un*x-like OS, you can compile the emulator yourself from the included source code)
* Any PC, from an old Pentium 200 all the way up to the fastest PC available on the market right now, provided it has at least 92 MB of RAM


=================================================
= How to create a program that will run on Hi65 =
=================================================

Just like the other emulators that support Commodore BASIC programs, Hi65 cannot simply load a text file that happens to be the source code of a program and run it. In order to run a program on Hi65, the source must be first tokenized, and for this, a utility called Petcat has been included in the Hi65 archive.
Supposing you already typed your BASIC 10 program in your favorite text editor, you have three ways to do so:
1) via the command prompt
2) with a supplied batch file
3) with the Hi65 Edit and Launch Tool

* For the first way, you have to open the command prompt and enter the following command:

  petcat -w10 -o <destination_name>.prg -- <source_name>.txt

  For example, if you saved your source file as test.txt, you will have to enter:

  petcat -w10 -o test.prg -- test.txt
  
  and then press Return. This will create a tokenized file with the .prg extension, that you will be able to load on Hi65.

* For the second way, you have to use the batch file called "tokenize.bat" included with the emulator. You can use your favorite text editor to edit that file with the name of your program, then run it to tokenize your program.

* For the third way, see the section "How to use Hi65 Edit and Launch Tool" below.


==========================================
= How to run a tokenized program on Hi65 =
==========================================

So now you have a tokenized program and you want to run it. You can do it in three possible ways:
1) from the command prompt
2) directly from the emulator
3) from the Hi65 Edit and Launch Tool

* For the first way, you will have to open the command prompt and enter the following command:

  hi65 <program_name>.prg

  For example, if the program you want to run is called test.prg, you will have to enter:

  hi65 test.prg

  and then press Return. The emulator will open and will automatically run the program you selected.

* For the second way, you will have to run the emulator, simply by double-clicking on its icon, or by entering "hi65" (without quotes) at the command prompt. The emulator will open to the starting page of the Commodore 65. From there, you will have to enter:

  dload "<program_name>.prg"

  For example, if the program you want to run is called test.prg, you will have to enter:

  dload "test.prg"

  and press Return. The program will be loaded, but will not yet run. To run it, you will have to type:

  run

  and press Return.

* For the third way, see the section "How to use Hi65 Edit and Launch Tool" below.


========================================
= How to use Hi65 Edit and Launch Tool =
========================================

The Windows version of Hi65 includes a frontend that lets you edit BASIC programs directly, without using external text editors. It also lets you tokenize programs you wrote as text files and load tokenized programs with Hi65.

To start the frontend, double-click on Hi65 Edit and Launch Tool.exe. The window is divided into three sections: the menus, the controls, and the text box.

Six out of seven options of the "File" menu correspond in functionality to the six buttons directly below. They are:

* New .TXT (stack of white paper sheets) - this clears the text box, to start editing a new .TXT file.

* Open .TXT (yellow folder) - this loads an existing .TXT file into the text box.

* Save .TXT and tokenize into .PRG (gray floppy disk with white label) - this saves the content of the text box into a file (if it's the first time saving anything, you will be asked for a name) and then it runs Petcat to generate the corresponding tokenized .PRG file.
There is also a "Save .TXT as... and tokenize into .PRG" menu option, with no corresponding button, which lets you choose a new name every time you use it.

* Open .TXT and tokenize into .PRG (stack of yellow folders) - this loads an existing .TXT file into the text box, then runs Petcat to tokenize it into a .PRG file.

* Select .PRG and launch Hi65 (gray cabinet) - this asks you to select a .PRG file, then it launches Hi65 using the name of the file you selected as a parameter. If it's a valid BASIC 10 program, Hi65 will run it.

* Launch Hi65 with current program (miniature screenshot) - this saves whatever is written in the text box as a .TXT file, it tokenizes it with Petcat and then it launches Hi65 with the .PRG file it generated. If it's a valid BASIC 10 program, Hi65 will run it.

To the right of the buttons are two comboboxes. The one on the top lets you select the resolution you want to use for Hi65. The one on the bottom lets you choose what version of Commodore BASIC you want to tokenize your programs as. The default value is BASIC 10 (the version for the Commodore 65, which you will need to use in order to run a program on Hi65).

You will notice that selecting another version will change the look of the rightmost button: this is done as a visual help to let you know what kind of Commodore computer would run the program you eventually tokenize. Selecting any version of BASIC except 10 will cause the frontend to attempt to load the program in VICE, instead of Hi65.

The Paths menu will let you set up the paths for Hi65 and the various executables of VICE. This will be useful if you want to use the frontend to make and run programs for Commodore systems other than the Commodore 65. Notice that, by default, the frontend assumes that both Hi65 and VICE reside in the same directory as the frontend. This is true for Hi65, but very probably not for VICE. In order to set up the path for VICE, click on the Paths menu and uncheck the last option. A common dialog window will open, telling you to look for and select any executable from VICE. So do it: use the common dialog window to navigate through the directories, reach the folder where you keep VICE and open any of the executables that comprise VICE. From now on, the frontend will know where VICE is.

The text box will let you create or edit a text file (with no syntax check), which you will be able to save, tokenize and run by using the buttons.


==================================================================
= How to fix the COMDLG32.OCX error in Hi65 Edit and Launch Tool =
==================================================================

Some Windows systems don't come with a COMDLG32.OCX library. To be able to use Hi65 Edit and Launch Tool on those systems, you will need to install COMDLG32.OCX yourself. This is how.

1) Open the "Comdlg32 fix" directory.
2) Double click on Comdlg32.zip.
3) Extract COMDLG32.OCX on your desktop.
4) Right click on COMDLG32.OCX and CUT it.
5) Open the directory c:\windows\system32. You might get a message asking you whether you really want to access that directory. If you do, click YES.
6) Right click inside the c:\windows\system32 window and PASTE COMDLG32.OCX.
7) If you are on Windows XP or an earlier version of Windows, open a command prompt. Otherwise, click on the command prompt icon with the RIGHT mouse button and select "Run as administrator."
8) Enter the following command:

regsvr32  %Systemroot%\System32\comdlg32.ocx

and press Enter. COMDLG32.OCX will be correctly installed and registered.


==================
= Other controls =
==================

* To quit Hi65, press ESC at the main screen, whenever the emulator is not running a program.


================================
= How to compile Hi65 on Linux =
================================

First, make sure you have Allegro installed. You can get them by going to https://www.allegro.cc/files/ and following the instructions to install it.

Then open a terminal and reach the directory where you unzipped the Hi65 archive. If you want to build a normal (non-debug) version of Hi65, you'll have to enter this command:

make -f Makefile.win CPP=g++ LIBS=-lalleg

Instead, if you want to build a debug version:

make -f Makefile.win CXXFLAGS=-g CPP=g++ LIBS=-lalleg

Building Hi65CFG is almost the same thing. Only, you'll have to reach the directory with the Hi65CFG source code instead, and enter the following command:

make -f Makefile.win CPP=g++

because Hi65CFG does not need Allegro.


=================
= Configuration =
=================

There are two configurable parameters: screen mode (full screen or windowed) and resolution.
Hi65 supports the following resolutions:
* 640 x 400 (16:10)
* 640 x 480 (4:3)
* 800 x 600 (4:3)
* 1280 x 720 (16:9)
* 1280 x 800 (16:10)
* 1360 x 768 (16:9)
* 1440 x 900 (16:10)
* 1600 x 900 (16:9)
* 1920 x 1080 (16:9)

There are two ways to configure the resolution. Either
* run hi65cfg.exe and follow the instruction in the text window, or
* run the Hi65 Edit and Launch Tool and configure the resolution from the combobox in the frontend window

The choice between windowed and full screen can only be done with hi65cfg.exe . It is purposely absent from the Hi65 Edit and Launch Tool, which will instead overwrite the current configuration to run Hi65 in full screen.

=======
= FAQ =
=======

Q: What does "Hi65" mean?
A: It means it's a *hi*gh level emulator of the Commodore *65*. The name has nothing to do with "saying hi to the Commodore 65" (yes, I've actually been asked that).

Q: Does Hi65 require a BIOS to run?
A: No, because the low-level architecture of the original machine is of no concern for Hi65. Parsing tokenized programs and executing the appropriate actions is done much more efficiently with routines written from scratch, without a BIOS.

Q: Does Hi65 contain any code by Commodore?
A: No, Hi65 has been written entirely by Simone Gremmo. The MuParser routines, which you can identify in the source code by their filenames starting with "muParser", have been instead written by Ingo Berg.

Q: When will the next release of Hi65 come out?
A: When it's done.

Q: Will you ever implement low-level emulation like in MAME?
A: No, because my approach to emulation is software-centric, as opposed to the hardware-centric approach followed by MAME.
My definition of a good emulator is an emulator that runs software well. To achieve that, a perfect description of the original hardware is not necessary: all that is necessary is a program that, given certain inputs, returns the same outputs (or a reasonable simulacrum thereof) as the original machine, not necessarily by following the same procedures. Exceeding the performance of the original machine is a desired goal; describing the original hardware is just a nice side effect.

Q: Who decides what constitutes a "reasonable simulacrum"?
A: I do, because I'm the author.

Q: What if I don't like your software-centric approach?
A: Feel free to download any other C65 emulator. Oh, wait...

Q: Nobody can be nostalgic for the Commodore 65, so why does a Commodore 65 emulator even exist?
A: The concept of emulation is completely distinct from nostalgia. The real purpose of emulation is, in fact, platform unification, which is the ability to run a program on a platform it was not written for. That was the purpose of the first emulator ever (an IBM 704 emulator for the IBM 709, written in 1957), that was the purpose of every emulator that came out in the 1980s and early-to-mid-1990s (when the various emulated platforms were too new to evoke nostalgia) and that is the purpose of every CPU emulator ever released. If emulation has no appeal for you except in using your PC to play console games that make you feel warm and fuzzy inside because you played them in your childhood, Hi65 is obviously not the program for you. The purpose of Hi65 is simply to run BASIC 10 programs on a PC. Nothing to do with nostalgia.
As for why one would want to run BASIC 10 programs on a PC... simple human curiosity, to see how an extremely rare computer would work without actually owning it.

Q: I want to provide feedback for Hi65, how can I contact you?
A: See the Contact section below.


===========
= Contact =
===========

If you want to send me questions, suggestions or remarks, contact me at:
devilmaster (a snail) email (a period) com .

If you want to send me spam, send it to /dev/null .

My web site is https://devilmaster.altervista.org/ .

If you want to make a donation to support the development of Hi65, you will find a Donate button in the Hi65 page at https://devilmaster.altervista.org/hi65.html .