XFME Desktop - starting games from the command line
=====================================================

XFME Desktop reads its command line the way MFME 20.1 does, so desktop shortcuts, batch files and game
selectors (front ends) written for MFME work with XFME by changing only the program's name and folder.

  XFME.exe "<path to the game's .gam file>" [options]


1. The game
-----------
* The first argument that names an EXISTING file is the game. Arguments that name nothing are skipped (MFME does the
  same); later file names are ignored.
* A full path ("C:\Fruit Machines\Andy Capp\Andy Capp DX.gam") or a path relative to the folder the program was started
  from (".\Andy Capp\Andy Capp DX.gam", "..\Games\Andy Capp DX.gam") both work. '\' and '/' are the same.
* Put the path in double quotes when it has spaces.
* Any name works: spaces, punctuation, "£", accented letters and characters from any language (Greek, Cyrillic,
  Japanese ...), local drives and network paths (\\server\share\...).
* The extension decides what is opened (any case):
    .gam   the game, started as when it is chosen in the Game Manager or the library
    .fml   the layout only, with no machine running (MFME's Load Layout)
    other  nothing is opened (MFME opens nothing either; XFME also says why)


2. Options (as MFME 20.1; upper or lower case; each value is the next argument)
-------------------------------------------------------------------------------
  -x <n> -y <n>      where the XFME Desktop window goes (both, each given once)
  -w <n> -h <n>      its size (both, each given once; used only with -x/-y, as in MFME)
  -mode <n>          how the game is shown, as MFME's window modes: 0 the XFME Desktop window, 1 the XFME Desktop
                     window maximised, 2 the machine alone without a frame (borderless), 3 full screen with the
                     machine at its own place (backdrop around it), 4 full screen with the machine fitted to the
                     screen (other values are ignored)
  -nohistory         the game is not added to File > recent games
  -slave             for linked machines only: the window stays on top (see 4 below)
  -i <name>          used by a top box to start its linked machines (see 4 below)
  -g <path>          the game path given explicitly (see 5)

  -x/-y, -w/-h and -mode place XFME Desktop, as they placed MFME's window in MFME:
  * -x/-y put the XFME Desktop window's top-left corner there; -w/-h give its size (XFME Desktop never gets smaller
    than its own minimum size). Without -w/-h it keeps its own size, made smaller where it would run off the screen.
  * In modes 2 and 3 the same place and size are the machine's own (without -w/-h: the layout's own size, smaller
    when it does not fit the screen), and Esc brings the XFME Desktop window back where -x/-y put it. Modes 1, 3 and
    4 use the screen that -x/-y are on.
  * -mode without -x/-y: the game is shown in that mode from XFME Desktop's own place.
  * A top box whose set runs in one process (4 below): -x/-y and -w/-h place only the XFME Desktop window (where Esc
    brings it back), and -mode is not applied to the set - the set opens in the mode its top box's .gam gives (else
    the Preferences' Load Mode), where the .gam's Position and Instance lines put its machines.
  -slave and -i are the options a top box gives the machines it starts as separate processes. With either of them,
  typed by hand too, the game opens in XFME Desktop placed as -x/-y, -w/-h and -mode say (-slave keeps the window on
  top). With -i naming no running top box the program closes once the game is loaded.

XFME's own switches (MFME ignores them):
  --RIPWizard        Design > Misc Tools also shows its hidden tools
  -Classic           ignored (earlier XFME test builds opened MFME's own window with it)


3. Examples
-----------
Command Prompt:
    "C:\XFME\XFME.exe" "D:\MFME Games\Andy Capp\Andy Capp DX.gam"
    cd /d "D:\MFME Games"
    "C:\XFME\XFME.exe" "Andy Capp\Andy Capp DX.gam" -nohistory

Desktop shortcut (right-click > New > Shortcut, then Properties):
    Target:   "C:\XFME\XFME.exe" "D:\MFME Games\Andy Capp\Andy Capp DX.gam"
    Start in: any folder (the game path above is a full path)

Batch file (save as e.g. andycapp.bat; the chcp line lets the file hold any character):
    @echo off
    chcp 65001 >nul
    start "" "C:\XFME\XFME.exe" "D:\MFME Games\Andy Capp\Andy Capp DX.gam"

Game selector / front end (the emulator entry):
    Program:    C:\XFME\XFME.exe
    Arguments:  "%ROMPATH%\%GAME%.gam"            (use your front end's own placeholders)
    Full screen: add  -mode 4
    The front end waits for XFME.exe to exit; closing the window (or File > Exit) ends it.


4. Linked machines
------------------
A top box whose .gam has "Instance" lines starts each linked machine itself; start only the top box's .gam yourself,
as any other game. The whole set runs in the one XFME process when every machine's system can run that way (always:
the earlier Extras > Linked Sets in One Process choice is gone), and XFME Desktop shows the set together: the top box
and its machines where the .gam's Position and Instance lines put them; -x/-y, -w/-h and -mode given to that top box do
not move or change the set (2 above). A set with a machine whose system cannot run that way yet runs each machine as
an XFME process of its own (as in MFME), started with -X -Y -W -H -Mode -I -NoHistory -Slave, each in an XFME Desktop
window where its Instance line puts it.


5. Differences from MFME 20.1 (deliberate)
------------------------------------------
* A path that names no file, an option that is not MFME's, or an option without a usable number: MFME opens an empty
  window and says nothing. XFME also opens no game, and shows a message saying what was wrong; the same is written to
  the error log (%LOCALAPPDATA%\XFME Desktop\logs\xfme_errors.log), so a front end user who sees nothing can look
  there. Nothing else is ever started in its place.
* -g: in MFME 20.1 this option only works when a file called "-g" exists in the current folder (a fault in MFME).
  XFME takes the next argument as the game.
* -i: MFME passes a window handle, XFME a link name; only top boxes use it.
* -x/-y, -w/-h and -mode place the XFME Desktop window and choose how it shows the game (2 above); in MFME they
  placed MFME's own window.
* A missing ROM: XFME starts the game and lists the missing files (where it looked, and what to do). It never
  downloads anything.
* With any argument on the command line, XFME (as MFME) does not open the Game Manager at start-up.
