The!Cart Studio

Welcome to "The!Cart Studio", the free cartridge image authoring tool for The!Cart and Atarimax Maxflash Cartridges . The program enables you to create workbooks for cartridge images which contain one or more ROMs or executables. The workbook an then be exported in different formats. Besides plain binary images (".BIN", ".ROM") for usage if an EPROM or external flash programming device, emulator images (".CAR") to run the cartridge in emulators and flash programming images (".ATR") which can be booted directly from the Atari to flash the target module. This is the English manual. The German manual is under construction and will provided completely once the English manual is complete. If you have question regarding "The!Cart" or "The!Cart Studio", you can contact me directly or post in the The!Cart thread on AtariAge (English) or in the ABBUC Forum (German) .

• Downloading the Program
• Starting the Program
• General Usage
• Creating Workbooks
• Adding Entries
• Previewing Workbooks
• Exporting Workbooks
• Printing Workbooks
• Programming Flash Cartridges
• Extended Menu
• Advanced Topics
• Appendix

Downloading the Program

This is version ${version} of the program. Click here to download the latest version of the program. The download is a single ".zip" archive file which contains the actual program. Simply extract the files from the archive into a folder of your choice.

Starting the Program

"The!Cart Studio" is implemented in Java which makes is compatible with all popular operating systems. In order to run the program you need has Java Runtime Environment (JRE) or Java Development Kit (JDK/SDK) with version 1.6 or newer versions installed. Using Java 1.7 is recommended because on the one hand Java 1.6 is out of maintenance and on the other hand, multi-selection in the file selection dialog will only work with JDK 1.7 or newer versions. "The!Cart Studio" requires enough RAM available for the Java process to be able to export images. The amount of available RAM is display in the "About" dialog. It should be twice the size of the cartridge you want to export. So for a 128 MB "The!Cart" export, the program requires at least 256 MB. You can specify this when you start from the command line via "java -Xmx256M -jar TheCartStudio.jar". By default "The!Cart Studio checks" in an update is available during the start. The check is performed in the background and has no impact on the startup time. You can disable this check in the options.

Windows

The installation of the Java runtime normally registers itself as the default application for the file extension ".jar". So by simply double-clicking the "TheCartStudio.jar" file or by choosing "Open" from the context menu, the program should start. If you have an archiving program like WinZIP or WinRAR installed, it may be the case that they registered also for this file extension. As a result the ".jar" file is opened in the archiving program instead of being executed. In this case you can choose "Open With... Java(TM) Platform Binary" from the context menu.

Alternatively you can run the program also from the command prompt ("cmd.exe"). In this case you can change the current path to the folder where "TheCartStudio.jar" is located and type "java.exe -jar TheCartStudio.jar".

Linux

The installation of the Java runtime normally registers itself as the default application for the file extension ".jar". So by simply double-clicking the "TheCartStudio.jar" file or by choosing "Open" from the context menu, the program should start. After extracting the "TheCartStudio.jar" file from the download archive, the so called "executable bit" is not set, resulting in the following error message when you double-click the file.

Open the file properties, set the executable flag a shown below. Now the program should start when the "TheCartStudio.jar" file is double-clicked.
Please note that there is a known bug in Ubuntu , for example 12.10 with openjdk7. It is tracked as "Unreadable menu bar with Ambiance theme in Java/Swing GTK L&F" and causes the menu to appear too dark; making is barely readable with the standard desktop theme. Changing the desktop theme fixes this.

MacOSX

This is the same as Linux, except that Java 1.6 is available by default in Mac OS X 10.9 "Mavericks". The amount of memory available to Java by default appears to be 128 MB. Consequently you have to start "The!Cart Studio" from the console using "java -Xmx256M -jar TheCartStudio.jar" TheCartStudio.jar" to reserve enough RAM for exporting a 128 MB cartridge.

General Usage

The UI of "The!Cart Studio" is localized and current comes with English and German screen texts. You can change the display language via the menu entry "Tools/Options...". The default value is "Automatic", which means that the language is determined automatically based on the language settings of the operating system.

