COMMANDS
========


after
-----

  Execute a command after a certain time, or after a certain time of being
  idle. It is possible the query a list of postponed commands and also to
  cancel postponed commands.

  usage:
    after time <seconds> <command>  execute a command after some time
    after idle <seconds> <command>  execute a command after some time being idle
    after frame <command>           execute a command after a new frame is drawn
    after break <command>           execute a command after a breakpoint is
                                    reached
    after info                      list all postponed commands
    after cancel <id>               cancel the postponed command with given id

  examples:
    after time 10 "set renderer SDLGL"
    after idle 100 quit
    after info
    after cancel 2
    

bind / unbind / bind_default / unbind_default
---------------------------------------------
  
  Associate key presses with commands. Whenever you press one of the programmed
  keys, the corresponding command will be executed.
  To customize your keybindings you should use the (un)bind commands. A script
  that wants to provide a default binding for its functionality needs to use
  bind_default. 
  
  usage:
    bind                    shows all bindings
    bind   <key>            shows binding for this key
    bind   <key> <command>  make a new binding
    unbind <key>            undo binding for this key
  
  examples:
    bind PAGEUP "set speed 100"
    bind PAGEDOWN "set speed 50"
    unbind F9
    bind F9 "set throttle off"
    bind F9,release "set throttle on"


cassetteplayer
--------------

  Insert a tape image in a virtual cassette player. The file must be in .wav
  format. Don't forget to connect the cassetteplayer to the cassette port.

  usage:
    cassetteplayer insert <tape image>  insert tape image in virtual cassette 
                                        player
    cassetteplayer eject                remove tape from virtual cassette player
    cassetteplayer rewind               rewind the current tape
    cassetteplayer motorcontrol on|off  sets whether motor control signal 
    					(remote) is obeyed (default: on)
    cassetteplayer new [<tape image>]   create new tape image and go to record
                                        mode
    cassetteplayer play                 go to play mode (when in record mode)
                                        and rewind the tape

debug
-----

  This command implements a debugger interface. It's meant to be used by an
  external debugger.

  usage:
    debug list                          returns a list of all debuggables
    debug desc <name>                   returns a description of this debuggable
    debug size <name>                   returns the size of this debuggable
    debug read <name> <addr>            read a byte from a debuggable
    debug write <name> <addr> <val>     write a byte to a debuggable
    debug set_bp <addr> [<condition>]   insert a new breakpoint
    debug remove_bp <id>                remove a certain breakpoint
    debug list_bp                       list the active breakpoints
    debug cont                          continue execution after break
    debug step                          execute one instruction
    debug break                         break CPU at current position
    debug breaked                       query CPU breaked status
    debug read_block <name> <addr> <size>     read a whole block at once
    debug write_block <name> <addr> <values>  write a whole block at once 
    debug disasm [<addr>]               disassemble instructions at PC or given
                                        address

  Note: in the share/scripts directory you'll find some TCL scripts that
        offer convenience wrapper around this command. For example:
           showmem, disasm, cpuregs, save_debuggable
    

diska / diskb
-------------

  Insert a disk image in a drive. Optionally apply an IPS patch to the disk
  image.
  Note: the command-name is the same as the drive-name and the drive-name is
        configurable

  usage:
    diska <disk image>        insert disk image in drive "diska"
    diska <disk image> <ips>  insert disk image and apply IPS patch
    diska -eject              remove disk from drive "diska"
    diska -ramdsk             insert scratch disk in drive "diska"


escape_grab
-----------

  Only has effect in windowed mode and when the 'grabinput' setting is active.
  Temporarily release the input grab. When window has lost and regained the
  focus the grab is again effective.

  usage:
    escape_grab  temporarily release the input grab


diskmanipulator
---------------

  Used to manipulate the (files on) a disk image.
  For an in-depth explanation and examples see the file 
  'Using-diskmanipulator.txt'.

  usage:
    diskmanipulator savedsk <disk name> <dskfilename>
    diskmanipulator import  <disk name> <host directory>
    diskmanipulator export  <disk name> <host directory>
    diskmanipulator mkdir   <disk name> <MSX directory>
    diskmanipulator chdir   <disk name> <MSX directory>
    diskmanipulator dir     <disk name>
    diskmanipulator format  <disk name>

    diskmanipulator create  <dskfilename> <size/option> <size/option> ...


