openMSX Console Command Reference

  1. Commands
    1. after
    2. bind / unbind / bind_default / unbind_default
    3. cart / cart<x>
    4. cassetteplayer
    5. cd<x>
    6. cycle / cycle_back
    7. debug
    8. disk<x> / virtual_drive
    9. diskmanipulator
    10. escape_grab
    11. exit
    12. ext
    13. findcheat
    14. hd<x>
    15. help
    16. incr
    17. iomap
    18. keymatrixdown / keymatrixup
    19. list_extensions
    20. load_icons
    21. load_settings
    22. machine
    23. create_machine / load_machine / activate_machine / list_machines / delete_machine
    24. machine_info
    25. monitor_type
    26. mute_channels / unmute_channels / solo
    27. nowind<x>
    28. openmsx_info
    29. osd
    30. palette
    31. plug / unplug
    32. psg_profile
    33. record
    34. record_channels
    35. remove_extension
    36. reset
    37. save_settings
    38. savestate / loadstate / list_savestates / delete_savestate
    39. screenshot
    40. set
    41. slotmap
    42. slotselect
    43. soundlog
    44. store_machine / restore_machine
    45. test_machine
    46. toggle
    47. trainer
    48. type
    49. unset
    50. update
    51. user_setting
    52. vdpregs
    53. other
  2. Old Commands
    1. alias / unalias
    2. decr
    3. quit
    4. restoredefault
  3. Settings
    1. accuracy
    2. audio-inputfilename
    3. autoruncassettes
    4. blur
    5. bootsector
    6. brightness
    7. cmdtiming
    8. color_matrix
    9. console
    10. consolebackground
    11. consolecolumns
    12. consolefont
    13. consolefontsize
    14. console_history_size
    15. consoleplacement
    16. consolerows
    17. console_remove_doubles
    18. contrast
    19. cputrace
    20. debugoutput
    21. default_machine
    22. deinterlace
    23. DirAsDSKmode
    24. display_deform
    25. frequency
    26. firmwareswitch
    27. fullscreen
    28. fullspeedwhenloading
    29. gamma
    30. glow
    31. grabinput
    32. horizontal_stretch
    33. inputdelay
    34. kbd_auto_toggle_code_kana_lock
    35. kbd_code_kana_host_key
    36. kbd_keymap_filename
    37. kbd_mapping_mode
    38. kbd_numkeypad_always_enabled
    39. kbd_numkeypad_enter_key
    40. kbd_trace_key_presses
    41. keyjoystick<n>.<button>
    42. led_<name>
    43. limitsprites
    44. master_volume
    45. maxframeskip
    46. midi-in-readfilename
    47. midi-out-logfilename
    48. minframeskip
    49. mute
    50. noise
    51. pause
    52. pause_on_lost_focus
    53. pointer_hide_delay
    54. power
    55. printerlogfilename
    56. print-resolution
    57. r800_freq / r800_freq_locked
    58. renderer
    59. renshaturbo
    60. resampler
    61. rs232-inputfilename
    62. rs232-outputfilename
    63. rtcmode
    64. samples
    65. save_settings_on_exit
    66. scale_algorithm
    67. scale_factor
    68. scanline
    69. sound_driver
    70. speed
    71. <soundchip>_balance
    72. <soundchip>_ch<channel>_record
    73. <soundchip>_ch<channel>_mute
    74. <soundchip>_detune_frequency
    75. <soundchip>_detune_percent
    76. <soundchip>_vibrato_frequency
    77. <soundchip>_vibrato_percent
    78. <soundchip>_volume
    79. throttle
    80. turborpause
    81. umr_callback
    82. user_directories
    83. vdpcmdtrace
    84. videosource
    85. v9990cmdtrace
    86. z80_freq / z80_freq_locked

Commands

after

Execute a command after a certain event occurs, for example a given amount of time has passed or the emulator has been idle for a given amount of time. Every postponed command executes just once; if you want a command to run periodically, you have to issue it again every time it runs. The after command returns the id of the postponed command. It is possible to query a list of postponed commands and also to cancel postponed commands.

usage:
after time <seconds> <command> Execute a command after some time. Timescale is in MSX seconds.
after realtime <seconds> <command> Execute a command after some time. Timescale is in host seconds.
after idle <seconds> <command> Execute a command after some time being idle
after frame <command> Execute a command when a video frame is finished (VDP scanning reaches vsync)
after break <command> Execute a command after a breakpoint is reached
after boot <command> Execute a command after a (re)boot
after machine_switch <command> Execute a command after switch to new a machine
after info List all postponed commands
after cancel <id> Cancel the postponed command with given id
examples:
after time 2.6 "set renderer SDLGL-PP"
after idle 100 exit
after info
after cancel after#2

bind / unbind / bind_default / unbind_default

Associate events (such as key presses) with commands. Whenever the specified event occurs (e.g. you press the specified key), the corresponding command will be executed. To customize your bindings you should use the (un)bind commands. A script that wants to provide a default binding for its functionality needs to use bind_default.

Events can be:

<key>[,release] Short for keyb <key>[,release]
keyb <key>[,release] <key> is pressed [or released]
mouse button<n> <up/down> Mouse button <n> went up or down
mouse motion <x> <y> Mouse motion of <x> and <y>
joy<n> button<m> <up/down> Button <m> of joystick <n> went up/down
joy<n> axis<m> <value> Axis <m> of joystick <n> got value <value>
focus <boolean> The openMSX window got (1) or lost (0) focus
usage:
bind Show all bindings
bind <key> Show binding for the given key
bind <event> Show binding for this event
bind <event> [-repeat] <command> Make a new binding
unbind <key> Undo binding for this event
examples:
bind PAGEUP "set speed 100"
bind PAGEDOWN "set speed 50"

Only run with full throttle while F9 is pressed (like BrMSX):
unbind F9
bind F9 "set throttle off"
bind F9,release "set throttle on"

Pause when window loses focus (like fMSX):
bind "focus 0" "set pause on"
bind "focus 1" "set pause off"

Middle-click to toggle input grabbing:
bind "mouse button2 down" "toggle grabinput"

Map button 8 of joystick 1 to F2-key:
bind "joy1 button8 down" "keymatrixdown 6 0x40"
bind "joy1 button8 up" "keymatrixup 6 0x40"

Use pageup/down to increase/decrease emulation speed.
bind pageup -repeat "incr speed 1"
bind pagedown -repeat "incr speed -1"

cart / cart<x>

Insert a ROM cartridge in a running MSX. The cart command inserts the cartridge in the first available slot. The carta, cartb etc. commands insert it in the specified slot. The cartridges can be removed again with the eject subcommand.

ROM cartridges are a special class of extensions. For extensions that are not ROM cartridges, see the commands ext, list_extensions and remove_extension.

usage:
cart KMARE.ROM Insert ROM cartridge in first free slot
cart insert KMARE.ROM Insert ROM cartridge in first free slot
carta USAS.ROM -ips USAS.IPS Insert ROM cartridge in slot A, with IPS patch applied to the ROM contents
carta eject Eject the currently inserted cartridge from slot A

cassetteplayer

Controls the openMSX cassette player. The various subcommands can be used to insert, remove, create and rewind tape images.

usage:
cassetteplayer insert <tape image> Insert tape image (WAV or CAS format) in the cassette player
cassetteplayer eject Remove tape from virtual cassette player
cassetteplayer rewind Rewind the current tape
cassetteplayer motorcontrol on|off Selects 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

cd<x>

Change the CDROM image. The commands cda, cdb etc. are assigned to all available CDROM drives in the MSX. They will not correspond to drive names as used in MSX-DOS.

usage:
cda <iso image> Use ISO image for CDROM drive "cda"
cda insert <iso image> Use ISO image for CDROM drive "cda"
cda eject Eject CDROM from CDROM drive "cda"
cda Show current ISO image for CDROM drive "cda"

cycle / cycle_back

Iterates through the values of an enumerated setting.

cycle_back does the same as cycle, but it goes in the opposite direction.

usage:
cycle <setting> Changes the specified setting to the next value in the cycle
cycle_back <setting> Changes the specified setting to the previous value in the cycle
examples:
cycle scale_algorithm
cycle videosource

debug

