openMSX Console Command Reference

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

Introduction

This manual describes all commands and settings which are available in openMSX. You can use them to control openMSX fully from the Console (a built in command line interface, use F10 to call it), via Tcl scripts and via remote connections (explained in Controlling openMSX from External Applications). If you want to unleash the full potential of openMSX or just want a reference of all available possibilities, this manual should serve you well.

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.

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. Any Tcl command or combination of commands separated with ; (normal Tcl syntax) can be used. 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. Using the -repeat option makes sure that if the event is repeated (especially useful for key events, so when keeping a key pressed), the command is repeated as well.

Events can be:

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.

cassetteplayer

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

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.

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.

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:

The probe subcommand again has subcommands:

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:

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.

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.

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.

exit

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

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.

filepool

With this command you can manage your file pool settings. File pools are directories on your host system (PC/Mac/Dingoo/etc.). They are used by openMSX to search files in, which are referred to from machine or extension definition files, save states or replays which you are trying to load. First, the file will be searched at the path that was also used when the save state or replay was created. But if it isn't found there (which is usually the case if you load such a state or replay you got from someone else), it will use the file pools to search instead. In other words, if you are trying to load such replays, it's probably a good idea to put the media files referred to (ROMs, disks, tapes) in the (proper) filepool.

File pools have the following properties:

path

The path to the directory which is the actual file pool

position

There exists a list of file pools, which are searched in order of their position.

type(s)

A file pool can serve specific types. Currently, the valid types are system_rom (for system ROMs, you are probably using this one already if you installed your system ROMs in the recommended place, share/systemroms), rom (for other ROM files), disk (for disk images) and tape for cassette/tape images.

Apart from the default sytem ROM file pool as mentioned above, the other default file pool is share/software, where openMSX will search for other (than system ROM) software.

An example of the default file pools for a Windows 7 system with user Quibus:

1: C:/Users/Quibus/Documents/openMSX/share/systemroms  [system_rom]
2: C:/Users/Quibus/Documents/openMSX/share/software  [rom disk tape]
3: C:/Program Files/openMSX/share/systemroms  [system_rom]
4: C:/Program Files/openMSX/share/software  [rom disk tape]

The first one is the system ROMs dir in the user's home directory. The second is the (new) software file pool for other software in the user's home directory. The last two are similar, but then on system level. On a UNIX like system, you get something very similar.

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.

help

Shows help info for console commands.

incr

Increment an integer setting.

iomap

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

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.

laserdiscplayer

Controls the Laserdisc player; a Laserdisc can be inserted or ejected. When a real Laserdisc player is connected to an MSX, no other controls are available either.

Note that this command is only available when the Pioneer PX-7 or Pioneer PX-V60 is being emulated

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.

load_icons

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

Icon sets are stored in the share/skins directory.

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.

machine

Switch to a new MSX 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.

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:

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.

monitor_type

Select a monitor color profile.

mute_channels / unmute_channels / solo

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

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:

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.

openmsx_info

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

openmsx_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.

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.

plug / unplug

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

psg_profile

Select a PSG sound profile.

record

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

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.

If any stereo sound devices are present or any sound device has an off-center balance, the recording will be made in stereo, otherwise it will be mono. If a recording is made in mono and then a stereo sound device is added, you'll receive a warning that stereo sound has been detected and that the two channels will be mixed down to mono. You can prevent this from happening by using the -stereo option to force a stereo recording even if no stereo devices are present at the time you enter the command. You can also force a mono recording with -mono to save space.

The soundlog command is a shorthand for record -audioonly.

Use record_chunks if you want some extra options. You can control the maximum length (in seconds) to record and also set up multiple recordings of a certain length. This is very useful if you want to record for e.g. YouTube. The default length is 14:59 (to make sure YouTube will accept it). Using this command implies -doublesize.

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. You can also specify all for the device, which means that all sound devices in the currently running MSX will be recorded. When starting recording, an option -prefix can be given to specify a filename prefix.

remove_extension

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

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.

reverse

Controls the reverse feature. When this feature is enabled (the default), openMSX will collect data while emulating, which enables you to go back (and forward) in MSX time. In other words: you cannot use the commands to go back and forward in time, if you disable the feature.

There are some extra helper commands to make the feature easier to use.

Because the reverse feature is very useful, it is automatically enabled via auto_enable_reverse setting.

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.

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' raw MSX screen, pass the -raw option. The screenshots are PNG files and (by default) are saved in the screenshots subdirectory of the openMSX data directory in your home directory. There's also an option -no-sprites to take a screenshot with sprite rendering disabled.

set

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

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

slotmap

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

slotselect

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

soundlog

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

This command is a shorthand for record -audioonly.

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.

restore_machine:

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

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.

toggle

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

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.

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.

unset

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

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.

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.

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.

decr