help
----

  Shows help info.

  usage:
    help            shows a list of all possible commands
    help <command>  shows help info for a specific command


keymatrixup / keymatrixdown
---------------------------

  Press or release keys from the MSX keyboard matrix. Mainly useful to make
  an external program press MSX keys.

  usage:
    keymatrixup <row> <mask>    release the indicated MSX keys
    keymatrixdown <row> <mask>  press the indicated MSX keys

  examples:
    keymatrixup 6 0x01
    keymatrixdown 6 0x01


load_settings
-------------

  Load settings from a given file. The settings file must not be complete,
  settings that are not mentioned in the given file are left untouched.

  usage:
    load_settings <filename>  Load settings from the given file


openmsx_info
------------

  Shows information about a certain topic.

  usage:
    openmsx_info          shows a list of all possible topics
    openmsx_info <topic>  shows info on this specific topic


palette
-------

  Shows the current VDP palette settings.
  [ mainly useful for debugging purposes ]
  

plug / unplug
-------------

  Plugs or unplugs a plug into a connector, for example plug a virtual joystick
  into a virtual joystick port.

  usage:
    plug                     shows all currently connected plugs
    plug <connector>         shows currently connected plug for the specified
                             connector
    plug <connector> <plug>  plugs the specified plug into the specified
                             connector
    unplug <connector>       unplugs the plug connected to the specified
                             connector

  examples:
    plug cassetteport cassetteplayer
    plug joyporta mouse
    plug printerport logger
    unplug joyportb


reset
-----

  Resets the emulated MSX.


screenshot
----------

  Take a screenshot.

  usage:
    screenshot              Write screenshot to file "openmsxNNNN.png"
    screenshot <filename>   Write screenshot to indicated file
    screenshot -prefix foo  Write screenshot to file "fooNNNN.png"


set
---

  Change or query the value of various settings.
  
  usage:
    set                    Shows a list of all supported settings 
    set <setting>          Query the current value of the specified setting
    set <setting> <value>  Change the specified setting to the given value
  
  Settings that can be adjusted with this command are listed below.

  examples:
    set accuracy pixel
    set blur 25
    set scanline 20
    set deinterlace on


slotmap
-------

  Shows the slot mappings of the emulated MSX.
  [ mainly useful for debugging purposes ]


slotselect
----------

  Shows the currently selected slots.
  [ mainly useful for debugging purposes ]


soundlog
--------

  Controls sound logging: writing the openMSX sound to a wav file.

  usage:
    soundlog start              Log sound to file "openmsxNNNN.wav"
    soundlog start <filename>   Log sound to indicated file
    soundlog start -prefix foo  Log sound to file "fooNNNN.wav"
    soundlog stop               Stop logging sound
    soundlog toggle             Toggle sound logging state


iomap
-----

  Shows what I/O ports are connected to which devices.
  [ mainly useful for debugging purposes ]


save_settings
-------------

  Write the current openMSX settings to a settings file.

  usage:
    save_settings             Save settings to the default settings file  
    save_settings <filename>  Save settings to the given filename


toggle
------

  Toggles any boolean (on-off) setting.

  usage:
    toggle <setting>  toggles the specified setting

  examples:
    toggle mute
    toggle throttle


type
----

  Type a string in the emulated MSX. This command automatically presses and
  releases keys in the simulated MSX keyboard matrix. This command is mainly
  useful for demoing.

  usage:
    type "Hello world!"

  
update
------

  Enable or disable update notifications of a certain type.
  This command is mainly useful for external programs controlling openmsx.

  usage:
    update enable <type>   enable notifications for this type
    update disable <type>  disable notifications for this type

  examples:
    update enable led
    update disable setting


vdpregs
-------

  Shows the current VDP register settings.
  [ mainly useful for debugging purposes ]
  


