XFME Desktop for Windows - release 1.2
======================================

XFME is a cross-platform continuation of Chris Wren's MFME fruit-machine emulator (MFME (C) 1997-2020 C.J.Wren).
XFME Desktop is the Windows / macOS / Linux edition; this is the Windows release. Website: https://www.xfme.co.uk

The exact build is in VERSION.txt and in Help > About (select the text there to copy it into a bug report).


Requirements
------------
* Windows 10 (version 1903 or later) or Windows 11, 64-bit.
* Nothing else: the Qt libraries and the Visual C++ runtime XFME needs are in this folder. No Visual Studio, Qt or
  MFME installation is needed, and nothing is installed into Windows.
* Your own MFME games (.gam + ROMs + layouts). No ROMs or layouts come with XFME.


Installing
----------
1. Unzip the whole folder somewhere you can write to, for example  C:\XFME\  or  Documents\XFME\.
   (Not inside "Program Files": XFME does not need it, and it keeps that folder clean of anything else.)
2. Start XFME.exe. The first time, the games library says what to do: ADD YOUR GAMES FOLDER... (see "Getting
   started" below).
3. For the cabinet sound effects (coin drop, reels, buttons, meters, payout): they are MFME's own sounds and do not
   come with XFME; without them the effects are silent even with their boxes ticked. If you have MFME 20.1, either
   let XFME copy them - Library menu (the three dots above the games list) > "Cabinet sound effects: find my MFME
   folder..." - or copy the "DefaultSounds" folder from your MFME folder into this folder, beside XFME.exe, yourself.
   (More under "Sound" below.)

Windows SmartScreen may say "Windows protected your PC" the first time, because XFME is not signed with a
code-signing certificate. Choose "More info" > "Run anyway" only if you downloaded the ZIP from www.xfme.co.uk and its
SHA-256 checksum matches the one published there (PowerShell: Get-FileHash .\<name>.zip -Algorithm SHA256). Do not
turn off any Windows security feature to run XFME.

Updating: Library menu (the three dots above the games list) > "Check for updates..." asks xfme.co.uk for the latest
version and shows what is new in it. "Update now" downloads it, checks it against XFME's own signature, replaces the
program's files and starts the new version; the version you had is kept in a folder beside the program
(previous-<version>). Nothing is ever installed unless you press Update now. By hand instead: unzip the new version
into a NEW folder (or replace the old folder's contents). Either way your settings, library and error log are not kept
in the program folder, so nothing is lost.

Removing: delete the folder. Optionally also delete  %LOCALAPPDATA%\XFME Desktop  (the library, logs) and the
registry key  HKEY_CURRENT_USER\Software\MFME\Reloaded  (XFME's settings).


IMPORTANT - use a COPY of your games
------------------------------------
Like MFME, XFME writes into a game's folder while you play it: the battery RAM (.ram and the board's other NV files),
XFME's quick-start snapshot (<game>.gam.xsnap) and, when the game closes, its statistics and reel positions in the .gam.
Point XFME at a COPY of your MFME collection, not the only copy, and keep a backup.
XFME never deletes your games, ROMs, layouts or pictures, and never downloads a game, ROM or layout. It uses the
internet only when you ask it to: "Send to XFME" in Report a problem, and "Check for updates..." (which you can also
tick to run when XFME starts; it is not ticked unless you tick it).


Where XFME keeps its own files
------------------------------
  %LOCALAPPDATA%\XFME Desktop\library\       the games library (names, ratings, pictures it made)
  %LOCALAPPDATA%\XFME Desktop\logs\          xfme_errors.log - only problems (games that would not load, missing
                                            files, files that could not be saved)
  %LOCALAPPDATA%\XFME Desktop\GameManager\   XFME's own Game Manager lists (one per main game folder)
  %LOCALAPPDATA%\XFME Desktop\DefaultSounds\ MFME's cabinet sounds, only when XFME copied them for you and could not
                                            write the program folder (otherwise they are beside XFME.exe)
  HKEY_CURRENT_USER\Software\MFME\Reloaded   XFME's settings


XFME and MFME 20.1 on the same PC
---------------------------------
XFME keeps everything of its own and shares nothing with an MFME installation:
* It does not read or change MFME 20.1's settings (HKEY_CURRENT_USER\Software\CJW\MFME): its options, recent games and
  Game Manager folders start empty in XFME.
* It never writes MFME's Game Manager list (gamesV20.0.db). XFME's Game Manager keeps its own list for each main game
  folder in %LOCALAPPDATA%\XFME Desktop\GameManager, even when the folder is one MFME also uses.
* If you want them, copy MFME's into XFME - MFME's own files and settings are only read, never changed:
    Library menu (the three dots above the games list) > Import MFME 20.1 settings...
        copies MFME's options, recent games and Game Manager folders where XFME has none of its own
        (then start XFME again)
    Library menu > Import a Game Manager list (MFME's gamesV20.0.db)...
        copies the games listed in the main game folder's gamesV20.0.db into XFME's own list
  When XFME first opens a main game folder that has such a list, it says so once and leaves it alone.
* Like MFME, XFME still writes into a GAME's own folder while you play it (see "use a COPY of your games" above).


Getting started
---------------
* First start: the games library on the left is empty and says so. Press ADD YOUR GAMES FOLDER..., choose the
  folder your games are in (a COPY of your collection), and XFME looks through it and lists every game it finds. If
  it finds none it says why (for example: no .gam file in that folder). The same commands are in the library menu
  (the three dots above the list): Main game folder..., Scan the game folders, Additional game folders...
* Pick a game and press PLAY (or double-click it).
* Games marked work in progress (WIP) and games that cannot run (a missing ROM, for example) are not listed at first.
  A line under the list counts them - "3 games hidden: 2 work in progress - show, 1 not running - show" - and a click
  on "show" lists them (the library menu's two ticks; XFME remembers them).
* File > Load Game opens a single .gam, as in MFME.
* Command line, shortcuts, batch files and game selectors: see COMMAND_LINE.txt.
* Coins: the COIN IN button, or the layout's own coin buttons / keys (as MFME). Service door, refill key, test and
  Clear RAM are under MACHINE CONTROLS and Configuration, as in MFME.
* Quick start: the first start of a game boots it like a real machine (this can take a while for some systems, shown at
  high speed). When you close the game XFME saves a snapshot, and the next start is almost instant. Configuration >
  Clear RAM resets the machine's RAM as MFME does.
* Full screen (F3, F2): XFME paints black around the machine. MFME fills that space with the layout's own border
  colour (white or silver on some layouts); for that, untick Extras > "Black around the machine in full screen".
* Something wrong? Library menu > "Report a problem..." (also in Help > About) makes ONE small zip: XFME's version,
  your Windows version and screen, the game's file names with their sizes and checksums (no ROM, layout or RAM file is
  put in it), the error log and what you write; your Windows user name is taken out of the paths. "Send to XFME"
  sends it to xfme.co.uk and gives you a reference to quote; "Save the zip..." keeps it on your PC instead, to attach
  to a post or an e-mail yourself. Send to XFME and Check for updates are the only times XFME uses the internet,
  and only when you press them:
  the server sees your internet address, as any website does, the report holds no address, and it is read only by
  XFME's author - never published.
* XFME Desktop is the interface: -Classic (MFME's own window in earlier XFME test builds) is ignored, and a game
  selector's placement options (-x/-y, -w/-h, -mode) place XFME Desktop (COMMAND_LINE.txt). The machines a top box
  starts as separate processes, and a game started with -slave or -i typed by hand, open in XFME Desktop too, placed
  as their options say.


Sound
-----
The machines' own sound chips are emulated. MFME's extra "cabinet" effects (coin drop, reel and button sounds,
payout) come from MFME's DefaultSounds folder, which is not part of XFME and is never downloaded. If you have MFME
20.1 installed: Library menu > "Cabinet sound effects: find my MFME folder...", choose your MFME folder, and XFME
copies its sounds (your MFME folder is only read) - beside XFME.exe, or into %LOCALAPPDATA%\XFME Desktop when the
program folder cannot be written. Copying the "DefaultSounds" folder beside XFME.exe by hand works as before. While
XFME has no such folder, a line under the games list offers this; "dismiss" puts the line away. The sounds play from
the next game you start. MFME's own layout font (MFME.ttf, as
MFME v20 ships it) is included. The Lithograph fonts are not: a layout that uses them looks as it does on a PC without
them, unless the fonts are installed in Windows or are in the game's folder.


Files in this folder
--------------------
  XFME.exe                   the program
  *.dll, platforms\, styles\, imageformats\, iconengines\   Qt (LGPL v3) and the Microsoft Visual C++ runtime
  assets\fonts\              the Fairfax font (with its own licence) used for LCD displays, and MFME.ttf (MFME's
                             layout font; the copy in assets\fonts\dev is the one the layouts are drawn with)
  VERSION.txt                this build's version, build number and source commit
  COMMAND_LINE.txt           starting games from shortcuts, batch files and game selectors
  KNOWN_ISSUES.txt           what is known not to work yet
  TESTING_INSTRUCTIONS.txt   what to test and how to report it
  BUG_REPORT_TEMPLATE.txt    the report form
  THIRD_PARTY_NOTICES.txt    the software XFME includes and its licences
  LICENSES\                  Qt's notices for every Qt file in this folder (QT_NOTICES.txt) and the full licence
                             texts (LGPL-3.0, GPL-3.0 and the third-party licences named there)
