
Overview:

XM6 Pro-68k emulates an X68000 computer.

It is a fork of PI's XM6 version 2.06 with a plethora of new features,
most of which are documented in the change log and reference manual.



Requirements:

 x86-compatible CPU with MMX(*) (Athlon, Celeron, Duron, Pentium II, etc.)
 Windows 2000 or later (certain versions of Wine also work)
 XM6 Pro-68k DLL Package (see below)

(*) If you don't know, just assume your CPU qualifies; not even SSE2 is needed.

The "XM6 Pro-68k DLL Package" is taken care of during an automatic installation.
It is a collection of DLLs and other files that are updated less frequently than
the program itself. It must be present and up-to-date for full functionality.

Note that you DO NOT need IPLROM.DAT and it should not be present unless you
have a compelling reason; otherwise it slows down XM6 on startup for no benefit.



Recommended Environment:

- Two or more physical processors/cores (Hypo-Threading does NOT count)

- A wired keyboard with a number pad and "real" function keys (F1 - F12)
- A mouse (as opposed to a trackpad or touch-screen) with a middle button
- One or more general-purpose game controllers (gamepad, joystick, etc.)



Automatic Installation:

The file "XM6 Pro-68k.zip" on the website now solely contains
scripts that will download all the program's components and
extract everything into the correct locations. (It is, in fact,
basically the same as the Web Package, which is described later.)

Simply run the "Download XM6 Pro-68k.bat" batch file while
connected to the Internet. The scripts have plenty of error
checking and have been heavily tested. Furthermore, they check
the cryptographically secure signatures for each package.

Note that this "installation" does not register anything with
your operating system; you are free to move the directory to
any location you like - it is fully portable.



Manual Installation:

(This is NOT recommended! The automatic installation method does
all of this for you while providing error checking. I estimate
that half of the support requests I get via email are from people
who failed to perform a manual installation correctly!)

Extract the files from "XM6 Pro-68k.7z" into a suitable directory.
Extract the files from "XM6 Pro-68k DLL Package.7z" into the same
directory. The files must be in the exact same location as the
main executable, not within a subdirectory.

Next try running the main executable (XM6.exe). If _any_ dialogs
or error messages appear, you probably didn't put the files from
the two packages together correctly. (Apparently it's harder than
one might assume.)

Also on the website is an optional "Web Package" which enables
a few useful features that utilize the Internet (but only when
explicitly requested to do so by the user). Extract the package
into the same directory as the main executable. Note that if you
want this feature then you might as well just do an automatic
installation because it utilizes the exact same files. (The only
difference is the Web Package contains installation instructions.)



Optional Installation Tasks:

The program itself has the ability to perform minor installation tasks
through the Tools menu. The Install submenu has a list of locations
where a shortcut to XM6 can be installed, and the Uninstall submenu
will revert any or all of the installed shortcuts to XM6. Please note
that certain shortcuts may not show up in your environment.

The "send-to menu" shortcut is quite handy: simply select one or more
disk images, or a state file, in Explorer. Next open the context menu,
select "Send To", and then type 'X' or click the XM6 Pro-68k shortcut.
(Note that "disk images" includes hard disk images and some archives.)

The optional desktop shortcut comes with a hotkey: Ctrl-Alt-X.
You can press that key combination to launch XM6 as long as the
installed shortcut remains on your desktop.

If you relocate the XM6 program, any shortcuts you previously installed
will then be broken, so they should be reinstalled (or uninstalled)
using the relevant menu items.



Uninstallation:

First run the program and select Tools > Uninstall > All Shortcuts
from the menu to delete any shortcuts. (This step is not necessary
if you never used the menu to install shortcuts in the first place.)

Finally, simply delete the program and associated files.



Updating:

Recently, this program has usually only been updated on a monthly basis,
but you can check for updates on a weekly or even daily basis if you wish.

Start the program and select "Check for Updates..." under the Help menu,
then follow the instructions. That is all you need to do - the process is
detailed below for those who would like more information.