OLD COMMANDS
============

  The following commands existed in older openMSX version. For backwards
  compatibility they are still supported for a while. In later versions they
  will be removed.


alias / unalias
---------------

  Create a new command that is an alias for another (group of) command(s).

  Note: This is not 100% compatible with the old alias command. Better use
        the more powerful TCL "proc" command.

  usage:
    alias <name> <command>  define an alias

  examples:
    alias gl "set renderer SDLGL"
    alias restart "set power off ; set power on"


decr
----

  Decrement an integer setting.

  This command is deprecated, better use the native TCL command "incr" and
  negate the offset.

  usage:
    decr                  shows all integer settings
    decr <setting>        decrement the specified setting
    decr <setting> <num>  decrement the specified setting with given amount

  examples:
    decr speed
    decr renshaturbo 10


incr
----

  Increment an integer setting.

  This command is now a native TCL command.

  usage:
    incr                  shows all integer settings
    incr <setting>        increment the specified setting
    incr <setting> <num>  increment the specified setting with given amount

  examples:
    incr speed
    incr renshaturbo 10


quit
----

  Quits the emulator.
  
  The native TCL command is called "exit".


restoredefault
--------------

  Restore the default value for a setting.

  This command is deprecated, better use "unset <setting>".

  usage:
    restoredefault <setting>  Restores the default value for the given setting

  examples:
    restoredefault PSG_volume

SETTINGS
========


accuracy
--------

  Sets the render accuracy. Currently there are three render modes:
    - screen accurate: This is the fastest but also least accurate mode.
    - line accurate: This is the recommended mode. Most tricks are 
                     rendered correctly.
    - pixel accurate: This is the slowest but also most accurate mode.
                      In this mode even the 'Unknown Reality scope part'
                      is rendered correctly.
  Note: not all renderers support all render modes

  usage:
    set accuracy          shows the current setting
    set accuracy screen   selects screen accurate rendering
    set accuracy line     selects line accurate rendering
    set accuracy pixel    selects pixel accurate rendering


audio-inputfilename
-------------------

  Sets the file(name) from which the wave input is read for the sampler.
  By default, it is read from "audio-input.wav" when available.
  
  usage:
    set audio-inputfilename                shows the current setting
    set audio-inputfilename mysample.wav   read from mysample.wav


blur
----

  Sets the amount of horizontal blur effect.
  Note: not all renderers support this.

  usage:
    set blur          shows the current setting
    set blur <value>  change the value


cmdtiming
---------

  Controls VDP command execution timing.
  [ mainly useful for debugging purposes ]
  

console
-------

  Turns the console on or off.

  usage:
    set console       shows the current setting
    set console on    turns the console on
    set console off   turns the console off
    

consolebackground
------------------

  Change the console background image. Most image formats (.png, .jpeg,
  .gif, ...) are supported. Some renderers (openGL) can use an alpha
  channel, this channel is only present in .png images.

  usage:
    set consolebackground          shows the current setting
    set consolebackground <image>  sets a new background


consolecolumns
--------------

  Change the width of the console measured by the number of columns.
  
  usage:
    set consolecolumns             shows the current setting
    set consolecolumns <value>	   set the specified width


consolefont
-----------

  Change the console font. Most image formats (.png, .jpeg, .gif, ...)
  are supported. The image must contain a 16x16 matrix with the characters
  in ASCII order. Some renderers (openGL) require an alpha channel to have
  transparency in the font, this channel is only present in .png images.

  usage:
    set consolefont          shows the current setting
    set consolefont <image>  sets a new font


consoleplacement
----------------

  Change the position of the console within the emulator

  usage:
    set consoleplacement	  shows the current setting
    set consoleplacement <place>  moves the console the the specified location

  <place> can be topleft, top, topright, left, center, right, bottomleft,
  bottom and bottomright.


consolerows
-----------

  Change the height of the console measured by the number of rows.

  usage:
    set consolerows            shows the current setting
    set consolerows <value>    set the specified width


cputrace
--------

  Enable/disable CPU instruction tracing
  [ only available when compiled with DEBUG option ]
 
 