This command provides access to the debugger functionality of openMSX. It's meant to be used by an external debugger (see also Controlling openMSX from External Applications). The general format of the debug command is:

debug <subcommand> [<extra arguments>]

where 'extra arguments' are specific for each subcommand. Below is a list of all subcommands:

debug list Return a list of all debuggables.
A debuggable is (part of) the state of
a MSX device that can be accessed via these debug commands.
Examples are:
  • the VDP registers
  • the currently visible memory for the Z80
  • the contents of the RAM
debug desc <name> Return a description of this debuggable
debug size <name> Return 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 read_block <name> <addr> <size> Read a whole block at once
debug write_block <name> <addr> <values> Write a whole block at once
debug probe <subcommand> See below.
debug break Break CPU at current position
debug breaked Query CPU break status
debug cont Continue execution after break
debug step Execute one instruction
debug list_bp List the active breakpoints
debug set_bp <addr> [<cond>] [<cmd>] Insert a new breakpoint at the given address. Optionally you can specify a condition and a command. When the CPU is about to execute the instruction at the given address, the condition will be evaluated, if this evaluates to true then the command is executed. The condition can be any Tcl expression and the command can be any Tcl command. The default condition is 'true' and the default command is "debug break".
debug remove_bp <id> Remove a certain breakpoint
debug list_watchpoints List all defined watchpoints
debug set_watchpoint <type> <region> [<cond>] [<cmd>] Insert a new watchpoint. When the CPU is about to read or write to/from the specified memory or I/O region, the condition is evaluated. If the condition evaluated to true, the command is executed. The condition and the command are similar to the ones in the set_bp subcommand. A watchpoint can either be set on a single memory address or I/O port (specify a single value), or on a whole memory or I/O port range (specify a begin/end pair). For example: debug set_watchpoint write_mem {0x8000 0x8FFF}
debug remove_watchpoint <id> Remove a certain watchpoint
debug list_conditions List the active conditions
debug set_condition <cond> [<cmd>] Set a new debugger condition. Conditions are like breakpoints, but not tied to a specific address. Simulation is much slower when conditions are used (though generally while debugging this is not a problem).
debug remove_condition <id> Remove a certain condition
debug disasm [<addr>] Disassemble instructions at PC or given address

The probe subcommand again has subcommands:

debug probe list Returns a list of all probes.
debug probe desc <probe> Returns a description of this probe.
debug probe read <probe> Returns the current value of a probe. But note that not all probes have a value
debug probe set_bp <probe> [<cond>] [<cmd>] Set a breakpoint of a probe. Like in the 'set_bp' subcommand you can optionally specify a condition and a command.
debug probe remove_bp <id> Remove the given breakpoint.
debug probe list_bp List the active breakpoints set on probes.

At first sight 'probes' and 'debuggables' are very similar. Though there are some important differences and that's why probes and debuggables use different subcommands:

A debuggable is an array of bytes. A probe is a single value and can have any type.
A debuggable is readable and (usually) writable. A probe is always read-only.
It's not possible to set breakpoints on a debuggable. You can set breakpoints on a probe (and sometimes this is the only purpose of a probe).

Many examples of usage of the debug command can be found in the scripts that come with openMSX (in the share/scripts directory). We also list a few here.

examples:
Note: Some of the commands are pretty low level. In the share/scripts directory you'll find some Tcl scripts that offer convenience wrappers around these commands. For example: showmem, disasm, cpuregs, save_debuggable, etc.

disk<x> / virtual_drive

Insert a disk image in a drive. Optionally apply an IPS patch to the disk image. The commands diska, diskb etc. are assigned to all available "physical" disk drives in the MSX. They might not correspond to drive names as used in MSX-DOS.

In addition to the physical disk<x> drives, there is the virtual_drive. This fake drive does not correspond to any MSX hardware. It can be used as a source or target for diskmanipulator operations just like physical drives.

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"

diskmanipulator

A collection of commands to manipulate (the files on) a disk image.

It can be used in so many different ways, that we wrote a separate manual for it: Using Diskmanipulator.

escape_grab

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

usage:
escape_grab Temporarily release the input grab

exit

This command exits the Tcl interpreter, which leads to openMSX exiting as well.

usage:
exit Exits the emulator

ext

Insert an MSX extension in a running MSX machine. The extension can be removed again with the remove_extension command. See also the commands cart, list_extensions and remove_extension.

usage:
ext fmpac Insert an FMPAC in a running MSX machine

findcheat

This is a tool to find new cheats, for example for a certain game it can help you find the memory location where the number of remaining lives is stored. These cheats can later be added to the trainer command.

It works more or less like this:

  1. Initialize the findcheat tool (this takes an initial snapshot of the MSX memory)
  2. Perform some action in the game that changes the variable that you're interested in. For example if you want to find the memory location where the number of lives is stored, you have to loose (or gain) a life in the game.
  3. Now use the findcheat tool to compare the current MSX memory state with the previous memory snapshot. findcheat offers a lot of possibilities here, for example you can search for memory locations that became bigger or smaller or locations whose value changed or didn't change.
  4. findcheat will show a list of memory locations that still match the search criteria.
  5. If there still are still too many matches, repeat from step 2.

Vampier wrote a very good tutorial on how to use findcheat, you can find it here.

hd<x>

Change the hard disk image. The commands hda, hdb etc. are assigned to all available hard disk drives in the MSX. They will not correspond to drive names as used in MSX-DOS.

usage:
hda <disk image> Use hard disk image for hard disk "hda"
hda insert <disk image> Use hard disk image for hard disk "hda"
hda Show current hard disk image for hard disk "hda"
Note: Because of disk caching, changing the hard disk when the MSX is running can lead to corruption of the hard disk contents. Therefore openMSX blocks the hd<x> commands unless the MSX is powered off.

help

Shows help info for console commands.

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

incr

Increment an integer setting.

This used to be an openMSX custom command, but is now a native Tcl command.

usage:
incr <setting> Increment the specified setting by one
incr <setting> <num> Increment the specified setting by the given amount
examples:
incr speed
incr renshaturbo 10
incr scanline -5

iomap

Shows what I/O ports are connected to which devices. The related command slotmap shows a similar overview, but for memory-mapped devices.

usage:
iomap Shows the I/O map of the current MSX machine

keymatrixdown / keymatrixup

Press or release keys in the MSX keyboard matrix. Can be used to make an external program or Tcl script press MSX keys. For some more information about the keymatrix, you could read the article on the MAP.

usage:
keymatrixdown <row> <mask> Press the indicated MSX keys
keymatrixup <row> <mask> Release the indicated MSX keys
examples:
keymatrixdown 6 0x01
keymatrixup 6 0x01

list_extensions

Returns a list of inserted cartridges and extensions. These can be removed with the remove_extension command or additional items can be added with the cart and ext commands.

usage:
list_extensions Lists all currently inserted cartridges and extensions

load_icons

Load a different icon set (used for the On Screen Display (OSD) LEDs).

Icon sets are stored in the share/skins directory.

usage:
load_icons <name> Load the given icon set, but don't change the position on the screen.
load_icons <name> <position> Load the given icon set and place them at the requested position. Position can be bottom, top, left or right.

load_settings

Load settings from a given settings XML file. The settings file does not have to be complete: settings that are not mentioned in the given file are left untouched. See also save_settings.

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

machine

Switch to a new MSX machine.

usage:
machine Returns the handle for the currently active machine
machine <machine name> Switch to the specified machine, also returns the handle for that machine
Note: The machine handle is mostly used by external applications controlling openMSX (see also Controlling openMSX from External Applications). For interactive use you can omit the machine handle to have the commands operate on the current machine.

create_machine / load_machine / activate_machine / list_machines / delete_machine

openMSX has the possibility to have multiple MSX machines concurrently in memory. This is more or less like multiple tabs in a web browser: you only work with one at-a-time, but you can have multiple open at the same time and easily switch between them. These commands are low level commands to manage this.

Some commands are specific per machine, for example if you insert a disk image into the disk drive of the emulated MSX machine and if you have multiple MSX machines, you need to specify in which MSX machine you want to insert the disk. To solve this, we introduced the concept of the 'active' MSX machine (this is also the machine that is visible and audible). All unqualified machine-specific command will act on the active machine. If you want to execute the command in a specific machine, you can qualify the command with a machineID prefix.

