File Loader

File Loader for firmware v1.1.0 (USB file upgrade) and above.

Using the File Loader function and a FAT32 formatted USB memory stick, THEC64 Mini loads programs from various C64 file formats. Supported file formats include:

Disk images: D64, G64, D81, D82
Tape image file:T64, TAP
Others: PRG, P00 and CRT

To make file browsing and selection less arduous, the File Loader currently has a display limit of 256 files and/or folders per-folder, including the root of the memory stick. This equates to 18 pages of listed items to navigate through with your joystick.

Please note that only C64 programs supplied by Retro Games Ltd for use on THEC64 Mini are covered by the Warranty. This does not affect your statutory rights. Please read the Warranty for further details.

Control how THEC64 Mini configures a program loaded from a USB memory stick in two ways:

Either method gives THEC64 Mini information used to load and run a program correctly from USB. Note that some programs will load and run correctly just using the default settings, explained below.

Default settings

In the absence of flags in filenames or CJM text configuration files, THEC64 Mini applies default settings to any supported file it finds on a USB memory stick:

Many programs load and run fine using the default settings. If your program does not, or you wish to change the configuration, please refer to Appendix A.

The File Loader

Whilst on the HOME screen, insert a USB memory stick that contains supported C64 files into an available USB port on THEC64 Mini. After a few seconds, an icon appears beneath the GAMES CAROUSEL to confirm the USB memory stick is connected.

Highlight the USB icon and press FIRE. The FILE LOADER screen lists any supported files and folders stored in the root of the USB memory stick.

Note that file extensions (for example, D64, TAP, CRT), flags added to filenames (for example _TP) and CJM files (for example, c64-disk.cjm) are NOT shown in the list.

Highlight a file and press FIRE. The selected file loads and runs. How long it takes to load will vary based upon the type of file and the settings used by THEC64 Mini to load it.

Move the highlight over a folder and press FIRE. The contents of the sub-folder appear. You cannot enter a folder that is empty or does not contain any other folders or supported C64 files.

When inside a folder on the USB memory stick, press button A on the joystick to move out of the current folder. Alternatively, push LEFT to come out of a folder when on the far left side of the File Loader list.

The C64 Fast Loader is switched on by default, speeding up loading times. For those programs that do not load if the fast loader is ON, press button C on the joystick (a red X appears over the Fast Loader icon) before you press FIRE to load. This turns the fast loader OFF.

Note that the faster disk access function remains ON unless you specifically turn it OFF via filename flags or a CJM file. See Appendix A for full details.

Save/Load from USB

When loading a program file from a USB memory stick, the Save/Load function (see CHAPTER 5 of the User Guide) saves and loads on the USB memory stick rather than on THEC64 Mini. You have four slots to save to per program.

Save files are stored inside a folder on the USB memory stick called .THEC64SAVE. Inside that folder are sub-folders that contain your saves.

For example, .THEC64SAVES\c64-disk\ contains saved files for a C64 disk image file called ‘c64-disk’.

BASIC and accessing a USB memory stick

Please note that the only file stored on a USB stick that can be loaded directly when running BASIC on THEC64 Mini is a disk image with the filename THEC64-drive8.d64. Please visit programming-in-c64-basic and faq for further details on BASIC and THEC64-drive8.d64 file.

APPENDIX A – CONFIGURING C64 PROGRAMS

Add flags to each filename

By adding flags to the end of the filename, you define which joystick port(s) are used, specify the machine type (PAL or NTSC), set a disk to be read-only, turn on accurate disk loading (for troublesome disk image files that won’t load quickly), and disable the on-screen disk icon.

For example, the program on a disk image file called ‘c64-disk.d64’ requires a joystick connected to port 1 on the original C64 computer. Rename your d64 file ‘c64-disk_J1.d64’.

Below is a list of all the available flags:

J1 This sets the primary joystick port as port 1. With a second Joystick connected, it automatically uses port 2
J2 This sets the primary joystick port as port 2. With a second Joystick connected, it automatically uses port 1. Note that port 2 is the default set by THEC64 Mini, so it doesn’t *have* to be specified by this flag
AD This flag turns ‘accurate disk drive’ mode on (for original slower disk loading) and turns off the fastdisk mode which is ON by default
RO This makes the disk appear as read-only (which prevents THEC64 Mini writing to the disk image)
NI This flag disables the drive icon from appearing on-screen during disk loading
TN This runs as an NTSC C64. It doesn’t affect the HDMI output
TP This runs as a PAL C64. It doesn’t affect the HDMI output