debugoutput
-----------

  Selects the file to where the output from the debug device goes.

  usage:
    set debugoutput                shows the current output file
    set debugoutput <output file>  set the specified output file


deinterlace
-----------

  Turns deinterlacing on/off.
  Note: not all renderers support deinterlacing.

  usage:
    set deinterlace      shows the current setting
    set deinterlace on   turns deinterlacing on
    set deinterlace off  turns deinterlacing off


frequency
---------

  The sound mixer frequency. Changing this setting only takes effect the next
  time openMSX is started.

  usage:
    set frequency        shows the current setting 
    set frequency 44100  use 44.1kHz mixing frequency


firmwareswitch
-----------

  Some machines (e.g. TurboR) have a switch on the front (or on the back) that
  controls if the machine should boot 'normally' or start the built in
  software, also called firmware. This setting controls the position of that
  switch.

  usage:
    set firmwareswitch      shows the current setting
    set firmwareswitch on   in this position the internal software is started
    set firmwareswitch off  in this position the machine boots 'normally'


fullscreen
----------

  Switch to / back from fullscreen mode.

  usage:
    set fullscreen      shows the current setting
    set fullscreen on   switch to fullscreen mode
    set fullscreen off  switch to normal mode


fullspeedwhenloading
--------------------

  When enabled, openMSX will try to detect when it is loading from diskette or
  cassette and in case it is, it will run at full speed (taking all CPU power
  it can get). This can be convenient if you're not interested in the realistic
  loading times on MSX. Default is off, because it is not according to the
  behaviour of a real MSX.

  usage:
    set fullspeedwhenloading      shows the current setting
    set fullspeedwhenloading on   enable the full speed when loading feature
    set fullspeedwhenloading off  disable the feature


gamma
-----

  Sets the amount of gamma correction: low is dark, high is bright

  usage:
    set gamma        shows the current value
    set gamma <num>  set new value

    
glow
----
  
  Sets the amount of glow effect.
  Note: not all renderers support this.

  usage:
    set glow          shows the current setting
    set glow <value>  change the value


grabinput
---------

  Controls whether openMSX grabs all input or not. When this setting is turned
  on, all input is directly passed to openMSX. The mouse pointer can't leave
  the openMSX window and the window manager won't be able to react to keyboard
  shortcuts.

  usage:
    set grabinput      shows the current setting
    set grabinput on   turn input grabbing mode on
    set grabinput off  turn input grabbing mode off


icon.<name>.xcoord
icon.<name>.ycoord
icon.<name>.active.image
icon.<name>.non-active.image
icon.<name>.active.fade-delay
icon.<name>.active.fade-duration
icon.<name>.non-active.fade-delay
icon.<name>.non-active.fade-duration
------------------------------------

  Controls the appearance of the OSD LED icons.
  
  <name> can be 'caps', 'fdd', 'kana', 'pause', 'power' or 'turbo'.

  The position is set with the 'xcoord' and 'ycoord' settings. The active and
  non-active version have the same position. The value is in pixels and (0,0)
  corresponds to the top-left of the screen.
  Note: In the future this will most likely change so that it is resolution
        independent (scale_factor setting)

  The image for the LED can be specified with the '(non-)active.image' setting.
  This can be an image of any size and the image can have an alpha
  (=transparency) channel. Typically this will be .png files.

  Fade duration and delay control how (and if) the icon will fade away. When
  the LED changes status (on->off or off->on) the image is always shown, after
  the 'delay' time it will start to fade out. The time from completely visible
  to completely transparent is controlled with the fade.duration setting. Both
  fade.duration and fade.delay are specified in milliseconds. A fade delay of 0
  means don't fade out. Duration and delay can be set independently for active
  and non-active image.

  usage:
    set icon.fdd.xcoord 250
    set icon.fdd.ycoord 0
    set icon.fdd.active.image fdd-on.png
    set icon.fdd.active.image fdd-off.png
    set icon.fdd.active.fade-delay 0             don't fade out active fdd LED
    set icon.fdd.active.fade-duration 5000
    set icon.fdd.non-active.fade-delay 5000
    set icon.fdd.non-active.fade-duration 5000
    