diska <diskimage> execute diska command in the active machine
<machine-ID>::diska <diskimage> execute diska command in the specified machine

create_machine:

This command returns a new machine-id. This machine-id can be used in the following commands. In the web browser analogy this command would open a new empty tab.

load_machine:

This command loads a machine configuration (= MSX model) into the given machine-ID. In the web browser analogy, this command would load a page in a previously created empty tab. And unlike a web browser, where you can load a different page in the same tab, you cannot load a different machine configuration in the same machine-ID.

activate_machine:

This command activates the given machine-ID. At any time there can only be one active machine-ID. This is analogue to switching tabs in a web browser.

list_machines:

Returns a list of all currently existing machine-IDs.

delete_machine:

Deletes the given machine-ID. This is analogue to closing a tab in a web browser.

examples:

set oldID [machineID] get the current machineID
set newID [create_machine] create a new machineID
$newID::load_machine Philips_NMS_8250 load an MSX2 configuration in that new machineID
activate_machine $newID switch to the new machine
activate_machine $oldID switch back to old machine
delete_machine $newID delete new machine
If you don't care about multiple active machines, the machine command is much more convenient to switch to a different MSX configuration.

machine_info

Shows information about a certain topic. This command is similar to the openmsx_info command. The topics of machine_info are all machine specific, while the topics of openmsx_info are generic.

usage:
machine_info Shows a list of all possible topics
machine_info <topic> Shows info on the given topic

monitor_type

Select a monitor color profile.

usage:
monitor_type Shows the currently selected color profile
monitor_type -list Lists all available color profiles
monitor_type <profile> Selects a new color profile
Note: This command is a convenience wrapper around the color_matrix setting.

mute_channels / unmute_channels / solo

Mute or unmute specific individual channels of sound devices. The syntax is very similar to the record_channels command.

usage:
mute_channels <device> [<channels>]] [<device> [<channels>]] Mute the specified channels of the specified device(s). If a device is given but no specific channels are specified, all channels of that device are muted. If no arguments are given at all, this command return a list of all currently muted channels.
unmute_channels <device> [<channels>]] [<device> [<channels>]] Unmute the specified channels of the specified device(s). If a device is given but no specific channels are specified, all channels of that device are unmuted. If no arguments are given at all, this command unmutes all channels of all devices.
solo <device> [<channels>]] [<device> [<channels>]] Mute all channels of all devices except for the specified channels.
examples:
mute_channels
mute_channels PSG
mute_channels SCC 2,4
unmute_channels
unmute_channels PSG 1 SCC 1,3-4
solo PSG 3

nowind<x>

Similar to the disk<x> commands there is a nowind<x> command for each nowind interface. This command is modeled after the 'usbhost' command of the real nowind interface. Though only a subset of the options is supported. Here's a short overview of the command line options:

long shortexplanation
--image -i specify disk image
--hdimage -m specify harddisk image
--romdisk -j enable romdisk
--ctrl -c no phantom disks
--no-ctrl -C enable phantom disks
--allow -a allow other diskroms to initialize
--no-allow-A don't allow other diskroms to initialize

If you don't pass any arguments to this command, you'll get an overview of the current nowind status.

This command will create a certain amount of drives on the nowind interface and (optionally) insert diskimages in those drives. For each of these drives there will also be a nowind<x><1..8> command created. Those commands are similar to e.g. the diska command. They can be used to access the more advanced diskimage insertion options.

In some cases it is needed to reboot the MSX before the changes take effect. In those cases you'll get a message that warns about this.

examples:
nowinda -a image.dsk -j Image.dsk is inserted into drive A: and the romdisk will be drive B:. Other diskroms will be able to install drives as well. For example when the MSX has an internal diskdrive, drive C: en D: will be available as well.
nowinda disk1.dsk disk2.dsk The two images will be inserted in A: and B: respectively.
nowinda -m hdimage.dsk Inserts a harddisk image. All available partitions will be mounted as drives.
nowinda -m hdimage.dsk:1 Inserts the first partition only.
nowinda -m hdimage.dsk:2-4 Inserts the 2nd, 3th and 4th partition as drive A: B: and C:.

openmsx_info

Shows information about a certain topic. For machine-specific topics, use the related command machine_info.

usage:
openmsx_info Shows a list of all possible topics
openmsx_info <topic> Shows info on the given topic

osd

openMSX has the possibility to show OSD (on screen display) elements. For example, the LEDs and the fps-indicator are implemented via OSD elements. This command allows to create new OSD elements, configure existing elements or delete elements.

This command is only useful if you plan to adjust or enhance the openMSX OSD, or create your own OSD widgets.

Execute "help osd" to get a detailed description of this command, which we will not repeat here.

palette

Shows the current VDP palette settings. Related command: vdpregs.

usage:
palette Show the currently active color palette

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

psg_profile

Select a PSG sound profile.

usage:
psg_profile Shows the currently selected sound profile
psg_profile -list Lists all available sound profiles
psg_profile <profile> Selects a new sound profile
Note: This command is a convenience wrapper around the PSG_vibrato_frequency, PSG_vibrato_percent, PSG_detune_frequency and PSG_detune_percent settings.

record

Controls video recording: write openMSX audio/video to an AVI file.

usage:
record start Record to file "openmsxNNNN.avi"
record start <filename> Record to indicated file
record start -prefix foo Record to file "fooNNNN.avi"
record stop Stop recording
record toggle Toggle recording

The start subcommand also accepts an optional -audioonly, -videoonly and a -doublesize flag. Videos are recorded in a 320×240 size by default and at 640×480 when the -doublesize flag is used. If only audio is recorded, the created file will be a WAV file instead of an AVI file. The soundlog command is a shorthand for record -audioonly.

record_channels

A high level command to record individual channels of sound chips to separate files. In the following variants of the command you can specify devices and channels. Multiple devices can be specified and multiple channels as well. If you want to specify channels of a device, put them right after the device.

usage:
record_channels [start] <device> [<channels>] [<device> [<channels>]] Start recording the specified channel(s) of the specified device(s). If no channels are given, all channels of the device are recorded.
record_channels stop [<device> [<channels>]] [<device> [<channels>]] Stop recording the specified channel(s) of the specified device(s). If no channels are given, recording for all channels is stopped for the given device(s). If no devices are given, all channel recording is stopped.
record_channels list Lists which channels of which sound chips are currently being recorded.
examples:
record_channels start PSG
record_channels PSG
record_channels SCC 1,4-5
record_channels SCC PSG 1
record_channels "MSX Music" 7-9 SCC 3,5 PSG 2
record_channels stop
record_channels stop PSG
record_channels stop SCC 3,5
record_channels list

remove_extension

Remove a cartridge or extension from a running MSX machine. See also the commands cart, ext, list_extensions.

usage:
remove_extension fmpac Removes the FMPAC extension from the running MSX

reset

Emulates the pressing of the reset button on the MSX. This sends a reset pulse to all devices, but does not erase memory contents.

usage:
reset Resets the current machine

save_settings

Write the current openMSX settings to a settings XML file. See also load_settings.

If you disabled save_settings_on_exit, you can use this command to save your preferences.

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

savestate / loadstate / list_savestates / delete_savestate

These command can be used to manage savestates. These are much easier to use than the lowlevel store_machine and restore_machine commands.

savestate [<name>]

This creates a snapshot of the currently emulated MSX machine. Optionally you can specify a name for the savestate, if you omit this name, the default name quicksave will be taken.

loadstate [<name>]

This restores a previously created savestate. Like above you can specify a name which defaults to quicksave if omitted.

list_savestates

This returns the names of all previously created savestates.

delete_savestate <name>

Delete a previously created savestate.

screenshot

Take a screenshot of the openMSX screen. By default this takes a screenshot of the 'scaled' MSX screen (see scale_algorithm setting) without OSD elements (e.g. console and icons). If you want to include the OSD elements pass the -with-osd option. If you want a screenshot of the 'unscaled' MSX screen, pass the -msxonly option. The screenshots are PNG files and (by default) are saved in the screenshots subdirectory of the openMSX data directory in your home directory.

