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
   7. debug
   8. disk<x>
   9. diskmanipulator
   10. escape_grab
   11. exit
   12. ext
   13. hd<x>
   14. help
   15. incr
   16. iomap
   17. keymatrixdown / keymatrixup
   18. list_extensions
   19. load_settings
   20. machine
   21. machine_info
   22. openmsx_info
   23. palette
   24. plug / unplug
   25. record
   26. remove_extension
   27. reset
   28. save_settings
   29. screenshot
   30. set
   31. slotmap
   32. slotselect
   33. soundlog
   34. toggle
   35. trainer
   36. type
   37. unset
   38. update
   39. vdpregs
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. consoleplacement
   14. consolerows
   15. contrast
   16. cputrace
   17. debugoutput
   18. default_machine
   19. deinterlace
   20. display_deform
   21. frequency
   22. firmwareswitch
   23. fullscreen
   24. fullspeedwhenloading
   25. gamma
   26. glow
   27. grabinput
   28. icon.<name>.<setting>
   29. inputdelay
   30. keyjoystick<n>.<button>
   31. limitsprites
   32. master_volume
   33. maxframeskip
   34. midi-in-readfilename
   35. midi-out-logfilename
   36. minframeskip
   37. mute
   38. noise
   39. pause
   40. power
   41. printerlogfilename
   42. print-resolution
   43. r800_freq / r800_freq_locked
   44. renderer
   45. renshaturbo
   46. rs232-inputfilename
   47. rs232-outputfilename
   48. rtcmode
   49. samples
   50. save_settings_on_exit
   51. scale_algorithm
   52. scale_factor
   53. scanline
   54. sound_driver
   55. speed
   56. <soundchip>_mode
   57. <soundchip>_volume
   58. throttle
   59. umr_callback
   60. user_directories
   61. vdpcmdtrace
   62. videosource
   63. v9990cmdtrace
   64. 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.

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:

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

Iterates through the values of an enumerated setting.

debug

This command provides access to the debugger functionality of openMSX. It's meant to be used by an external debugger. 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:

disk<x>

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.

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.

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

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.

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

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.

openmsx_info

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

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.

record

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

The start subcommand also accepts an optional -audioonly or -videoonly flag. 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.

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.

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.

screenshot

Take a screenshot of the openMSX screen. This includes the console and icons if those are visible when the screenshot is taken. The screenshots are PNG files and are saved in the screenshots subdirectory of the openMSX data directory in your home directory.

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.

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.

update

Enable or disable update notifications of a certain type. This command is intended for external programs controlling openMSX.

vdpregs

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

Old Commands

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

alias / unalias

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

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

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.

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 brigtness 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 3x3 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 | x | 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. 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). Some renderers (OpenGL) can use an alpha channel, this channel is only present in PNG images.

consolecolumns

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

consolefont

Change the console font. 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). The image must contain a 16x16 matrix with the characters in ASCII order. Some renderers (OpenGL) require an alpha channel to have transparency in the font, this channel is only present in PNG images.

consoleplacement

Changes the position of the console on the emulator screen.

consolerows

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

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.

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.

display_deform

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

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

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.

icon.<name>.<setting>

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

Controls the appearance of the OSD LED icons.

<name> can be caps, fdd, kana, pause, power or turbo.

The position is set with the xcoord and ycoord settings. The active and non-active version have the same position. The value is in pixels and (0,0) corresponds to the top-left corner of the screen.

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

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

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.

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.

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.

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

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.

rs232-inputfilename

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

rs232-outputfilename

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

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 256x212) 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>_mode

Sets the channel mode for individual sound chips. Note that stereo chips can only be in stereo mode and mono chips can never be set to stereo mode.

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

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.

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.

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 6291 2007-04-14 19:56:47Z mthuurne $