Mercurial > repos > blastem

comparison README @ 2289:92449b47cce8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Integrate VGM player into main blastem binary
author Michael Pavone <pavone@retrodev.com>
date Sat, 04 Feb 2023 22:44:44 -0800
parents 8aeac7bd9fa7
children 62f316b76e9a
comparison
equal deleted inserted replaced
2288:efc75ea79164 2289:92449b47cce8
7 Extract this archive to a directory of your choosing. 7 Extract this archive to a directory of your choosing.
8 8
9 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config 9 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config
10 and save files. If you're upgrading from a previous version on Windows, you will 10 and save files. If you're upgrading from a previous version on Windows, you will
11 need to move them manually. For config files, the relevant paths are in the 11 need to move them manually. For config files, the relevant paths are in the
12 previous paragraph. For save files, move all the directories found in 12 previous paragraph. For save files, move all the directories found in
13 %userprofile%\.local\share\blastem to %localappdata%\blastem 13 %userprofile%\.local\share\blastem to %localappdata%\blastem
14 14
15 Usage 15 Usage
16 ----- 16 -----
17 17
27 27
28 Some operations are currently only supported through the command line. To get a 28 Some operations are currently only supported through the command line. To get a
29 list of supported command line options on Linux or OSX type: 29 list of supported command line options on Linux or OSX type:
30 30
31 ./blastem -h 31 ./blastem -h
32 32
33 From within your BlastEm directory. On Windows type: 33 From within your BlastEm directory. On Windows type:
34 34
35 blastem.exe -h 35 blastem.exe -h
36 36
37 Lock-On Support 37 Lock-On Support
38 --------------- 38 ---------------
39 39
40 This version of BlastEm has some preliminary support for Sonic & Knuckles lock 40 This version of BlastEm has some preliminary support for Sonic & Knuckles lock
41 on technology. This is available via both the menu and the command line. To use 41 on technology. This is available via both the menu and the command line. To use
44 to lock on. The system will then reload with the combined game. To use it from 44 to lock on. The system will then reload with the combined game. To use it from
45 the command line, specify the Sonic & Knuckles ROM as the primary ROM and 45 the command line, specify the Sonic & Knuckles ROM as the primary ROM and
46 specify the ROM to be locked on using the -o option. As an example: 46 specify the ROM to be locked on using the -o option. As an example:
47 47
48 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin 48 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin
49 49
50 Please note that Sonic 2 lock-on does not work at this time. 50 Please note that Sonic 2 lock-on does not work at this time.
51 51
52 Configuration 52 Configuration
53 ------------- 53 -------------
54 54
55 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on 55 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on
56 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists. 56 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists.
57 Othwerise it is read from default.cfg from the same directory as the BlastEm 57 Othwerise it is read from default.cfg from the same directory as the BlastEm
58 executable. Sections are denoted by a section name followed by an open curly 58 executable. Sections are denoted by a section name followed by an open curly
59 bracket, the section's contents and a closing curly bracket. Individual 59 bracket, the section's contents and a closing curly bracket. Individual
60 configuration values are set by entering the value's name followed by a space 60 configuration values are set by entering the value's name followed by a space
61 or tab and followed by the desired value. 61 or tab and followed by the desired value.
62 62
63 Bindings 63 Bindings
105 play 105 play
106 search 106 search
107 back 107 back
108 108
109 The pads subsection is used to map gamepads and joysticks. Gamepads that are 109 The pads subsection is used to map gamepads and joysticks. Gamepads that are
110 recognized, can have their buttons and axes mapped with semantic names. 110 recognized, can have their buttons and axes mapped with semantic names.
111 Xbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be 111 Xbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be
112 mapped using numeric button and axis ids. The following button names are 112 mapped using numeric button and axis ids. The following button names are
113 recognized by BlastEm: 113 recognized by BlastEm:
114 a, cross 114 a, cross
115 b, circle 115 b, circle
116 x, square 116 x, square
127 lefty 127 lefty
128 rightx 128 rightx
129 righty 129 righty
130 lefttrigger, l2 130 lefttrigger, l2
131 righttrigger, r2 131 righttrigger, r2
132 132
133 133
134 The mice subsection is used to map mice to emulated Mega/Sega mice. The default 134 The mice subsection is used to map mice to emulated Mega/Sega mice. The default
135 configuration maps both the first and second host mice to the first emulated 135 configuration maps both the first and second host mice to the first emulated
136 mouse. This should not need modification for most users. 136 mouse. This should not need modification for most users.
137 137
161 ui.exit Returns to the menu ROM if currently in a game 161 ui.exit Returns to the menu ROM if currently in a game
162 that was launched from the menu. Exits otherwise 162 that was launched from the menu. Exits otherwise
163 ui.save_state Saves a savestate to the quicksave slot 163 ui.save_state Saves a savestate to the quicksave slot
164 ui.set_speed.N Selects a specific machine speed specified by N 164 ui.set_speed.N Selects a specific machine speed specified by N
165 which should be a number between 0-9. Speeds are 165 which should be a number between 0-9. Speeds are
166 specified in the "clocks" section of the config 166 specified in the "clocks" section of the config
167 ui.next_speed Selects the next machine speed 167 ui.next_speed Selects the next machine speed
168 ui.prev_speed Selects the previous machine speed 168 ui.prev_speed Selects the previous machine speed
169 ui.toggle_fullscreen Toggles between fullscreen and windowed mode 169 ui.toggle_fullscreen Toggles between fullscreen and windowed mode
170 ui.soft_reset Resets a portion of the emulated machine 170 ui.soft_reset Resets a portion of the emulated machine
171 Equivalent to pushing the reset button on the 171 Equivalent to pushing the reset button on the
174 a hard reset of the emulated device 174 a hard reset of the emulated device
175 ui.sms_pause Triggers a press of the pause button when in SMS 175 ui.sms_pause Triggers a press of the pause button when in SMS
176 mode 176 mode
177 ui.toggle_keyboard_captured Toggles the capture state of the host keyboard 177 ui.toggle_keyboard_captured Toggles the capture state of the host keyboard
178 when an emulated keyboard is present 178 when an emulated keyboard is present
179 179
180 IO 180 IO
181 -- 181 --
182 182
183 This section controls which peripherals are attached to the emulated console. 183 This section controls which peripherals are attached to the emulated console.
184 IO assignments can be overridden by the ROM database when appropriate. For 184 IO assignments can be overridden by the ROM database when appropriate. For
201 left unspecified, it will be calculated from "width" and "aspect". 201 left unspecified, it will be calculated from "width" and "aspect".
202 202
203 "vertex_shader" and "fragment_shader" define the GLSL shader program that 203 "vertex_shader" and "fragment_shader" define the GLSL shader program that
204 produces the final image for each frame. Shaders can be used to add various 204 produces the final image for each frame. Shaders can be used to add various
205 visual effects or enhancements. Currently BlastEm only ships with the default 205 visual effects or enhancements. Currently BlastEm only ships with the default
206 shader and a "subtle" crt shader. If you write your own shaders, place them in 206 shader and a "subtle" crt shader. If you write your own shaders, place them in
207 $HOME/.config/blastem/shaders and then specify the basename of the new shader 207 $HOME/.config/blastem/shaders and then specify the basename of the new shader
208 files in the "vertex_shader" and "fragment_shader" config options. Note that 208 files in the "vertex_shader" and "fragment_shader" config options. Note that
209 shaders are not available in the SDL fallback renderer. 209 shaders are not available in the SDL fallback renderer.
210 210
211 "scanlines" controls whether there is any emulation of the gaps between display 211 "scanlines" controls whether there is any emulation of the gaps between display
332 the following special variables: $HOME, $EXEDIR. Additionally, variables 332 the following special variables: $HOME, $EXEDIR. Additionally, variables
333 defined in the OS environment can be used. 333 defined in the OS environment can be used.
334 334
335 "remember_path" specifies whether BlastEm should remember the last path used in 335 "remember_path" specifies whether BlastEm should remember the last path used in
336 the file browser. When it is set to "on", the last path will be remembered and 336 the file browser. When it is set to "on", the last path will be remembered and
337 used instead of "initial_path" in subsequent runs. If it is set to "off", 337 used instead of "initial_path" in subsequent runs. If it is set to "off",
338 "initial_path" will always be used. 338 "initial_path" will always be used.
339 339
340 "screenshot_path" specifies the directory "internal" screenshots will be saved 340 "screenshot_path" specifies the directory "internal" screenshots will be saved
341 in. It accepts the same special variables as "initial_path". 341 in. It accepts the same special variables as "initial_path".
342 342
362 362
363 This section explains the meaning of the special path variables referenced 363 This section explains the meaning of the special path variables referenced
364 in the previous section. 364 in the previous section.
365 365
366 $HOME The home directory of the current user. On most Unix variants, it 366 $HOME The home directory of the current user. On most Unix variants, it
367 will be a subdirectory of /home. On Windows it will typically be a 367 will be a subdirectory of /home. On Windows it will typically be a
368 subdirectory of C:\Users 368 subdirectory of C:\Users
369 $EXEDIR The directory the BlastEm executable is located in 369 $EXEDIR The directory the BlastEm executable is located in
370 $USERDATA This is an OS-specific path used for storing application specific 370 $USERDATA This is an OS-specific path used for storing application specific
371 user data. On Unix variants, it will be $HOME/.local/share/blastem 371 user data. On Unix variants, it will be $HOME/.local/share/blastem
372 On Windows it will be %LOCALDATA%/blastem 372 On Windows it will be %LOCALDATA%/blastem
451 where BLASTEM_PATH is the relative or absolute path to your BlastEm 451 where BLASTEM_PATH is the relative or absolute path to your BlastEm
452 installation and ROM_FILE.bin is the name of the raw binary for your program. 452 installation and ROM_FILE.bin is the name of the raw binary for your program.
453 BlastEm will halt at the beginning of your program's entry point and return 453 BlastEm will halt at the beginning of your program's entry point and return
454 control to GDB. This will allow you to set breakpoints before your code runs. 454 control to GDB. This will allow you to set breakpoints before your code runs.
455 455
456 On Windows, the procedure is slightly different. First run 456 On Windows, the procedure is slightly different. First run
457 blastem.exe ROM_FILE.bin -D 457 blastem.exe ROM_FILE.bin -D
458 This will cause BlastEm to wait for a socket connection on port 1234. It will 458 This will cause BlastEm to wait for a socket connection on port 1234. It will
459 appear to be frozen until gdb connects to it. Now open the ELF file in gdb 459 appear to be frozen until gdb connects to it. Now open the ELF file in gdb
460 and type: 460 and type:
461 461
466 Included Tools 466 Included Tools
467 -------------- 467 --------------
468 468
469 BlastEm ships with a few small utilities that leverage portions of the emulator 469 BlastEm ships with a few small utilities that leverage portions of the emulator
470 code. 470 code.
471 471
472 dis - 68K disassembler 472 dis - 68K disassembler
473 zdis - Z80 disassembler 473 zdis - Z80 disassembler
474 vgmplay - Very basic VGM player 474
475 stateview - GST save state viewer
476
477 Sync Source and VSync 475 Sync Source and VSync
478 ----- 476 -----
479 477
480 This section includes information about using VSync with BlastEm. Currently, 478 This section includes information about using VSync with BlastEm. Currently,
481 the best way to use VSync is to set the sync source to "video". This will force 479 the best way to use VSync is to set the sync source to "video". This will force
507 Charles MacDonald - While it hasn't been updated in a while, I still find his 505 Charles MacDonald - While it hasn't been updated in a while, I still find his
508 VDP document to be my favorite reference. His Genesis 506 VDP document to be my favorite reference. His Genesis
509 hardware document has also come in handy. 507 hardware document has also come in handy.
510 508
511 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in 509 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in
512 Genesis games and also left some useful very helpful 510 Genesis games and also left some useful very helpful
513 comments about problematic games in Genesis Plus GX 511 comments about problematic games in Genesis Plus GX
514 512
515 Sauraen - Sauraen has analyzed the YM2203 and YM2612 dies and written 513 Sauraen - Sauraen has analyzed the YM2203 and YM2612 dies and written
516 a VHDL operator implementation. These have been useful in 514 a VHDL operator implementation. These have been useful in
517 improving the accuracy of my YM2612 core. 515 improving the accuracy of my YM2612 core.
518 516
519 Alexey Khokholov - Alexey (aka Nuke.YKT) has analyzed the YM3438 die and written 517 Alexey Khokholov - Alexey (aka Nuke.YKT) has analyzed the YM3438 die and written
522 YM2612 core. 520 YM2612 core.
523 521
524 Bart Trzynadlowski - His documents on the Genecyst save-state format and the 522 Bart Trzynadlowski - His documents on the Genecyst save-state format and the
525 mapper used in Super Street Fighter 2 were definitely 523 mapper used in Super Street Fighter 2 were definitely
526 appreciated. 524 appreciated.
527 525
528 KanedaFR - Kaneda's SpritesMind forum is a great resource for the 526 KanedaFR - Kaneda's SpritesMind forum is a great resource for the
529 Sega development community. 527 Sega development community.
530 528
531 Titan - Titan has created what are without a doubt the most 529 Titan - Titan has created what are without a doubt the most
532 impressive demos on the Megadrive. Additionally, I am very 530 impressive demos on the Megadrive. Additionally, I am very
533 grateful for the documentation provided by Kabuto and the 531 grateful for the documentation provided by Kabuto and the
534 assistance of Kabuto, Sik and Jorge in getting Overdrive 2 532 assistance of Kabuto, Sik and Jorge in getting Overdrive 2
535 to run properly in BlastEm. 533 to run properly in BlastEm.
536 534
537 flamewing - flamewing created a very handy exhaustive test ROM for 68K 535 flamewing - flamewing created a very handy exhaustive test ROM for 68K
538 BCD instructions and documented the proper behavior for 536 BCD instructions and documented the proper behavior for
539 certain BCD edge cases 537 certain BCD edge cases
540 538
541 r57shell - r57shell created a test ROM for 68K instruction sizes that 539 r57shell - r57shell created a test ROM for 68K instruction sizes that