usage:
screenshot [-with-osd] [-msxonly [-doublesize]] [-prefix <prefix>] [<filename>]
examples:
screenshot Write screenshot to file "openmsxNNNN.png"
screenshot <filename> Write screenshot to indicated file
screenshot -prefix foo Write screenshot to file "fooNNNN.png"
screenshot -msxonly Create screenshot of the MSX screen only (so no icons or console)
screenshot -msxonly -doublesize Create screenshot of the MSX screen only, with resolution 640×480
screenshot -with-osd Create screenshot of the scaled screen, including OSD elements

set

Change or query the value of various settings. See also: unset.

usage:
set <setting> Query the current value of the specified setting
set <setting> <value> Change the specified setting to the given value

The settings that can be adjusted with this command are listed and explained at the end of this document.

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

slotmap

Shows what devices are inserted into which slots. The related command iomap shows a similar overview, but for I/O mapped devices.

usage:
slotmap Shows the slot map of the current MSX machine

slotselect

Shows the currently selected slots. To see what devices are located in the slots, use the slotmap command.

usage:
slotselect Shows the currently selected slot for each page

soundlog

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

This command is a shorthand for record -audioonly.

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

store_machine / restore_machine

These are low-level commands, used to implement savestates.

store_machine:

Saves the state of the specified machine to a file.

store_machine Save state of current machine to file "openmsxNNNN.xml.gz"
store_machine <machineID> Save state of indicated machine to file "openmsxNNNN.xml.gz"
store_machine <machineID> <filename> Save state of indicated machine to specified file

restore_machine:

Load a previously saved machine in a new machine-ID, next to the already available machines. See the section on activate_machine.

restore_machine Load state from last saved state in default directory
restore_machine <filename> Load state from indicated file
Note: These commands are pretty low level. The savestate and loadstate scripts are build on top of this and are much more convenient to use.

test_machine

Test whether the given MSX machine configuration works. For example whether you have all required system-roms for this machine. See also load_machine.

usage:
test_machine <machine-config> Test whether the given machine configuration is OK.

toggle

Toggles any boolean (on/off) setting: if it was on, it will be turned off and vice versa.

usage:
toggle <setting> Toggles the specified setting
examples:
toggle mute
toggle throttle

trainer

Control game trainers. You can enable or disable individual cheats of each trainer. Make use of the TAB key to see what is available. When switching trainers, the currently active trainer will be deactivated.

usage:
trainer See which trainer is currently active
trainer <game> See which cheats are currently active in the trainer
trainer <game> all Activate all cheats in the trainer of <game>
trainer <game> \[<cheat> ..\] Toggle cheats of <game> on/off
trainer deactivate Deactivate all trainers
examples:
trainer Frogger all
trainer Circus\ Charlie 1 2
trainer Pippols lives \"jump shoes\"\

type

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

usage:
type "Hello world!" Yet another manifestation of the most famous program

unset

Undefines a Tcl variable. When used on openMSX settings, they are reverted to their default value. See also: set.

usage:
unset <variable> Undefines the given variable
unset <setting> Reverts the given setting to its default value

update

Enable or disable update notifications of a certain type. This command is intended for external programs controlling openMSX. More about this in Controlling openMSX from External Applications.

usage:
update enable <type> enable notifications for this type
update disable <type> disable notifications for this type
examples:
update enable led
update disable setting

user_setting

This command is only meant to be used in Tcl scripts. It allows to create Tcl variables that act very much like built-in openMSX settings. They have a description (can be queried with "help set <setting-name>") and their value is stored saved/restored when openMSX is quit/restarted.

Execute "help user_setting" to get a detailed description of this command.

vdpregs

Shows the current register settings of the Video Display Processor (VDP). Related command: palette.

usage:
vdpregs Shows the current VDP control register contents

other

Most commands described above are generally useful. openMSX also has a bunch of other more specialized commands. Some of these are intended for programmers who code MSX programs using openMSX as a tool. Other of these commands are more like toys or examples that show the openMSX scripting capabilities.

We've only listed a very brief overview of these command. As always execute "help <command-name>" to get a more detailed description of the command.

about Search command help-texts for given keyword
cpuregs Gives overview of the CPU registers
data_file Helps locate openMSX data files
disasm Print disassembled instructions at given memory location
getcolor Query V99x8 palette settings
get_color_count Gives an overview of the used colors in the current screen
get_screen Capture the content of a MSX text screen in a Tcl string
get_selected_slot Returns the selected slot for the given memory page
guess_title Use heuristics to guess the title of the current game (cartridge, disk or tape)
listing Reimplementation of the BASIC LIST command in Tcl
load_debuggable Write the content of a file to a openMSX debuggable
multi_screenshot Take screenshots of multiple successive frames
pc_in_slot Check whether CPU is executing from the specified slot (useful as breakpoint condition)
peek Read a byte from given memory location
peek16 Read a 16 bit word from given memory location
poke Write a byte to given memory location
poke16 Write a 16 bit word to given memory location
psg_log Log or replay PSG register values in binary format
reg Read or write CPU registers
reg_log Log or replay register values for the specified debuggable in ASCII format
run_to Execute instructions until PC reaches specified address
save_debuggable Save the content of a debuggable to a file
setcolor Change V99x8 palette settings
set_help_text Associate help text with a Tcl proc
set_tabcompletion_proc Associate tab completion with a Tcl proc
showdebuggable Print the content of a debuggable in a table
showmem Print the content of memory in a table
show_osd Print an overview of the defined OSD elements
stack Print the top of the CPU stack
step_in Execute one CPU instruction, go into subroutines
step_over Execute one CPU instruction, but don't go into subroutines
step_out Step out of the current subroutine
text_echo Echo all printed MSX text on stderr
toggle_fps Show (or hide) an fps indicator
toggle_freq Switch between PAL/NTSC
toggle_info_panel Show (or hide) a panel with various types of info on the currently running MSX (emulation); similar to the info in the panel you get when using the DIGIblue theme in blueMSX
toggle_mog_overlay Enable (or disable) graphical extra information and game hints when playing The Maze of Galious
toggle_scc_viewer Show a graphical view of the SCC chip(s) of the system, showing waveforms and volume per channel.
toggle_vu_meters Show (or hide) a graphical view of the volumes of the sound channels of several sound chips
umrcallback Example proc to use with the umr_callback setting
v9990reg Read or write a V9990 register
v9990regs Print an overview of all V9990 registers
vdpreg Read or write a V99x8 register
vdrive Easily switch disks in multi-disk games
vpeek/vpoke Read/write bytes from/to video RAM

The source code of all these scripts is located in share/scripts directory. Feel free to inspect these scripts and modify them to suit your needs.

Old Commands

The following commands existed in older openMSX versions. 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).

It is better to use the more powerful Tcl proc command.

usage:
alias <name> <command> Defines an alias
examples:
alias gl "set renderer SDLGL-PP"
alias restart "set power off ; set power on"
Note: The backwards compatibility implementation of the alias command is not 100% compatible with the old alias command. It is recommended that you update your scripts to use the Tcl proc command.

decr

Decrement an integer setting.

This command is deprecated, please use the incr command with a negative offset instead.

usage:
decr <setting> Decrement the specified setting by one
decr <setting> <num> Decrement the specified setting by the given amount
examples:
decr speed
decr renshaturbo 10

quit

Quits the emulator.

Please use exit instead.

usage:
quit Exits openMSX

restoredefault

Restore the default value for a setting.

This command is deprecated, please use unset <setting> instead.

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

Settings

Settings control many aspects of openMSX. Below, the available settings are listed and described. You can change setting values with the set command.

accuracy

Sets the render accuracy. openMSX supports three levels of render accuracy:

screen accurate:
Changes in VDP state become effective only once per video frame. Works well for most MSX1 software, but will break a lot of MSX2 software (anything that does so-called raster effects).
line accurate:
Changes in VDP state become effective only once per display line. Works well for almost all software.
pixel accurate:
Changes in VDP state become effective immediately. In this mode even the 'Unknown Reality scope part' is rendered correctly.

In some cases switching to a lower accuracy level can speed up emulation, but in many cases the speed difference is negligible.

The default is pixel accuracy, since this is the most realistic. If the software you are running shows a jittery screen split and you would prefer a stable screen split, switching to line accuracy can help.

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 audio file 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"
Note: The file is fully read into memory, so under Linux/UNIX do not attempt to read from a device node such as /dev/dsp.