Add flags to the end of the filename in any order. For example:

c64-disk_TNROJ1.d64 or
c64-disk_ROJ1TN.d64 or
c64-disk_J1TNRO.d64

Create a CJM file for each program file

Using a computer that can create new files, create a text file on the USB memory stick that includes joystick port requirements, machine type (PAL or NTSC) settings, accurate disk loading options, additional joystick button mappings and other settings for each program file.

You can use the standard text editors that come with Windows, Linux and Mac OS to create CJM files. Ensure that your file does end with a .cjm file extension, otherwise it will not be recognised by THEC64 Mini. For those who are interested, the files needs to be UTF-8 or ASCII encoded and must not contain any non-standard characters.

Save the CJM text file in the same folder as the program file on your USB stick. For example, ‘c64-disk.d64’ has a corresponding file ‘c64-disk.cjm’.

THEC64 Mini always uses a CJM file in preference to any filename flags or default settings.

An example CJM file looks like this:


X:pal,accuratedisk,driveicon
J:2*:JU,JD,JL,JR,JF,JF,SP,1,SP,2,3,4,JF
J:1:JU,JD,JL,JR,JF,JF,JF,JF,JF,,,,JF
V:12

As you can see from the example given, each line in a CJM text file complies with the following:

type: value [,value]

Entity name Entity type Values Description
Computer configuration X pal
ntsc
driveicon
readonly
accuratedisk
This sets the parameters needed to configure the C64 computer before it loads and runs the program.

The values are case sensitive and must be in lower case.

pal – This makes the program behave as though running on a European (PAL) C64. It doesn’t affect the HDMI output of THEC64 Mini.

ntsc – This makes the program behave as though running on a North American (NTSC) C64. It doesn’t affect the HDMI output of THEC64 Mini.

driveicon – This activates the on-screen drive icon, to show when a disk is accessed.

readonly – This makes a disk read-only, meaning THEC64 Mini cannot write back to the disk.

accuratedisk – This switches ON accurate (slower) disk drive functionality, necessary for some programs to load correctly. This is off by default.

Vertical display shift V -16 to +16 This number moves the screen position up or down over a range of + or – 16 display lines (pal). This is useful if a game has graphics that appear in the top or bottom border, as an HDMI 720p television screen can otherwise clip them. For ntsc programs, going above +7 or +8 could exhibit display problems at the bottom of the screen.
Joystick configuration J See following table for allowed values

Note that the entity type is always a capital letter rather than lower case, e.g. an X rather than an x, otherwise THEC64 Mini will ignore the entity type and the values associated with it in the CJM file.

Joystick configuration consists of 13 values that define how the joystick is to operate in the program.

The first value (after the J: entity) defines the primary port (1 or 2, with primary indicated by an *), followed by what happens when the joystick is pushed UP, DOWN, LEFT or RIGHT. The next two values define what happens when the LEFT FIRE and RIGHT FIRE buttons are pressed. The next two values define what happens when the TL and TR triangle buttons are pressed. The next value is an extra joystick button (not available on THEC64 Mini Joystick) but it usually assigned the same value as the TR button. The next three values are buttons A, B and C on THEC64 Joystick. The final value is another button not available on THEC64 Joystick, but is usually assigned the same value as the TL button. For example:

In the shown example, the joystick is behaving as if connected to port 2 on the original C64 computer. Moving up, down, left and right using the stick is as you would expect. Both FIRE buttons perform the same joystick fire (JF) function. Pressing TL on the joystick is the same as pressing the Spacebar (SP). Pressing TR is the same as pressing the 1 key, and buttons A, B and C do the same job as pressing keys 2, 3 and 4 respectively.

Joystick parameters are the port assignments first, then the joystick standard functions, then the button mapping:

Joystick to key map ID Description
JU JD JL JR JF Joystick directions Up, Down, Left, Right and Fire
F1 F2 F3 F4 F5 F6 F7 F8 C64 function keys F1 to F8
AL Arrow Left
AU Arrow Up
CM C64 key
CO Comma
CT Control
CU Cursor Up
CD Cursor Down
CL Cursor Left
CR Cursor Right
DL Delete
EN Return
HM Home
RS RUN/STOP
RE RESTORE
SL SHIFT Left
SR SHIFT Right
SS SHIFT Lock
SP Spacebar
PO Pound (£)

Assigning letters and numbers to joystick buttons is easy. For example, to assign pressing key A to a Joystick button, just enter A in the CJM data for the relevant button.

Considerations

In all of the games provided with THEC64 Mini, the LEFT and RIGHT joystick FIRE buttons have the same function (JF) so both left and right-handed players can use either button as FIRE. However, the LEFT and RIGHT joystick FIRE buttons are independent, so you can assign one FIRE button to JF and the other to a different function if you wish in your CJM files.

In addition, for consistency all of the games on the GAMES CAROUSEL start by pressing TL or by pressing a FIRE button. If you wish to retain this logic, keep in mind how your program starts once it has finished loading when you assign joystick buttons in the CJM file. If FIRE does not start the program, then assign the appropriate key press to the TL button.

Programming in C64 BASIC

The GAMES CAROUSEL gives you access to the BASIC programming language.

If you want to follow through the BASIC examples, we strongly recommend connecting a USB keyboard to THEC64 Mini, rather than trying to use the Virtual Keyboard. Please read CHAPTER 6: KEYBOARDS In the User Guide PDF before starting this introduction to BASIC.

If a compatible USB memory stick (formatted to FAT32) is attached to THEC64 Mini before BASIC is launched, then you can save your BASIC code to the memory stick. See Saving and Loading below for further information.


WHAT IS BASIC?

When you power-on a C64 computer, the first thing you see is BASIC. We provide access to BASIC on THEC64 Mini for those who wish to experience programming using version 2 of the C64 variant of the Beginners All-purpose Symbolic Instruction Code.

BASIC is a high-level programming language, designed to be easy to use. It is an interpreted language, meaning any BASIC instructions you type have to be translated by the computer before it can run them. This actually happens quite quickly and is done invisibly and automatically by the computer.

Computers like the original C64 and THEC64 Mini natively ‘talk’ in machine code, which is a series of zeros (0) and ones (1). When they use machine code, they operate very fast. However, people don’t directly program in machine code, so we use a different way to send instructions to the computer, using programming languages that are closer to what we are used to.

Some programming languages are a few steps closer to machine code, and so they are interpreted (or translated if you prefer) quicker than those that aren’t.

BASIC has always been an excellent introduction to programming for complete beginners even though it is quite a few steps away from machine code.

Learning to program using C64 BASIC helps you think programatically, and it also teaches you how to type on a keyboard. Both of these skills are important to learn.


BASIC KEYWORDS

C64 BASIC has a series of keywords that tell the computer what to do next. Learn those and you will be writing BASIC code in no time at all. There are 71 BASIC keywords to discover.

If you think 71 sounds a lot, don’t worry. You don’t have to learn them all at once. Many of them are related to doing mathematical calculations, and only come into play when you start doing more complex coding. More on keywords later!


LAUNCHING C64 BASIC

When you first launch BASIC from the GAMES CAROUSEL on the HOME screen, you see a blue screen. It begins by revealing how much computer memory is available for programming. Underneath that information is a READY prompt and underneath that is a steadily blinking square cursor.

Staring at the cursor won’t get you very far. It’s ready and waiting for you to enter your first BASIC commands.

There are two ways of entering BASIC code. You can type it in and press RETURN. The computer will immediately try and run your code. However, to repeat the same code later on, you have to type it in again. That’s not so good. The second method is a lot more efficient. You place numbers at the start of each line of your code that tells the computer in which order to run them. The great thing is that using line numbers also means it won’t run your code until you type the RUN keyword *and* it means you don’t have to type it all in again (as long as you don’t turn off the computer).


YOUR FIRST BASIC PROGRAM

Below is an example BASIC program. We will look at each line of code in turn before doing this on THEC64 Mini.