By default, only the most frequently used columns are display in the various tables. You drag & drop to change the order of the columns. Clicking on column header with SHIFT or CONTROL held down extends the sort order by appending this column. This way you can sort by genre first and then by title for example. Clicking a column header without pressing SHIFT or CONTROL resets the sort order to that single column. You can also use the context menu to hide visible columns, unhide invisible columns and reset visibility and sort order to the default. All layout changes are saved automatically when the program is closed. This also applies to the size and the position of the main window and to the different folders that were last used for loading/saving workbooks, adding entries and exporting cartridge images.

All relevant commands also have a key binding, so you can use your keyboard to fully control the program.

Creating Workbooks

In the "File" menu you can find the usual "New", "Open", Save", "Save As" and "Close" actions. When "The!Cart Studio" is opened, a new unnamed project is already prepared. You can display the dialog to edit the workbook options via the menu entry "Edit/Workbook Options...".

Adding Entries

You can add files for new entries via the menu entry "Edit/Add Entries...". The file chooser has multi-selection enabled, that means you can select multiple files at once and add them in go. Alternatively you can use drag & drop to drop one or multiple files onto the window to add entries.

"The!Cart Studio" contains a database of popular ROMs and will assign the correct title automatically based on size and the CRC32 checksum of the file. If no matching entry is found in the data, the title of the entry is defaulted from the file name by removing the file extension.

When new files are added, they remain at their original location first. When you save the workbook, all newly added files will be copied into the data folder (".tcd") of the workbook. This way you have all files and the workbook together in one location. As a consequence, a file in the workbook is uniquely identified by its case-insensitive file name, irrespective of the folder it was originally copied from. Adding files with the same file name will result in a confirmation dialog where you can choose to overwrite the existing file in the data folder with the new file, rename the file automatically during copying or to skip the new file, leaving the existing file in the data folder unchanged. The choice can either be applied to the current file only or to the current file and all following files.

Entry Properties

The information for every entry is displayed in the columns of table on the "Entries" tab". Only the most important columns are visible by default. They are show with bold names on the table. You can configure the visibility and order of the columns as described in the section General Usage . Columns listed as editable can be read-only for certain entries depending on the type of the entry or other conditions.

File Format and Content Type

Several file formats are supported when adding entries. In order to properly handle the ROM specific bank switching scheme, every entry must know its content type. For those file formats where the content type cannot be determined automatically, for example because there are multiple possible options, you have to select it in the "Content Type" column. The value help in the "Content Type" column is automatically filtered based on the file length and content. So it only offers the potentially matching content types. In additional some file formats even automatically converted before they are added to the workbook. Saving the workbook is possible at any time, even if there are entries with unknown content type. Only when the workbook is exported, the content type for all entries must be present. Here is a description of the supported file formats and their handling.