autoruncassettes

Switches the "auto-run cassettes" feature on or off. When it's enabled, openMSX will try to type the proper loading instruction when a cassette is inserted.

usage:
set autoruncassettes Shows the current setting
set autoruncassettes on Try to run cassettes automatically
set autoruncassettes off Do nothing when cassettes are inserted
Note: This only works with CAS images for now and it is still an experimental feature.

blur

Sets the amount of horizontal blur effect. A value of 0 turns off blur, while 100 selects maximum blur.

usage:
set blur Shows the current setting
set blur <value> Change the value
Note: this setting may be overridden by scaling algorithms.

bootsector

Sets the boot sector type for DirAsDSK. Default: DOS2. Only relevant on turboR, because it boots differently depending on the type of boot sector on the disk in drive A.

usage:
set bootsector Shows the current setting
set bootsector DOS1 Use a DOS1 boot sector

brightness

Controls the brightness of the video output. Can be between -100 and 100. Lower values are darker, higher values are brighter. The default is 0, which is neutral. This setting shifts the brightness of all colors, including black and white, while the gamma setting changes the relative brightness of colors but does not change black and white.

The section about the noise setting describes a typical way of using brightness.

usage:
set brightness Shows the current setting
set brightness 5 Make the video output a bit brighter than default

cmdtiming

Controls VDP command execution timing.

This is useful for debugging and for speeding up games where the command engine performance is a bottleneck.

usage:
set cmdtiming Shows the current setting
set cmdtiming broken Make VDP commands finish instantly
set cmdtiming real Make VDP commands take a realistic amount of time
Note: When set to broken the emulated MSX acts different from a real MSX. This might cause some software to fail.

color_matrix

This setting represents a 3×3 matrix that is used to transform MSX RGB colors to host RGB colors. This setting can be used to generate all kind of color schemes, see scripts/monitor.tcl for examples.

To get the following color transformation:

        | a b c |   | Rm |   | Rh |
        | d e f | × | Gm | = | Gh |
        | g h i |   | Bm |   | Bh |
  

Use this command:

        set color_matrix { { a b c } { d e f } { g h i } }
  
usage:
set color_matrix Shows the current value
set color_matrix { { 1 0 0 } { 0 1 0 } { 0 0 1 } } This is the default (no color transformation)
set color_matrix { { .33 .33 .33 } { .33 .33 .33 } { .33 .33 .33 } } Transform to grey scale
Note: It is often more convenient to use the monitor_type command.

console

Turns the openMSX on-screen 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. Images in the PNG format are certainly supported, other image formats such as JPEG and GIF might be supported depending on how your openMSX was compiled (more accurately, how SDL_image was compiled). Background images may also have an alpha channel (amount of transparency per pixel), this channel is only present in PNG images.

usage:
set consolebackground Shows the current setting
set consolebackground <image> Sets a new background image

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. This should be the filename of a True Type Font. The default value is skins/VeraMono.ttf.gz.

In older openMSX releases (pre-0.7.1). You had to specify a PNG image here that contained a 16×16 matrix with the characters in ASCII order. This is no longer supported.

usage:
set consolefont Shows the current setting
set consolefont <myfont.ttf> Sets a new font

consolefontsize

Set the size for the console font. The default value is 12.

usage:
set consolefontsize Shows the current setting
set consolefont 16 Set a bigger than default font size

console_history_size

Determines how many commands are saved into the console history.

usage:
set console_history_size Shows the current setting
set console_history_size 5000 Keep a maximum of 5000 commands in the console history

consoleplacement

Changes the position of the console on the emulator screen.

usage:
set consoleplacement Shows the current setting
set consoleplacement <place> Moves the console to the specified location; <place> can be topleft, top, topright, left, center, right, bottomleft, bottom or 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

console_remove_doubles

Determines whether the console history remembers two identical subsequent commands.

usage:
set console_remove_doubles Shows the current setting
set console_remove_doubles on Remove (do not remember) the last command if it's the same as the previous (default)
set console_remove_doubles off Allow double subsequent command entries in the console history

contrast

Controls the contrast of the video output. Can be between -100 and 100. Lower values are less contrast, higher values are more contrast. The default is 0, which is neutral.

The section about the noise setting describes a typical way of using contrast.

usage:
set contrast Shows the current setting
set contrast -5 Reduce the video contrast a bit

cputrace

Enable/disable CPU instruction tracing. When enabled, the state of the CPU (Z80/R800) is printed on stdout after every instruction. This creates a lot of output and slows down emulation considerably, but it can be very useful for debugging.

usage:
set cputrace Shows the current setting
set cputrace on Enables CPU tracing
set cputrace off Disables CPU tracing

debugoutput

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

The User's Manual describes the debug device in more detail.

usage:
set debugoutput Shows the current output file name
set debugoutput stdout Writes debug output to openMSX's standard output stream
set debugoutput stderr Writes debug output to openMSX's standard error stream
set debugoutput <output file> Writes debug output to the specified file
Note: This setting only exists if the debugdevice extension is present in the current MSX machine.

default_machine

Selects the default MSX model. openMSX uses this machine when it is started without the -machine option. This is a typical setting that should be saved, see also save_settings.

usage:
set default_machine Shows current setting
set default_machine Panasonic_FS-A1GT Use the turboR GT the next time openMSX is started

DirAsDSKmode

Determine the behavior of the DirAsDSK when inserting a directory to be used as diskimage.

The possible values are read_only, cached_write, nodelete and full.

Although it is the most risky mode, the default is set to full, since this is what most users expect from using DirAsDSK.

read_only The MSX can not write to the virtual disk.
Changes on the host-OS are still reflected on the virtual disk, however.
cached_write The MSX can write to the virtual disk, however, all changes are only cached in memory, no changes are passed onto the host-OS.
Changes on the host-OS are still reflected on the virtual disk and will override any changes that the MSX has made.
nodelete Changes are two ways, from host-OS to MSX and vice versa.
However, deleting a file on the MSX will not delete the file on the host-OS. This can lead to unexpected behavior when the MSX later recreates a file with the same name, since this will be reflected towards the host-OS.
full All changes are performed both ways, no restrictions apply.
usage:
set DirAsDSKmode Shows the current setting
set DirAsDSKmode read_only Disk image will be read only
Note: this setting is only used when the directory is inserted, it is not possible to change the behaviour of the current virtual disk by altering the setting. The new setting will become effective after the current virtual disk has been ejected.
Note: On turboR machines, the MSX keeps a cache of the directory sectors in memory. This means that changes made on the host OS are detected by the DirAsDSK routine, but will not show up in those machines. The data sectors will have been changed when reading, however. This can cause unexpected data to be read in the MSX environment. To rectify this situation, perform a disk eject and reinsert the directory again. This will cause the hardware switch that the turboR has to be toggled, and its internal cache to be invalidated. Since the turboR machines do not use a write cache, the changes on the MSX side are correctly written to the host OS.

deinterlace

Turns deinterlacing on/off. Deinterlace is a filter which combines the even and odd field of interlaced video into a single frame which has double vertical resolution. It results in a sharp and stable image, but can show artifacts on fast animations.

usage:
set deinterlace Shows the current setting
set deinterlace on Turns deinterlacing on
set deinterlace off Turns deinterlacing off
Note: Not all renderers support deinterlacing.

display_deform

Select display deformation effect. This effect is only supported in the SDLGL-PP renderer.

usage:
set display_deform Shows the current setting
set display_deform normal Turns off display deform
set display_deform 3d Deforms the image in 3D, to look like a CRT (like JEmu2)
Note: In the past there was also a 'horizontal_stretch' mode. This is now replaced by the horizontal_stretch setting.

frequency

Sets the sound mixer frequency. Sound hardware and sound APIs typically support a limited set of frequencies, such as 11025 Hz, 22050 Hz, 44100 Hz and 48000 Hz.

usage:
set frequency Shows the current setting
set frequency 44100 Use 44.1 kHz mixing frequency (CD quality)

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 Boot into the internal software
set firmwareswitch off Boot into MSX-BASIC or on-disk software

fullscreen

Switch to/from fullscreen mode.

