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