File Format	Description
CAR Cartridge Image	This is the recommended format to add ROM files. It is also by emulators. It contains a header with the exact type of the ROM file and a check sum to verify its integrity. This enables emulators to run the file without prompting the user for the exact content type upon each start. Similarly it enables "The!Cart Studio" to automatically determine the content type, so you don't have to choose something and the content type is not editable in this case.
BIN Cartridge Image ROM Cartridge Image	This is the regular dump format for ROM file. It does no contain any information on the type of module was dumped from and the require bank switching to run it. Based on the size of the file, the "Content Type" column is restricted to those values that represent ROM of with the exact size of the file. For example a file with exactly 1 MB of data could be "Atarimax 1MB", "Mega Cart 1MB", "XEGS 1MB" or "Switchable XEGS 1MB". If you want to use your ROM files also in an emulator, it is advisable to convert the plain ROM file into a .CAR" files. All popular emulators have this function built in. This way you don't have to choose the correct module type on every start.
ATR Programming Images	Collections created with the "Maxflash Cartridge Studio" are sometimes available as "ATR Programming Images" instead of "BIN" or "ROM" cartridge images. They are bootable disk images which contain the program to flash the "Maxflash" cartridge directly from the Atari. They cannot be run or tested in an emulator. These programming images are recognized by "The!Cart Studio". When you add such a file as entry, it is first converted into a "CAR" cartridge image which is saved in the folder of the programming image. In case the ".car" file already exists in that folder, it will be overwritten. The new ".car" file is added to the workbook. This way you can even run and test the content of the "CAR" image in an emulator before flashing.
ATR Disk Images	This is the standard Atari disk image format used in emulators. Many disk based programs that are available in this format can also be started from flash cartridges. But there are some natural limitations arising from the fact that loading the ATR images requires a simulation of the SIO routines that are located in ROM of the original Atari OS. For example the code for the simulation must be located in the RAM and may be overwritten when the loading from the ATR image starts. In addition the banks of the flash cartridge have to be activated during the SIO operation to load the data of the ATR image. As a consequence a program that uses a display list, graphics or interrupts in the module memory area will run into problems. Also programs that try to write data to the disk will fail when run from an ATR simulation. For the simulation itself two approaches are used, Modified ATR Images and Modified Atari OS in RAM . It depends on the individual ATR file and its programs which of them will work best. Modified ATR Images This is the approach used by the The!Cart Extended Menu. When you add an ATR file directly to a workbook, the file is analyzed and all potential code locations that call the Atari OS SIO routines are identified. For disks that contain a known DOS (DOS 2.0S, DOS 2.5, MyDOS) and its "DOS.SYS" file, only the sectors that belong to that file are patched by default. For disks that contain the Bootmanager by Mike Langer, only the sectors or the Bootmanager are patched. For all other disks, the complete disk is scanned for usages of the SIO and that may potentially result in some false positives you have to removed manually from the parameters. The result of this analysis is stored in the "Parameters" column in the form "base=$100, $123=SIOV, $456=DSKINV". This column is hidden by default and can be made visible via the context menu of the table. When the workbook is exported for to the Atari, the calls at the found offsets are modified to point to the SIO simulation which as located at the address specified with the "base=$...." parameter. The advantage of this approach is that it works also for software that uses the RAM under the OS like for example "Turbo Basic XL 1.5" or "The Brundles". And by specifying the corresponding parameters it will work even for software that uses nonstandard SIO routines instead of the Atari OS SIO routines like for example "MyPicoDOS". The disadvantage of this approach is that it will not work with program where the code that calls the SIO vectors is packed or encrypted in the ATR. The following parameters are supported. Numbers are given in hexadecimal notation and are just example values. In the appendix Compatibility Patches you can find a list of known parameter combinations for programs that don't work with the default parameters. base=$100 This specified the base address for the SIO simulation code which is less than 256 bytes in size. The default base address is $400. If the ATR crashes while loading, it might be the case that the program overwrites this memory area. For example MyPicoDOS uses the memory location $400-$40f during loading. To solve this problem you can change the base address to $410 for example. Other good choices for base addresses are $100, $400, $480,$500,$600 and $100. Just try which one works for the specific program. $123=SIOV The two bytes starting at offset $123 are changed to the start address of emulation code for the SIOV vector ($e459). $123=<SIOV The byte at offset $123 is changed to the low byte of start address of emulation code for the SIOV vector ($e459). $123=>SIOV The byte at offset $123 is changed to the high byte of start address of emulation code for the SIOV vector ($e459). $123=DSKINV The two bytes starting at offset $123 are changed to the start address of emulation code for the DSKINV vector ($e453). $123=<DSKINV The byte at offset $123 is changed to the low byte of start address of emulation code for the DSKINV vector ($e453). $123=>DSKINV The byte at offset $123 is changed to the high byte of start address of emulation code for the DSKINV vector ($e453). $123=SELECTEDITEMNUMBER The two bytes at offset $123 is changed to memory location which contains the item number of the selected menu entry. This can be used to modify inner menus to skip the selection and start the selected entry automatically. The item numbers are counted starting at zero. For example if you select the a menu entry which represents the 3rd item on a disk based ATR, the values in the memory location will be "2". If you messed up the parameters somehow, you can simply add the ATR file again to the workbook and choose to overwrite the existing file in the workbook. In this case, the analysis is performed again and a default for the parameters is generated. The SIO simulation in this approach supports both the read ("R", $52) and the status ("S", $53) command for "D1:". The status command set the 3 density bits of the "DVSTAT" status based on the density and size of the ATR. Using other disk units than "D1:" results in the error code "130 - Nonexistent Device". Using commands than "R" and "S" results in the error code "132 - Unknown command". Modified Atari OS in RAM This is the approach used by the Atarimax Maxflash Menu or MegaCart Menu. The operating system is copied to the RAM under the OS ROM and is then modified to load the "disk sectors" from the flash cartridge instead of the real disk. The advantage of this approach is that it works equally for all software that uses the standard Atari OS SIO vectors, even if the SIO relevant code on the ATR is packed on encrypted. The disadvantage is that the approach will not work with programs that use the RAM under the OS themselves. You can use the Maxflash Cartridge Studio to create 128 KB or 1 MB collections with ATR disk images. This program comes with proven emulation and provides several options to specify how the disk image shall be handled. You can then export the collection as BIN or CAR cartridge image and add it to the workbook.
COM Executable EXE Executable XEX Executable	This is the Atari DOS composite file format of executable files that can be loaded from a DOS. Many disk based programs that are available in this format can also be started from flash cartridges. To achieve this, typically a minimal DOS is copied to the RAM. The DOS is modified to load the "file segment" from the flash cartridge instead of the real disk. Of course this emulation has its limitations, for example for programs that use the RAM where the DOS or loader is located or perform real DOS operations like reading the directory or writing to disk. Currently cannot add these files directly to a workbook. Instead you can use the Maxflash Cartridge Studio to create 128 KB or 1 MB collections with COM or EXE executables. This program comes with proven emulation and provides several options to specify how the executable shall be handled. You can then export the collection as BIN or CAR cartridge image and add it to the workbook.