usage:
set fullscreen Shows the current setting
set fullscreen on Switch to fullscreen mode
set fullscreen off Switch to windowed mode

fullspeedwhenloading

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

Unlike the fast loading features in for example fMSX, fullspeedwhenloading does not intercept BIOS calls. Instead, it speeds up the emulation of the entire MSX, including all hardware devices. This avoids bugs like VRAM corruption in several games (for example the intro of Aleste Gaiden), as well as working correctly with software that uses a custom loader that bypasses the BIOS.

usage:
set fullspeedwhenloading Shows the current setting
set fullspeedwhenloading on Load as fast as possible
set fullspeedwhenloading off Load at the same speed as a real MSX

gamma

Sets the amount of gamma correction. A value of 1.0 will turn off gamma correction. Lower values will result in a darker image, higher values in a brighter image.

If you want to get a realistic picture, set the openMSX gamma correction to PC gamma / MSX gamma. TVs use a standardised gamma of 2.5, let's take that as the value of MSX gamma. You can measure the gamma of your PC screen with a simple test such as the Gamma Measurement Image in Robert W. Berger's "An Explanation of Monitor Gamma". If your PC gamma would be for example 2.0, the most realistic value for gamma correction would be 2.0 / 2.5 = 0.8.

Alternatively, you can just try a few values and see what you like.

usage:
set gamma Shows the current value
set gamma <num> Sets a new gamma correction amount

glow

Sets the amount of afterglow effect: 0 is off and 100 is a very heavy afterglow.

usage:
set glow Shows the current setting
set glow <value> Change the amount of afterglow
Note: Not all renderers support this.

grabinput

Controls whether openMSX grabs all input events or not. When this setting is turned on, all input events are 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.

You can turn this setting on when you want to use mouse-controlled MSX software while openMSX is in windowed mode. It is best turned off in all other cases. See also escape_grab.

usage:
set grabinput Shows the current setting
set grabinput on Starts grabbing all input events
set grabinput off Stops grabbing all input events

horizontal_stretch

Sets the amount of horizontal stretch, thus also the aspect ratio of the screen. More specifically, a setting of n means stretch the center n MSX pixels to the full width of the host output window (at scale_factor 1).

