Filename flags and CJM files

If the default settings on THEC64 device aren’t suitable for your chosen program running from your USB stick, then customise how it loads using one of two methods:

Either method passes information to THEC64 device to load and run the program from the USB stick. Note that only a cjm text file can remap joystick functions.

Unless otherwise stated, these instructions apply to the File loader and the Media access functionality (the latter is only available on the full-size THEC64).

Add filename flags to each file

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), disable the on-screen disk icon during drive access, and much more.

For example, the program on a virtual disk file called ‘c64-disk.d64’ requires a joystick connected to port 1 on the original C64 computer, rather than the more common port 2. 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. For VIC 20 programs (THEC64 only), this is the default and any port 2 settings are ignored.
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 for C64 computers, so it doesn’t *have* to be specified by this flag
AD This flag turns ‘accurate disk drive’ mode on (for original slower but more accurate disk loading) and turns off the fast disk access mode, which is on by default
RO This makes the disk file read-only (which prevents THEC64 device writing back to the disk file)
NI This flag disables the drive icon from appearing on-screen during disk loading
TN This runs the program on an NTSC computer. It doesn’t affect the HDMI output
TP This runs the program on a PAL computer. It doesn’t affect the HDMI output
FH This forces the entire display – including top and bottom borders – into the 720p output image, sacrificing the accurate display but showing everything (Firmware 1.3.1+)
NS This disables audio scaling, which automatically compensates for the adjustments in pitch of generated (rather than sampled) audio when running a computer at different refresh rates (Firmware 1.3.1+)
M6 This instructs THEC64 to use a C64 computer. This is only used by the full-size THEC64
MV This instructs THEC64 to use a VIC 20 computer. This is only used by the full-size THEC64

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

Introducing cjm files

The alternative to filename flags are cjm files, which have the additional benefit of being able to change controller buttons so you can map specified key presses to specific buttons. THEC64 device always uses a cjm file in preference to any filename flags or default settings.

THEC64 device will apply settings in the following order:

  1. If a cjm file is present for the program being loaded from a USB stick, its settings are applied;
  2. Otherwise, if a default cjm file is present in the folder containing the program (or one of its parent folders) then those settings are applied;
  3. Otherwise, any filename flags present at the end of the program filename are applied as settings;
  4. Otherwise, the default THEC64 device settings are applied to the program.

Creating a cjm 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.

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.

A cjm file for each virtual file

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’.

A cjm file that applies to multiple files

If you name the cjm file ‘thec64-default.cjm‘ then the settings contained within that file apply to every virtual file stored in the same directory (or any programs stored inside any child (sub) folders) on your USB stick, unless it has its own cjm file.

An example CJM file looks like this:

X:64,pal,accuratedisk,driveicon
J:1*:JU,JD,JL,JR,JF,JF,1,2,JF,A,B,C,JF,3,5
J:2:JU,JD,JL,JR,JF,JF,F1,F2,JF,1,2,3,JF,F3,F4
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
Computer configuration X 64
vic
pal
ntsc
driveicon
readonly
accuratedisk
fullheight
noaudioscale

The X entity sets the parameters needed to configure the 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 or THEC64 Mini.
driveicon – This activates the on-screen drive icon, to show when a virtual 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.
fullheight – This outputs the full height of the computer display when running the program, sacrificing the accurately scaled display to fit everything (including the top and bottom borders) into the 720p image
noaudioscale – This turns off the Audio scaling option, which is enabled by default.

Entity name Entity type Values
Vertical display shift V -15 to +17 (C64)

This number moves the screen position up or down over the stated range of 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.

Entity name Entity type Values
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 or 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 a shoulder trigger button (not available on THEC64 Joystick) but is usually assigned as a FIRE button. The next three values are buttons A, B and C on THEC64 Joystick. The following value is another shoulder trigger button not available on THEC64 Joystick, but again is usually assigned as FIRE. The final two values (only used in firmware 1.3.0 or above on either THEC64 device) are for controllers with two sticks that can also be pressed as a 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 1 key. Pressing TR is the same as pressing the 2 key, and buttons A, B and C do the same job as pressing keys A, B and C respectively. If using an alternative controller, pressing either shoulder trigger will FIRE, and pressing on either stick on some controllers will produce key press 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 and 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.