:orphan:

==========
rzxplay.py
==========

SYNOPSIS
========
``rzxplay.py`` [options] FILE [OUTFILE]

DESCRIPTION
===========
``rzxplay.py`` plays an RZX file. If 'OUTFILE' is given, an SZX or Z80 snapshot
or an RZX file is written after playback has completed.

OPTIONS
=======
-c, --cmio
  Simulate memory and I/O contention delays and the MEMPTR register.

--flags FLAGS
  Set playback flags. Do ``--flags help`` for more information, or see the
  section on ``FLAGS`` below.

--force
  Force playback when an unsupported machine is detected.

--fps FPS
  Run at this many frames per second (default: 50). 0 means run at maximum
  speed and update the screen 50 times per second. A negative value (-N) means
  run at maximum speed and update the screen N times per second.

-I, --ini `param=value`
  Set the value of a configuration parameter (see ``CONFIGURATION``),
  overriding any value found in ``skoolkit.ini``. This option may be used
  multiple times.

--map FILE
  Log addresses of executed instructions to a file.

--no-screen
  Run without a screen.

--python
  Use the pure Python Z80 simulator even if the C version is available.

--quiet
  Don't print progress percentage during playback.

--scale SCALE
  Scale the display up by this factor (default: 2).

--show-config
  Show configuration parameter values.

--snapshot FILE
  Specify an external snapshot file to start with.

--stop FRAMES
  Stop after playing this many frames.

--trace FILE
  Log executed instructions to a file.

-V, --version
  Show the SkoolKit version number and exit.

SUPPORTED MACHINES
==================
``rzxplay.py`` can play RZX files that were recorded in 48K, 128K or +2 mode
with no peripherals (e.g. Interface 1) attached. If any peripherals are
attached, playback may fail. The ``--force`` option can be used to make
``rzxplay.py`` attempt playback of a file that was recorded on an unsupported
machine, but it is unlikely to play to the end.

SCREEN
======
If pygame is installed, ``rzxplay.py`` will use it to render the Spectrum's
screen contents at 50 frames per second by default. Use the ``--fps`` option
to change the frame rate. Specifying ``--fps 0`` makes ``rzxplay.py`` run at
maximum speed. To disable the screen and make ``rzxplay.py`` run even faster,
use the ``--no-screen`` option.

CODE EXECUTION MAP
==================
The ``--map`` option can be used to log the addresses of instructions executed
during playback to a file. This file can then be used by ``sna2ctl.py`` to
produce a control file. If the file specified by the ``--map`` option already
exists, any addresses it contains will be merged with those of the instructions
executed.

FLAGS
=====
The ``--flags`` option sets flags that control the playback of RZX frames when
interrupts are enabled. If an RZX file fails to play to completion, setting one
or more of these flags may help. ``FLAGS`` is the sum of the following values,
chosen according to the desired outcome:

* 1 - When the last instruction in a frame is either 'LD A,I' or 'LD A,R',
  reset bit 2 of the flags register. This is the expected behaviour of a real
  Z80, but some RZX files fail when this flag is set.

* 2 - When the last instruction in a frame is 'EI', and the next frame is a
  short one (i.e. has a fetch count of 1 or 2), block the interrupt in the next
  frame. By default, and according to RZX convention, ``rzxplay.py`` accepts an
  interrupt at the start of every frame except the first, regardless of whether
  the instruction just executed would normally block it. However, some RZX
  files contain a short frame immediately after an 'EI' to indicate that the
  interrupt should in fact be blocked, and therefore require this flag to be
  set to play back correctly.

* 4 - Ignore any snapshots after the first one. By default, ``rzxplay.py`` will
  use a snapshot embedded in an RZX file to update its internal state (i.e.
  memory and registers) before continuing to process the next input recording
  block. However, some RZX files created by the Fuse emulator do not play
  correctly under that scheme, and require this flag to be set.

OUTPUT FILE
===========
If ``OUTFILE`` is given, and ends with either '.z80' or '.szx', then a snapshot
in the corresponding format is written when playback ends. Similarly, if
``OUTFILE`` ends with '.rzx', then an RZX file is written when playback ends.
However, this makes sense only if ``--stop`` is used to end playback somewhere
in the middle of the input RZX file, otherwise the output RZX file will be
empty (i.e. contain no frames).

CONFIGURATION
=============
``rzxplay.py`` will read configuration from a file named ``skoolkit.ini`` in
the current working directory or in ``~/.skoolkit``, if present. The recognised
configuration parameters are:

  :Screen: Display screen contents while running (``1``, the default), or don't
    (``0``).
  :ScreenFps: Screen refresh rate in frames per second (default: ``50``). If
    set to 0, run at maximum speed and update the screen 50 times per second.
    If set to a negative value (-N), run at maximum speed and update the screen
    N times per second.
  :ScreenScale: Screen scale factor (default: ``2``).
  :TraceHeader: The header to write in the trace log file (default: None).
  :TraceLine: The format of each line in the trace log file (default:
    ``F:{fr:0{fw}} C:{fc:05} I:{rr:05} ${pc:04X} {i}``).
  :TraceOperand: The prefix, byte format, and word format for the numeric
    operands of instructions in the trace log file, separated by commas
    (default: ``$,02X,04X``). The byte and word formats are standard Python
    format specifiers for numeric values, and default to empty strings if not
    supplied.

``TraceLine`` is a standard Python format string that recognises the following
replacement fields:

|
|  ``fc`` - opcode fetch counter
|  ``fr`` - frame number (0-indexed)
|  ``fw`` - maximum width required for the frame number field
|  ``i`` - the current instruction
|  ``m[address]`` - the contents of a memory address
|  ``pc`` - the address of the current instruction (program counter)
|  ``r[X]`` - the X register (see below)
|  ``rr`` - the number of input readings remaining in the frame
|  ``t`` - the current timestamp (in T-states)

When using the ``m`` (memory) replacement field, ``address`` must be either a
decimal number, or a hexadecimal number prefixed by '$' or '0x'.

The register name ``X`` in ``r[X]`` must be one of the following::

  a b c d e f h l bc de hl
  ^a ^b ^c ^d ^e ^f ^h ^l ^bc ^de ^hl
  ix ixh ixl iy iyh iyl
  i r sp memptr

The names that begin with ``^`` denote the shadow registers.

Wherever ``\n`` appears in the ``TraceHeader`` parameter value, it is replaced
by a newline character.

Configuration parameters must appear in a ``[rzxplay]`` section. For example,
to make ``rzxplay.py`` write instruction addresses and operands in a trace log
file in decimal format by default, add the following section to
``skoolkit.ini``::

  [rzxplay]
  TraceLine={pc:05} {i}
  TraceOperand=

Configuration parameters may also be set on the command line by using the
``--ini`` option. Parameter values set this way will override any found in
``skoolkit.ini``.

EXAMPLES
========
1. Play ``game.rzx``:

|
|   ``rzxplay.py game.rzx``

2. Log the instructions executed while playing ``game.rzx``:

|
|   ``rzxplay.py --trace game.log game.rzx``

3. Play only 100 frames of ``game.rzx`` and then write ``game-100.rzx``:

|
|   ``rzxplay.py --stop 100 game.rzx game-100.rzx``