usage:
set horizontal_stretch Shows the current setting
set horizontal_stretch <value> Change the amount of horizontal stretch
examples of typical useful values:
set horizontal_stretch 320 (no horizontal stretch)
set horizontal_stretch 272 (approach real aspect ratio of MSX screen)
set horizontal_stretch 284 (default: show all generated border pixels, so that all border demo effects are still visible)
set horizontal_stretch 256 (borders are not visible at all; doesn't work well in combination with set-adjust)
Note: Not all renderers support this: currently only the SDLGL-PP renderer.

inputdelay

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.

usage:
set inputdelay Shows the current value
set inputdelay <time> Sets the input delay to the specified number of seconds
Note: The default value of 0.03 seconds 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. Please do not change the value of this setting unless you know what you are doing.

kbd_auto_toggle_code_kana_lock

Switches the "Automatically toggle the CODE/KANA lock" feature on or off. When it's on, openMSX will automatically toggle the CODE/KANA lock when a user enters a character for which the CODE/KANA lock state must be changed.

usage:
set kbd_auto_toggle_code_kana_lock Shows the current setting
set kbd_auto_toggle_code_kana_lock on Automatically toggle the CODE/KANA lock when required
set kbd_auto_toggle_code_kana_lock off Only toggle CODE/KANA lock status when user presses the CODE/KANA lock key
Note: This only works on MSX models for which the CODE/KANA key locks (e.g. Japanese MSX models and the Philips VG8010). On other models, this setting is ignored.

kbd_code_kana_host_key

Host key that maps to the MSX CODE/KANA key.

It is especially useful for people with AZERTY host keyboard, on which the right-ALT key (RALT, which is the default value of this setting) has a special function; it is called the ALT-GR key and it's used to enter some special characters (some keys are tagged with 3 characters; normal, key+SHIFT, key+ALT-GR).

It is also useful for people with a Japanese (jp106) keyboard; they can map the HENKAN_MODE key (which is similar to the KANA Lock on Japanese MSX models) to the CODE/KANA key.

usage:
set kbd_code_kana_host_key Shows the current setting
set kbd_code_kana_host_key MENU Binds the MENU key on the host keyboard to the MSX CODE/KANA key
set kbd_code_kana_host_key HENKAN_MODE Binds the HENKAN_MODE key on the host keyboard to the MSX CODE/KANA key

kbd_keymap_filename

Sets the filename of the file that contains a mapping from host keys to MSX keys.

In CHARACTER mapping mode, it is only used for special keys for which no unicode character exists, like the SHIFT key, the ALT key and so on.

In KEY mapping mode, it is used for all keys but the ones for which a special setting exists (like kbd_numkeypad_enter_key).

By default, this setting is not set but a built-in mapping is used. The built-in mapping maps from a US-QWERTY host keyboard to an 'international'-QWERTY MSX keyboard

usage:
set kbd_keymap_filename Shows the current value
set kbd_keymap_filename keymap.jp2eng Use the mapping from the file keymap.jp2eng

kbd_mapping_mode

The keyboard driver can work in two mapping modes; KEY mapping and CHARACTER mapping.

KEY mapping:
A key pressed on the host keyboard maps to one specific key on the MSX keyboard. This mode is convenient when the host keyboard and the MSX keyboard have the same layout or when working with a program that directly reads the keyboard matrix and forces the user to enter a certain key combination that can not be auto-generated in the CHARACTER mapping mode.
CHARACTER mapping:
A character entered by the user is mapped to the correct key combination on the MSX to enter that character. For example, when the user enters an ! character and openMSX is emulating an 'international' MSX model, the keyboard driver will press SHIFT and 1 on the MSX keyboard. This will be done regardless of the key or keys that the user pressed on the host keyboard to enter the ! character.
This is especially useful when the user has an AZERTY host keyboard and is working on a QWERTY style MSX or when he has a US-QWERTY keyboard and is working on a Japanese MSX.
Note that special keys (like CAPSLOCK) are mapped directly, just like in the KEY mapping mode.
usage:
set kbd_mapping_mode Shows the current mode
set kbd_mapping_mode CHARACTER Set the CHARACTER mapping mode
set kbd_mapping_mode KEY Set the KEY mapping mode

kbd_numkeypad_always_enabled

Some real MSX computers do not have a numeric keypad. openMSX will ignore key presses on the host numeric keypad when emulating such an MSX model. With this parameter, you can indicate that even on such MSX models, presses on the host numeric keypad must be mapped to the MSX numeric keypad. So, you can override accurate behaviour with it, which is the reason that by default, this setting is set to 'off'.

usage:
set kbd_numkeypad_always_enabled Shows the current setting
set kbd_numkeypad_always_enabled on Enables numeric keypad, even if the emulated MSX does not have one

kbd_numkeypad_enter_key

There is a subtle difference between numeric keypad of MSX computers and of most host computers; the MSX computers have a '.' and a ',' on the numeric keypad. On the other hand, the host computers have a '.' and an 'ENTER' key on the keypad.

In some respect it is logical that the 'ENTER' key on the host numeric keypad is mapped to the 'normal' MSX 'ENTER' key. On the other hand, that would make it impossible to enter the ',' on the MSX numeric keypad. Therefore, the user can choose whether the host numeric keypad ENTER key should be mapped to the MSX numeric keypad ',' (which is the default) or to the main 'ENTER' key.

usage:
set kbd_numkeypad_enter_key Shows the current value
set kbd_numkeypad_enter_key ENTER Maps the keypad enter key to the main 'ENTER' key, instead of the comma key on the MSX keypad

kbd_trace_key_presses

Log SDL key code, SDL modifiers and Unicode value for each key that gets pressed on the host keyboard on stderr. Also show Unicode value and corresponding MSX key-presses for characters that get 'pasted' into the MSX by the console type command. This setting is especially useful when defining unicode keymap files, so that you can find out the unicode values belonging to certain keys/characters.

usage:
set kbd_trace_key_presses Shows the current setting
set kbd_trace_key_presses on Turn logging of key presses on

keyjoystick<n>.<button>

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

Valid values for <n>: 1, 2.

Valid values for <button>: up, down, left, right, triga, trigb.

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

led_<name>

These are read-only settings. Their value reflects the current status of the corresponding LED on the emulated MSX machine. The currently supported LED names are: power, caps, kana, pause, turbo and FDD.

As for any setting you can use the native trace Tcl command to trigger a callback when the value of these settings changes. (In fact this possibility was the main motivation to make these read-only settings instead of topics of the machine_info command.)

limitsprites

Controls whether the VDP has a limit on the number of sprites it can display per line. The default is on, because the real VDP has such a limit. You can turn off the limit to reduce sprite flashing in games such as Aleste. Note that some games (Penguin Adventure, among others) make use of this limitation, so they will display incorrectly if the limit is turned off.

The 5th/9th sprite status flag of the VDP is not influenced by the limitsprites setting: the flag always takes the limit into account.

usage:
set limitsprites Shows the current value
set limitsprites on Limits number of sprites per line
set limitsprites off Turns off number of sprites per line limit

master_volume

Controls the overall openMSX volume. The volume of individual sound devices can be controlled with the <soundchip>_volume settings.

usage:
set master_volume Shows current setting
set master_volume 50 Sets master volume to 50%

maxframeskip

Sets the maximum amount of frames to skip: show a frame and then skip at most <number> frames. So 0 means show everything (no frame skipping), 1 means show at least every second frame etc.

Frame skipping is done on demand, as a way to keep the flow of time for the emulated MSX in sync with the flow of real time. You can set limits on the amount of frame skipping with the minframeskip and maxframeskip setting.

In a situation where the number of consecutive frames specified by maxframeskip has been skipped, openMSX will display the next frame, even if that means emulation will start lagging behind real time.

When throttle is off, the number of skipped frames will be equal to maxframeskip.

usage:
set maxframeskip Shows the current setting
set maxframeskip <number> Sets the maximum number of consecutive frame skips

midi-in-readfilename

Sets the file from which the MIDI input is read. By default, it is set to /dev/midi when available.

usage:
set midi-in-readfilename Shows the current setting
set midi-in-readfilename mymidilog.dat Read MIDI events from "mymidilog.dat"

midi-out-logfilename

Sets the file 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 MIDI events to "mymidilog.dat"

minframeskip

Sets the minimum amount of frames to skip: show a frame and then skip at least <number> frames. So 0 means no forced frame skipping, 1 means skip at least every second frame etc.

Frame skipping is done on demand, as a way to keep the flow of time for the emulated MSX in sync with the flow of real time. You can set limits on the amount of frame skipping with the minframeskip and maxframeskip setting.

The minframeskip setting can be useful if you want to ease the burden on your PC processor, for example for longer battery life on a laptop. It can also be useful if your PC is consistently too slow to run without frame skipping: in such cases video might be smoother with a low but constant frame rate than with a fluctuating frame rate.

usage:
set minframeskip Shows the current setting
set minframeskip <number> Sets the number of frame skips

mute

Mute/unmute all sound output.

usage:
set mute Shows the current setting
set mute on Mute sound
set mute off Unmute sound

noise

Controls the amount of Gaussian noise that is added to the video output. A small amount of noise can give a more authentic look to the video output on TFTs. Values can be between 0 and 100, where 0 is no noise and 100 is lots of noise.

This setting is best combined with brightness and contrast: noise creates small random fluctuations in the brightness of pixels. When noise is applied to pure black, it is not possible to make it any darker, so half of the time the noise is ineffective. The same happens with pure white. By setting the brightness slightly above 0 and contrast slightly below 0, you will get a better looking noise effect.

usage:
set noise Shows the current setting
set noise 7 Add a moderate amount of noise

pause

Pauses the emulation.

usage:
set pause Shows the current setting
set pause on Pauses emulation
set pause off Unpauses emulation
Note: Some video settings cannot be applied to an already rendered frame and will therefore not take effect until openMSX is unpaused.

pause_on_lost_focus

When this setting is enabled, the emulation will be paused when the openMSX window loses focus.

usage:
set pause_on_lost_focus Shows the current setting
set pause_on_lost_focus on Emulation will be paused when the openMSX window loses focus
set pause_on_lost_focus off Emulation will continue when the openMSX window loses focus (default)

pointer_hide_delay

The amount of seconds before the mouse pointer will be automatically hidden after it got shown due to mouse activity. A negative amount means that it will never be hidden, an amount of 0 means that it will be always hidden. By default the pointer is hidden 1 second after the last mouse activity.

usage:
set pointer_hide_delay Shows the current setting
set pointer_hide_delay -1 Never hide the mouse pointer
set pointer_hide_delay 0 Always hide the mouse pointer
set pointer_hide_delay 3.4 Hide the mouse pointer after 3.4 seconds of inactivity

power

Turn the power of the emulated MSX machine on or off.

usage:
set power Shows the current setting
set power on Turns the MSX machine on (the default)
set power off Turns the MSX machine off

printerlogfilename

Sets the file to which the printer logger writes.

usage:
set printerlogfilename Shows the current setting
set printerlogfilename myprinterlog.txt Log to "myprinterlog.txt"

print-resolution

Sets the resolution (in dpi) for the emulated dot-matrix printer.

The emulated printer 'prints' pages as PNG files. This settings determines the resolution of those images.

usage:
set print-resolution Shows the current setting
set print-resolution 600 Sets resolution to 600 dpi

r800_freq / r800_freq_locked

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

renderer

Switch to a different video renderer. See the User's Manual for a description of the available renderers.

usage:
set renderer Shows the current setting
set renderer <name> Switches to the given renderer

renshaturbo

Sets the speed of the built-in auto fire on some Japanese MSX models, for example the turboR machines. A value of 0 turns off auto fire, while 100 selects the most rapid auto fire.

usage:
set renshaturbo Shows the current renshaturbo value
set renshaturbo <num> Sets speed to value <num>
Note: This setting is only available if the current MSX machine has hardware Rensha Turbo support.

resampler

Sets the method to resample the sound of sound chips from their native frequency to the desired output frequency.

usage:
set resampler Shows the currently active resampler
set resampler fast Sets a fast, but low quality resampler. This uses simple linear interpolation, which can result in very audible aliasing effects in some cases. Although this is a relatively low quality algorithm, it's the algorithm that was used in pre-0.6.3 openMSX versions (and most other MSX emulators).
set resampler blip Sets the Blip_Buffer based resampler, which has the best quality per CPU usage ratio (this is the default value).
set resampler hq Sets the highest quality resampler, but it also takes the most CPU time. It's based on the libsamplerate algorithm.

rs232-inputfilename

Sets the file from which the RS232-tester reads data.

usage:
set rs232-inputfilename Shows the current setting
set rs232-inputfilename myrs232input.txt Reads from "myrs232input.txt"

rs232-outputfilename

Sets the file to which the RS232-tester writes the data.

usage:
set rs232-outputfilename Shows the current setting
set rs232-outputfilename myrs232output.txt Write to "myrs232output.txt"

rtcmode

Sets the Real Time Clock mode. Can be either RealTime or EmuTime.

In RealTime mode the MSX clock is always synchronized with the host clock, even when for example emulation is paused for a while or when emulation is run at 200% of real speed.

In EmuTime mode the time is only synchronized with the host clock when openMSX starts. From then on the clock ticks at the same pace as the emulated machine. So when emulation is paused, the clock is paused as well. If emulation is run at 200% speed, the clock also ticks twice as fast.

In EmuTime mode it's not possible for a MSX program to detect whether it's running on a real or on an emulated machine. That's why this is the default mode. On the other hand the RealTime mode might be better if for example you care that timestamps of files written by the emulated MSX machine are in sync with the host machine time.

usage:
set rtcmode Shows the current mode
set rtcmode EmuTime Set EmuTime mode (the default)
set rtcmode RealTime Set RealTime mode

samples

Sets the size of the sound mixer buffer. Higher values help against buffer underruns (hickups), but increase the latency of the sound output.

usage:
set samples Shows the current setting
set samples 1024 Use a mixing buffer of 1024 samples

save_settings_on_exit

Automatically save the current settings when openMSX exits: execute a save_settings command on exit.

usage:
set save_settings_on_exit Show current setting
set save_settings_on_exit on Enable auto save
set save_settings_on_exit off Disable auto save

scale_algorithm

Selects the algorithm used to transform MSX pixels to host pixels. The User's Manual contains more information about scalers.

usage:
set scale_algorithm Shows the current setting
set scale_algorithm simple Selects the default scale algorithm
set scale_algorithm hq Selects the HQ2x/3x/4x scale algorithm
Note: Not all renderers support all scale algorithms.

scale_factor

Selects the scale factor. Scale factor <n> means the typical MSX pixel (MSX resolution 256×212) is mapped on <n> by <n> host pixels. For the moment the possible values are 1 to 4. In the future we may support a wider range or even non-integer values. The User's Manual contains more information about scalers.

usage:
set scale_factor Shows the current setting
set scale_factor <n> Sets a new scale factor
Note: Not all renderers support all scale factors.

scanline

Sets the amount of scanline effect.

usage:
set scanline Shows the current setting
set scanline <value> Changes the value
Note: Some scalers will not render scanlines at all.

sound_driver

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

usage:
set sound_driver sdl Selects the SDL sound driver (all platforms)
set sound_driver directx Selects the DirectX sound driver (Windows only)

speed

Sets the emulation speed relative to the speed of a real MSX. Speed 100 means as fast as a real MSX, lower values are slower than real MSX, higher values are faster than real MSX.

usage:
set speed Shows current emulation speed
set speed <num> Sets new emulation speed

<soundchip>_balance

Sets the balance (distribution over the left and right channel) for individual sound chips. It replaces the previously available <soundchip>_mode setting. The range is between -100 (totally left) and 100 (totally right).

usage:
set <soundchip>_balance Shows the current setting
set <soundchip>_balance 0 Plays the output of this chip on both the left and right channel
set <soundchip>_balance -100 Plays the output of this chip on only the left channel
set <soundchip>_balance 75 Plays the output of this chip mostly on the right channel, but also a bit on the left channel
examples:
set PSG_balance
set PSG_balance -100
set FMPAC_balance 0

<soundchip>_ch<channel>_record

Sets the filename to which the sound of an individual channel of individual sound chips should be recorded. When this setting is not set, no recording takes place and recording starts as soon as the setting is set. Normally, you would probably prefer to use the record_channels command to set up channel recording instead of this low level setting.

usage:
set <soundchip>_ch<channel>_record Shows the current setting
set <soundchip>_ch<channel>_record filename Starts recording the sound of the specified chip and channel to the file with name <filename>
examples:
set SCC_ch1_record
set PSG_ch3_record /tmp/PSG_ch3.wav

<soundchip>_ch<channel>_mute

Use to mute a specific channel of an individual sound chip. Normally, you would probably prefer to use the mute_channels command to set up channel muting instead of this low level setting.

usage:
set <soundchip>_ch<channel>_mute Shows the current setting
set <soundchip>_ch<channel>_record on Mutes the sound of the specified channel of the specified chip
set <soundchip>_ch<channel>_record off Unmutes the sound of the specified channel of the specified chip
examples:
set SCC_ch1_mute
set PSG_ch3_mute on
set SCC_ch5_mute off

<soundchip>_detune_frequency

Sets the frequency of the detune (a random variation in a sound's frequency) effect. It makes a sound fatter and more natural, as if played by a human being.

usage:
set <soundchip>_detune_frequency Shows the current setting
set <soundchip>_detune_frequency <num> Sets new detune frequency in Hz; 1 is minimum, 100 is maximum
examples:
set PSG_detune_frequency
set PSG_detune_frequency 5 (default)
Note: For now, this setting is only available for the PSG soundchip.
Note: It is often more convenient to use the psg_profile command.

<soundchip>_detune_percent

Sets the strength of the detune effect. By default it is 0, which means the effect is switched off.

usage:
set <soundchip>_detune_percent Shows the current setting
set <soundchip>_detune_percent <num> Sets new detune strength; 0 is minimum, 10 is maximum
examples:
set PSG_detune_percent
set PSG_detune_percent 0 (switched off, default)
set PSG_detune_percent 0.5 (recommended)
Note: For now, this setting is only available for the PSG soundchip.
Note: It is often more convenient to use the psg_profile command.

<soundchip>_vibrato_frequency

Sets the frequency of the vibrato (a periodic variation in a sound's frequency) effect.

usage:
set <soundchip>_vibrato_frequency Shows the current setting
set <soundchip>_vibrato_frequency <num> Sets new vibrato frequency in Hz; 1 is minimum, 10 is maximum
examples:
set PSG_vibrato_frequency
set PSG_vibrato_frequency 5 (default)
Note: For now, this setting is only available for the PSG soundchip.
Note: It is often more convenient to use the psg_profile command.

<soundchip>_vibrato_percent

Sets the strength of the vibrato effect. By default it is 0, which means the effect is switched off.

usage:
set <soundchip>_vibrato_percent Shows the current setting
set <soundchip>_vibrato_percent <num> Sets new vibrato strength; 0 is minimum, 10 is maximum
examples:
set PSG_vibrato_percent
set PSG_vibrato_percent 0 (switched off, default)
set PSG_vibrato_percent 1 (recommended)
Note: For now, this setting is only available for the PSG soundchip.
Note: It is often more convenient to use the psg_profile command.

<soundchip>_volume

Sets the volume for individual sound chips. The overall volume is controlled by the master_volume setting.

usage:
set <soundchip>_volume Shows the current setting
set <soundchip>_volume <num> Sets new volume; 0 is off, 100 is maximum
examples:
set PSG_volume
set PSG_volume 60
set "FMPAC_volume" 50

throttle

Sets throttle mode. In throttle mode the emulator tries to run at the specified speed relative to a real MSX (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 (normal operation)
set throttle off Turn throttle mode off (fast forward)

turborpause

Controls the pause key on a MSX turboR machine.

usage:
set turborpause Shows the current setting
set turborpause on Activate the pause key
set turborpause off Deactivate the pause key
Note: If you use this setting often, it may be useful to bind it to a key on your PC keyboard. See the bind and toggle commands.

umr_callback

Selects the Tcl procedure to be called when an Uninitialized Memory Read has been detected. This is useful for debugging MSX programs: uninitialized memory is not guaranteed to have any particular value, so reading it is most likely a bug.

By default this setting is empty, which means that nothing is done when an Uninitialized Memory Read is detected. We ship a useful procedure called umrcallback which logs all UMRs. You can activate it with set umr_callback umrcallback. You can find the source code for this procedure in scripts/umrcallback.tcl.

usage:
set umr_callback Shows the current UMR callback setting
set umr_callback umrcallback Sets callback proc to umrcallback

user_directories

Contains the list of "user directories". This makes it a bit more convenient to insert disks, tapes, ROMs etc. The Setup Guide describes how the user directories mechanism works. 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. When enabled, every VDP command is logged on stdout. This is useful when debugging MSX programs that use the VDP command engine.

usage:
set vdpcmdtrace Shows the current setting
set vdpcmdtrace on Enables VDP command tracing
set vdpcmdtrace off Disables VDP command tracing

videosource

Switch between MSX (V99x8) or GFX9000 (V9990) video source.

usage:
set videosource Shows the current setting
set videosource MSX Switch to normal MSX screen
set videosource GFX9000 Switch to GFX9000 screen
Note: This setting is only available if the gfx9000 extension is present.

v9990cmdtrace

Enable/disable V9990 command tracing. This is the V9990 equivalent of vdpcmdtrace.

usage:
set v9990cmdtrace Shows the current setting
set v9990cmdtrace on Enables V9990 command tracing
set v9990cmdtrace off Disables V9990 command tracing
Note: This setting is only available if the gfx9000 extension is present.

z80_freq / 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.5 MHz (or optionally 5.3 MHz on some machines). When z80_freq_locked is false the value of z80_freq is taken as the Z80 clock frequency.

examples:
Overclock Z80 to 14 MHz:
set z80_freq 14318180
set z80_freq_locked false

F8 switches between 3.5 MHz and 7 MHz:
set Z80_freq 7159090
bind F8 "toggle z80_freq_locked"

$Id: commands.html 10003 2009-06-07 20:54:16Z m9710797 $