inputdelay
----------

  [ Only Change this if you understand what this setting does]

  Input events for the MSX machine are delayed by this amount. Increase this
  value when the MSX machine misses keyboard presses when you type very fast.
  Decrease this value to reduce the latency between pressing a key on the host
  machine and seeing it being typed in the MSX machine.
  
  Note: the default value (3/100s) should almost always be OK, this small delay
        is practically not noticeable and still allows the MSX machine to get
        accurate timing on the input events.


keyjoystick<n>.<button>
-----------------------

  <n>        1, 2
  <button>   up, down, left, right, triga, trigb

  Configure the keys of the keyjoysticks. It's likely this will change in the
  future.

  usage:
    set keyjoystick1.up W
    set keyjoystick1.down S
    set keyjoystick1.left A
    set keyjoystick1.right D
    set keyjoystick1.triga SPACE


limitsprites
------------

  Limit number of sprites per line. Turn on for realism (default), turn off to
  reduce sprite flashing. Note that some games make use of this limitation.

  usage:
    set limitsprites
    set limitsprites on   limit number of sprites per line
    set limitsprites off  no limit on number of sprites per line


machine
-------

  The default machine. OpenMSX uses this machine when it is started without
  "-machine" option.

  usage:
    set machine                     shows current setting
    set machine Panasonic_FS-A1GT   use this machine next time openMSX is
                                    started

midi-in-readfilename
--------------------

  Sets the file(name) from which the MIDI input is read.
  By default, it is read from /dev/midi when available.
  
  usage:
    set midi-in-readfilename                shows the current setting
    set midi-in-readfilename mymidilog.dat  read from mymidilog.dat



midi-out-logfilename
--------------------

  Sets the file(name) to which the MIDI output is logged.
  By default, it logs to /dev/midi when available.
  
  usage:
    set midi-out-logfilename                shows the current setting
    set midi-out-logfilename mymidilog.dat  log to mymidilog.dat


maxframeskip
------------

  Set the maximum amount of frame skips. Frame skip here means: "show a frame
  and then skip <number> frames". So 0 means show everything, 1 means show
  every second frame, ...

  usage:
    set maxframeskip           shows the current setting
    set maxframeskip <number>  sets the number of frame skips


minframeskip
------------

  Set the minimum amount of frame skips. Frame skip here means: "show a frame
  and then skip <number> frames". So 0 means show everything, 1 means show
  every second frame, ...

  usage:
    set minframeskip           shows the current setting
    set minframeskip <number>  sets the number of frame skips

  
mute
----

  Mute / unmute the sound output.

  usage:
    set mute      shows the current setting
    set mute on   mute sound
    set mute off  unmute sound


pause
-----

  Pauses the emulation.

  usage:
    set pause      shows the current setting
    set pause on   pauses emulation
    set pause off  unpauses emulation


printerlogfilename
------------------

  Sets the file(name) to which the printer logger logs
  
  usage:
    set printerlogfilename                   shows the current setting
    set printerlogfilename myprinterlog.txt  log to myprinterlog.txt


r800_freq and r800_freq_locked
------------------------------

  These two settings control the R800 clock frequency. See z80_freq and
  z80_freq_locked for more details.


renderer
--------

  Switch to a different VDP renderer.

  usage:
    set renderer        shows the current setting
    set renderer SDL    switch to the SDL renderer
    set renderer SDLGL  switch to the SDLGL renderer

renshaturbo
-----------

  Sets the speed of the built-in auto fire on some Japanese MSX models
  (including the TurboR machines)

  usage:
    set renshaturbo        shows the current renshaturbo value
    set renshaturbo <num>  set speed to value <num>, from 0 to 100 (0 means off)

rs232-inputfilename
-------------------

  Sets the file(name) from which the RS232-tester reads data
  
  usage:
    set rs232-inputfilename                   shows the current setting
    set rs232-inputfilename myrs232input.txt  read from myrs232input.txt