There are three separate lines of BASIC code to explain.
10 PRINT “RETRO GAMES LIMITED”
20 PRINT “HELLO WORLD!”
30 GOTO 10

Line 10 uses the keyword PRINT which sends whatever appears between the quotation marks “” to the computer screen (and not to a printer as you might expect!).

Line 20 does the same as line 10 but will send different words to the screen.

Line 30 instructs the computer to go to line 10, which places the computer in a loop of running line 10, then line 20, then line 30 telling it to go back to line 10 again and so on.

The line numbers are in units of ten just in case we want to insert extra lines of code, e.g. a line 15 that comes between line 10 and line 20. If you type a line of code that begins with the same line number as an existing line, the new line will replace the old one as soon as you press RETURN, without any warnings. If you type just the line number and nothing else then press RETURN, you delete that line number.

Now type each line exactly as you see it (above). Press RETURN at the end of each numbered line to commit that line to the computer’s memory and to move down a line, before starting to type the next one.

Press RETURN at the end of line 30.

If you make a mistake, use the Backspace key on your USB keyboard (or press the C button on the joystick when using the Virtual keyboard). Each press will erase the character immediately to the left of the cursor’s position on the screen.

If you’re happy that you’ve typed everything in correctly, type the RUN keyword (without a line number). Your code will then run!

If you’re wondering how to stop your new BASIC code from running forever, try pressing ESC (on a USB keyboard) or RUN/STOP (if using the virtual keyboard). You have instructed THEC64 Mini to BREAK into your code. Don’t worry – it’s not as bad as it sounds!

To see your code is still intact, you can type the following keyword at the square cursor:
LIST
Your three lines of code are displayed, safe and sound just as they were the last time you saw them.


BASIC Keywords

Believe it or not, you’ve already used four BASIC keywords. To prove it, here is a table showing all 71 of them.

ABS AND ASC ATN CHR$ CLOSE CLR CMD
CONT COS DATA DEF DIM END EXP FN
FOR FRE GET GET$ GOSUB GOTO IF INPUT
INPUT$ INT LEFT$ LEN LET LIST LOAD LOG
MID$ NEW NEXT NOT ON OPEN OR PEEK
POKE POS PRINT PRINT$ READ REM RESTORE RETURN
RIGHT$ RND RUN SAVE SGN SIN SPC SQR
STATUS STEP STOP STR$ SYS TAB TAN THEN
TIME TIME$ TO USR VAL VERIFY WAIT

We’re now going to slightly change your code so that it only prints the two lines of text five times before stopping, rather than going on forever.
5 FOR A=1 TO 5
10 PRINT “RETRO GAMES LIMITED”
20 PRINT “HELLO WORLD!”
30 NEXT A

You should immediately notice that we have added a line number 5 and we have changed what was on line 30.

Look at these two new lines of code for a moment and ignore lines 10 and 20 in-between. These lines introduce two new concepts to your BASIC knowledge as well as two new keywords.

One concept is defining and using variables in your code. In this example, we are using ‘A’ as a container to temporarily store a number inside. The letter A was chosen but it could easily have been the word ‘WORLD’, so it could have read…
5 FOR WORLD=1 TO 5
(lines 10 and 20 remain the same as before)
30 NEXT WORLD

… and your program would still have worked. You could also have changed the number at the end of your line of code from 5 to 6. Variable names are chosen by you and can (almost) be anything you like. However, there are rules to naming these handy variables for storing things in.

You can’t use reserved keywords used by BASIC or by the C64 for its own system variables. How do you know which ones can’t be used? Well, if you had used LIST as your variable name, running the program would have produced:
?SYNTAX ERROR IN 5
It’s not the most helpful of errors, but if THEC64 Mini returns that error, you know something is wrong. Remember that list of C64 BASIC keywords? Don’t use any of those as names for your variables and you can’t go far wrong.

Try to keep your variable names short, but relevant where you can. If your code isn’t overly complex, then you can just use A, B, C and so on, just as long as you remember what they are used for!


Types of Variable

The only other thing to know is that there are three types of variable, and they are defined by what type of information is stored in them.

The two most common that you will use are integer and string variables.