If the menu item is disabled, you most likely performed a manual installation
and did not install the Web Package, or failed to install it properly.

Before anything happens, the server URL will be displayed, and you will be
given an opportunity to abort if you do not wish to access the Internet at
the time. You can abort by closing the window or typing Ctrl-C followed by
the letter 'Y' and then Return or Enter.

If an update is available, you will be asked if you wish to install it.
Before downloading and installing an update, the previous version of the
main executable will be backed up. During the update process, the DLL Package
might also be updated.

After installation, the program will be restarted, and any special one-time
processing to handle differences between versions will run automatically.

As a side note, after you consent to checking for updates, but prior
to checking for updates to the program itself, if any updates to the
"infrastructure" were detected, they will be processed first, then the
update process will be restarted. Any such updates will be very rare.

Please note that _all_ updates retrieved by this package are signed using
public key encryption and will be rejected if they have been tampered with.
This makes it highly unlikely that this software could be misused as a vector
for delivering malware. (E.g. from a server hack or man-in-the-middle attack.)

Due to the above, this method of retrieving updates is more secure than
downloading them directly from the website. If you still insist on manual
updates, make sure you download and install the DLL package every time.
Also be aware that you won't get any special inter-version processing
(mentioned earlier) if you do it this way, which could cause minor issues.



7-Zip Support:

If 7Z.DLL is available (which it should be in a normal installation),
it will be used to load certain types of files from .7z or .zip archives.

7-Zip archives (with the .7z extension) are similar to .zip files but
backed by better technology. By default, they are solid, which improves
compression for multiple files but takes longer to extract. In the worst
case, it can take several seconds to load floppy disk images from 7-Zip
archives. In order to reduce load times, files extracted from archives
are cached, so that they do not have to be unpacked the next time they
are called for.

The cache manager will only keep a limited number of archives in memory,
and will become more aggressive about removing cache items if heuristics
suggest that the system is under memory pressure. The worst case combined
memory usage for cached archives composed exclusively of floppy images
is around 200 MB.

Compressed state files can also be loaded if 7Z.DLL is available. XM6 does
not normally compress state files itself; the intent is for the user to
use the 7-Zip program to compress all their state files associated with
a particular game into a single, solid .7z archive. The resulting file
will usually be smaller than a single uncompressed state file, even if
hundreds of state files are packed into the same archive. XM6 recognizes
the .XM6s ('s' for plural) file name extension if you wish to differentiate
such archives from normal archives, but this is not obligatory. Note that
if XM6 discovers state files in an archive loaded via the floppy interface,
it will, so to speak, reroute the archive to the state loading mechanism.

If an archive contains more than one state file (or a mix of files),
XM6 will load the contents into the Menu-Based File System Browser
(see the manual). Opening the File > Nearby States menu is one way
to select state files from the archive. Control-Backspace (with or
without Shift) also works.

Be aware that archives which don't meet the original constraints for
compressed floppy disk images (namely containing 16 or fewer images
and no other XM6-compatible files, such as state files) are handled
differently. Although some caching is employed, it is not as extensive.
And because there are no practical limits to the size of the archive,
a dialog will appear if decompression is taking longer than a few
seconds, affording the opportunity to cancel the extraction process.
The menu interface is also different, as noted above.

Also be aware that files from huge, solid, 7-Zip archives may fail
to load if the dictionary size used for compression was too large.
Such archives are typically impractical anyway, often taking minutes
to extract a single file.

XM6 can also read and write state files in XZ format, which uses the
same LZMA compression algorithm as 7-Zip archives but applied only
to a single file. Therefore, you do not get the extreme compression
ratios achievable when state files made from the same game are grouped
together. Because of this, XZ-compressed state files can only be made
manually using the Save As command. It is intended for situations where
you only make one or two state files for a particular game.