Decrement an integer setting.

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

quit

Quits the emulator.

Please use exit instead.

restoredefault

Restore the default value for a setting.

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

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.

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.

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.

autorunlaserdisc

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

auto_enable_reverse

Using the reverse feature has a small memory and performance cost. Therefore it has to be enabled before it can be used. This setting controls whether the reverse feature should automatically be activated when openMSX starts. On desktop computers this generally won't be a problem. But for small handheld devices it can be.

blur

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

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.

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.

cmdtiming

Controls VDP command execution timing.

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

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 } }
  

console

Turns the openMSX on-screen console on or off.

consolebackground

Change the console background image. Only images in the PNG format are supported. Background images may also have an alpha channel (amount of transparency per pixel).

consolecolumns

Change the width of the console measured by the number of columns.

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.

consolefontsize

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

console_history_size

Determines how many commands are saved into the console history.

consoleplacement

Changes the position of the console on the emulator screen.

consolerows

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

console_remove_doubles

Determines whether the console history remembers two identical subsequent commands.

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.

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.

debugoutput

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

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

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.

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.

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.

disablesprites

Can be used to disable sprite rendering. Only the rendering itself is disabled, all other MSX behaviour (like sprite collision detection) stays the same.

display_deform

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

enable_session_management

Controls session management. When enabled, openMSX will store the state of all machines when you exit openMSX and restore that state again when starting it up next time. Note that the reverse history is not saved.

Sessions can also be saved manually with the command save_session, and explicitly loaded with load_session. A list of saved sessions can be retrieved with list_sessions.

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.

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.

fullscreen

Switch to/from fullscreen mode.

fullspeedwhenloading

When enabled, openMSX will try to detect when the MSX is loading from diskette, cassette or laserdisc. 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.

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.

glow

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

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.

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).

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.

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.

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.

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.

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'.

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.

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.

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.

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.

master_volume

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

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.

midi-in-readfilename

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

midi-out-logfilename

Sets the file to which the MIDI output is logged. By default, it logs to /dev/midi when available.

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.

mode

Sets the active mode. A mode is a set of settings (mostly key bindings, but also OSD widgets that are activated) that are most suitable for a certain task. Currently only mode 'normal' and 'tas' exist.

TAS mode

So far, the only special mode is the TAS mode, which is made for doing Tool Assisted Speedruns, with TAS widgets and easier ways to save replays. It is still experimental, but already very useful for doing a TAS. This mode enables the following widgets:

• frame counter (can also be toggled with toggle_frame_counter), which shows the VDP (not V9990) frame number on screen
• cursors (can also be toggled with toggle_cursors), shows which keys (important for games) are pressed

It also (re)enables the reverse bar widget.

The mode configures the following key bindings, overriding any existing key bindings (note: Mac key bindings are not proper yet...):

Note that this mode is still experimental and may change in future releases!

mute

Mute/unmute all sound output.

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.

pause

Pauses the emulation.

pause_on_lost_focus

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

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.

power

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

printerlogfilename

Sets the file to which the printer logger writes.

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.

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.

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.

resampler

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

rs232-inputfilename

Sets the file from which the RS232-tester reads data. Note that the rs232-tester has to be plugged in the msx-rs232 connector for this to become useful. When plugging the tester, this setting needs to point to a valid file.

rs232-outputfilename

Sets the file to which the RS232-tester writes the data. Note that the rs232-tester has to be plugged in the msx-rs232 connector for this to become useful. When plugging the tester, this setting needs to point to a valid file.

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.

samples

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

save_settings_on_exit

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

scale_algorithm

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

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.

scanline

Sets the amount of scanline effect.

sound_driver

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

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.

<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).

<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.

<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.

<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.

<soundchip>_detune_percent

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

<soundchip>_vibrato_frequency

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

<soundchip>_vibrato_percent

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

<soundchip>_volume

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

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.

turborpause

Controls the pause key on a MSX turboR machine.

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.

vdpcmdinprogress_callback

Selects the Tcl procedure to be called when a write to a VDP command engine register is detected while there is still a VDP command in progress. Often this is an indication of a bug in the running MSX program. Note that writes to VDP register R#44 with a command in progress are normal behaviour, so the callback is not triggered for such writes.

By default this setting is empty, which means that nothing is done when a suspicious VDP command engine write is detected. We ship an example proc called vdpcmdinprogresscallback which simply logs all occurrences. You can activate it with set vdpcmdinprogress_callback vdpcmdinprogresscallback. You can find the source code for this proc in scripts/umrcallback.tcl. Feel free to write your own proc that does exactly what you need. For example it might be a good idea to execute debug break in your callback, so that you can easily examine what code triggered this write.

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.

videosource

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

v9990cmdtrace

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

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.

$Id: commands.html 12343 2012-01-07 11:51:03Z m9710797 $