An integer is simply a whole number, so no fractions or decimal points. A string is letters or letters and numbers.

How do you say which type of variable you want to use? For integers, you just use a name for your variable, without anything else, e.g. WORLD. For strings, you add a $ to the end of the variable name, so RECIPE$ might be used to store the name of your favourite cake or biscuit recipe, e.g. “Rocky Road”.

So, looking at your amended BASIC example, we know that ‘A’ is used to store a whole number (which can actually be between -32768 up to 32767). In our example, it is only going to reach a maximum value of 5.

Now let’s discuss the FOR and NEXT keywords. These are paired together and create a FOR… NEXT loop. What this does is from the FOR keyword, the computer stores a number inside ‘A’ that starts at 1 and will end at 5 (in this particular example).

Each time the running code encounters the NEXT ‘variable’ (NEXT A in our example), it returns to the line with the FOR keyword and increments (adds one to) the current number stored in the variable called ‘A’. The code then runs each line of code it comes across afterwards (i.e. line 10 and line 20) until it hits NEXT A again, then it returns to the FOR keyword and repeats the process until the value of ‘A’ equals 5, then it stops.

So, add in line 5 exactly as shown previously, change line 30, and then RUN the amended code and see what happens.

Now, it would be useful to show what the current value of ‘A’ is. Add a new line 25:
25 Print A
Now RUN your code again.

You can now see the two lines of printed text are followed by a number that goes up by one each time, e.g. 1, 2, 3, 4, 5.

It’s useful to see the value stored in variable ‘A’ as you can now see how it changes within that FOR… NEXT loop, adding one automatically whenever it reaches NEXT.

Let’s now make this look a little better by adding something to line 25.
25 PRINT “VARIABLE ‘A’ IS NOW“;A
The semi-colon at the end tells BASIC to keep the cursor on the same line as the text it is printing to the screen, and then display the value of the variable A.

RUN this latest version of your code.

That’s a little better. It’s clear now what those numbers mean and we’ve learned how to place the value of a variable into a PRINT command at the same time!

That almost concludes the introduction to C64 BASIC. However, before we finish, let’s learn how you can keep (save) your code so it can be run and amended in future.


Saving and Loading

On THEC64 Mini, you have two available methods for saving your BASIC programs:

1. Press the MENU button and select ‘Save/Load game’ and then save to an available slot on THEC64 Mini as you would do for a game. See CHAPTER 5: PLAYING GAMES in the User Guide PDF for more details on saving and loading to slots.

2. If a compatible USB memory stick (formatted to FAT32) is attached to THEC64 Mini before BASIC is launched, then you can save your BASIC code to the memory stick. When launching BASIC, THEC64 Mini looks for a specific disk image file on the memory stick. If the file isn’t found, then a THEC64-drive8.d64 file is automatically created on the USB memory stick for you. You will then be able to save and load to and from this file from BASIC.

Please note that to accommodate THEC64 Joystick, a USB Keyboard and a USB memory stick at the same time, you need to connect a separate USB hub (not supplied) which gives access to additional USB ports. Retro Games Ltd cannot guarantee that all USB hubs will work with THEC64 Mini and some hubs require a separate power source.


SAVE

With a compatible USB memory stick connected, you can save to the disk image using the standard SAVE to disk command, e.g.

SAVE “RGL”,8

The name of the file goes between the speech marks and it can be whatever you like, as long as it isn’t longer than 15 characters. In this example, it’s nice and short. The number 8 after the filename is a device ID number that is allocated to the disk image file on your USB memory stick.

Press RETURN afterwards to begin the save.

BASIC will report ‘SAVING’ followed by your chosen filename, and when it is completed, it returns to the READY prompt and the square cursor.

To save over an existing file with the same filename, add @0: to the front, like this:

SAVE “@0:RGL”,8

Please be aware that C64 BASIC won’t give any warnings that you are over-writing the file when you do this.


VERIFY

You can check that the save worked by using the VERIFY keyword.

VERIFY "RGL",8
If everything is okay, you will see VERIFYING followed by OK.


LOAD

Another time, ensure that the same USB storage device is connected to THEC64 Mini before you run BASIC, and then type the following command in BASIC to get your program back.
LOAD “RGL”,8


