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

usage:

`after time <seconds> <command>` | Execute a command after some time
`after idle <seconds> <command>` | Execute a command after some time being idle
`after frame <command>` | Execute a command 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"`
`after idle 100 exit`
`after info`
`after cancel 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> <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"`

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

Iterates through the values of an enumerated setting.

usage:

`cycle <setting>` | Changes the specified setting to the next 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. 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 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 IO 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 IO port (specify a single value), or on a whole memory or IO 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 disasm [<addr>]` | Disassemble instructions at PC or given address

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`, `vdp` etc.

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

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

### 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` | Shows all integer settings
`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.

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_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 mostly used for external applications controlling openMSX. For interactive use you can omit the machine handle to have the commands operate on the current 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.

usage:

`machine_info` | Shows a list of all possible topics
`machine_info <topic>` | Shows info on the given topic

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

### 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`

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

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

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

usage:

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

### set

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

usage:

`set` | Shows a list of all supported settings
`set <setting>` | Query the current value of the specified setting
`set <setting> <value>` | Change the specified setting to the given value

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

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

usage:

`update enable <type>` | enable notifications for this type
`update disable <type>` | disable notifications for this type

examples:
`update enable led`
`update disable setting`

### vdpregs

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

usage:

`vdpregs` | Shows the current VDP control register contents

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

usage:

`alias <name> <command>` | Defines an alias

examples:
`alias gl "set renderer SDLGL"`
`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` | Shows all integer settings
`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 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.

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: Not all renderers support this.

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

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

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 greyscale

Note: It is often more convenient to use the `scripts/monitor.tcl` script.

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

usage:

`set consolebackground` | Shows the current setting
`set consolebackground <image>` | Sets a new background 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. 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.

usage:

`set consolefont` | Shows the current setting
`set consolefont <image>` | Sets a new font

### consoleplacement

Changes the position of the console on the emulator screen.

usage:

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

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

usage:

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

### 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 horizontal_stretch` | Stretches the image horizontally, to match the aspect ratio of the real MSX
`set display_deform 3d` | Deforms the image in 3D, to look like a CRT (like JEmu2)

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

usage:

`set grabinput` | Shows the current setting
`set grabinput on` | Starts grabbing all input events
`set grabinput off` | Stops grabbing all input events

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

usage:

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

Note: In the future the position `xcoord` and `ycoord` settings will most likely change so that it is resolution independent (see `scale_factor` setting)

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

### 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`

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

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.

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

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

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

usage:

`set <soundchip>_mode` | Shows the current setting
`set <soundchip>_mode mono` | Plays a mono sound on both the left and right channel
`set <soundchip>_mode left` | Plays a mono sound on only the left channel
`set <soundchip>_mode right` | Plays a mono sound on only the right channel

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

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

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