rs232-outputfilename
-------------------

  Sets the file(name) to which the RS232-tester outputs the data
  
  usage:
    set rs232-outputfilename                    shows the current setting
    set rs232-outputfilename myrs232output.txt  write to myrs232output.txt


samples
-------

  Sets the size of the sound mixer buffer. Changing this setting only takes
  effect the next time openMSX is started.

  usage:
    set samples       shows the current setting 
    set samples 1024  use mixing buffer of 1024 samples


save_settings_on_exit
---------------------

  Automatically save the current settings when openMSX exits (execute a
  save_settings command).

  usage:
    set save_settings_on_exit        Show current setting
    set save_settings_on_exit true   Enable auto save
    set save_settings_on_exit false  Disable auto save
    

scale_algorithm
---------------
  
  Select the algorithm used to transform MSX pixels to host pixels.
  
  usage:
    set scale_algorithm         Show current setting
    set scale_algorithm simple  Select the default scale algorithm
    set scale_algorithm hq      Select the hq scale algorithm


scale_factor
------------

  Select the scale factor. Scale factor 'n' means the typical MSX pixel
  (MSX resolution 256x212) is mapped on 'n' host pixels. For the moment
  the possible values are 1, 2 or 3. In the future we may support a wider
  range or even non integer values.

  usage:
    set scale_factor       Show current setting
    set scale_factor <n>   Set a new scale factor


scanline
--------

  Sets the amount of scanline effect.
  Note: not all renderers support this.

  usage:
    set scanline          shows the current setting
    set scanline <value>  change the value


sound_driver
------------

  Select the sound output driver. The list of available sound drivers is
  platform specific.

  usage:
    set sound_driver sdl

speed
-----

  Sets the emulation speed relative to the speed of a real MSX. Speed 100 means
  as fast as a real MSX.

  usage:
    set speed        shows current emulation speed
    set speed <num>  set new emulation speed


[soundchip]_mode
------------------

  Sets the channel mode for individual sound chips. Note that chips which are in
  stereo mode cannot be set to another mode and chips that are not in stereo
  mode, can of course never be set to stereo mode.

  usage:
    set [soundchip]_mode        shows the current setting
    set [soundchip]_mode <mode> set new mode

  examples:
    set PSG_mode
    set PSG_mode left
    set "FMPAC_mode" mono


[soundchip]_volume
------------------

  Sets the volume for individual sound chips.

  usage:
    set [soundchip]_volume        shows the current setting
    set [soundchip]_volume <num>  set new volume

  examples:
    set PSG_volume
    set PSG_volume 18000
    set "FMPAC_volume" 15000


throttle
--------

  Sets throttle mode. In throttle mode the emulator tries to run at the
  specified speed (see speed command). When throttling is turned off the
  emulator runs as fast as possible.

  usage:
    set throttle      shows the current setting
    set throttle on   turn throttle mode on
    set throttle off  turn throttle mode off
    

user_directories
----------------

  The list of "user directories". This makes it a bit more convenient to
  insert disks, tapes, roms, ... See manual for more details.
  This setting is a list in TCL format (items are space separated or enclosed
  in braces, see TCL manual for details). Thus all TCL functions to manipulate
  lists can be used on this setting.

  usage:
    set user_directories                   Shows the current list
    set user_directories "~/disks ~/roms"  Replace the list with a new one
    set user_directories {}                Remove all user directories
    lappend user_directories ~/tapes       Add a directory to the list


vdpcmdtrace
-----------

  Enable/disable VDP command tracing.
  [ mainly useful for debugging purposes ]


z80_freq and z80_freq_locked
----------------------------

  These two settings control the Z80 clock frequency. When z80_freq_locked is
  true the emulated Z80 runs at the normal 3.5MHz (or optionally 5.3MHz on some
  machines). When z80_freq_locked is false the value of z80_freq is taken as
  Z80 clock frequency.

  usage:
    set z80_freq 14318180
    set z80_freq_locked false
       overclock Z80 to 14MHz
       
    set Z80_freq 7159090
    bind F8 "toggle z80_freq_locked"
       F8 now switches between 3.5MHz and 7MHz
       
