annotate README @ 2286:5d3411f52d00

Fix ui.reload for locked-on ROMs
author Michael Pavone <pavone@retrodev.com>
date Fri, 13 Jan 2023 23:42:46 -0800
parents 8aeac7bd9fa7
children 92449b47cce8
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
1 BlastEm 0.6.0
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
2 -------------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
3
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
4 Installation
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
5 ------------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
6
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
7 Extract this archive to a directory of your choosing.
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
8
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
9 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
10 and save files. If you're upgrading from a previous version on Windows, you will
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
11 need to move them manually. For config files, the relevant paths are in the
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
12 previous paragraph. For save files, move all the directories found in
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
13 %userprofile%\.local\share\blastem to %localappdata%\blastem
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
14
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
15 Usage
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
16 -----
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
17
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
18 This version of BlastEm has a GUI that allows access to most configuration options.
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
19 Simply start BlastEm without passing a ROM filename on the command line to access
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
20 the main menu. You can also access the menu by hitting the button mapped to the ui.exit
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
21 action (default Esc).
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
22
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
23 If Open GL is disabled or unavaible, or you explicitly request it, the old ROM-based UI
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
24 will be used instead. This UI does not support configuration so you will need to modify
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
25 the configuration file manually if you use it. See the rest of this README for instructions
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
26 on modifying the configuration file.
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
27
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
28 Some operations are currently only supported through the command line. To get a
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
29 list of supported command line options on Linux or OSX type:
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
30
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
31 ./blastem -h
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
32
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
33 From within your BlastEm directory. On Windows type:
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
34
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
35 blastem.exe -h
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
36
1017
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
37 Lock-On Support
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
38 ---------------
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
39
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
40 This version of BlastEm has some preliminary support for Sonic & Knuckles lock
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
41 on technology. This is available via both the menu and the command line. To use
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
42 it from the menu, first load Sonic & Knuckles normally. Enter the menu (mapped
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
43 to the Escape key by default) and select the "Lock On" option to select a ROM
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
44 to lock on. The system will then reload with the combined game. To use it from
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
45 the command line, specify the Sonic & Knuckles ROM as the primary ROM and
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
46 specify the ROM to be locked on using the -o option. As an example:
1017
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
47
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
48 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
49
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
50 Please note that Sonic 2 lock-on does not work at this time.
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
51
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
52 Configuration
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
53 -------------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
54
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
55 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
56 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists.
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
57 Othwerise it is read from default.cfg from the same directory as the BlastEm
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
58 executable. Sections are denoted by a section name followed by an open curly
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
59 bracket, the section's contents and a closing curly bracket. Individual
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
60 configuration values are set by entering the value's name followed by a space
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
61 or tab and followed by the desired value.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
62
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
63 Bindings
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
64 --------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
65
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
66 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
67 actions. The key name goes on the left and the action is on the right.
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
68 Most keys are named for the character they produce when pressed. For keys that
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
69 don't correspond to a normal character, check the list below:
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
70
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
71 Name | Description
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
72 -----------------
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
73 up Up arrow
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
74 down Down arrow
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
75 left Left arrow
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
76 right Right arrow
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
77 space
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
78 tab
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
79 backspace Backspace on PC keyboards, Delete on Mac keyboards
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
80 esc
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
81 delete
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
82 lshift Left shift
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
83 rshift Right shift
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
84 lctrl Left control
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
85 rctrl Right control
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
86 lalt Left alt on PC keyboards, Option on Mac keyboards
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
87 ralt Right alt on PC keyboards, Option on Mac keyboards
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
88 home
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
89 end
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
90 pageup
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
91 pagedown
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
92 f1
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
93 f2
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
94 f3
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
95 f4
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
96 f5
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
97 f6
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
98 f7
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
99 f8
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
100 f9
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
101 f10
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
102 f11
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
103 f12
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
104 select
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
105 play
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
106 search
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
107 back
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
108
1227
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
109 The pads subsection is used to map gamepads and joysticks. Gamepads that are
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
110 recognized, can have their buttons and axes mapped with semantic names.
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
111 Xbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
112 mapped using numeric button and axis ids. The following button names are
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
113 recognized by BlastEm:
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
114 a, cross
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
115 b, circle
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
116 x, square
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
117 y, trinagle
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
118 start, options
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
119 back, select, share
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
120 guide
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
121 leftbutton, l1
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
122 rightbutton, r1
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
123 leftstick, l3
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
124 rightstick, r3
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
125 The following axis names are recognized by BlastEm:
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
126 leftx
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
127 lefty
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
128 rightx
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
129 righty
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
130 lefttrigger, l2
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
131 righttrigger, r2
262c0ce8f586 WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents: 1069
diff changeset
132
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
133
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
134 The mice subsection is used to map mice to emulated Mega/Sega mice. The default
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
135 configuration maps both the first and second host mice to the first emulated
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
136 mouse. This should not need modification for most users.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
137
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
138 One special mapping deserves a mention. By default, the 'r' key is mapped to
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
139 ui.release_mouse. When operating in windowed mode the mouse has a capture
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
140 behavior. Mouse events are ignored until you click in the window. The mouse
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
141 will then be "captured" and the cursor will be both made invisible and locked
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
142 to the window. The ui.release_mouse binding releases the mouse so it can be
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
143 used normally.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
144
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
145 UI Actions
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
146 ----------
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
147
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
148 This section lists the various "UI" actions that can be triggered by a key or
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
149 gamepad binding.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
150
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
151 ui.release_mouse Releases the mouse if it is currently captured
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
152 ui.plane_debug Toggles the VDP plane debug view
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
153 ui.vram_debug Toggles the VDP VRAM debug view
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
154 ui.cram_debug Toggles the VDP CRAM debug view
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
155 ui.compositing_debug Toggles the VDP compositing debug view
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
156 ui.vdp_debug_mode Cycles the mode/palette of the VDP debug view
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
157 that currently has focus
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
158 ui.enter_debugger Enters the debugger for the main CPU of the
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
159 currently emulated system
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
160 ui.screenshot Takes an internal screenshot
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
161 ui.exit Returns to the menu ROM if currently in a game
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
162 that was launched from the menu. Exits otherwise
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
163 ui.save_state Saves a savestate to the quicksave slot
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
164 ui.set_speed.N Selects a specific machine speed specified by N
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
165 which should be a number between 0-9. Speeds are
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
166 specified in the "clocks" section of the config
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
167 ui.next_speed Selects the next machine speed
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
168 ui.prev_speed Selects the previous machine speed
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
169 ui.toggle_fullscreen Toggles between fullscreen and windowed mode
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
170 ui.soft_reset Resets a portion of the emulated machine
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
171 Equivalent to pushing the reset button on the
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
172 emulated device
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
173 ui.reload Reloads the current ROM from a file and performs
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
174 a hard reset of the emulated device
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
175 ui.sms_pause Triggers a press of the pause button when in SMS
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
176 mode
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
177 ui.toggle_keyboard_captured Toggles the capture state of the host keyboard
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
178 when an emulated keyboard is present
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
179
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
180 IO
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
181 --
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
182
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
183 This section controls which peripherals are attached to the emulated console.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
184 IO assignments can be overridden by the ROM database when appropriate. For
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
185 instance, games with mouse support can automatically use the mouse and games
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
186 that only support 3-button pads can automatically force an appropriate pad.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
187 Unforunately, the ROM database is not yet exhaustive so manual configuration
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
188 may be needed here in some cases.
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
189
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
190 Video
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
191 -----
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
192
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
193 The video section contains settings that affect the visual output of BlastEm.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
194
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
195 "aspect" is used to control the aspect ratio of the emulated display. The
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
196 default of 4:3 matches that of a standard definition television.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
197
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
198 "width" is used to control the window width when not in fullscreen mode.
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
199
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
200 "height" is used to control the window height when not in fullscreen mode. If
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
201 left unspecified, it will be calculated from "width" and "aspect".
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
202
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
203 "vertex_shader" and "fragment_shader" define the GLSL shader program that
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
204 produces the final image for each frame. Shaders can be used to add various
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
205 visual effects or enhancements. Currently BlastEm only ships with the default
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
206 shader and a "subtle" crt shader. If you write your own shaders, place them in
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
207 $HOME/.config/blastem/shaders and then specify the basename of the new shader
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
208 files in the "vertex_shader" and "fragment_shader" config options. Note that
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
209 shaders are not available in the SDL fallback renderer.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
210
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
211 "scanlines" controls whether there is any emulation of the gaps between display
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
212 lines that are present when driving a CRT television with a 240p signal. This
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
213 emulation is very basic at the moment so this option is off by default.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
214
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
215 "vsync" controls whether the drawing of frames is synchronized to the monitor
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
216 refresh rate. Valid values for this setting are "off", "on" and "tear". The
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
217 latter will attempt to use the "late tear" option if it's available and normal
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
218 vsync otherwise. Currently it's recommended to leave this at the default of
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
219 "off" as it may not work well with the default "audio" sync method and the
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
220 "video" sync method will automatically enable "vsync". See "Sync Source and
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
221 VSync" for more details.
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
222
1017
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
223 "fullscreen" controls whether BlastEm starts in fullscreen or windowed mode.
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
224 This can be overridden on the command line with the -f flag. If fullscreen
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
225 is set to "off", -f will turn it on. Conversely, if fullscreen is set to "on"
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
226 in the config, -f will turn it off.
216fa63749b3 Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents: 1014
diff changeset
227
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
228 "gl" controls whether OpenGL is used for rendering. The default value is on.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
229 If it is set to off instead, the fallback renderer which uses SDL2's render API
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
230 will be used instead. This option is mostly useful for users on hardware that
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
231 lacks OpenGL 2 support. While BlastEm will fall back automatically even if gl
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
232 is set to on there will be a warning. Disabling gl eliminates this warning.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
233
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
234 "scaling" controls the type of scaling used for textures in both the GL and
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
235 SDL renderers. Valid values are "nearest" and "linear". Note that shaders also
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
236 impact how pixels are scaled.
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
237
1352
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
238 The "ntsc" and "pal" sub-sections control overscan settings for the emulated
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
239 video output for NTSC and PAL consoles respectively. More details are available
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
240 in the Overscan section.
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
241
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
242 Overscan
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
243 --------
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
244
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
245 Analog televisions generally don't display the entirety of a video frame. Some
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
246 portion is cropped at the edges of the display. This is called overscan.
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
247 Unfortunately, the amount of cropping performed varies considerably and is even
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
248 adjustable on many TV sets. To deal with this, BlastEm allows overscan to be
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
249 customized.
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
250
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
251 Overscan values are specified in the "ntsc" and "pal" sub-sections of the
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
252 "video" section of the config file. The "overscan" sub-section contains four
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
253 settings for specifying the number of pixels cropped on each side of the
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
254 display: "top", "bottom", "left" and "right".
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
255
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
256 The default settings hide the horizontal border completely for both NTSC and
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
257 PAL consoles. For the vertical borders, the NTSC overscan settings are chosen
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
258 to give square pixels with the default aspect ratio of 4:3. For PAL, the
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
259 default settings are set so that the PAL-exclusive V30 mode will produce a
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
260 visible border that is the same size as what is shown in V28 mode in NTSC. This
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
261 results in a slightly squished picture compared to NTSC which is probably
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
262 appropriate given that a PAL display has more lines than an NTSC one.
90c9922b5430 Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents: 1227
diff changeset
263
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
264 Audio
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
265 -----
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
266
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
267 The audio section contains settings that affect the audio output of BlastEm.
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
268
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
269 "rate" selects the preferred sample rate for audio output. Your operating
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
270 system may not accept this value in which case a different rate will be chosen.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
271 This should generally be either the native sample rate of your sound card or an
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
272 integral divisor of it. Most modern sound cards have a native output rate that
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
273 is a multiple of 48000 Hz so the default setting should work well for most users.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
274
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
275 "buffer size" controls how large of a buffer uses for audio data. Smaller values
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
276 will reduce latency, but too small of a value can lead to dropouts. 512 works
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
277 well for me, but a higher or lower value may be more appropriate for your system.
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
278
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
279 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
280 low-pass filter. The default value of 3390 Hz is supposedly what is present in
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
281 at least some Genesis/Megadrive models. Other models reportedly use an even
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
282 lower value.
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
283
1812
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
284 "gain" specifies the gain in decibels to be applied to the overall output.
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
285
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
286 "fm_gain" specifies the gain to be applied to the emulated FM output before
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
287 mixing with the PSG.
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
288
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
289 "psg_gain" specifies the gain to be applied to the emulated PSG output before
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
290 mixing with the FM chip.
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
291
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
292 "fm_dac" controls the characteristics of the DAC in the emulated FM chip. If
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
293 this is set to "linear", then the DAC will have precise linear output similar
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
294 to the integrated YM3438 in later Gen/MD consoles. If it is set to "zero_offset",
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
295 there will be a larger gap between -1 and 0. This is commonly referred to as the
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
296 "ladder effect". This will also cause "leakage" on channels that are muted or
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
297 panned to one side in a similar manner to a discrete YM2612.
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
298
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
299
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
300 Clocks
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
301 ------
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
302
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
303 The clocks section contains settings that affect how fast things run.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
304
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
305 "m68k_divider" describes the relationsip between the master clock (which is
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
306 53693175 Hz for NTSC mode and 53203395 Hz for PAL mode). The default value of 7
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
307 matches the real hardware. Set this to a lower number to overclock the 68000
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
308 and set it to a higher number to underclock it.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
309
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
310 "max_cycles" controls how often the system is forced to synchronize all
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
311 hardware. BlastEm generally uses a sync on demand approach to synchronizing
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
312 components in the system. This can provide perfect synchronization for most
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
313 components, but since the Z80 can steal cycles from the 68000 at unpredictable
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
314 times 68000/Z80 synchronization is imperfect. The default value of 3420
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
315 corresponds to the number of master clock cycles per line. Larger numbers may
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
316 produce a modest performance improvement whereas smaller numbers will improve
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
317 68000/Z80 synchronization.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
318
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
319 "speeds" controls the speed of the overall emulated console at different
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
320 presets. Preset 0 is the default speed and should normally be set to 100. The
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
321 other presets enable the slow/turbo mode functionality.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
322
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
323 UI
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
324 --
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
325
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
326 The UI section contains settings that affect the user interface.
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
327
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
328 "rom" determines the path of the Genesis/Megadrive ROM that implements the UI.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
329 Relative paths will be loaded relative to the BlastEm executable.
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
330
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
331 "initial_path" specifies the starting path for the ROM browser. It can contain
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
332 the following special variables: $HOME, $EXEDIR. Additionally, variables
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
333 defined in the OS environment can be used.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
334
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
335 "remember_path" specifies whether BlastEm should remember the last path used in
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
336 the file browser. When it is set to "on", the last path will be remembered and
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
337 used instead of "initial_path" in subsequent runs. If it is set to "off",
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
338 "initial_path" will always be used.
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
339
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
340 "screenshot_path" specifies the directory "internal" screenshots will be saved
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
341 in. It accepts the same special variables as "initial_path".
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
342
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
343 "screenshot_template" specifies a template for creating screenshot filenames.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
344 It is specified as a format string for the C library function strftime
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
345
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
346 "save_path" specifies the directory that savestates, SRAM and EEPROM data will
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
347 be saved in for a given game. It can contain the following special variables:
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
348 $HOME, $EXEDIR, $USERDATA, $ROMNAME. Like "initial_path" it can also reference
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
349 variables from the environment.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
350
1442
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
351 "extensions" specifies the file extensions that should be displayed in the file
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
352 browser.
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
353
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
354 "state_format" specifies the preferred format for saving save states. Valid
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
355 values are "native" (the default) and "gst". "native" save states do a better
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
356 job of preserving the state of the emulated system, but "gst" save states are
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
357 compatible with other emulators like Kega and Gens. This setting has no effect
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
358 for systems other than the Genesis/Mega Drive
59e1dbb795a7 Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents: 1354
diff changeset
359
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
360 Path Variables
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
361 --------------
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
362
1353
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
363 This section explains the meaning of the special path variables referenced
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
364 in the previous section.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
365
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
366 $HOME The home directory of the current user. On most Unix variants, it
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
367 will be a subdirectory of /home. On Windows it will typically be a
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
368 subdirectory of C:\Users
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
369 $EXEDIR The directory the BlastEm executable is located in
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
370 $USERDATA This is an OS-specific path used for storing application specific
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
371 user data. On Unix variants, it will be $HOME/.local/share/blastem
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
372 On Windows it will be %LOCALDATA%/blastem
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
373 $ROMNAME The name of the currently loaded ROM file without the extension
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
374
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
375 System
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
376 ------
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
377
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
378 "ram_init" determines how the RAM in the emulated system is initialized. The
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
379 default value of "zero" will cause all RAM to be zeroed out before the system
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
380 is started. Alternatively, "random" can be used to initialize RAM with values
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
381 from a pseudo-random number generator. This option is mostly useful for
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
382 developers that want to debug initialization issues in their code.
52d9e3c36b4f Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents: 1352
diff changeset
383
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
384 "default_region" determines the console region that will be used when region
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
385 detection fails and when there are multiple valid regions. The default of 'U'
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
386 specifies a 60Hz "foreign" console.
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
387
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
388 "sync_source" controls whether BlastEm uses audio or video output to control
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
389 execution speed. "video" can provide a smoother experience when your display
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
390 has a similar refresh rate to the emulated system, but has some limitations
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
391 in the current version. The default value is "audio".
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
392
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
393 "megawifi" enables or disables support for MegaWiFi cart emulation. MegaWiFi
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
394 is a cartridge that contains WiFi hardware for network functionality. Enabling
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
395 this means that ROMs potentially have access to your network (and the internet)
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
396 which obviously has security implications. For this reason, it is disabled by
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
397 default. If you wish to try out MegaWiFi emulation, set this to "on". Note that
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
398 the support for MegaWiFi hardware is preliminary in this release.
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
399
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
400 Debugger
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
401 --------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
402
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
403 BlastEm has an integrated command-line debugger loosely based on GDB's
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
404 interface. The interface is very rough at the moment. Available commands in the
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
405 68K debugger are:
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
406 b ADDRESS - Set a breakpoint at ADDRESS
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
407 d BREAKPOINT - Delete a 68K breakpoint
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
408 co BREAKPOINT - Run a list of debugger commands each time
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
409 BREAKPOINT is hit
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
410 a ADDRESS - Advance to address
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
411 n - Advance to next instruction
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
412 o - Advance to next instruction ignoring branches to
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
413 lower addresses (good for breaking out of loops)
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
414 s - Advance to next instruction (follows bsr/jsr)
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
415 c - Continue
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
416 bt - Print a backtrace
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
417 p[/(x|X|d|c)] VALUE - Print a register or memory location
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
418 di[/(x|X|d|c)] VALUE - Print a register or memory location each time
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
419 a breakpoint is hit
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
420 vs - Print VDP sprite list
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
421 vr - Print VDP register info
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
422 zb ADDRESS - Set a Z80 breakpoint
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
423 zp[/(x|X|d|c)] VALUE - Display a Z80 value
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
424 q - Quit BlastEm
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
425 Available commands in the Z80 debugger are:
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
426 b ADDRESS - Set a breakpoint at ADDRESS
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
427 de BREAKPOINT - Delete a Z80 breakpoint
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
428 a ADDRESS - Advance to address
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
429 n - Advance to next instruction
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
430 c - Continue
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
431 p[/(x|X|d|c)] VALUE - Print a register or memory location
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
432 di[/(x|X|d|c)] VALUE - Print a register or memory location each time
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
433 a breakpoint is hit
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
434 q - Quit BlastEm
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
435
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
436 The -d flag can be used to cause BlastEm to start in the debugger.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
437 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
438 by default) to enter the debugger while a game is running. To debug the menu
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
439 ROM, use the -dm flag.
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
440
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
441 GDB Remote Debugging
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
442 --------------------
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
443
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
444 In addition to the native debugger, BlastEm can also act as a GDB remote
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
445 debugging stub. To use this, you'll want to configure your Makefile to produce
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
446 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
447 the ELF file. Once inside the gdb session, type:
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
448
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
449 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
450
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
451 where BLASTEM_PATH is the relative or absolute path to your BlastEm
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
452 installation and ROM_FILE.bin is the name of the raw binary for your program.
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
453 BlastEm will halt at the beginning of your program's entry point and return
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
454 control to GDB. This will allow you to set breakpoints before your code runs.
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
455
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
456 On Windows, the procedure is slightly different. First run
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
457 blastem.exe ROM_FILE.bin -D
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
458 This will cause BlastEm to wait for a socket connection on port 1234. It will
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
459 appear to be frozen until gdb connects to it. Now open the ELF file in gdb
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
460 and type:
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
461
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
462 target remote :1234
808
2953708d02af Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents: 785
diff changeset
463
536
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
464 Trace points and watch points are not currently supported.
69cfdc81a87c Update README
Mike Pavone <pavone@retrodev.com>
parents: 468
diff changeset
465
810
1f75614d7be8 Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents: 808
diff changeset
466 Included Tools
1f75614d7be8 Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents: 808
diff changeset
467 --------------
1f75614d7be8 Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents: 808
diff changeset
468
1f75614d7be8 Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents: 808
diff changeset
469 BlastEm ships with a few small utilities that leverage portions of the emulator
1f75614d7be8 Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents: 808
diff changeset
470 code.
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
471
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
472 dis - 68K disassembler
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
473 zdis - Z80 disassembler
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
474 vgmplay - Very basic VGM player
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
475 stateview - GST save state viewer
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
476
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
477 Sync Source and VSync
1013
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
478 -----
f2f983e262e2 WIP README updates
Michael Pavone <pavone@retrodev.com>
parents: 810
diff changeset
479
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
480 This section includes information about using VSync with BlastEm. Currently,
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
481 the best way to use VSync is to set the sync source to "video". This will force
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
482 VSync on and use video output for controlling the speed of emulation. In this
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
483 mode, audio will have it's rate automatically adjusted to keep pace with video.
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
484 The code for this is still a bit immature, so you may experience dropouts or
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
485 pitch changes in this mode.
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
486
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
487 If you experience problems, please switch back to the "audio" sync source,
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
488 which is the default. You can also enable vsync when using the "audio" sync
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
489 source by changing the "vsync" setting. This will generally work okay as long
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
490 as the emulated refresh rate is below your monitor refresh rate (even if only
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
491 slightly), but you will occassionally get a doubled frame (or frequently if
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
492 the refresh rates are very different).
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
493
1662
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
494 Turbo mode will currently not work when vsync is on, regardless of which sync
35c308355bfb Updated README
Mike Pavone <pavone@retrodev.com>
parents: 1661
diff changeset
495 source is used. Slow mode will work with "audio" sync, but not "video" sync.
1014
ef923c4b8977 More README updates
Michael Pavone <pavone@retrodev.com>
parents: 1013
diff changeset
496
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
497 --------------
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
498
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
499 My work has been made much easier by the contributions of those in the Genesis
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
500 community past and present. I'd like to thank the people below for their help.
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
501
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
502 Nemesis - His work reverse engineering and documenting the VDP and
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
503 YM-2612 has saved me an immeasurable amount of time. I've
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
504 found both his sprite overflow test ROM and VDP FIFO
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
505 Testing ROM to be quite helpful.
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
506
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
507 Charles MacDonald - While it hasn't been updated in a while, I still find his
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
508 VDP document to be my favorite reference. His Genesis
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
509 hardware document has also come in handy.
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
510
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
511 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
512 Genesis games and also left some useful very helpful
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
513 comments about problematic games in Genesis Plus GX
1812
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
514
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
515 Sauraen - Sauraen has analyzed the YM2203 and YM2612 dies and written
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
516 a VHDL operator implementation. These have been useful in
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
517 improving the accuracy of my YM2612 core.
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
518
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
519 Alexey Khokholov - Alexey (aka Nuke.YKT) has analyzed the YM3438 die and written
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
520 a fairly direct C implementation from that analysis. This
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
521 has been a useful reference for verifying and improving my
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
522 YM2612 core.
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
523
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
524 Bart Trzynadlowski - His documents on the Genecyst save-state format and the
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
525 mapper used in Super Street Fighter 2 were definitely
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
526 appreciated.
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
527
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
528 KanedaFR - Kaneda's SpritesMind forum is a great resource for the
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
529 Sega development community.
1354
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
530
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
531 Titan - Titan has created what are without a doubt the most
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
532 impressive demos on the Megadrive. Additionally, I am very
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
533 grateful for the documentation provided by Kabuto and the
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
534 assistance of Kabuto, Sik and Jorge in getting Overdrive 2
1661
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
535 to run properly in BlastEm.
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
536
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
537 flamewing - flamewing created a very handy exhaustive test ROM for 68K
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
538 BCD instructions and documented the proper behavior for
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
539 certain BCD edge cases
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
540
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
541 r57shell - r57shell created a test ROM for 68K instruction sizes that
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
542 was invaluable in fixing the remaining bugs in my 68K instruction
c3c3b65f17aa Updated special thanks
Mike Pavone <pavone@retrodev.com>
parents: 1442
diff changeset
543 decoder
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
544
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
545 I'd also like to thank the following people who have performed compatibility
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
546 testing or submitted helpful bug reports
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
547
1354
34798ad9c570 Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents: 1353
diff changeset
548 micky, Sasha, lol-frank, Sik, Tim Lawrence, ComradeOj, Vladikcomper
1066
58e3d50f6a4e Updated README
Michael Pavone <pavone@retrodev.com>
parents: 1017
diff changeset
549
468
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
550 License
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
551 -------
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
552
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
553 BlastEm is free software distributed under the terms of the GNU General Public
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
554 License version 3 or higher. This gives you the right to redistribute and/or
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
555 modify the program as long as you follow the terms of the license. See the file
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
556 COPYING for full license details.
949c7d875693 Added README file
Mike Pavone <pavone@retrodev.com>
parents:
diff changeset
557
1812
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
558 Binary releases of BlastEm are packaged with GLEW, SDL2 and zlib which have their
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
559 own licenses. See GLEW-LICENSE and SDL-LICENSE for details. For zlib license
8aeac7bd9fa7 Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents: 1662
diff changeset
560 information, please see zlib.h in the source code release.