Cartridge Database

The title and content type of many popular ROMs is also stored in the cartridge database. If you ROM is found in the database, the title and if known the content type are proposed. If no matching entry is found, the content type is set to "Unknown" and you have to select the appropriate content type manually before exporting the cartridge in and form.

The cartridge database is based on the list maintained by Tomasz Krasuski (Kr0tki) at AtariAge . It currently contains over 700 known titles and almost 700 known content types. The exact number are shown on the about dialog. You can support "The!Cart Studio" and improve the quality of the cartridge database by sending your own workbook file without (!) the ROMs to .

Display Mode

Via the column "Display Mode" you can select how the entry is represented in the extended menu. Possible values are:

• Single Entry
  The entry is represented as single entry in the extended menu. The entry title in the workbook is used as entry title in the extended menu.
• Multiple Entries
  This value can only be selected if the file behind the entry contains an own inner menu that is supported by The!Cart Studio. The inner menu entries are extracted from the file during the export of the workbook. Only the titles of the inner menu entry, but not the title of the workbook entry, will appear in the extended menu.

The following types and versions of inner menus are currently supported. For all of them, you can add the inner menu entries to the extended menu by choosing "Multiple Entries". When you add an entry to the workbook, the "Display Mode" will be set to "Multiple Entries" automatically by default. You can of course change the values if you don't want the inner menu entries to show up separately. By default you will start the inner menu when you select one of its entries in the extended menu. For some inner menus dedicated support has be implemented so selecting the inner menu entry even starts it directly.

Previewing Workbooks

The menu entry "Tools/Preview" allows for a testing preview of the complete cartridge export and its menu in an emulator. For the preview, the workbook is exported as ".car" file with a fixed name into the temporary folder of the user. A previously existing preview is overwritten automatically. If no path to an emulator executable is configured in the options, "The!Cart Studio" tries to open the ."car" file with the associated default program of the operating system. If that fails, it will ask you to maintain the full path to the emulator, for example to "Altirra.exe" or "atari800.exe", in the options.

Exporting Workbooks

Export Formats

The export always also generates a ".txt" index file with the title and origin of all menu entries. This way you can use the file system search of your operating system function to find games in exports. The index file also contains the information the for example "Amaurote 128 (130 XE)" is one of the menu entry that steems from the "Multiple Entries" setting for the workbook entry with the title "GAMES403" stored in "GAMES403.ATR"."