What’s on my disk?

From BASIC, you can look at a disk and see what files are on there. To do that requires use of the LOAD command, but in a slightly different way from before. Instead of typing a filename we are using the reserved variable $.
LOAD “$”,8
BASIC will report SEARCHING FOR $ followed by LOADING and then it returns to the READY prompt once again.

To see what’s on the disk is simple. Just type the following command:
LIST
Instead of listing BASIC code, this time the command shows what is on the disk.

In the above example, we have just one program on the disk and it’s the program we just saved called RGL. The program uses up 1 block on the disk and there are 663 blocks still free to save programs to in the future.

Be aware that if you load the directory of a disk and have some BASIC code on the C64 at the same time, the $ listing will replace the BASIC listing in the computer’s memory and you will lose your program (if you haven’t already saved it).

If you want to use multiple disks, then you will need to use a different USB memory stick for each disk, or temporarily rename the files because the .D64 file is always saved with the same filename – THEC64-drive8.d64 – each time.


Read Only

If you don’t have a USB storage device attached, but decide to try saving to device 8 anyway, BASIC will look like it has successfully saved but when you load the directory of the disk it will be empty. This is because without USB storage, BASIC uses a disk image that can only be read, not saved to. The tell-tale sign is the name of the disk, which is READONLY instead of THEC64. The disk is completely empty and cannot have anything saved to it.

To overcome this, you can always save in one of the four save slots, switch off THEC64 Mini, insert a USB memory stick into a spare USB port, switch THEC64 Mini back on, load BASIC, restore the save slot and then save to the D64 disk image using the SAVE command detailed earlier. Device 8 will now be the disk image on your USB memory stick.


Learn More

Before we finish, how many C64 BASIC commands have you used now?

ABS AND ASC ATN CHR$ CLOSE CLR CMD
CONT COS DATA DEF DIM END EXP FN
FOR FRE GET GET$ GOSUB GOTO IF INPUT
INPUT$ INT LEFT$ LEN LET LIST LOAD LOG
MID$ NEW NEXT NOT ON OPEN OR PEEK
POKE POS PRINT PRINT$ READ REM RESTORE RETURN
RIGHT$ RND RUN SAVE SGN SIN SPC SQR
STATUS STEP STOP STR$ SYS TAB TAN THEN
TIME TIME$ TO USR VAL VERIFY WAIT

You’re up to 11/71 commands already! We hope this small introductions has given you an interest to learn more. There are plenty of online resources available. Also, have a look at our Links page.

A video of this quick introductory tutorial is also available to watch below.

Loading Programs in C64 BASIC

Aside from the File Loader function, you can also load and run your own legally obtained C64 programs (including games, demos, utilities and so on) from BASIC on THEC64 Mini by following these simple instructions.

Please note that only C64 programs supplied by Retro Games Ltd for use on THEC64 Mini are covered by the Warranty. This does not affect your statutory rights. Please read the Warranty for further details.

First step: Preparation

1. You need a USB memory stick (maximum size of 64Gb) which must be formatted using FAT32
2. Copy the d64 disk file that contains the program you want to load onto the root of the USB memory stick
3. Rename your disk file on the memory stick to THEC64-drive8.d64
4. You are now ready to load your program from BASIC on THEC64 Mini.

Second step: Loading your Program

1. Make sure you’re at the Carousel screen then insert your USB stick into THEC64 Mini
2. If you have firmware v1.1.0 or above installed, a USB icon will appear on the HOME screen after a few seconds
3. Launch BASIC from the Carousel
4. Type the following two commands exactly as shown here:

LOAD “$”,8
LIST

4. Identify the name of the program you want to run from the list displayed
5. Type the following command, replacing NAME with the name of the program from step 4:

LOAD “NAME”,8,1

6. Some programs will load and start automatically. For others, you may need to type the following command afterwards:

RUN

Notes

Don’t forget to press RETURN after typing each command.

There are some limitations to the existing method of loading programs from a USB memory stick when in BASIC:

If these limitations are too restrictive for you, please see the File Loader for an alternative method for loading other programs on THEC64 Mini.

Due to licensing requirements, we cannot offer advice as to which programs currently work using this method and which ones do not.