The compression parameters passed to 7Z.DLL have been tuned for state files,
so you will most likely not be able to achieve significantly better results
on your own. In the worst case, state file compression can take many seconds,
but the VM thread continues to run and respond to input at the same time so
the impacts should be minor, except possibly on slower, single-core systems.



The Non-Unicode Edition:

Within the MBCS subdirectory is a second version of the executable.
This is the non-Unicode version of the program, which is also known
as the "ANSI" or MBCS edition. It is not recommended for most users,
lacking the updated graphics and flexibility of the Unicode edition.
It is, however, a bit less CPU intensive when running certain games.
It requires all the same files as the main version in order to run.
(I.e. you need to duplicate the DLL package in the MBCS directory.)
Its state files are backward compatible with the original XM6.

It may be useful for troubleshooting problems with the main version
because certain features are sometimes excluded from the MBCS edition.
It does, however, have its own set of problems, particularly on systems
that use multi-byte encoding schemes: certain sequences in file names
may be misinterpreted as path components.

Note that the MBCS version cannot be installed, because it is intended
to be used sparingly. One can create shortcuts manually, if so desired.

You can consult the manual for more information about the MBCS edition.



Basic Troubleshooting:

- You get a message saying the application configuration is incorrect.

The Visual C++ 2008 Redistributable Package needs to be installed.
You can get a recent version of it on my website, along with an
alternative package of DLLs that can be used without being installed.

Or you could simply perform an automatic installation.


- The program silently fails to start (or consistently crashes immediately)

Please report the problem via email along with your system specs.
It is likely some sort of compatibility issue. This sort of thing
may be fixable but not if you don't report it!


- You see garbage where you are expecting glyphs.

CGROM.DAT is missing or corrupt. This file isn't technically required,
depending on the software you're trying to run, but is highly recommended.
You can get a copy on my website.

Or you could simply perform an automatic installation.

If you are unsure whether this file is properly installed, and are not
seeing the warning message on startup, open the software keyboard (Alt-K).
If the virtual keys all look the same then CGROM.DAT is not being loaded.


- On startup, you get a warning message about the CG-ROM.

See previous answer.

You may be given the option to generate a replacement CG-ROM file called
CGROM.TMP which doesn't look authentic but should suffice. It is created
using fonts installed on your machine so the process can fail if you lack
the necessary files. Likewise, you should not assume that all CGROM.TMP
files are the same; different systems may produce different files.

If you want to see how it looks, move CGROM.DAT out of the XM6 directory
before starting XM6 to trigger the dialog. (Note that the dialog won't
appear if the CG-ROM check is disabled in the Advanced configuration.)


- You are having other problems.

See the reference manual for additional troubleshooting tips, most of which
are related to emulation problems rather than issues with XM6 itself.

As a last resort, run the "Reinstall XM6 Pro-68k.bat" batch file included
with the program and follow the instructions. If that batch file doesn't
even exist then go to the website and do a proper automatic installation!



Acknowledgments:

The author would like to thank Artemio Urbina for his invaluable
contributions to improving emulation accuracy through research.

Big thanks to Matthew Callis for years of hosting on eludevisibility.org

PNG support is available due to the generosity of the authors
of the PNG Reference Library and 'zlib'.

See also Help > About concerning other code linked into XM6.exe

The 7-Zip header files were written by Igor Pavlov.



Technical Support:

Support requests must come via email. DO NOT include links in your emails!
The email address can be found on the website. All relevant initial emails
will be replied to eventually, so if you did not get a response to your
initial inquiry, you are welcome to try again.



Website:

The following website is the only official place to get this program:

https://mijet.eludevisibility.org/

https://mijet.eludevisibility.org/XM6 Pro-68k/XM6 Pro-68k.html

Do not rehost this program! Link to either of the above URLs instead.

Running programs obtained through unofficial channels is a security risk.
If you did not receive this program from the site shown above, please take
a few extra minutes and go get the latest version from the official site.

For extra security, type "XM6 Pro-68k" into an Internet search engine
and make sure the top result matches the Web address in this document.