Printing Workbooks

You can print the content of the workbook including the list of entries via the menu entry "File/Print" (CTRL-P). The columns in the print output are the visible columns on the entries tab. Hence you can configure the columns you want to see as described in the section General Usage . For example you can make the column with the start bank visible, so you can use the simple menu to start entries and see the banks which are assigned to user space entries.

Programming Flash Cartridges

For the time being, please refer to the documentation you received with your flash cartridge.

Extended Menu

Advanced Topics

A number of advanced features of "The!Cart Studio" that are not so interesting for the regular user are also available.

• Displaying additional columns in the entries tab
  By default only the most frequently used columns are visible on the entries tab. Using the context menu on the header row of table , you can make more columns information about the entry visible.
• Using fixed start banks
  By default entries are assigned automatically to a suitable start bank and the user cannot change this assignment. For developers who want to create software that uses "The!Cart" directly, for example in "Flexi-Mode" to directly access the 128 MB, it may be required to put certain content in certain banks. To do this, use the context menu to make the column "Start Bank Fixed" visible". This column offers a check box and if the check box is active for an entry, the column "Start Bank" becomes editable for this entry and the entry is excluded from automatic bank assignment.
• Defining User Space
  By default all banks of the flash cartridge are under control of "The!Cart Studio". But if you want, you can reserve a portion of the flash cartridge for direct flashing from the Atari. This portion of the flash cartridge is called "User Space". You can define the size of the user space in the workbook options. You can enter the size in bytes, kilo bytes or mega bytes, e.g. "1023 B", "8 KB" or "2 MB". The effective size of the user space rounded to the next full bank, depending on the bank size. In addition the size of user space automatically rounded to a multiple of the flash block size, i.e. to 64 KB for the flash target types "Atarimax 128 KB/ 1 MB" and "Flash MegaCart 4 MB" and to 128 KB for "The!Cart 128 MB". The use space is always located in the last banks of the flash cartridge. This way the ATR programming images are shorter and the flash software does not overwrite the banks that belong to the user space.
  Though the content of the user space is fully under control of the Atari you can still define entries with "The!Cart Studio" to start the content in the user space from the cartridge menu. Via the menu entry "Edit/Add User Space Entry" a new user space entry is added to the list. This type of entries does not have an associated file in the project. Instead it is mandatory to specify the content type and the start bank manually. Therefore these two columns become visible if a user space entry is added.
• Using a special version of the "The!Cart" Atari flashing software and standard menu
  By default "The!Cart Studio" uses the Atari flashing software and standard menu that is included in the ".jar" file. In case you want to use a more recent or modified version of the "The!Cart" Atari flashing software and standard menu instead of the version which is currently included in "The!Cart Studio", you can put the "cartmenu.rom" file in the same folder as the "TheCartStudio.jar". Whether the built-in or the external software is used and which version it has is displayed in the "About" dialog.

Appendix

Related Links

• Atari flashing software on HiassofT's Atari 8bit world by Matthias Reichl .

Compatibility Patches

This is a list of patches for programs that don't work out of the box with newer or non-standard Operating Systems or with the ATR loader of The!Cart. For them you can adapt the default parameters determined by The!Cart Studio. Just enter the solution listed in the "Parameters" column of the respective workbook entry the to patch the files during the export. Since the offsets specified here are specific for a given disk image, they may not work on other disk images.

Change History

2014-09-25

2014-09-24

2014-09-22

2014-09-16

2014-09-11

2014-08-04

2014-07-18

2014-07-12

2014-07-02

2014-04-03

2014-03-18

2014-03-02

2014-02-27

2014-02-22

2014-02-16

2014-02-13

2014-01-23

2014-01-17

2014-01-15

2014-01-14

2013-12-28

2013-12-26

2013-12-18

2013-12-13

2013-12-12

2013-12-11

2013-12-06

2013-12-05

2013-12-04

2013-12-02

2013-12-01

2013-11-26

2013-11-25

2013-11-04