<p>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 <aclass="external"href="openmsx-control.html">Controlling openMSX from External Applications</a>). 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.</p>
201
202
<h2><aid="commands">Commands</a></h2>
203
204
<h3><aid="after">after</a></h3>
205
206
<p>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.
207
Every postponed command executes just once; if you want a command to run periodically, you have to issue it again every time it runs.
208
The <code>after</code> command returns the id of the postponed command.
209
It is possible to query a list of
210
postponed commands and also to cancel postponed commands.</p>
211
212
<divclass="subsectiontitle">
213
usage:
214
</div>
215
216
<table>
217
<tr>
218
<td><code>after time <seconds><command></code></td>
219
220
<td>Execute a command after some time. Timescale is in MSX seconds.</td>
<td>Execute a command after the given input event occurs. The events are e.g. mouse, joystick, focus and resize events, the same ones as for the <aclass="internal"href="#bind">bind</a> command.</td>
270
</tr>
271
272
<tr>
273
<td><code>after info</code></td>
274
275
<td>List all postponed commands</td>
276
</tr>
277
278
<tr>
279
<td><code>after cancel <id></code></td>
280
281
<td>Cancel the postponed command with given id</td>
282
</tr>
283
</table>
284
285
<divclass="subsectiontitle">
286
examples:
287
</div>
288
289
<divclass="examples">
290
<code>after time 2.6 "set renderer SDLGL-PP"</code><br />
React to joystick or cursor up movement in a Tcl script:<br />
442
<code>bind_default "OSDcontrol UP PRESS" -repeat {osd_menu::menu_action UP }</code><br />
443
React to joystick button 1 or spacebar press in a Tcl script:<br />
444
<code>bind_default "OSDcontrol A PRESS" -repeat {osd_menu::menu_action A }</code><br />
445
</div>
446
447
<h3><aid="cart">cart / cart<x></a></h3>
448
449
<p>Insert a ROM cartridge in a running MSX. The <code>cart</code> command inserts the cartridge in the first available slot. The <code>carta</code>, <code>cartb</code> etc. commands insert it in the specified slot. The cartridges can be removed again with the <code>eject</code> subcommand.</p>
450
451
<p>ROM cartridges are a special class of extensions. For extensions that are not ROM cartridges, see the commands <code><aclass="internal"href="#ext">ext</a></code>, <code><aclass="internal"href="#list_extensions">list_extensions</a></code> and <code><aclass="internal"href="#remove_extension">remove_extension</a></code>.</p>
<p>Cycle through the current running machines.</p>
600
601
<p><code>cycle_back_machine</code> does the same as <code>cycle_machine</code>, but it goes in the opposite direction.</p>
602
603
<divclass="subsectiontitle">
604
usage:
605
</div>
606
607
<table>
608
<tr>
609
<td><code>cycle_machine</code></td>
610
<td>Changes the current machine to the next one in the cycle</td>
611
</tr>
612
<tr>
613
<td><code>cycle_back_machine</code></td>
614
<td>Changes the current machine to the previous one in the cycle</td>
615
</tr>
616
</table>
617
618
619
<h3><aid="debug">debug</a></h3>
620
621
<p>This command provides access to the debugger functionality of openMSX. It can be used by an external debugger (see also <aclass="external"href="openmsx-control.html">Controlling openMSX from External Applications</a>), but openMSX has since evolved to include its own debugger. The general format of the debug command is:</p>
<td><aclass="internal"href="#debug-trace">Trace related commands</a>.</td>
726
</tr>
727
728
<tr>
729
<td><code>debug disasm [<addr>]</code></td>
730
<td>Disassemble instructions at PC or given address</td>
731
</tr>
732
733
</table>
734
735
<p>This command is much better documented in openMSX itself. Type <code>help debug</code> or <code>help debug <subcommand></code> for more detailed help.</p>
<td>List all active breakpoints. The result is a Tcl dict where each key is a breakpoint ID and each value is another dict containing the properties of that breakpoint (see <code>create</code> below).</td>
<td>Create a new breakpoint with the given properties and return its ID. Supported properties:
750
<ul>
751
<li><code>-address</code>: the address where the breakpoint should trigger. An address is just a number [0..0xFFFF], but can also be dynamically evaluated from a known symbol by specifying <code>{$sym(MySymbol)}</code>.</li>
752
<li><code>-condition</code>: a Tcl expression that must evaluate to true for the breakpoint to trigger (default = no condition).</li>
753
<li><code>-command</code>: a Tcl command that should be executed when the breakpoint triggers (default = <code>debug break</code>).</li>
754
<li><code>-enabled</code>: set to false to (temporarily) disable this breakpoint.</li>
755
<li><code>-once</code>: if true, the breakpoint is automatically removed after it triggered (default = false, meaning recurring).</li>
<td>List all active watchpoints. The result is a Tcl dict where each key is a watchpoint ID and each value is another dict containing the properties of that watchpoint (see <code>create</code> below).</td>
<td>Create a new watchpoint with the given properties and return its ID. Supported properties:
784
<ul>
785
<li><code>-type</code>: one of <code>read_io</code>, <code>write_io</code>, <code>read_mem</code> or <code>write_mem</code>.</li>
786
<li><code>-address</code>: the address(es) where the watchpoint should trigger, either a single address or a begin/end pair. An address is just a number [0..0xFFFF], but can also be dynamically evaluated from a known symbol by specifying <code>{$sym(MySymbol)}</code>.</li>
787
<li><code>-condition</code>: a Tcl expression that must evaluate to true for the watchpoint to trigger (default = no condition).</li>
788
<li><code>-command</code>: a Tcl command that should be executed when the watchpoint triggers (default = <code>debug break</code>).</li>
789
<li><code>-enabled</code>: set to false to (temporarily) disable this watchpoint.</li>
790
<li><code>-once</code>: if true, the watchpoint is automatically removed after it triggered (default = false, meaning recurring).</li>
<p>A debug condition is evaluated continuously while the emulated MSX is
811
running; unlike breakpoints and watchpoints it is not tied to a specific
812
address or I/O access.</p>
813
814
<table>
815
<tr>
816
<td><code>debug condition list</code></td>
817
<td>List all active debug conditions. The result is a Tcl dict where each key is a debug condition ID and each value is another dict containing the properties of that condition (see <code>create</code> below).</td>
<td>Set a breakpoint on the given probe and return its ID. When <code>-once</code> is given, the breakpoint is automatically removed after it triggered. <code><cond></code> is an optional Tcl expression that must evaluate to true for the breakpoint to trigger; <code><cmd></code> is an optional Tcl command that should be executed when the breakpoint triggers (default = <code>debug break</code>).</td>
<td>Remove the probe breakpoint with the given ID.</td>
877
</tr>
878
879
<tr>
880
<td><code>debug probe list_bp</code></td>
881
<td>Returns all breakpoints that are set on probes, as a Tcl dict where each key is a probe-breakpoint ID and each value contains the probe name, the condition and the command.</td>
<p>Watch expressions are mostly a GUI feature: they are evaluated while the
890
emulated MSX is running and their values are shown in the debugger view of
891
the openMSX GUI (menu bar > Debugger > Watch expression).</p>
892
893
<table>
894
<tr>
895
<td><code>debug watchexpr list</code></td>
896
<td>List all active watch expressions. The result is a Tcl dict where each key is a watch expression ID and each value is another dict containing the properties of that expression (see <code>create</code> below).</td>
<td>Add a new data point to the trace with the given name (the trace is created on first use); the timestamp of the data point is the current emulation time. The optional value can be an integer, a floating point number or a string; if no value is given, a void value is used. Flags: <code>-merge</code> ignores consecutive equal values; <code>-description <text></code> gives a description for this trace; <code>-type <t></code> must be one of <code>void</code>, <code>bool</code>, <code>int</code>, <code>double</code> or <code>string</code>; <code>-format <f></code> must be one of <code>bin</code>, <code>dec</code> or <code>hex</code> (only relevant for type int). Typically the latter three options are only used once, while <code>-merge</code> is repeated on every invocation.</td>
973
</tr>
974
975
<tr>
976
<td><code>debug trace list [<name>]</code></td>
977
<td>Without arguments, list the names of all created traces. With a name argument, list all data points of the given trace in chronological order; each data point consists of a timestamp (seconds since emulation start) and a value.</td>
978
</tr>
979
980
<tr>
981
<td><code>debug trace drop [<name>]</code></td>
982
<td>Without arguments, drop all traces and their data points. With a name argument, drop only the trace with the given name (this also removes traces that were being filled automatically via <code>debug trace probe</code>).</td>
<td>Start collecting changes of the given <aclass="internal"href="#debug-probe">probe</a>: as if on each change there's an automatic <code>debug trace add <name><value></code>.</td>
988
</tr>
989
</table>
990
991
<p>A convenient wrapper around these subcommands is the <code>cpu_trace</code>
992
Tcl procedure (defined in <code>scripts/_trace.tcl</code>): execute e.g.
993
<code>cpu_trace instr A HL</code> to trace the executed instructions together
994
with the A and HL register values, and execute <code>cpu_trace</code> without
995
arguments to disable tracing again. Note this can be expensive and/or can
996
quickly consume a lot of memory: the Z80 (and certainly the R800) can execute
997
almost one million instructions per second, so it is recommended to enable
998
only those items you need and to limit the trace duration.</p>
999
1000
<p>Many examples of usage of the debug command can be found in the scripts that come with openMSX (in the <code>share/scripts</code> directory). We also list a few here.
1001
</p>
1002
1003
<divclass="subsectiontitle">
1004
examples:
1005
</div>
1006
1007
<divclass="examples">
1008
<ul>
1009
<li>break (only!) after 0 is written to 0x8000):<br/>
<li>list the contents of all symbol files previously loaded by the Symbol Manager or by the <code>debug symbols load</code> subcommand:<br/>
1022
<code>debug symbols lookup</code></li>
1023
</ul>
1024
</div>
1025
1026
<divclass="note">
1027
Note: Some of the commands are pretty low level. In the share/scripts directory you'll find some Tcl scripts that
1028
offer convenience wrappers around these commands. For example: <aclass="internal"href="#other"><code>showmem</code></a>, <aclass="internal"href="#other"><code>disasm</code></a>, <aclass="internal"href="#other"><code>cpuregs</code></a>, <aclass="internal"href="#other"><code>save_debuggable</code></a>, etc.
<p>Insert a disk image in a drive. Optionally apply an IPS patch to the disk image.
1034
The commands <code>diska</code>, <code>diskb</code> etc. are
1035
assigned to all available "physical" disk drives in the MSX. They might not correspond to drive names as used in
1036
MSX-DOS.</p>
1037
1038
<p>In addition to the physical <code>disk<x></code> drives, there is the <code>virtual_drive</code>. This fake drive does not correspond to any MSX hardware. It can be used as a source or target for <code><aclass="internal"href="#diskmanipulator">diskmanipulator</a></code> operations just like physical drives.</p>
<p>A collection of commands to manipulate (the files on) a disk image.</p>
1074
1075
<p>It can be used in so many different ways, that we wrote a separate manual for it: <aclass="external"href="diskmanipulator.html">Using Diskmanipulator</a>.</p>
1076
1077
<h3><aid="escape_grab">escape_grab</a></h3>
1078
1079
<p>Only has effect in windowed mode and when the <code><aclass="internal"href="#grabinput">grabinput</a></code> setting is active. Temporarily release the input grab.
1080
After the openMSX window has lost and regained the focus, the grab is again effective.</p>
1081
1082
<divclass="subsectiontitle">
1083
usage:
1084
</div>
1085
1086
<table>
1087
<tr>
1088
<td><code>escape_grab</code></td>
1089
1090
<td>Temporarily release the input grab</td>
1091
</tr>
1092
</table>
1093
1094
<h3><aid="exit">exit</a></h3>
1095
1096
<p>Terminate the openMSX application. Optionally you can pass an exit-code.</p>
1097
1098
<divclass="subsectiontitle">
1099
usage:
1100
</div>
1101
1102
<table>
1103
<tr>
1104
<td><code>exit [exit-code]</code></td>
1105
<td>Exits the emulator</td>
1106
</tr>
1107
</table>
1108
1109
<h3><aid="ext">ext / ext<x></a></h3>
1110
1111
<p>Insert an MSX extension in a running MSX machine. The <code>ext</code> command inserts the extension in the first available slot. The <code>exta</code>, <code>extb</code> etc. commands insert it in the specified slot. The extension can be removed again with the <code><aclass="internal"href="#remove_extension">remove_extension</a></code>
1112
command. See also the commands <code><aclass="internal"href="#cart">cart</a></code>, <code><aclass="internal"href="#list_extensions">list_extensions</a></code> and <code><aclass="internal"href="#remove_extension">remove_extension</a></code>.</p>
1113
1114
<p>To get a list of possible extensions it's convenient to use the tab-completion feature, i.e. type '<code>ext<space><tab></code>'. Alternatively the command '<code><aclass="internal"href="#openmsx_info">openmsx_info</a> extensions</code>' gives you the same information (and is easier to use in a scripting context).</p>
1115
1116
<p>Note that some extensions (i.e. those without any memory) will not physically occupy any slot when inserted, even when they were inserted in a specific slot.</p>
1117
1118
<divclass="subsectiontitle">
1119
usage:
1120
</div>
1121
1122
<table>
1123
<tr>
1124
<td><code>ext fmpac</code></td>
1125
1126
<td>Insert an FMPAC in a running MSX machine in the first free slot</td>
1127
</tr>
1128
<tr>
1129
<td><code>extb scc</code></td>
1130
1131
<td>Insert the empty SCC cart in slot B of the running MSX machine</td>
1132
</tr>
1133
</table>
1134
1135
<h3><aid="filepool">filepool</a></h3>
1136
1137
<p>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) file pool.</p>
1138
1139
<p>File pools have the following properties:</p>
1140
<dl>
1141
<dt>path</dt>
1142
<dd>The path to the directory which is the actual file pool</dd>
1143
1144
<dt>position</dt>
1145
<dd>There exists a list of file pools, which are searched in order of their position.</dd>
1146
1147
<dt>type(s)</dt>
1148
<dd>A file pool can serve specific types. Currently, the valid types are
1149
<dl>
1150
<dt><code>system_rom</code></dt>
1151
<dd>for system ROMs, you are probably using this one already if you installed your system ROMs in the recommended place <code>share/systemroms</code>,</dd>
1152
<dt><code>rom</code></dt>
1153
<dd>for other ROM files,</dd>
1154
<dt><code>disk</code></dt>
1155
<dd>for disk images and</dd>
1156
<dt><code>tape</code></dt>
1157
<dd>for cassette/tape images.</dd>
1158
</dl>
1159
</dd>
1160
</dl>
1161
1162
<p>Apart from the default system ROM file pool as mentioned above, the other default file pool is <code>share/software</code>, which is configured for all other (than type <code>system_rom</code>) software files.</p>
1163
1164
<divclass="subsectiontitle">
1165
usage:
1166
</div>
1167
1168
<table>
1169
<tr>
1170
<td><code>filepool list</code></td>
1171
1172
<td>Shows the currently defined file pool entries (see below for example output)</td>
<td>Add a new entry with the given properties as explained above. For the types, use a format like <code>"rom tape disk"</code>. Optionally, you can also specify where in the list of existing file pools the new file pool should be added. By default, this is at the end.</td>
4: C:/Program Files/openMSX/share/software [rom disk tape]
1200
</pre>
1201
<p>The first one is the system ROMs dir in the user's home directory. The second is the 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.</p>
1202
1203
<h3><aid="findcheat">findcheat</a></h3>
1204
1205
<p>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 <code><aclass="internal"href="#trainer">trainer</a></code> command.</p>
1206
1207
<p>It works more or less like this:</p>
1208
<ol>
1209
<li>Initialize the <code>findcheat</code> tool, this takes an initial snapshot of the MSX memory.</li>
1210
<li>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.</li>
1211
<li>Now use the <code>findcheat</code> tool to compare the current MSX memory state with the previous memory snapshot. <code>findcheat</code> 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.</li>
1212
<li><code>findcheat</code> will show a list of memory locations that still match the search criteria.</li>
1213
<li>If there still are still too many matches, repeat from step 2.</li>
1214
</ol>
1215
1216
<p>Vampier made a video tutorial on how to use <code>findcheat</code>, you can find it <aclass="external"href="http://www.youtube.com/watch?v=F11ltfkCtKo">here</a>.</p>
<p>Shows the (text) content of the clipboard as a string.</p>
1221
1222
<divclass="subsectiontitle">
1223
usage:
1224
</div>
1225
1226
<table>
1227
<tr>
1228
<td><code>get_clipboard_text</code></td>
1229
1230
<td>Returns the text content of the clipboard as a string.</td>
1231
</tr>
1232
</table>
1233
1234
1235
<h3><aid="hd">hd<x></a></h3>
1236
1237
<p>Change the hard disk image. The commands <code>hda</code>, <code>hdb</code> etc. are assigned to all available hard disk drives in the MSX. They will not correspond to drive names as used in MSX-DOS.</p>
<td>Show current hard disk image for hard disk "hda"</td>
1260
</tr>
1261
</table>
1262
1263
<divclass="note">
1264
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 <code>hd<x></code> commands unless the MSX is powered off. See <code><aclass="internal"href="#power">power</a></code> setting.
<td>Increment the specified setting by the given amount (can be negative)</td>
1311
</tr>
1312
</table>
1313
1314
<divclass="subsectiontitle">
1315
examples:
1316
</div>
1317
1318
<divclass="examples">
1319
<code>incr speed</code><br />
1320
<code>incr renshaturbo 10</code><br />
1321
<code>incr scanline -5</code>
1322
</div>
1323
1324
<h3><aid="iomap">iomap</a></h3>
1325
1326
<p>Shows what I/O ports are connected to which devices. The related command <code><aclass="internal"href="#slotmap">slotmap</a></code> shows a similar overview, but for memory-mapped devices.</p>
1327
1328
<divclass="subsectiontitle">
1329
usage:
1330
</div>
1331
1332
<table>
1333
<tr>
1334
<td><code>iomap</code></td>
1335
1336
<td>Shows the I/O map of the current MSX machine</td>
<p>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 <ahref="http://map.grauw.nl/articles/keymatrix.php">article on the MAP</a>.</p>
<p>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.</p>
1372
1373
<p>Note that this command is only available when the Pioneer PX-7 or Pioneer PX-V60 MSX machine is being emulated, and only when openMSX was built with Laserdisc support (Laserdisc support is an optional compile-time feature)</p>
<p>Returns a list of inserted cartridges and extensions. These can be removed with the <code><aclass="internal"href="#remove_extension">remove_extension</a></code> command or
1396
additional items can be added with the <code><aclass="internal"href="#cart">cart</a></code> and <code><aclass="internal"href="#ext">ext</a></code> commands.</p>
1397
1398
<divclass="subsectiontitle">
1399
usage:
1400
</div>
1401
1402
<table>
1403
<tr>
1404
<td><code>list_extensions</code></td>
1405
1406
<td>Lists all currently inserted cartridges and extensions</td>
1407
</tr>
1408
</table>
1409
1410
<h3><aid="load_settings">load_settings</a></h3>
1411
1412
<p>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 <code><aclass="internal"href="#save_settings">save_settings</a></code>.</p>
<td>Switch to the specified machine, also returns the handle for that machine</td>
1445
</tr>
1446
</table>
1447
1448
<divclass="note">
1449
Note: The machine handle is mostly used by external applications controlling openMSX (see also <aclass="external"href="openmsx-control.html">Controlling openMSX from External Applications</a>). For interactive use you can omit the machine handle to have the commands operate on the current machine.
<p>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.</p>
1456
1457
<p>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.</p>
1458
1459
<table>
1460
<tr>
1461
<td><code>diska <diskimage></code></td>
1462
<td>execute the diska command in the active machine</td>
<td>execute the diska command in the specified machine</td>
1467
</tr>
1468
</table>
1469
1470
<h4><code>create_machine</code>:</h4>
1471
<p>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.</p>
1472
1473
<h4><code>load_machine</code>:</h4>
1474
<p>This command loads a machine configuration (= MSX model) into the given machine-ID.
1475
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 reload a different page in the same tab, you can only load a machine configuration once in the same machine-ID.</p>
1476
1477
<h4><code>activate_machine</code>:</h4>
1478
<p>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.</p>
1479
1480
<h4><code>list_machines</code>:</h4>
1481
<p>Returns a list of all currently existing machine-IDs.</p>
1482
1483
<h4><code>delete_machine</code>:</h4>
1484
<p>Deletes the given machine-ID. This is analogue to closing a tab in a web browser.</p>
<td>load an MSX2 configuration in that new machineID</td>
1499
</tr>
1500
<tr>
1501
<td><code>activate_machine $newID</code></td>
1502
<td>switch to the new machine</td>
1503
</tr>
1504
<tr>
1505
<td><code>activate_machine $oldID</code></td>
1506
<td>switch back to old machine</td>
1507
</tr>
1508
<tr>
1509
<td><code>delete_machine $newID</code></td>
1510
<td>delete new machine</td>
1511
</tr>
1512
</table>
1513
1514
<divclass="note">
1515
If you don't care about multiple active machines, the <code><aclass="internal"href="#machine">machine</a></code> command is much more convenient to switch to a different MSX configuration.
1516
</div>
1517
1518
1519
<h3><aid="machine_info">machine_info</a></h3>
1520
1521
<p>Shows information about a certain topic. This command is similar to the <code><aclass="internal"href="#openmsx_info">openmsx_info</a></code> command. The topics of
1522
<code>machine_info</code> are all machine specific, while the topics of <code><aclass="internal"href="#openmsx_info">openmsx_info</a></code> are generic.</p>
1523
1524
<divclass="subsectiontitle">
1525
usage:
1526
</div>
1527
1528
<table>
1529
<tr>
1530
<td><code>machine_info</code></td>
1531
1532
<td>Shows a list of all possible topics</td>
1533
</tr>
1534
1535
<tr>
1536
<td><code>machine_info <topic></code></td>
1537
1538
<td>Shows info on the given topic</td>
1539
</tr>
1540
</table>
1541
1542
<h3><aid="message">message</a></h3>
1543
<p>Show a message, with optional level (info, warning, error). By default this message will be shown in a coloured box at the top of the screen for a (short) duration and then fade away.</p>
<p>Mute or unmute specific individual channels of sound devices. The syntax is very similar to the <code><aclass="internal"href="#record_channels">record_channels</a></code> command.</p>
<td>Mute the specified channels of the specified device(s). If a device is given but no specific channels are specified, all channels of that device are muted. If no arguments are given at all, this command return a list of all currently muted channels.</td>
<td>Unmute the specified channels of the specified device(s). If a device is given but no specific channels are specified, all channels of that device are unmuted. If no arguments are given at all, this command unmutes all channels of all devices. </td>
command. They can be used to access the more advanced diskimage insertion
1698
options.</p>
1699
1700
<p>In some cases it is needed to reboot the MSX before the changes take
1701
effect. In those cases you'll get a message that warns about this.</p>
1702
1703
<divclass="subsectiontitle">examples:</div>
1704
<table>
1705
<tr>
1706
<td><code>nowinda -a image.dsk -j</code></td>
1707
<td>Image.dsk is inserted into drive A: and the romdisk will be drive B:.
1708
Other diskroms will be able to install drives as well. For example when
1709
the MSX has an internal diskdrive, drive C: en D: will be available as
1710
well.</td>
1711
</tr>
1712
<tr>
1713
<td><code>nowinda disk1.dsk disk2.dsk</code></td>
1714
<td>The two images will be inserted in A: and B: respectively.</td>
1715
</tr>
1716
<tr>
1717
<td><code>nowinda -m hdimage.dsk</code></td>
1718
<td>Inserts a harddisk image. All available partitions will be mounted
1719
as drives.</td>
1720
</tr>
1721
<tr>
1722
<td><code>nowinda -m hdimage.dsk:1</code></td>
1723
<td>Inserts the first partition only.</td>
1724
</tr>
1725
<tr>
1726
<td><code>nowinda -m hdimage.dsk:2-4</code></td>
1727
<td>Inserts the 2nd, 3th and 4th partition as drive A: B: and C:.</td>
1728
</tr>
1729
</table>
1730
1731
1732
<h3><aid="openmsx_info">openmsx_info</a></h3>
1733
1734
<p>Shows information about a certain topic. For machine-specific topics, use the related command <code><aclass="internal"href="#machine_info">machine_info</a></code>.</p>
1735
1736
<divclass="subsectiontitle">
1737
usage:
1738
</div>
1739
1740
<table>
1741
<tr>
1742
<td><code>openmsx_info</code></td>
1743
1744
<td>Shows a list of all possible topics</td>
1745
</tr>
1746
1747
<tr>
1748
<td><code>openmsx_info <topic></code></td>
1749
1750
<td>Shows info on the given topic</td>
1751
</tr>
1752
</table>
1753
1754
1755
<h3><aid="openmsx_update">openmsx_update</a></h3>
1756
1757
<p>Enable or disable update notifications of a certain type. This command is intended for external programs controlling openMSX. More about this in <aclass="external"href="openmsx-control.html">Controlling openMSX from External Applications</a>.</p>
<p>openMSX has the possibility to show OSD (on screen display) elements. For example, the game overlays and TAS tools are implemented via OSD elements. This command allows to create new OSD elements, configure existing elements or delete elements.</p>
1790
1791
<p>This command is only useful if you plan to adjust or enhance the openMSX OSD, or create your own OSD widgets.</p>
1792
1793
<!-- do we really have to repeat the help text from the openmsx source code here? -->
1794
1795
<p>Execute "<code>help osd</code>" to get a detailed description of this command, which we will not repeat here.</p>
1796
1797
<h3><aid="palette">palette</a></h3>
1798
1799
<p>Shows the current VDP palette settings. Related command: <code><aclass="internal"href="#vdpregs">vdpregs</a></code>.</p>
1800
1801
<divclass="subsectiontitle">
1802
usage:
1803
</div>
1804
1805
<table>
1806
<tr>
1807
<td><code>palette</code></td>
1808
1809
<td>Show the currently active color palette</td>
1810
</tr>
1811
</table>
1812
1813
<h3><aid="plugunplug">plug / unplug</a></h3>
1814
1815
<p>Plugs or unplugs a plug into a connector, for example plug a virtual joystick into a virtual joystick port.</p>
1816
1817
<divclass="subsectiontitle">
1818
usage:
1819
</div>
1820
1821
<table>
1822
<tr>
1823
<td><code>plug</code></td>
1824
1825
<td>Shows all currently connected plugs</td>
1826
</tr>
1827
1828
<tr>
1829
<td><code>plug <connector></code></td>
1830
1831
<td>Shows currently connected plug for the specified connector</td>
<td>Shows the currently selected sound profile</td>
1871
</tr>
1872
1873
<tr>
1874
<td><code>psg_profile -list</code></td>
1875
1876
<td>Lists all available sound profiles</td>
1877
</tr>
1878
1879
<tr>
1880
<td><code>psg_profile <profile></code></td>
1881
1882
<td>Selects a new sound profile</td>
1883
</tr>
1884
</table>
1885
1886
<divclass="note">
1887
Note: This command is a convenience wrapper around the <code><aclass="internal"href="#soundchip_vibrato_frequency">PSG_vibrato_frequency</a></code>, <code><aclass="internal"href="#soundchip_vibrato_percent">PSG_vibrato_percent</a></code>, <code><aclass="internal"href="#soundchip_detune_frequency">PSG_detune_frequency</a></code> and <code><aclass="internal"href="#soundchip_detune_percent">PSG_detune_percent</a></code> settings.
1888
</div>
1889
1890
<h3><aid="record">record</a></h3>
1891
1892
<p>Controls video recording: write openMSX audio/video to an AVI file.</p>
<p>The <code>start</code> subcommand also accepts an optional <code>-audioonly</code>, <code>-videoonly</code>, <code>-doublesize</code> and a <code>-triplesize</code> flag. Videos are recorded in a 320×240 size by default, at 640×480 when the <code>-doublesize</code> flag is used and 960×720 when using the <code>-triplesize</code> flag.
1931
If only audio is recorded, the created file will be a WAV file instead of an AVI file.</p>
1932
<p>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.
1933
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.
1934
You can prevent this from happening by using the <code>-stereo</code> option to force a stereo recording even if no stereo devices are present at the time you enter the command.
1935
You can also force a mono recording with <code>-mono</code> to save space.</p>
1936
<p>The <code><aclass="internal"href="#soundlog">soundlog</a></code> command is a shorthand for <code>record -audioonly</code>.</p>
1937
<p>Use <code>record_chunks</code> 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 <code>-doublesize</code>.</p>
1938
<p>Use <code>record_chunks_on_framerate_changes</code> if you want to split up the recording in several files, whenever the frame rate of the MSX changes. An AVI file cannot contain video of multiple frame rates, so sound and video will get out of sync if that happens without using this special version of the command. Do not specify the target filename with this variant, or openMSX will record all chunks to the same file.</p>
<p>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 <code>all</code> for the device, which means that all sound devices in the currently running MSX will be recorded. When starting recording, an option <code>-prefix</code> can be given to specify a filename prefix.</p>
<td>Stop recording the specified channel(s) of the specified device(s). If no channels are given, recording for all channels is stopped for the given device(s). If no devices are given, all channel recording is stopped.</td>
1959
</tr>
1960
1961
<tr>
1962
<td><code>record_channels all -prefix justtesting</code></td>
1963
1964
<td>Record all channels of all sound devices and create the file names with prefix 'justtesting' (e.g. to quickly delete all these files again).</td>
1965
</tr>
1966
1967
<tr>
1968
<td><code>record_channels list</code></td>
1969
1970
<td>Lists which channels of which sound chips are currently being recorded.</td>
<p>Remove a cartridge or extension from a running MSX machine. See also the commands <code><aclass="internal"href="#cart">cart</a></code>, <code><aclass="internal"href="#ext">ext</a></code>, <code><aclass="internal"href="#list_extensions">list_extensions</a></code>.</p>
1994
1995
<divclass="subsectiontitle">
1996
usage:
1997
</div>
1998
1999
<table>
2000
<tr>
2001
<td><code>remove_extension fmpac</code></td>
2002
2003
<td>Removes the FMPAC extension from the running MSX</td>
2004
</tr>
2005
</table>
2006
2007
<h3><aid="reset">reset</a></h3>
2008
2009
<p>Emulates the pressing of the reset button on the MSX. This sends a reset pulse to all devices, but does not erase memory contents.</p>
2010
2011
<divclass="subsectiontitle">
2012
usage:
2013
</div>
2014
2015
<table>
2016
<tr>
2017
<td><code>reset</code></td>
2018
2019
<td>Resets the current machine</td>
2020
</tr>
2021
</table>
2022
2023
<h3><aid="reverse">reverse</a></h3>
2024
2025
<p>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.</p>
2026
2027
<divclass="subsectiontitle">
2028
usage:
2029
</div>
2030
2031
<table>
2032
<tr>
2033
<td><code>reverse start</code></td>
2034
2035
<td>Start collecting data (enable the reverse feature).</td>
2036
</tr>
2037
<tr>
2038
<td><code>reverse stop</code></td>
2039
2040
<td>Stop collecting data (disable reverse feature) and remove all collected data.</td>
2041
</tr>
2042
<tr>
2043
<td><code>reverse status</code></td>
2044
2045
<td>Gives information about the reverse feature and the data it collected. Mostly useful for scripts.</td>
2046
</tr>
2047
<tr>
2048
<td><code>reverse goback <n></code></td>
2049
2050
<td>Go back <n> seconds in time. Of course, you cannot go back to a time before the time the <code>reverse start</code> command was given.</td>
<td>Control the view only mode of the reverse feature. In view only mode, the replay will never get interrupted by any user actions that normally would interrupt the replay. Use this to safely view a replay without accidentally ruining it by touching a key.</td>
2056
</tr>
2057
<tr>
2058
<td><code>reverse goto <time></code></td>
2059
2060
<td>Go to the indicated absolute moment in MSX time (given in seconds). If the time is before the time openMSX started collecting data (with the <code>reverse start</code> command) openMSX will jump to the time when collecting started.</td>
2061
</tr>
2062
<tr>
2063
<td><code>reverse truncatereplay</code></td>
2064
2065
<td>Stop replaying and wipe all replay data that is in the future (so after <strong>now</strong>). This is useful if you are hindered by the future events somehow, for instance when you are playing a game and jumped too early and therefore reversed. Be careful with this, as there is no way to recover this future. If you are at time 0, it means your whole replay will be gone after executing this command!</td>
<td>Load the replay from the given file and start it. It loads the initial snapshot, starts replaying the recorded events, and enables the reverse feature automatically. With the <code>-goto</code> option, you can specify where to jump to in the replay after loading (<code>begin</code> is default), where <code>savetime</code> is the time at which the replay was saved and <code>n</code> is an absolute time in seconds in the replay. The <code>-viewonly</code> option is a shortcut to put the reverse feature in viewonly mode directly after loading the replay. Without this option, it will always go to normal mode.</td>
2076
</tr>
2077
</table>
2078
2079
<p>There are some extra helper commands to make the feature easier to use.</p>
<td>Go back in time to the previous (internal) snapshot. The further back in the past the less dense the amount of snapshots are. So, executing this command multiple times, will take successively bigger steps in the past. You can optionally specify a minimal and maximal step size. You will at least go back the minimal amount of time (even if there's a snapshot closer to the current time) and at most the maximal amount of time (even if there's no snapshot within the maximum specified time from the current time).</td>
<td>As <code>reverse_prev</code> but then it goes to the closest snapshot in the future (if possible).</td>
2100
</tr>
2101
</table>
2102
2103
<p>Because the reverse feature is very useful, it is automatically enabled via <code><aclass="internal"href="#auto_enable_reverse">auto_enable_reverse</a></code> setting.</p>
2104
2105
<h3><aid="save_settings">save_settings</a></h3>
2106
2107
<p>Write the current openMSX settings to a settings XML file. See also <code><aclass="internal"href="#load_settings">load_settings</a></code>.</p>
2108
2109
<p>If you disabled <code><aclass="internal"href="#save_settings_on_exit">save_settings_on_exit</a></code>, you can use this command to save your preferences.</p>
2110
2111
<divclass="subsectiontitle">
2112
usage:
2113
</div>
2114
2115
<table>
2116
<tr>
2117
<td><code>save_settings</code></td>
2118
2119
<td>Save settings to the default settings file</td>
<p>These commands can be used to manage savestates. These are much easier to use than the lowlevel <code><aclass="internal"href="#store_machine">store_machine</a></code> and <code><aclass="internal"href="#store_machine">restore_machine</a></code> commands.</p>
2133
2134
<h4><code>savestate [<name>]</code></h4>
2135
<p>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 <code>quicksave</code> will be taken.</p>
2136
2137
<h4><code>loadstate [<name>]</code></h4>
2138
<p>This restores a previously created savestate. Like above you can specify a name which defaults to <code>quicksave</code> if omitted.</p>
2139
2140
<h4><code>list_savestates</code></h4>
2141
<p>This returns the names of all previously created savestates.</p>
<p>Take a screenshot of the openMSX screen. By default this takes a screenshot of the 'scaled' MSX screen (see <code><aclass="internal"href="#scale_algorithm">scale_algorithm</a></code> setting) without OSD/GUI elements (e.g. console and icons). If you want to include the GUI and OSD elements pass the <code>-with-osd</code> option. If you want a screenshot of the 'unscaled' raw MSX screen, pass the <code>-raw</code> option. The screenshots are PNG files and (by default) are saved in the <code>screenshots</code> subdirectory of the openMSX data directory in your home directory. There's also an option <code>-no-sprites</code> to take a screenshot with sprite rendering disabled.</p>
<td>Switch to the specified setup, which you have saved before with the GUI or the <code><aclass="internal"href="#store_setup">store_setup</a></code> command. Also returns the handle of the new machine.</td>
2280
</tr>
2281
</table>
2282
2283
<divclass="note">
2284
Note: The machine handle is mostly used by external applications controlling openMSX (see also <aclass="external"href="openmsx-control.html">Controlling openMSX from External Applications</a>). For interactive use you can omit the machine handle to have the commands operate on the current machine.
2285
</div>
2286
2287
2288
<h3><aid="sha1sum">sha1sum</a></h3>
2289
2290
<p>Calculates sha1 value for the given file. If the file is (g)zipped the sha1 is calculated on the unzipped version.</p>
2291
2292
<divclass="subsectiontitle">
2293
usage:
2294
</div>
2295
2296
<table>
2297
<tr>
2298
<td><code>sha1sum <filename></code></td>
2299
2300
<td>Returns a string with the sha1 value for the specified file.</td>
2301
</tr>
2302
</table>
2303
2304
2305
<h3><aid="slotmap">slotmap</a></h3>
2306
2307
<p>Shows what devices are inserted into which slots. The related command <code><aclass="internal"href="#iomap">iomap</a></code> shows a similar overview, but for I/O mapped devices.</p>
2308
2309
<divclass="subsectiontitle">
2310
usage:
2311
</div>
2312
2313
<table>
2314
<tr>
2315
<td><code>slotmap</code></td>
2316
2317
<td>Shows the slot map of the current MSX machine</td>
2318
</tr>
2319
</table>
2320
2321
2322
<h3><aid="slotselect">slotselect</a></h3>
2323
2324
<p>Shows the currently selected slots. To see what devices are located in the slots, use the <code><aclass="internal"href="#slotmap">slotmap</a></code> command.</p>
2325
2326
<divclass="subsectiontitle">
2327
usage:
2328
</div>
2329
2330
<table>
2331
<tr>
2332
<td><code>slotselect</code></td>
2333
2334
<td>Shows the currently selected slot for each page</td>
2335
</tr>
2336
</table>
2337
2338
2339
<h3><aid="soundlog">soundlog</a></h3>
2340
2341
<p>Controls sound logging: writing the openMSX sound to a WAV file.</p>
2342
2343
<p>This command is a shorthand for <code><aclass="internal"href="#record">record</a> -audioonly</code>.</p>
<td>Save state of indicated machine to specified file</td>
2393
</tr>
2394
</table>
2395
2396
<h4><code>restore_machine</code>:</h4>
2397
<p>Load a previously saved machine in a new machine-ID, next to the already available machines. See the section on <code><aclass="internal"href="#machines">activate_machine</a></code>.</p>
2398
2399
<table>
2400
<tr>
2401
<td><code>restore_machine</code></td>
2402
<td>Load state from last saved state in default directory</td>
Note: These commands are pretty low level. The <code><aclass="internal"href="#savestate">savestate</a></code> and <code><aclass="internal"href="#savestate">loadstate</a></code> scripts are built on top of this and are much more convenient to use.
<td>Save the setup with the given depth to specified file</td>
2423
</tr>
2424
</table>
2425
2426
<p>If the filename isn't specified, openMSX creates a unique one for you, based on the name of the machine. The depth argument is mandatory and must be one of the following.</p>
2427
2428
<dl>
2429
<dt><code>machine</code></dt>
2430
<dd>Save only the machine. This isn't too useful... but you can use it to give your favourite machine your own setup name</dd>
2431
<dt><code>extensions</code></dt>
2432
<dd>Save the machine with all plugged in extensions</dd>
2433
<dt><code>connectors</code></dt>
2434
<dd>As previous, but also include plugged in equipment in its connectors</dd>
2435
<dt><code>media</code></dt>
2436
<dd>As previous, but also include inserted media in its media slots</dd>
2437
<dt><code>complete_state</code></dt>
2438
<dd>As previous, but also include the run time state. This is basically identical to a savestate</dd>
2439
</dl>
2440
2441
<p>Storing the current setup can also be done with the GUI via <spanclass="menu-reference">Main menu bar
<p>Test whether the given MSX machine configuration works. For example whether you have all required system ROMs for this machine. See also <code><aclass="internal"href="#machines">load_machine</a></code>. This is an alternative to using the equivalent option in the GUI <spanclass="menu-reference">Main menu bar
2448
→ Machine → Test MSX hardware</span></p>
<td>Test whether the given machine configuration is OK.</td>
2457
</tr>
2458
</table>
2459
2460
<p>Use the convenience commands <code>test_all_machines</code> and <code>test_all_extensions</code> to get a full overview on which system ROMs you are still missing.</p>
2461
2462
2463
<h3><aid="toggle">toggle</a></h3>
2464
2465
<p>Toggles any boolean (on/off) setting: if it was on, it will be turned off and vice versa.
2466
See also: <code><aclass="internal"href="#cycle">cycle</a></code>.</p>
2467
2468
<divclass="subsectiontitle">
2469
usage:
2470
</div>
2471
2472
<table>
2473
<tr>
2474
<td><code>toggle <setting></code></td>
2475
2476
<td>Toggles the specified setting</td>
2477
</tr>
2478
</table>
2479
2480
<divclass="subsectiontitle">
2481
examples:
2482
</div>
2483
2484
<divclass="examples">
2485
<code>toggle mute</code><br />
2486
<code>toggle throttle</code>
2487
</div>
2488
2489
2490
<h3><aid="trainer">trainer</a></h3>
2491
2492
<p>Control game trainers. You can enable or disable individual cheats of each trainer. Make use of the TAB key to see
2493
what is available. When switching trainers, the currently active trainer will be deactivated.</p>
2494
2495
<divclass="subsectiontitle">
2496
usage:
2497
</div>
2498
2499
<table>
2500
<tr>
2501
<td><code>trainer</code></td>
2502
2503
<td>See which trainer is currently active</td>
2504
</tr>
2505
2506
<tr>
2507
<td><code>trainer <game></code></td>
2508
2509
<td>See which cheats are currently active in the trainer</td>
2510
</tr>
2511
2512
<tr>
2513
<td><code>trainer <game> all</code></td>
2514
2515
<td>Activate all cheats in the trainer of <game></td>
<td>Prints MSX code for a smiley face if emulating an 'international' MSX model</td>
2637
</tr>
2638
</table>
2639
</div>
2640
2641
2642
<h3><aid="unset">unset</a></h3>
2643
2644
<p>Undefines a Tcl variable. When used on openMSX settings, they are reverted to their default value. See also: <code><aclass="internal"href="#set">set</a></code>.</p>
2645
2646
<divclass="subsectiontitle">
2647
usage:
2648
</div>
2649
2650
<table>
2651
<tr>
2652
<td><code>unset <variable></code></td>
2653
2654
<td>Undefines the given variable</td>
2655
</tr>
2656
2657
<tr>
2658
<td><code>unset <setting></code></td>
2659
2660
<td>Reverts the given setting to its default value</td>
2661
</tr>
2662
</table>
2663
2664
2665
<h3><aid="user_setting">user_setting</a></h3>
2666
2667
<p>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 "<code>help set <setting-name></code>") and their value is stored saved/restored when openMSX is quit/restarted.</p>
2668
2669
<!-- do we really have to repeat the help text from the openmsx source code here? -->
2670
2671
<p>Execute "<code>help user_setting</code>" to get a detailed description of this command.</p>
2672
2673
2674
<h3><aid="vdpregs">vdpregs</a></h3>
2675
2676
<p>Shows the current register settings of the Video Display Processor (VDP). Related command: <code><aclass="internal"href="#palette">palette</a></code>.</p>
2677
2678
<divclass="subsectiontitle">
2679
usage:
2680
</div>
2681
2682
<table>
2683
<tr>
2684
<td><code>vdpregs</code></td>
2685
2686
<td>Shows the current VDP control register contents</td>
2687
</tr>
2688
</table>
2689
2690
2691
<h3><aid="other">other</a></h3>
2692
2693
<p>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.</p>
2694
2695
<p>We've only listed a very brief overview of these commands. As always execute "<code>help <command-name></code>" to get a more detailed description of the command.</p>
2696
2697
<table>
2698
<tr>
2699
<td><code>about</code></td>
2700
<td>Searches command and setting help-texts for the given keyword</td>
2701
</tr>
2702
<tr>
2703
<td><code>address_in_slot</code></td>
2704
<td>Tests whether an address is inside a certain slot</td>
2705
</tr>
2706
<tr>
2707
<td><code>cpuregs</code></td>
2708
<td>Gives an overview of the CPU registers</td>
2709
</tr>
2710
<tr>
2711
<td><code>data_file</code></td>
2712
<td>Helps locate openMSX data files</td>
2713
</tr>
2714
<tr>
2715
<td><code>disasm</code></td>
2716
<td>Prints disassembled instructions at the given memory location</td>
2717
</tr>
2718
<tr>
2719
<td><code>getcolor</code></td>
2720
<td>Queries V99x8 palette settings</td>
2721
</tr>
2722
<tr>
2723
<td><code>get_active_cpu</code></td>
2724
<td>Returns the active cpu, z80 or r800</td>
2725
</tr>
2726
<tr>
2727
<td><code>get_breakponts_dir</code></td>
2728
<td>Returns breakpoints directory for this user</td>
2729
</tr>
2730
<tr>
2731
<td><code>get_color_count</code></td>
2732
<td>Gives an overview of the used colors in the current screen</td>
2733
</tr>
2734
<tr>
2735
<td><code>get_mapper_size</code></td>
2736
<td>Returns the size of the memory mapper in a given slot or 0 when there is no memory mapper in the slot</td>
2737
</tr>
2738
<tr>
2739
<td><code>get_screen</code></td>
2740
<td>Captures the content of an MSX text screen in a Tcl string</td>
2741
</tr>
2742
<tr>
2743
<td><code>get_screen_mode</code></td>
2744
<td>Decodes the current screen mode from the VDP registers and returns it as a Tcl string. <code>get_screen_mode_number</code> returns it as a number which would also be used for the basic command <code>SCREEN</code>.</td>
2745
</tr>
2746
<tr>
2747
<td><code>get_selected_slot</code></td>
2748
<td>Returns the selected slot for the given memory page</td>
2749
</tr>
2750
<tr>
2751
<td><code>guess_title</code></td>
2752
<td>Uses heuristics to guess the title of the current game (cartridge, disk or tape). For specific media use <code>guess_cassette_title</code>, <code>guess_disk_title</code> or <code>guess_rom_title</code>.</td>
2753
</tr>
2754
<tr>
2755
<td><code>listing</code></td>
2756
<td>Reimplementation of the BASIC LIST command in Tcl</td>
2757
</tr>
2758
<tr>
2759
<td><code>load_debuggable</code></td>
2760
<td>Writes the content of a file to a openMSX debuggable</td>
2761
</tr>
2762
<tr>
2763
<td><code>load_breakpoints</code></td>
2764
<td>Loads all breakpoint subtypes (breakpoints, watchpoints and conditions) from a given file</td>
2765
</tr>
2766
<tr>
2767
<td><code>multi_screenshot</code></td>
2768
<td>Takes screenshots of multiple successive frames</td>
2769
</tr>
2770
<tr>
2771
<td><code>next_frame</code></td>
2772
<td>Emulates until the (start of) the next frame, then pause emulation</td>
2773
</tr>
2774
<tr>
2775
<td><code>prev_frame</code></td>
2776
<td>Rewinds to the (start of) the previous frame</td>
2777
</tr>
2778
<tr>
2779
<td><code>pc_in_slot</code></td>
2780
<td>Checks whether CPU is executing from the specified slot (useful as breakpoint condition)</td>
2781
</tr>
2782
<tr>
2783
<td><code>peek</code></td>
2784
<td>Reads a byte from the given memory location</td>
2785
</tr>
2786
<tr>
2787
<td><code>peek16</code></td>
2788
<td>Reads a 16 bit word from the given memory location</td>
2789
</tr>
2790
<tr>
2791
<td><code>peek16_BE</code></td>
2792
<td>Reads a 16 bit word (big endian) from the given memory location</td>
2793
</tr>
2794
<tr>
2795
<td><code>peek16_LE</code></td>
2796
<td>Reads a 16 bit word (little endian) from the given memory location</td>
2797
</tr>
2798
<tr>
2799
<td><code>peek8</code></td>
2800
<td>Reads a byte from the given memory location</td>
2801
</tr>
2802
<tr>
2803
<td><code>peek_s16</code></td>
2804
<td>Reads a signed 16 bit word from the given memory location</td>
2805
</tr>
2806
<tr>
2807
<td><code>peek_s16_BE</code></td>
2808
<td>Reads a signed 16 bit word (big endian) from the given memory location</td>
2809
</tr>
2810
<tr>
2811
<td><code>peek_s16_LE</code></td>
2812
<td>Reads a signed 16 bit word (little endian) from the given memory location</td>
2813
</tr>
2814
<tr>
2815
<td><code>peek_s8</code></td>
2816
<td>Reads a signed byte from the given memory location</td>
2817
</tr>
2818
<tr>
2819
<td><code>peek_u16</code></td>
2820
<td>Reads an unsigned 16 bit word from the given memory location</td>
2821
</tr>
2822
<tr>
2823
<td><code>peek_u16_BE</code></td>
2824
<td>Reads an unsigned 16 bit word (big endian) from the given memory location</td>
2825
</tr>
2826
<tr>
2827
<td><code>peek_u16_LE</code></td>
2828
<td>Reads an unsigned 16 bit word (little endian) from the given memory location</td>
2829
</tr>
2830
<tr>
2831
<td><code>peek_u8</code></td>
2832
<td>Reads an unsigned byte from the given memory location</td>
2833
</tr>
2834
<tr>
2835
<td><code>poke</code></td>
2836
<td>Writes a byte to the given memory location. Use <code>dpoke</code> to only write if the value to be written is different from the current value.</td>
2837
</tr>
2838
<tr>
2839
<td><code>poke16</code></td>
2840
<td>Writes a 16 bit word to the given memory location</td>
2841
</tr>
2842
<tr>
2843
<td><code>psg_log</code></td>
2844
<td>Logs or replays PSG register values in binary format</td>
2845
</tr>
2846
<tr>
2847
<td><code>ram_watch</code></td>
2848
<td>Adds or removes RAM watch addresses to/from the list on the right side of the screen, useful for debugging or tool assisted speedrunning (TAS)</td>
2849
</tr>
2850
<tr>
2851
<td><code>reg</code></td>
2852
<td>Reads or writes CPU registers</td>
2853
</tr>
2854
<tr>
2855
<td><code>reg_log</code></td>
2856
<td>Logs or replays register values for the specified debuggable in ASCII format</td>
2857
</tr>
2858
<tr>
2859
<td><code>reverse_bookmarks</code></td>
2860
<td>Controls the reverse bookmarks functionality</td>
2861
</tr>
2862
<tr>
2863
<td><code>rom_info</code></td>
2864
<td>Gives information about the given ROM device, coming from the software database. If no argument is given, the first found (external) ROM device is assumed. This command replaces the info that was previously (before openMSX 0.8.1) automatically printed on stdout.</td>
2865
</tr>
2866
<tr>
2867
<td><code>run_to</code></td>
2868
<td>Executes instructions until the PC reaches the specified address</td>
2869
</tr>
2870
<tr>
2871
<td><code>save_breakpoints</code></td>
2872
<td>Saves all breakpoints subtypes (breakpoints, watchpoints, conditions) to a given file</td>
2873
</tr>
2874
<tr>
2875
<td><code>save_debuggable</code></td>
2876
<td>Saves the (partial) content of a debuggable to a file</td>
2877
</tr>
2878
<tr>
2879
<td><code>save_msx_screen</code></td>
2880
<td>Saves the current MSX screen into an MSX compatible binary file (BLOAD format).</td>
2881
</tr>
2882
<tr>
2883
<td><code>save_to_file</code></td>
2884
<td>Helper function to save data (e.g. the output of another command) to a file.</td>
2885
</tr>
2886
<tr>
2887
<td><code>setcolor</code></td>
2888
<td>Changes V99x8 palette settings</td>
2889
</tr>
2890
<tr>
2891
<td><code>set_help_proc</code></td>
2892
<td>Associates help text with a Tcl proc</td>
2893
</tr>
2894
<tr>
2895
<td><code>set_help_text</code></td>
2896
<td>Associates help text with a Tcl proc</td>
2897
</tr>
2898
<tr>
2899
<td><code>set_tabcompletion_proc</code></td>
2900
<td>Associates tab completion with a Tcl proc</td>
2901
</tr>
2902
<tr>
2903
<td><code>showdebuggable</code></td>
2904
<td>Prints the content of a debuggable in a table</td>
2905
</tr>
2906
<tr>
2907
<td><code>showmem</code></td>
2908
<td>Prints the content of memory in a table</td>
2909
</tr>
2910
<tr>
2911
<td><code>show_osd</code></td>
2912
<td>Prints an overview of the defined OSD elements</td>
2913
</tr>
2914
<tr>
2915
<td><code>shuffler</code></td>
2916
<td>A basic ROM-game shuffler, that switches between a set of ROM programs in a given folder after a certain time is passed.</td>
2917
</tr>
2918
<tr>
2919
<td><code>skip_instruction</code></td>
2920
<td>Skips the current CPU instruction</td>
2921
</tr>
2922
<tr>
2923
<td><code>stack</code></td>
2924
<td>Prints the top of the CPU stack</td>
2925
</tr>
2926
<tr>
2927
<td><code>start_of_frame</code></td>
2928
<td>Rewinds to the start of the current frame</td>
2929
</tr>
2930
<tr>
2931
<td><code>step</code></td>
2932
<td>Same as step_in</td>
2933
</tr>
2934
<tr>
2935
<td><code>step_in</code></td>
2936
<td>Executes one CPU instruction, go into subroutines</td>
2937
</tr>
2938
<tr>
2939
<td><code>step_over</code></td>
2940
<td>Executes one CPU instruction, but don't go into subroutines</td>
2941
</tr>
2942
<tr>
2943
<td><code>step_out</code></td>
2944
<td>Steps out of the current subroutine</td>
2945
</tr>
2946
<tr>
2947
<td><code>step_back</code></td>
2948
<td>Steps one instruction back in time</td>
2949
</tr>
2950
<tr>
2951
<td><code>text_echo</code></td>
2952
<td>Echoes all printed MSX text on stderr</td>
2953
</tr>
2954
<tr>
2955
<td><code>toggle_breaked</code></td>
2956
<td>Toggles breaked status</td>
2957
</tr>
2958
<tr>
2959
<td><code>toggle_cursors</code></td>
2960
<td>Shows (or hides) a widget which shows which keys are pressed</td>
2961
</tr>
2962
<tr>
2963
<td><code>toggle_frame_counter</code></td>
2964
<td>Shows (or hides) a widget which shows the current frame number since start-up</td>
2965
</tr>
2966
<tr>
2967
<td><code>toggle_freq</code></td>
2968
<td>Switches between PAL/NTSC</td>
2969
</tr>
2970
<tr>
2971
<td><code>toggle_metal_gear_overlay</code></td>
2972
<td>Shows OSD widgets that help you play Metal Gear</td>
2973
</tr>
2974
<tr>
2975
<td><code>toggle_mog_editor</code></td>
2976
<td>Enables (or disables) wall drawing and Popolon-placement with the mouse when playing The Maze of Galious; needs to have the MoG overlay enabled, see <code>toggle_mog_overlay</code></td>
2977
</tr>
2978
<tr>
2979
<td><code>toggle_mog_overlay</code></td>
2980
<td>Enables (or disables) graphical extra information and game hints when playing The Maze of Galious</td>
2981
</tr>
2982
<tr>
2983
<td><code>toggle_movie_length_display</code></td>
2984
<td>Toggles display of the movie length in the upper right corner</td>
2985
</tr>
2986
<tr>
2987
<td><code>toggle_music_keyboard</code></td>
2988
<td>Enables (or disables) keyboard view of all existing music channels. EXPERIMENTAL! Be careful, it's very slow when many channels are present in the system</td>
2989
</tr>
2990
<tr>
2991
<td><code>toggle_nemesis_1_shield</code></td>
2992
<td>Enables (or disables) an OSD drawn shield in Nemesis (Gradius) 1, all enemy objects will repel from it</td>
2993
</tr>
2994
<tr>
2995
<td><code>toggle_psg2scc</code></td>
2996
<td>Enables (or disables) playing PSG sound on SCC</td>
2997
</tr>
2998
<tr>
2999
<td><code>toggle_scc_editor</code></td>
3000
<td>Shows a graphical view of the SCC chip(s) of the system, showing waveforms and volume per channel and also enables you to edit the waveforms per channel</td>
3001
</tr>
3002
<tr>
3003
<td><code>toggle_scc_viewer</code></td>
3004
<td>Shows a graphical view of the SCC chip(s) of the system, showing
3005
waveforms and volume per channel. In the future, this will be fully
3006
replaced by <spanclass="menu-reference">Main menu bar → Tools
3007
→ SCC viewer</span>.
3008
</td>
3009
</tr>
3010
<tr>
3011
<td><code>toggle_tron</code></td>
3012
<td>Shows (or hides) an OSD implementation of the MSX-BASIC TRON command to trace what the current line number of the BASIC interpreter is</td>
3013
</tr>
3014
<tr>
3015
<td><code>toggle_vdp_access_test</code></td>
3016
<td>Enables (or disables) reporting in the console when VDP I/O is done which could possibly cause data corruption on the slowest VDP (TMS9xxx), which is not emulated</td>
3017
</tr>
3018
<tr>
3019
<td><code>toggle_vdp_busy</code></td>
3020
<td>Enables (or disables) display on the OSD of how busy the VDP is</td>
3021
</tr>
3022
<tr>
3023
<td><code>type_via_keybuf</code></td>
3024
<td>Alternative to the <code>type_via_keyboard</code> (the default <code><aclass="internal"href="#type">type</a></code> command), that uses the keyboard buffer; only works if the running software uses the standard keyboard buffer functions to get keyboard input, but is much faster</td>
3025
</tr>
3026
<tr>
3027
<td><code>umrcallback</code></td>
3028
<td>Example proc to use with the umr_callback setting</td>
3029
</tr>
3030
<tr>
3031
<td><code>vdpcmdinprogresscallback</code></td>
3032
<td>Example proc to use with the vdpcmdinprogress_callback setting</td>
3033
</tr>
3034
<tr>
3035
<td><code>v9990reg</code></td>
3036
<td>Reads or writes a V9990 register</td>
3037
</tr>
3038
<tr>
3039
<td><code>v9990regs</code></td>
3040
<td>Prints an overview of all V9990 registers</td>
3041
</tr>
3042
<tr>
3043
<td><code>vdpreg</code></td>
3044
<td>Reads or writes a V99x8 register</td>
3045
</tr>
3046
<tr>
3047
<td><code>vdpstatus</code></td>
3048
<td>Shortcut for reading the VDP status registers</td>
3049
</tr>
3050
<tr>
3051
<td><code>vdpvramaddress</code></td>
3052
<td>Gives the current VDP VRAM pointer</td>
3053
</tr>
3054
<tr>
3055
<td><code>vdrive</code></td>
3056
<td>Easily switch disks in multi-disk games</td>
3057
</tr>
3058
<tr>
3059
<td><code>vgm_rec</code></td>
3060
<td>Records the music played by PSG, MSX-MUSIC, MSX-AUDIO, OPL4 and SCC into a VGM file</td>
3061
</tr>
3062
<tr>
3063
<td><code>vpeek/vpoke</code></td>
3064
<td>Reads/writes bytes from/to video RAM</td>
3065
</tr>
3066
</table>
3067
3068
<p>The source code of all these scripts is located in <code>share/scripts</code> directory. Feel free to inspect these scripts and modify them to suit your needs.</p>
3069
3070
<h2><aid="settings">Settings</a></h2>
3071
3072
<p>Settings control many aspects of openMSX. Below, the available settings are listed and described. You can change setting values with the <code><aclass="internal"href="#set">set</a></code> command.</p>
3073
3074
3075
<h3><aid="accuracy">accuracy</a></h3>
3076
3077
<p>Sets the render accuracy. openMSX supports three levels of render accuracy:</p>
3078
3079
<dl>
3080
<dt>screen accurate:</dt>
3081
<dd>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).</dd>
3082
3083
<dt>line accurate:</dt>
3084
<dd>Changes in VDP state become effective only once per display line. Works well for almost all software.</dd>
3085
3086
<dt>pixel accurate:</dt>
3087
<dd>Changes in VDP state become effective immediately. In this mode even the 'Unknown Reality scope part' is rendered correctly.</dd>
3088
</dl>
3089
3090
<p>In some cases switching to a lower accuracy level can speed up emulation, but in many cases the speed difference is negligible.</p>
3091
3092
<p>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.</p>
<p>Switches the "auto-run cassettes" feature on or off. When it's enabled, openMSX will try to type the proper loading
3157
instruction when a cassette is inserted.</p>
3158
3159
<divclass="subsectiontitle">
3160
usage:
3161
</div>
3162
3163
<table>
3164
<tr>
3165
<td><code>set autoruncassettes</code></td>
3166
3167
<td>Shows the current setting</td>
3168
</tr>
3169
3170
<tr>
3171
<td><code>set autoruncassettes on</code></td>
3172
3173
<td>Try to run cassettes automatically</td>
3174
</tr>
3175
3176
<tr>
3177
<td><code>set autoruncassettes off</code></td>
3178
3179
<td>Do nothing when cassettes are inserted</td>
3180
</tr>
3181
</table>
3182
3183
<divclass="note">
3184
Note: Autorun works practically always for cassette images in the CAS and TSX formats. If that fails or for WAV files, openMSX will try to find a hint of the loading instruction (in upper case) in the filename.
<p>Switches the "auto-run laserdisc" feature on or off. When it's enabled, openMSX will try to type the proper loading
3191
instruction when a laserdisc is inserted.</p>
3192
3193
<p>Note that this setting is only available when the Pioneer PX-7 or Pioneer PX-V60 MSX machine is being emulated, and only when openMSX was built with Laserdisc support (Laserdisc support is an optional compile-time feature).</p>
<p>Using the <code><aclass="internal"href="#reverse">reverse</a></code> feature comes at 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. While with desktop computers this generally won't be a problem, the performance drop might be more noticeable on older/smaller handheld devices.</p>
3223
3224
<divclass="subsectiontitle">
3225
usage:
3226
</div>
3227
3228
<table>
3229
<tr>
3230
<td><code>set auto_enable_reverse</code></td>
3231
<td>Shows the current setting</td>
3232
</tr>
3233
<tr>
3234
<td><code>set auto_enable_reverse off</code></td>
3235
<td>Don't automatically enable the reverse feature</td>
3236
</tr>
3237
<tr>
3238
<td><code>set auto_enable_reverse on</code></td>
3239
<td>Enable the reverse feature when openMSX starts. Default setting for Desktop/PC</td>
<p>Enable this setting to make automatic backups of your current replay. The replay is saved to the filename specified in the <code>auto_save_replay_filename</code> setting (default: "auto_save") at an interval as specified by the <code>auto_save_replay_interval</code> setting (default: 30 seconds). The interval is in real clock time, not in MSX time.</p>
3247
3248
3249
<h3><aid="blur">blur</a></h3>
3250
3251
<p>Sets the amount of horizontal blur effect. A value of 0 turns off blur, while 100 selects maximum blur.</p>
3252
3253
<divclass="subsectiontitle">
3254
usage:
3255
</div>
3256
3257
<table>
3258
<tr>
3259
<td><code>set blur</code></td>
3260
3261
<td>Shows the current setting</td>
3262
</tr>
3263
3264
<tr>
3265
<td><code>set blur <value></code></td>
3266
3267
<td>Change the value</td>
3268
</tr>
3269
</table>
3270
3271
<divclass="note">
3272
Note: Only some <aclass="internal"href="#scale_algorithm">scale algorithms</a> apply horizontal blur; the default algorithm "simple" does.
3273
</div>
3274
3275
3276
<h3><aid="bootsector">bootsector</a></h3>
3277
3278
<p>Sets the boot sector type for DirAsDSK. Default: DOS2. Only relevant on turboR, because it boots differently
3279
depending on the type of boot sector on the disk in drive A.</p>
3280
3281
<divclass="subsectiontitle">
3282
usage:
3283
</div>
3284
3285
<table>
3286
<tr>
3287
<td><code>set bootsector</code></td>
3288
3289
<td>Shows the current setting</td>
3290
</tr>
3291
3292
<tr>
3293
<td><code>set bootsector DOS1</code></td>
3294
3295
<td>Use a DOS1 boot sector</td>
3296
</tr>
3297
</table>
3298
3299
3300
<h3><aid="brightness">brightness</a></h3>
3301
3302
<p>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 colours, including black and white, while the <code><aclass="internal"href="#gamma">gamma</a></code> setting changes the relative brightness of colours but does not change black and white.</p>
3303
3304
<p>The section about the <code><aclass="internal"href="#noise">noise</a></code> setting describes a typical way of using <code>brightness</code>.</p>
3305
3306
<divclass="subsectiontitle">
3307
usage:
3308
</div>
3309
3310
<table>
3311
<tr>
3312
<td><code>set brightness</code></td>
3313
3314
<td>Shows the current setting</td>
3315
</tr>
3316
3317
<tr>
3318
<td><code>set brightness 5</code></td>
3319
3320
<td>Make the video output a bit brighter than default</td>
3321
</tr>
3322
</table>
3323
3324
3325
<h3><aid="cmdtiming">cmdtiming</a></h3>
3326
3327
<p>Controls VDP command execution timing.</p>
3328
3329
<p>This is useful for debugging and for speeding up games where the command engine performance is a bottleneck.</p>
3330
3331
<divclass="subsectiontitle">
3332
usage:
3333
</div>
3334
3335
<table>
3336
<tr>
3337
<td><code>set cmdtiming</code></td>
3338
3339
<td>Shows the current setting</td>
3340
</tr>
3341
3342
<tr>
3343
<td><code>set cmdtiming broken</code></td>
3344
3345
<td>Make VDP commands finish instantly</td>
3346
</tr>
3347
3348
<tr>
3349
<td><code>set cmdtiming real</code></td>
3350
3351
<td>Make VDP commands take a realistic amount of time</td>
3352
</tr>
3353
</table>
3354
3355
<divclass="note">
3356
Note: When set to <code>broken</code> the emulated MSX acts different from a real MSX. This might cause some software to fail.
3357
</div>
3358
3359
3360
<h3><aid="color_matrix">color_matrix</a></h3>
3361
3362
<p>This setting represents a 3×3 matrix that is used to transform MSX RGB colours to host RGB colours. This setting can
3363
be used to generate all kind of colour schemes, see <code>scripts/monitor.tcl</code> for examples.</p>
3364
3365
<p>To get the following colour transformation:</p>
3366
<pre>
3367
| a b c | | Rm | | Rh |
3368
| d e f | × | Gm | = | Gh |
3369
| g h i | | Bm | | Bh |
3370
</pre>
3371
<p>Use this command:</p>
3372
<pre>
3373
set color_matrix { { a b c } { d e f } { g h i } }
Note: It is often more convenient to use the <code><aclass="internal"href="#monitor_type">monitor_type</a></code> command.
3402
</div>
3403
3404
3405
<h3><aid="console">console</a></h3>
3406
3407
<p>Turns the openMSX on-screen console on or off.</p>
3408
3409
<divclass="subsectiontitle">
3410
usage:
3411
</div>
3412
3413
<table>
3414
<tr>
3415
<td><code>set console</code></td>
3416
3417
<td>Shows the current setting</td>
3418
</tr>
3419
3420
<tr>
3421
<td><code>set console on</code></td>
3422
3423
<td>Turns the console on</td>
3424
</tr>
3425
3426
<tr>
3427
<td><code>set console off</code></td>
3428
3429
<td>Turns the console off</td>
3430
</tr>
3431
</table>
3432
3433
3434
<h3><aid="contrast">contrast</a></h3>
3435
3436
<p>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.</p>
3437
3438
<p>The section about the <code><aclass="internal"href="#noise">noise</a></code> setting describes a typical way of using <code>contrast</code>.</p>
3439
3440
<divclass="subsectiontitle">
3441
usage:
3442
</div>
3443
3444
<table>
3445
<tr>
3446
<td><code>set contrast</code></td>
3447
3448
<td>Shows the current setting</td>
3449
</tr>
3450
3451
<tr>
3452
<td><code>set contrast -5</code></td>
3453
3454
<td>Reduce the video contrast a bit</td>
3455
</tr>
3456
</table>
3457
3458
3459
<h3><aid="cputrace">cputrace</a></h3>
3460
3461
<p>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.</p>
<p>Selects the default MSX model. openMSX uses this machine when it is started without the <code>-machine</code> option and without the <code>-setup</code> option and the <code><aclass="internal"href="#default_setup">default_setup</a></code> setting is empty or pointing to a non-existing setup. This is a typical setting that should be saved, see also <aclass="internal"href="#save_settings"><code>save_settings</code></a>.</p>
3532
3533
<p>In the GUI, under <spanclass="menu-reference">Main menu bar → Machine
3534
→ Setup settings</span> you can also configure what openMSX must do at startup, configuring this setting there.</p>
<td>Use the turboR GT the next time openMSX is started</td>
3551
</tr>
3552
</table>
3553
3554
3555
<h3><aid="default_setup">default_setup</a></h3>
3556
3557
<p>Selects the default setup. openMSX uses this setup when it is started without the <code>-setup</code> or <code>-machine</code> option. By default, this setting is empty, because no setups are shipped with openMSX: they have to be created by users, after which this setting can be set to automatically start that setup that got saved earlier. If it is indeed empty or pointing to a non-existing setup, the value for the <code><aclass="internal"href="#default_machine">default_machine</a></code> setting is used to determine what to start.</p>
3558
3559
<p>In the GUI, under <spanclass="menu-reference">Main menu bar → Machine
3560
→ Setup settings</span> you can also configure what openMSX must do at startup, configuring this setting there.</p>
3561
3562
<divclass="subsectiontitle">
3563
usage:
3564
</div>
3565
3566
<table>
3567
<tr>
3568
<td><code>set default_setup</code></td>
3569
3570
<td>Shows current setting</td>
3571
</tr>
3572
3573
<tr>
3574
<td><code>set default_setup mymsx</code></td>
3575
3576
<td>Use the <code>mymsx</code> setup the next time openMSX is started without specifying setup or machine</td>
3577
</tr>
3578
</table>
3579
3580
<divclass="note">
3581
If you set this setting to the same value as the <code><aclass="internal"href="#save_setup_at_exit_name">save_setup_at_exit_name</a></code> setting and have the <code><aclass="internal"href="#save_setup_at_exit_depth">save_setup_at_exit_depth</a></code> setting set to another depth than <code>none</code> , openMSX will automatically continue with the last setup when being started up again (and no other machine or setup is specified).
3582
</div>
3583
3584
3585
<h3><aid="DirAsDSKmode">DirAsDSKmode</a></h3>
3586
3587
<p>Determine the behaviour of the DirAsDSK when inserting a directory to be used as diskimage.</p>
3588
3589
<p>The possible values are <code>read_only</code> and <code>full</code>. The default mode is <code>full</code>.</p>
3590
3591
<table>
3592
<tr>
3593
<td><code>read_only</code></td>
3594
<td>The MSX can not write to the virtual disk.<br/>Changes on the host-OS are still reflected on the virtual disk, however.</td>
3595
</tr>
3596
<tr>
3597
<td><code>full</code></td>
3598
<td>All changes are performed both ways, no restrictions apply.</td>
3599
</tr>
3600
</table>
3601
3602
<divclass="subsectiontitle">
3603
usage:
3604
</div>
3605
<table>
3606
<tr>
3607
<td><code>set DirAsDSKmode</code></td>
3608
<td>Shows the current setting</td>
3609
</tr>
3610
<tr>
3611
<td><code>set DirAsDSKmode read_only</code></td>
3612
<td>Disk image will be read only</td>
3613
</tr>
3614
</table>
3615
3616
<divclass="note">
3617
Note: this setting is only used when the directory is inserted, it is not possible to change the behaviour of the current virtual disk by altering the setting. The new setting will become effective after the current virtual disk has been ejected.
3618
</div>
3619
3620
3621
<h3><aid="deflicker">deflicker</a></h3>
3622
3623
<p>Turns deflicker on/off. deflicker is a filter which tries to detect pixels
3624
that alternate each frame between two different colour values and replaces
3625
those alternations with the average colour. It gives a very nice result for
3626
software (mostly demos) that use this technique to get the optical illusion
3627
of more colours than are actually supported by the hardware. It also works
3628
well in games with flickering sprites on a static background (like Maze of
3629
Galious). This setting is disabled by default because there aren't that many
3630
situations where the performance cost justifies the improved video quality. </p>
3631
3632
<divclass="subsectiontitle">
3633
usage:
3634
</div>
3635
3636
<table>
3637
<tr>
3638
<td><code>set deflicker</code></td>
3639
<td>Shows the current setting</td>
3640
</tr>
3641
3642
<tr>
3643
<td><code>set deflicker on</code></td>
3644
<td>Turns deflicker on</td>
3645
</tr>
3646
3647
<tr>
3648
<td><code>set deflicker off</code></td>
3649
<td>Turns deflicker off</td>
3650
</tr>
3651
</table>
3652
3653
3654
<h3><aid="deinterlace">deinterlace</a></h3>
3655
3656
<p>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.</p>
3657
3658
<divclass="subsectiontitle">
3659
usage:
3660
</div>
3661
3662
<table>
3663
<tr>
3664
<td><code>set deinterlace</code></td>
3665
<td>Shows the current setting</td>
3666
</tr>
3667
3668
<tr>
3669
<td><code>set deinterlace on</code></td>
3670
<td>Turns deinterlacing on</td>
3671
</tr>
3672
3673
<tr>
3674
<td><code>set deinterlace off</code></td>
3675
<td>Turns deinterlacing off</td>
3676
</tr>
3677
</table>
3678
3679
3680
<h3><aid="disablesprites">disablesprites</a></h3>
3681
3682
<p>Can be used to disable sprite rendering. Only the rendering itself is
3683
disabled, all other MSX behaviour (like sprite collision detection) stays
3684
the same.</p>
3685
3686
<divclass="subsectiontitle">
3687
usage:
3688
</div>
3689
3690
<table>
3691
<tr>
3692
<td><code>set disablesprites</code></td>
3693
<td>Shows the current setting</td>
3694
</tr>
3695
3696
<tr>
3697
<td><code>set disablesprites on</code></td>
3698
<td>Disable sprite rendering</td>
3699
</tr>
3700
3701
<tr>
3702
<td><code>set disablesprites off</code></td>
3703
<td>Enable sprite rendering (the default)</td>
3704
</tr>
3705
</table>
3706
3707
3708
<h3><aid="display_deform">display_deform</a></h3>
3709
3710
<p>Select display deformation effect.</p>
3711
3712
<divclass="subsectiontitle">
3713
usage:
3714
</div>
3715
3716
<table>
3717
<tr>
3718
<td><code>set display_deform</code></td>
3719
3720
<td>Shows the current setting</td>
3721
</tr>
3722
3723
<tr>
3724
<td><code>set display_deform normal</code></td>
3725
3726
<td>Turns off display deform</td>
3727
</tr>
3728
3729
<tr>
3730
<td><code>set display_deform 3d</code></td>
3731
3732
<td>Deforms the image in 3D, to look like a CRT (like JEmu2)</td>
3733
</tr>
3734
</table>
3735
3736
<divclass="note">
3737
Note: In the past there was also a 'horizontal_stretch' mode. This is now replaced by the <code><aclass="internal"href="#horizontal_stretch">horizontal_stretch</a></code> setting.
<p>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.
3765
</p>
3766
3767
<p>Sessions can also be saved manually with the command <code>save_session</code>, and explicitly loaded with <code>load_session</code>. A list of saved sessions can be retrieved with <code>list_sessions</code>.
3768
</p>
3769
3770
3771
<h3><aid="fastforward">fastforward</a></h3>
3772
3773
<p>Chooses between normal speed (off) and fastforward speed (on).</p>
3774
3775
<divclass="subsectiontitle">
3776
usage:
3777
</div>
3778
3779
<table>
3780
<tr>
3781
<td><code>set fastforward</code></td>
3782
3783
<td>Shows the current setting</td>
3784
</tr>
3785
3786
<tr>
3787
<td><code>set fastforward on</code></td>
3788
3789
<td>Run at fastforward speed: the <code><aclass="internal"href="#fastforwardspeed">fastforwardspeed</a></code> setting determines how fast the emulated MSX runs compared to real time</td>
3790
</tr>
3791
3792
<tr>
3793
<td><code>set fastforward off</code></td>
3794
3795
<td>Run at normal speed: the <code><aclass="internal"href="#speed">speed</a></code> setting determines how fast the emulated MSX runs compared to real time</td>
<p>Sets the emulation speed relative to the speed of a real MSX when we are running in <aclass="internal"href="#fastforward">fastforward mode</a>. Speed 100 means as fast as a real MSX, lower values are slower than real MSX, higher values are faster than real MSX.</p>
<td>Sets new fastforward speed to <num>% of real time</td>
3819
</tr>
3820
</table>
3821
3822
3823
<h3><aid="frequency">frequency</a></h3>
3824
3825
<p>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.</p>
3826
3827
<divclass="subsectiontitle">
3828
usage:
3829
</div>
3830
3831
<table>
3832
<tr>
3833
<td><code>set frequency</code></td>
3834
3835
<td>Shows the current setting</td>
3836
</tr>
3837
3838
<tr>
3839
<td><code>set frequency 44100</code></td>
3840
3841
<td>Use 44.1 kHz mixing frequency (CD quality)</td>
3842
</tr>
3843
</table>
3844
3845
3846
<h3><aid="firmwareswitch">firmwareswitch</a></h3>
3847
3848
<p>Some machines (e.g. turboR) have a switch on the front (or on the back) that controls if the machine should boot
3849
'normally' or start the built-in software, also called firmware. This setting controls the position of that
<p>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 (<code><aclass="internal"href="#throttle">throttle</a></code> 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 how a real MSX behaves.</p>
3909
3910
<p>Unlike the fast loading features in for example fMSX, <code>fullspeedwhenloading</code> does not intercept BIOS calls. Instead, it speeds up the emulation of the entire MSX, including all hardware devices.</p>
<p>Stretches the image to fill the entire screen when in fullscreen mode. This setting is useful when you want to use the full screen real estate, for example when displaying 4:3 content on a 16:9 monitor, or when you prefer to eliminate any black borders around the image.</p>
3940
3941
<divclass="subsectiontitle">
3942
usage:
3943
</div>
3944
3945
<table>
3946
<tr>
3947
<td><code>set full_stretch</code></td>
3948
<td>Shows the current setting</td>
3949
</tr>
3950
3951
<tr>
3952
<td><code>set full_stretch on</code></td>
3953
<td>Enable full screen stretching</td>
3954
</tr>
3955
3956
<tr>
3957
<td><code>set full_stretch off</code></td>
3958
<td>Disable full screen stretching</td>
3959
</tr>
3960
</table>
3961
3962
3963
<h3><aid="gamma">gamma</a></h3>
3964
3965
<p>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.</p>
3966
3967
<p>If you want to get a realistic picture, set the openMSX gamma correction to <i>PC gamma / MSX gamma</i>. TVs use a standardised gamma of 2.5, let's take that as the value of <i>MSX gamma</i>. You can measure the gamma of your PC screen with a simple test such as the Gamma Measurement Image in <aclass="external"href="https://web.archive.org/web/20150714015749/http://www.bberger.net/rwb/gamma.html">Robert W. Berger's "An Explanation of Monitor Gamma"</a>. If your <i>PC gamma</i> would be for example 2.0, the most realistic value for gamma correction would be 2.0 / 2.5 = 0.8.</p>
3968
3969
<p>Alternatively, you can just try a few values and see what you like.</p>
3970
3971
<divclass="subsectiontitle">
3972
usage:
3973
</div>
3974
3975
<table>
3976
<tr>
3977
<td><code>set gamma</code></td>
3978
3979
<td>Shows the current value</td>
3980
</tr>
3981
3982
<tr>
3983
<td><code>set gamma <num></code></td>
3984
3985
<td>Sets a new gamma correction amount</td>
3986
</tr>
3987
</table>
3988
3989
3990
<h3><aid="glow">glow</a></h3>
3991
3992
<p>Sets the amount of afterglow effect: 0 is off and 100 is a very heavy afterglow.</p>
3993
3994
<divclass="subsectiontitle">
3995
usage:
3996
</div>
3997
3998
<table>
3999
<tr>
4000
<td><code>set glow</code></td>
4001
4002
<td>Shows the current setting</td>
4003
</tr>
4004
4005
<tr>
4006
<td><code>set glow <value></code></td>
4007
4008
<td>Change the amount of afterglow</td>
4009
</tr>
4010
</table>
4011
4012
4013
<h3><aid="grabinput">grabinput</a></h3>
4014
4015
<p>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.</p>
4016
4017
<p>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 <aclass="internal"href="#escape_grab"><code>escape_grab</code></a>.</p>
<p>Sets the amount of horizontal stretch, thus also the aspect ratio of the screen. More specifically, a setting of <code>n</code> means stretch the centre <code>n</code> MSX pixels to the full width of the host output window (at the virtual <code><aclass="internal"href="#scale_factor">scale_factor</a></code> 1).</p>
<code>set horizontal_stretch 320</code> (no horizontal stretch)<br />
4072
<code>set horizontal_stretch 272</code> (approach real aspect ratio of MSX screen)<br />
4073
<code>set horizontal_stretch 280</code> (default: show all generated border pixels, so that all border demo effects are still visible)<br />
4074
<code>set horizontal_stretch 256</code> (borders are not visible at all; doesn't work well in combination with set-adjust)
4075
</div>
4076
4077
4078
<h3><aid="inputdelay">inputdelay</a></h3>
4079
4080
<p>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.</p>
4081
4082
<divclass="subsectiontitle">
4083
usage:
4084
</div>
4085
4086
<table>
4087
<tr>
4088
<td><code>set inputdelay</code></td>
4089
<td>Shows the current value</td>
4090
</tr>
4091
<tr>
4092
<td><code>set inputdelay <time></code></td>
4093
<td>Sets the input delay to the specified number of seconds</td>
4094
</tr>
4095
</table>
4096
4097
<divclass="note">
4098
Note: The default value of 0.0 seconds (no extra delay) should almost
4099
always be OK. It only makes sense to increase this setting if you have
4100
a slow host machine and you're typing text very fast and the emulated
<p>Selects the Tcl procedure to be called when the running MSX software has selected an invalid PPI mode. Or at least a PPI mode that's not yet correctly emulated. Typically on a real machine these modes will hang the MSX.</p>
4135
4136
<p>The default openMSX startup scripts initialize this setting with a proc that prints a warning message just once. Though if you're a developer you may want to change this to always print the warning or automatically break emulation when this happens so you can debug the problem.</p>
<p>Selects the Tcl procedure to be called when the running MSX software has selected invalid PSG port directions (port A should always be set as input).</p>
4156
4157
<p>The default openMSX startup scripts initialize this setting with a proc that prints a warning message just once. Though if you're a developer you may want to change this to always print the warning or automatically break emulation when this happens, so you can debug the problem.</p>
<td>Only toggle CODE/KANA lock status when user presses the CODE/KANA lock key</td>
4319
</tr>
4320
</table>
4321
4322
<divclass="note">
4323
Note: This only works on MSX models for which the CODE/KANA key locks (e.g. Japanese MSX models and the Philips VG8010). On other models, this setting is ignored.
<p>Host key that maps to the MSX CODE/KANA key. By default right-ALT (RALT) key.</p>
4330
<p>It is especially useful for
4331
people with AZERTY host keyboard, on which the RALT key has a special function; on
4332
azerty keyboards it is called the ALT-GR key and not the right-ALT key and it's used to
4333
enter some special characters (some keys are tagged with 3 characters; normal, key+SHIFT, key+ALT-GR).</p>
4334
<p>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.</p>
<p>The keyboard driver can work in several mapping modes: CHARACTER, POSITIONAL or KEY.</p>
4482
4483
<dl>
4484
<dt>CHARACTER mapping:</dt>
4485
<dd>A character entered by the user on the host keyboard is mapped to the correct key combination on the MSX keyboard to
4486
enter that same character. For example, when the user enters an '!' character and openMSX is emulating an 'international'
4487
MSX model, the keyboard driver will press SHIFT and '1' on the MSX keyboard. This will be done regardless of the key
4488
or keys that the user pressed on the host keyboard to enter that '!' character.<br/>
4489
This is especially useful when the user has an AZERTY host keyboard and is working on a QWERTY style MSX or
4490
when he has a US-QWERTY keyboard and is working on a Japanese MSX.<br/>
4491
In other words: in this mode openMSX is aware of both the host and the MSX keyboard layout and tries to remap host key-combinations to the corresponding MSX key-combinations that produce the same character.<br/>
4492
Special host keys (like CURSOR keys or CAPSLOCK) are mapped directly to the corresponding MSX keys.<br/>
4493
Note that CHARACTER mode isn't perfect (help to improve it is always appreciated). In some cases it may be more convenient or even required to use one of the other mapping modes.</dd>
4494
4495
<dt>POSITIONAL mapping:</dt>
4496
<dd>In this mode both the host and the MSX keyboard layout are ignored. Host keys get mapped to MSX keys that are (approximately) in the same position on both keyboards. (More technically, host 'scan-codes' get mapped to MSX 'keyboard-matrix positions'.)</dd>
4497
4498
<dt>KEY mapping:</dt>
4499
<dd>This mode is deprecated, it's superseded by the previous two modes and may get removed in a future openMSX release.<br/>
4500
This mode has rudimentary knowledge about the host keyboard layout, but no knowledge about the MSX keyboard layout. It remaps individual keys, not key combinations. Take for example a French AZERTY host keyboard and an emulated MSX with 'international' keyboard layout. Pressing the 'A' host key correctly maps to the 'A' MSX key. But pressing SHIFT+'3' on the host (which produces '3'), maps to SHIFT+'3' on the MSX keyboard (which produces '#').</dd>
<p>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: <code>power</code>, <code>caps</code>, <code>kana</code>, <code>pause</code>, <code>turbo</code> and <code>FDD</code>.</p>
4623
4624
<p>As for any setting you can use the native <code>trace</code> 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 <code><aclass="internal"href="#machine_info">machine_info</a></code> command.)</p>
4625
4626
4627
<h3><aid="limitsprites">limitsprites</a></h3>
4628
4629
<p>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.</p>
4630
4631
<p>The 5th/9th sprite status flag of the VDP is not influenced by the <code>limitsprites</code> setting: the flag always takes the limit into account.</p>
4632
4633
<divclass="subsectiontitle">
4634
usage:
4635
</div>
4636
4637
<table>
4638
<tr>
4639
<td><code>set limitsprites</code></td>
4640
4641
<td>Shows the current value</td>
4642
</tr>
4643
4644
<tr>
4645
<td><code>set limitsprites on</code></td>
4646
4647
<td>Limits number of sprites per line</td>
4648
</tr>
4649
4650
<tr>
4651
<td><code>set limitsprites off</code></td>
4652
4653
<td>Turns off number of sprites per line limit</td>
4654
</tr>
4655
</table>
4656
4657
4658
<h3><aid="master_volume">master_volume</a></h3>
4659
4660
<p>Controls the overall openMSX volume. The volume of individual sound devices can be controlled with the <code><aclass="internal"href="#soundchip_volume"><soundchip>_volume</a></code> settings.</p>
4661
4662
<divclass="subsectiontitle">
4663
usage:
4664
</div>
4665
4666
<table>
4667
<tr>
4668
<td><code>set master_volume</code></td>
4669
4670
<td>Shows current setting</td>
4671
</tr>
4672
4673
<tr>
4674
<td><code>set master_volume 50</code></td>
4675
4676
<td>Sets master volume to 50%</td>
4677
</tr>
4678
</table>
4679
4680
4681
<h3><aid="maxframeskip">maxframeskip</a></h3>
4682
4683
<p>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.</p>
4684
4685
<p>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 <code><aclass="internal"href="#minframeskip">minframeskip</a></code> and <code>maxframeskip</code> setting.</p>
4686
4687
<p>In a situation where the number of consecutive frames specified by <code>maxframeskip</code> has been skipped, openMSX will display the next frame, even if that means emulation will start lagging behind real time.</p>
<p>Sets the minimum amount of frames to skip: show a frame and then skip at least <number> frames.
4757
So 0 means no forced frame skipping, 1 means skip at least every second frame etc.</p>
4758
4759
<p>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 <code>minframeskip</code> and <code><aclass="internal"href="#maxframeskip">maxframeskip</a></code> setting.</p>
4760
4761
<p>The <code>minframeskip</code> 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.</p>
<p>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.</p>
4785
4786
<divclass="subsectiontitle">
4787
usage:
4788
</div>
4789
4790
<table>
4791
<tr>
4792
<td><code>set mode</code></td>
4793
4794
<td>Shows the current setting</td>
4795
</tr>
4796
4797
<tr>
4798
<td><code>set mode tas</code></td>
4799
4800
<td>Change mode to TAS mode</td>
4801
</tr>
4802
4803
<tr>
4804
<td><code>set mode normal</code></td>
4805
4806
<td>Set mode back to normal, which is the default (all purpose) mode</td>
4807
</tr>
4808
</table>
4809
4810
<h4>TAS mode</h4>
4811
4812
<p>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:</p>
4813
<ul>
4814
<li>frame counter (can also be toggled with <code>toggle_frame_counter</code>), which shows the VDP (not V9990) frame number on screen</li>
4815
<li>cursors (can also be toggled with <code>toggle_cursors</code>), shows which keys (important for games) are pressed</li>
4816
</ul>
4817
<p>The mode configures the following key bindings, overriding any existing key bindings (note: Mac key bindings are not proper yet...):</p>
<tr><td>F8</td><td>(F8)</td><td>Save replay to current slot</td></tr>
4823
<tr><td>End</td><td>(End)</td><td>Advance one frame (<code>advance_frame</code>)</td></tr>
4824
<tr><td>ScrollLock</td><td>(ScrollLock)</td><td>Reverse one frame (<code>reverse_frame</code>)</td></tr>
4825
</table>
4826
4827
<p>Note that this mode may change in future releases!</p>
4828
4829
4830
<h3><aid="mute">mute</a></h3>
4831
4832
<p>Mute/unmute all sound output.</p>
4833
4834
<divclass="subsectiontitle">
4835
usage:
4836
</div>
4837
4838
<table>
4839
<tr>
4840
<td><code>set mute</code></td>
4841
4842
<td>Shows the current setting</td>
4843
</tr>
4844
4845
<tr>
4846
<td><code>set mute on</code></td>
4847
4848
<td>Mute sound</td>
4849
</tr>
4850
4851
<tr>
4852
<td><code>set mute off</code></td>
4853
4854
<td>Unmute sound</td>
4855
</tr>
4856
</table>
4857
4858
4859
<h3><aid="noise">noise</a></h3>
4860
4861
<p>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.</p>
4862
4863
<p>This setting is best combined with <code><aclass="internal"href="#brightness">brightness</a></code> and <code><aclass="internal"href="#contrast">contrast</a></code>: 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 <code><aclass="internal"href="#brightness">brightness</a></code> slightly above 0 and <code><aclass="internal"href="#contrast">contrast</a></code> slightly below 0, you will get a better looking noise effect.</p>
4864
4865
<divclass="subsectiontitle">
4866
usage:
4867
</div>
4868
4869
<table>
4870
<tr>
4871
<td><code>set noise</code></td>
4872
4873
<td>Shows the current setting</td>
4874
</tr>
4875
4876
<tr>
4877
<td><code>set noise 7</code></td>
4878
4879
<td>Add a moderate amount of noise</td>
4880
</tr>
4881
</table>
4882
4883
4884
<h3><aid="pause">pause</a></h3>
4885
4886
<p>Pauses the emulation.</p>
4887
4888
<divclass="subsectiontitle">
4889
usage:
4890
</div>
4891
4892
<table>
4893
<tr>
4894
<td><code>set pause</code></td>
4895
4896
<td>Shows the current setting</td>
4897
</tr>
4898
4899
<tr>
4900
<td><code>set pause on</code></td>
4901
4902
<td>Pauses emulation</td>
4903
</tr>
4904
4905
<tr>
4906
<td><code>set pause off</code></td>
4907
4908
<td>Unpauses emulation</td>
4909
</tr>
4910
</table>
4911
4912
<divclass="note">
4913
Note: Some video settings cannot be applied to an already rendered frame and will therefore not take effect until openMSX is unpaused.
<p>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.
<p>These two settings control the R800 clock frequency. See <code><aclass="internal"href="#z80_freq">z80_freq / z80_freq_locked</a></code> for details.</p>
5215
5216
5217
<h3><aid="renderer">renderer</a></h3>
5218
5219
<p>Switch to a different video renderer. However, currently there is only one alternative: <code>none</code>, and that is useful only for disabling rendering in scripts completely.</p>
5220
5221
<divclass="subsectiontitle">
5222
usage:
5223
</div>
5224
5225
<table>
5226
<tr>
5227
<td><code>set renderer</code></td>
5228
5229
<td>Shows the current setting</td>
5230
</tr>
5231
5232
<tr>
5233
<td><code>set renderer none</code></td>
5234
5235
<td>Disable rendering completely</td>
5236
</tr>
5237
</table>
5238
5239
5240
<h3><aid="renshaturbo">renshaturbo</a></h3>
5241
5242
<p>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.</p>
5243
5244
<divclass="subsectiontitle">
5245
usage:
5246
</div>
5247
5248
<table>
5249
<tr>
5250
<td><code>set renshaturbo</code></td>
5251
5252
<td>Shows the current renshaturbo value</td>
5253
</tr>
5254
5255
<tr>
5256
<td><code>set renshaturbo <num></code></td>
5257
5258
<td>Sets speed to value <num></td>
5259
</tr>
5260
</table>
5261
5262
<divclass="note">
5263
Note: This setting is only available if the current MSX machine has hardware Ren-Sha Turbo support.
5264
</div>
5265
5266
5267
<h3><aid="resampler">resampler</a></h3>
5268
5269
<p>Sets the method to resample the sound of sound chips from their native frequency to the <aclass="internal"href="#frequency">desired output frequency</a>.</p>
5270
5271
<divclass="subsectiontitle">
5272
usage:
5273
</div>
5274
5275
<table>
5276
<tr>
5277
<td><code>set resampler</code></td>
5278
5279
<td>Shows the currently active resampler</td>
5280
</tr>
5281
5282
<tr>
5283
<td><code>set resampler blip</code></td>
5284
5285
<td>Sets the <ahref="http://slack.net/~ant/libs/audio.html#Blip_Buffer">Blip_Buffer</a> based resampler, which has the best quality per CPU usage ratio.</td>
5286
</tr>
5287
5288
<tr>
5289
<td><code>set resampler hq</code></td>
5290
5291
<td>Sets the highest quality resampler, but it also takes the most CPU time. It's based on the <ahref="http://www.mega-nerd.com/SRC/">libsamplerate</a> algorithm. This is the default value on most platforms, as it gives the best quality.</td>
<p>Enable the use of the IP232 protocol when used in conjunction with the <code>TCPSer</code> software modem. Note that
5386
<code>rs232-net</code> has to be plugged in the <code>msx-rs232</code>
5387
connector and <code>rs232-net-address</code> must point to the ip address and port of a running TCPSer instance.</p>
5388
<p>The IP232 protocol permits the correct emulation of some of the RS-232 port control lines.</p>
5389
<p>This setting must be disabled when using <code>rs232net</code> without <code>TCPSer</code>.</p>
5390
5391
<divclass="subsectiontitle">
5392
usage:
5393
</div>
5394
5395
<table>
5396
<tr>
5397
<td><code>set rs232-net-ip232</code></td>
5398
5399
<td>Shows the current setting</td>
5400
</tr>
5401
5402
<tr>
5403
<td><code>set rs232-net-ip232 on</code></td>
5404
5405
<td>Enable the IP232 protocol</td>
5406
</tr>
5407
5408
<tr>
5409
<td><code>set rs232-net-ip232 off</code></td>
5410
5411
<td>Disable the IP232 protocol</td>
5412
</tr>
5413
5414
</table>
5415
5416
5417
<h3><aid="rtcmode">rtcmode</a></h3>
5418
5419
<p>Sets the Real Time Clock mode. Can be either <code>RealTime</code> or <code>EmuTime</code>.</p>
5420
5421
<p>In <code>RealTime</code> 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.</p>
5422
5423
<p>In <code>EmuTime</code> 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.</p>
5424
5425
<p>In <code>EmuTime</code> mode it's not possible for an 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 <code>RealTime</code> 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.</p>
5426
5427
<divclass="subsectiontitle">
5428
usage:
5429
</div>
5430
5431
<table>
5432
<tr>
5433
<td><code>set rtcmode</code></td>
5434
5435
<td>Shows the current mode</td>
5436
</tr>
5437
5438
<tr>
5439
<td><code>set rtcmode EmuTime</code></td>
5440
5441
<td>Set EmuTime mode (the default)</td>
5442
</tr>
5443
5444
<tr>
5445
<td><code>set rtcmode RealTime</code></td>
5446
5447
<td>Set RealTime mode</td>
5448
</tr>
5449
</table>
5450
5451
5452
<h3><aid="samples">samples</a></h3>
5453
5454
<p>Sets the size of the sound mixer buffer. Higher values help against buffer underruns (hickups), but increase the latency of the sound output.</p>
<p>Automatically save the current settings when openMSX exits: execute a <code><aclass="internal"href="#save_settings">save_settings</a></code> command on exit.</p>
<p>Specify the setup name to use when automatically saving the setup when exiting openMSX is active. See also the <code><aclass="internal"href="#save_setup_at_exit_depth">save_setup_at_exit_depth</a></code> setting.</p>
5507
5508
<p>In the GUI, under <spanclass="menu-reference">Main menu bar → Machine
5509
→ Setup settings</span> you can also configure what openMSX must do at startup, configuring this setting there.</p>
<p>Specify the depth to use when automatically saving the setup when exiting openMSX. If the depth is set to <code>none</code> (which is the default), the auto-save is not active, but otherwise the setup will be saved under the name specified by the <code><aclass="internal"href="#save_setup_at_exit_name">save_setup_at_exit_name</a></code> setting. See also the <code><aclass="internal"href="#store_setup">store_setup</a></code> command to find out about other depths that can be specified.</p>
5534
5535
<p>In the GUI, under <spanclass="menu-reference">Main menu bar → Machine
5536
→ Setup settings</span> you can also configure what openMSX must do at startup, configuring this setting there.</p>
<td>When openMSX exits, the complete state is saved into the setup.</td>
5559
</tr>
5560
5561
</table>
5562
5563
<divclass="note">
5564
If you enable this auto save of the setup and use the same name as for the <code><aclass="internal"href="#default_setup">default_setup</a></code> setting, openMSX will automatically continue with the last setup when being started up again (and no other machine or setup is specified).
<p>Selects the algorithm used to transform MSX pixels to host pixels. The User's Manual contains <aclass="external"href="user.html#scalers">more information about scalers</a>.
5571
</p>
5572
5573
<divclass="subsectiontitle">
5574
usage:
5575
</div>
5576
5577
<table>
5578
<tr>
5579
<td><code>set scale_algorithm</code></td>
5580
5581
<td>Shows the current setting</td>
5582
</tr>
5583
5584
<tr>
5585
<td><code>set scale_algorithm simple</code></td>
5586
5587
<td>Selects the default scale algorithm</td>
5588
</tr>
5589
5590
<tr>
5591
<td><code>set scale_algorithm hq</code></td>
5592
5593
<td>Selects the HQ2x/3x/4x scale algorithm</td>
5594
</tr>
5595
</table>
5596
5597
5598
<h3><aid="scale_factor">scale_factor</a></h3>
5599
5600
<p>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 2 to 4. In the future we may support a wider range or even non-integer values. The User's Manual contains <aclass="external"href="user.html#scalers">more information about scalers</a>.</p>
5601
5602
<divclass="subsectiontitle">
5603
usage:
5604
</div>
5605
5606
<table>
5607
<tr>
5608
<td><code>set scale_factor</code></td>
5609
5610
<td>Shows the current setting</td>
5611
</tr>
5612
5613
<tr>
5614
<td><code>set scale_factor <n></code></td>
5615
5616
<td>Sets a new scale factor</td>
5617
</tr>
5618
</table>
5619
5620
5621
<h3><aid="scanline">scanline</a></h3>
5622
5623
<p>Sets the amount of scanline effect.</p>
5624
5625
<divclass="subsectiontitle">
5626
usage:
5627
</div>
5628
5629
<table>
5630
<tr>
5631
<td><code>set scanline</code></td>
5632
5633
<td>Shows the current setting</td>
5634
</tr>
5635
5636
<tr>
5637
<td><code>set scanline <value></code></td>
5638
5639
<td>Changes the value</td>
5640
</tr>
5641
</table>
5642
5643
<divclass="note">
5644
Note: Some scalers will not render scanlines at all.
5645
</div>
5646
5647
5648
<h3><aid="sound_driver">sound_driver</a></h3>
5649
5650
<p>Select the sound output driver.</p>
5651
5652
<divclass="subsectiontitle">
5653
usage:
5654
</div>
5655
5656
<table>
5657
<tr>
5658
<td><code>set sound_driver sdl</code></td>
5659
5660
<td>Selects the SDL sound driver</td>
5661
</tr>
5662
5663
<tr>
5664
<td><code>set sound_driver null</code></td>
5665
5666
<td>Selects the null sound driver (no sound)</td>
5667
</tr>
5668
</table>
5669
5670
5671
<h3><aid="speed">speed</a></h3>
5672
5673
<p>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.</p>
5674
5675
<divclass="subsectiontitle">
5676
usage:
5677
</div>
5678
5679
<table>
5680
<tr>
5681
<td><code>set speed</code></td>
5682
5683
<td>Shows current emulation speed</td>
5684
</tr>
5685
5686
<tr>
5687
<td><code>set speed <num></code></td>
5688
5689
<td>Sets new emulation speed to <num>% of real time</td>
<p>Sets the balance (distribution over the left and right channel) for individual sound chips. It replaces the previously available <code><soundchip>_mode</code> setting. The range is between -100 (totally left) and 100 (totally right).</p>
<p>Sets the volume for individual sound chips. The overall volume is controlled by the <code><aclass="internal"href="#master_volume">master_volume</a></code> setting.
<td>Sets new volume; 0 is off, 100 is maximum</td>
5840
</tr>
5841
</table>
5842
5843
<divclass="subsectiontitle">
5844
examples:
5845
</div>
5846
5847
<divclass="examples">
5848
<code>set PSG_volume</code><br />
5849
<code>set PSG_volume 60</code><br />
5850
<code>set "FMPAC_volume" 50</code>
5851
</div>
5852
5853
5854
<h3><aid="throttle">throttle</a></h3>
5855
5856
<p>Sets throttle mode. In throttle mode the emulator tries to run at the specified speed relative to a real MSX (see <aclass="internal"href="#speed">speed</a> command). When throttling is turned off the emulator runs as fast as possible.</p>
<td>Attempt to map touch coordinates to corresponding MSX pixel coordinates.</td>
5982
</tr>
5983
</table>
5984
5985
<!-- TODO write Tcl scripts to setup this matrix
5986
<div class="note">
5987
Note: It is often more convenient to use the <code><a class="internal" href="#monitor_type">monitor_type</a></code> command.
5988
</div>
5989
-->
5990
5991
<h3><aid="turborpause">turborpause</a></h3>
5992
5993
<p>Controls the pause key on an MSX turboR machine.</p>
5994
5995
<divclass="subsectiontitle">
5996
usage:
5997
</div>
5998
5999
<table>
6000
<tr>
6001
<td><code>set turborpause</code></td>
6002
6003
<td>Shows the current setting</td>
6004
</tr>
6005
6006
<tr>
6007
<td><code>set turborpause on</code></td>
6008
6009
<td>Activate the pause key</td>
6010
</tr>
6011
6012
<tr>
6013
<td><code>set turborpause off</code></td>
6014
6015
<td>Deactivate the pause key</td>
6016
</tr>
6017
</table>
6018
6019
<divclass="note">
6020
Note: If you use this setting often, it may be useful to bind it to a key on your PC keyboard. See the <code><aclass="internal"href="#bind">bind</a></code> and <code><aclass="internal"href="#toggle">toggle</a></code> commands.
6021
</div>
6022
6023
6024
<h3><aid="umr_callback">umr_callback</a></h3>
6025
6026
<p>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.</p>
6027
6028
<p>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 <code>umrcallback</code> which logs all UMRs. You can activate it with <code>set umr_callback umrcallback</code>. You can find the source code for this procedure in <code>scripts/callbackprocs.tcl</code>.</p>
<p>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.</p>
6048
6049
<p>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 <code>vdpcmdinprogresscallback</code> which simply logs all occurrences. You can activate it with <code>set vdpcmdinprogress_callback vdpcmdinprogresscallback</code>. You can find the source code for this proc in <code>scripts/callbackprocs.tcl</code>. Feel free to write your own proc that does exactly what you need. For example it might be a good idea to execute <code>debug break</code> in your callback, so that you can easily examine what code triggered this write.</p>
<td>Sets callback to <code>vdpcmdinprogresscallback</code></td>
6062
</tr>
6063
</table>
6064
6065
6066
<h3><aid="vdpcmdtrace">vdpcmdtrace</a></h3>
6067
6068
<p>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.</p>
6069
6070
<divclass="subsectiontitle">
6071
usage:
6072
</div>
6073
6074
<table>
6075
<tr>
6076
<td><code>set vdpcmdtrace</code></td>
6077
6078
<td>Shows the current setting</td>
6079
</tr>
6080
6081
<tr>
6082
<td><code>set vdpcmdtrace on</code></td>
6083
6084
<td>Enables VDP command tracing</td>
6085
</tr>
6086
6087
<tr>
6088
<td><code>set vdpcmdtrace off</code></td>
6089
6090
<td>Disables VDP command tracing</td>
6091
</tr>
6092
</table>
6093
6094
6095
<h3><aid="videosource">videosource</a></h3>
6096
6097
<p>Switch between video sources: <code>MSX</code> (V99x8, default when no
6098
Video 9000 is available), <code>GFX9000</code> (V9990),
6099
<code>Video9000</code> (V9990 superimposed on top of V99x8, default if
6100
available) and <code>Laserdisc</code> (for Palcom machines). There can be
6101
even more video sources, e.g. offered by cartridges with a built-in VDP such as the Neos MA-20(V).
6102
</p>
6103
6104
<divclass="subsectiontitle">
6105
usage:
6106
</div>
6107
6108
<table>
6109
<tr>
6110
<td><code>set videosource</code></td>
6111
6112
<td>Shows the current setting</td>
6113
</tr>
6114
6115
<tr>
6116
<td><code>set videosource MSX</code></td>
6117
6118
<td>Switch to normal MSX screen</td>
6119
</tr>
6120
6121
<tr>
6122
<td><code>set videosource GFX9000</code></td>
6123
6124
<td>Switch to GFX9000 screen</td>
6125
</tr>
6126
</table>
6127
6128
<divclass="note">
6129
Note: This setting is only available if multiple video sources are present.
6130
</div>
6131
6132
6133
<h3><aid="vsync">vsync</a></h3>
6134
6135
<p>Enables or disables vsync. This setting determines whether MSX frame rendering should be synchronized to your host monitors frame rate (e.g. 60fps).</p>
6136
<p>The default value is not to synchronize ("<code>off</code>"). When enabled, adaptive vsync is attempted if your hardware and driver support it, which means that if a frame is too late, it will be output immediately anyway. If not supported, normal vsync will be used, which may mean a frame is output later, when the sync is missed.</p>
6137
<p>Enable this if your MSX is running at about the same frame rate as your monitor (e.g. 60Hz MSX output on a 60Hz host monitor) and you want to avoid (or reduce) tearing, which can be quite visible in smooth horizontal scrolling demos. Keep in mind <aclass="internal"href="#throttle">throttle mode</a> off works a bit differently if vsync is enabled (see there).</p>
6138
6139
<divclass="subsectiontitle">
6140
usage:
6141
</div>
6142
6143
<table>
6144
<tr>
6145
<td><code>set vsync</code></td>
6146
6147
<td>Shows the current setting</td>
6148
</tr>
6149
6150
<tr>
6151
<td><code>set vsync off</code></td>
6152
6153
<td>No synchronization to monitor frame rate: draw immediately</td>
6154
</tr>
6155
6156
<tr>
6157
<td><code>set vsync on</code></td>
6158
6159
<td>Synchronize to monitor frame rate when possible, otherwise draw immediately. Or, when this is not available on the host hardware/driver, synchronize to monitor frame rate always (default)</td>
6160
</tr>
6161
6162
</table>
6163
6164
6165
<h3><aid="v9990cmdtrace">v9990cmdtrace</a></h3>
6166
6167
<p>Enable/disable V9990 command tracing. This is the V9990 equivalent of <code><aclass="internal"href="#vdpcmdtrace">vdpcmdtrace</a></code>.</p>
6168
6169
<divclass="subsectiontitle">
6170
usage:
6171
</div>
6172
6173
<table>
6174
<tr>
6175
<td><code>set v9990cmdtrace</code></td>
6176
6177
<td>Shows the current setting</td>
6178
</tr>
6179
6180
<tr>
6181
<td><code>set v9990cmdtrace on</code></td>
6182
6183
<td>Enables V9990 command tracing</td>
6184
</tr>
6185
6186
<tr>
6187
<td><code>set v9990cmdtrace off</code></td>
6188
6189
<td>Disables V9990 command tracing</td>
6190
</tr>
6191
</table>
6192
6193
<divclass="note">
6194
Note: This setting is only available if the <code>gfx9000</code> or
<p>These two settings control the Z80 clock frequency. When <code>z80_freq_locked</code> is true the emulated Z80 runs at the normal 3.579545 MHz (or possibly 5.369318 MHz on machines that are able to switch the CPU to 'turbo' mode, e.g. the Panasonic MSX2+ models). When <code>z80_freq_locked</code> is false the value of <code>z80_freq</code> is taken as the Z80 clock frequency. Note: the value of <code>z80_freq</code> is by default the MSX Z80 standard of 3579545, so when <code>z80_freq</code> is untouched, setting <code>z80_freq_locked</code> to false will set the clock frequency of a CPU in 5.37 Mhz turbo mode back to 3.58 Mhz.</p>
6202
6203
<p>WARNING: be careful when changing these settings. When saving the settings in which a different clock is activated, this will be applied for all machines, as these are global settings. Some software (like demos) may stop working properly with a changed CPU clock frequency. Specifically, using a value (just) below the normal value may cause problems loading CAS images, as these are converted to a high baud rate WAV file internally and when the MSX becomes slower it cannot handle that high baud rate.</p>
<p>Like with the commands, there are also some specialized settings, for which we only list a very brief overview. As always execute "<code>help setting <setting-name></code>" to get a more detailed description of the setting.</p>
6223
6224
<table>
6225
<tr>
6226
<td><code>fast_cas_load_hack_enabled</code></td>
6227
<td>Enable a hack that lets you quickly load CAS files, without having openMSX convert them to WAV</td>
6228
</tr>
6229
</table>
6230
6231
<p>The source code of all these scripts is located in <code>share/scripts</code> directory. Feel free to inspect these scripts and modify them to suit your needs.</p>