{"id":19797050,"url":"https://github.com/amatcoder/blastem-gtk","last_synced_at":"2025-05-01T03:31:22.695Z","repository":{"id":86451215,"uuid":"103415386","full_name":"AmatCoder/blastem-gtk","owner":"AmatCoder","description":"A fork of BlastEm (https://www.retrodev.com/blastem/)","archived":false,"fork":false,"pushed_at":"2017-11-19T15:53:12.000Z","size":1657,"stargazers_count":7,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-06T08:26:48.383Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmatCoder.png","metadata":{"files":{"readme":"README","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-13T15:13:06.000Z","updated_at":"2023-04-09T22:04:16.000Z","dependencies_parsed_at":"2023-03-07T01:30:40.575Z","dependency_job_id":null,"html_url":"https://github.com/AmatCoder/blastem-gtk","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmatCoder%2Fblastem-gtk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmatCoder%2Fblastem-gtk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmatCoder%2Fblastem-gtk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmatCoder%2Fblastem-gtk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmatCoder","download_url":"https://codeload.github.com/AmatCoder/blastem-gtk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251818051,"owners_count":21648856,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T07:23:31.759Z","updated_at":"2025-05-01T03:31:22.688Z","avatar_url":"https://github.com/AmatCoder.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"BlastEm 0.5.1\n-------------\n\nInstallation\n------------\n\nExtract this archive to a directory of your choosing. If you wish to change the\nconfiguration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg \nand modify the copy. If you are on Windows, the config file should be placed in\n%localappdata%\\blastem. You may also whish to add the blastem directory to your\nPATH environment variable.\n\nNOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config\nand save files. If you're upgrading from a previous version on Windows, you will\nneed to move them manually. For config files, the relevant paths are in the\nprevious paragraph. For save files, move all the directories found in \n%userprofile%\\.local\\share\\blastem to %localappdata%\\blastem\n\nUsage\n-----\n\nThis version of BlastEm has an experimental GUI that is implemented as a Genesis\nROM running inside the emulator. This UI can be operated with either a mouse or\nthe first emulated gamepad. By default, both the keyboard and the first game\ncontroller are mapped to said gamepad. For more information on bindings see the\nBindings section.\n\nSome operations are currently only supported through the command line. To get a\nlist of supported command line options on Linux or OSX type:\n\n    ./blastem -h\n    \nFrom within your BlastEm directory. On Windows type:\n    \n    blastem.exe -h\n    \nLock-On Support\n---------------\n\nThis version of BlastEm has some preliminary support for Sonic \u0026 Knuckles lock\non technology. This is available via both the menu and the command line. To use\nit from the menu, first load Sonic \u0026 Knuckles normally. Enter the menu (mapped\nto the Escape key by default) and select the \"Lock On\" option to select a ROM\nto lock on. The system will then reload with the combined game. To use it from\nthe command line, specify the Sonic \u0026 Knuckles ROM as the primary ROM and\nspecify the ROM to be locked on using the -o option. As an example:\n\n    ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin\n    \nPlease note that Sonic 2 lock-on does not work at this time.\n\nConfiguration\n-------------\n\nConfiguration is read from the file at $HOME/.config/blastem/blastem.cfg on\nUnix-like systems and %localappdata%\\blastem\\blastem.cfg if it exists.\nOthwerise it is read from default.cfg from the same directory as the BlastEm\nexecutable. Sections are denoted by a section name followed by an open curly \nbracket, the section's contents and a closing curly bracket. Individual\nconfiguration values are set by entering the value's name followed by a space\nor tab and followed by the desired value.\n\nBindings\n--------\n\nThe keys subsection of bindings maps keyboard keys to gamepad buttons or UI\nactions. The key name goes on the left and the action is on the right.\nMost keys are named for the character they produce when pressed. For keys that\ndon't correspond to a normal character, check the list below:\n\n  Name       | Description\n  -----------------\n  up           Up arrow\n  down         Down arrow\n  left         Left arrow\n  right        Right arrow\n  space\n  tab\n  backspace    Backspace on PC keyboards, Delete on Mac keyboards\n  esc\n  delete\n  lshift       Left shift\n  rshift       Right shift\n  lctrl        Left control\n  rctrl        Right control\n  lalt         Left alt on PC keyboards, Option on Mac keyboards\n  ralt         Right alt on PC keyboards, Option on Mac keyboards\n  home\n  end\n  pageup\n  pagedown\n  f1\n  f2\n  f3\n  f4\n  f5\n  f6\n  f7\n  f8\n  f9\n  f10\n  f11\n  f12\n  select\n  play\n  search\n  back\n\nThe pads subsection is used to map gamepads and joysticks. Gamepads that are\nrecognized, can have their buttons and axes mapped with semantic names. \nXbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be \nmapped using numeric button and axis ids. The following button names are\nrecognized by BlastEm:\n\ta, cross\n\tb, circle\n\tx, square\n\ty, trinagle\n\tstart, options\n\tback, select, share\n\tguide\n\tleftbutton, l1\n\trightbutton, r1\n\tleftstick, l3\n\trightstick, r3\nThe following axis names are recognized by BlastEm:\n\tleftx\n\tlefty\n\trightx\n\trighty\n\tlefttrigger, l2\n\trighttrigger, r2\n\t\n\nThe mice subsection is used to map mice to emulated Mega/Sega mice. The default\nconfiguration maps both the first and second host mice to the first emulated\nmouse. This should not need modification for most users.\n\nOne special mapping deserves a mention. By default, the 'r' key is mapped to\nui.release_mouse. When operating in windowed mode the mouse has a capture\nbehavior. Mouse events are ignored until you click in the window. The mouse\nwill then be \"captured\" and the cursor will be both made invisible and locked\nto the window. The ui.release_mouse binding releases the mouse so it can be\nused normally.\n\nUI Actions\n----------\n\nThis section lists the various \"UI\" actions that can be triggered by a key or\ngamepad binding.\n\nui.release_mouse             Releases the mouse if it is currently captured\nui.vdp_debug_mode            Cycles through the various VDP debug views\nui.vdp_debug_pal             Cycles through the selected palette when viewing\n                             the VDP memory viewer\nui.enter_debugger            Enters the debugger for the main CPU of the\n\t\t\t\t\t\t\t currently emulated system\nui.screenshot                Takes an internal screenshot\nui.exit                      Returns to the menu ROM if currently in a game\n                             that was launched from the menu. Exits otherwise\nui.save_state                Saves a savestate to the quicksave slot\nui.set_speed.N               Selects a specific machine speed specified by N\n                             which should be a number between 0-9. Speeds are\n                             specified in the \"clocks\" section of the config\t\t\t\t\nui.next_speed                Selects the next machine speed\nui.prev_speed                Selects the previous machine speed\nui.toggle_fullscreen         Toggles between fullscreen and windowed mode\nui.soft_reset                Resets a portion of the emulated machine\n                             Equivalent to pushing the reset button on the\n                             emulated device\nui.reload                    Reloads the current ROM from a file and performs\n                             a hard reset of the emulated device\nui.sms_pause                 Triggers a press of the pause button when in SMS\n                             mode\nui.toggle_keyboard_captured  Toggles the capture state of the host keyboard\n                             when an emulated keyboard is present\n\t\t\nIO\n--\n\nThis section controls which peripherals are attached to the emulated console.\nIO assignments can be overridden by the ROM database when appropriate. For\ninstance, games with mouse support can automatically use the mouse and games\nthat only support 3-button pads can automatically force an appropriate pad.\nUnforunately, the ROM database is not yet exhaustive so manual configuration\nmay be needed here in some cases.\n\nVideo\n-----\n\nThe video section contains settings that affect the visual output of BlastEm.\n\n\"aspect\" is used to control the aspect ratio of the emulated display. The\ndefault of 4:3 matches that of a standard definition television.\n\n\"width\" is used to control the window width when not in fullscreen mode.\n\n\"height\" is used to control the window height when not in fullscreen mode. If\nleft unspecified, it will be calculated from \"width\" and \"aspect\".\n\n\"vertex_shader\" and \"fragment_shader\" define the GLSL shader program that\nproduces the final image for each frame. Shaders can be used to add various\nvisual effects or enhancements. Currently BlastEm only ships with the default\nshader and a \"subtle\" crt shader. If you write your own shaders, place them in \n$HOME/.config/blastem/shaders and then specify the basename of the new shader\nfiles in the \"vertex_shader\" and \"fragment_shader\" config options. Note that\nshaders are not available in the SDL fallback renderer.\n\n\"scanlines\" controls whether there is any emulation of the gaps between display\nlines that are present when driving a CRT television with a 240p signal. This\nemulation is very basic at the moment so this option is off by default.\n\n\"vsync\" controls whether the drawing of frames is synchronized to the monitor\nrefresh rate. Valid values for this setting are \"off\", \"on\" and \"tear\". The\nlatter will attempt to use the \"late tear\" option if it's available and normal\nvsync otherwise. Currently it's recommended to leave this at the default of\n\"off\" as BlastEm synchronizes to audio and does not yet have the necessary code\nto fully handle conflicts between the audio rate and monitor refresh rate.\nAdditionally, the \"turbo\" feature does not function properly with vsync\nenabled. These issues will be addressed in a future release. If you wish to use\nvsync, please see the VSync section at the bottom of the README.\n\n\"fullscreen\" controls whether BlastEm starts in fullscreen or windowed mode.\nThis can be overridden on the command line with the -f flag. If fullscreen\nis set to \"off\", -f will turn it on. Conversely, if fullscreen is set to \"on\"\nin the config, -f will turn it off.\n\n\"gl\" controls whether OpenGL is used for rendering. The default value is on.\nIf it is set to off instead, the fallback renderer which uses SDL2's render API\nwill be used instead. This option is mostly useful for users on hardware that\nlacks OpenGL 2 support. While BlastEm will fall back automatically even if gl\nis set to on there will be a warning. Disabling gl eliminates this warning.\n\n\"scaling\" controls the type of scaling used for textures in both the GL and\nSDL renderers. Valid values are \"nearest\" and \"linear\". Note that shaders also\nimpact how pixels are scaled.\n\nThe \"ntsc\" and \"pal\" sub-sections control overscan settings for the emulated\nvideo output for NTSC and PAL consoles respectively. More details are available\nin the Overscan section.\n\nOverscan\n--------\n\nAnalog televisions generally don't display the entirety of a video frame. Some\nportion is cropped at the edges of the display. This is called overscan.\nUnfortunately, the amount of cropping performed varies considerably and is even\nadjustable on many TV sets. To deal with this, BlastEm allows overscan to be\ncustomized.\n\nOverscan values are specified in the \"ntsc\" and \"pal\" sub-sections of the\n\"video\" section of the config file. The \"overscan\" sub-section contains four\nsettings for specifying the number of pixels cropped on each side of the\ndisplay: \"top\", \"bottom\", \"left\" and \"right\".\n\nThe default settings hide the horizontal border completely for both NTSC and\nPAL consoles. For the vertical borders, the NTSC overscan settings are chosen\nto give square pixels with the default aspect ratio of 4:3. For PAL, the\ndefault settings are set so that the PAL-exclusive V30 mode will produce a\nvisible border that is the same size as what is shown in V28 mode in NTSC. This\nresults in a slightly squished picture compared to NTSC which is probably\nappropriate given that a PAL display has more lines than an NTSC one.\n\nAudio\n-----\n\nThe audio section contains settings that affect the audio output of BlastEm.\n\n\"rate\" selects the preferred sample rate for audio output. Your operating\nsystem may not accept this value in which case a different rate will be chosen.\nThis should generally be either the native sample rate of your sound card or an\nintegral divisor of it. Most modern sound cards have a native output rate that\nis a multiple of 48000 Hz so the default setting should work well for most users.\n\n\"buffer size\" controls how large of a buffer uses for audio data. Smaller values\nwill reduce latency, but too small of a value can lead to dropouts. 512 works\nwell for me, but a higher or lower value may be more appropriate for your system.\n\n\"lowpass_cutoff\" controls the cutoff, or knee, frequency of the RC-style\nlow-pass filter. The default value of 3390 Hz is supposedly what is present in\nat least some Genesis/Megadrive models. Other models reportedly use an even\nlower value.\n\nClocks\n------\n\nThe clocks section contains settings that affect how fast things run.\n\n\"m68k_divider\" describes the relationsip between the master clock (which is\n53693175 Hz for NTSC mode and 53203395 Hz for PAL mode). The default value of 7\nmatches the real hardware. Set this to a lower number to overclock the 68000\nand set it to a higher number to underclock it.\n\n\"max_cycles\" controls how often the system is forced to synchronize all\nhardware. BlastEm generally uses a sync on demand approach to synchronizing\ncomponents in the system. This can provide perfect synchronization for most\ncomponents, but since the Z80 can steal cycles from the 68000 at unpredictable\ntimes 68000/Z80 synchronization is imperfect. The default value of 3420\ncorresponds to the number of master clock cycles per line. Larger numbers may\nproduce a modest performance improvement whereas smaller numbers will improve\n68000/Z80 synchronization.\n\n\"speeds\" controls the speed of the overall emulated console at different\npresets. Preset 0 is the default speed and should normally be set to 100. The\nother presets enable the slow/turbo mode functionality.\n\nUI\n--\n\nThe UI section contains settings that affect the user interface.\n\n\"rom\" determines the path of the Genesis/Megadrive ROM that implements the UI.\nRelative paths will be loaded relative to the BlastEm executable.\n\n\"initial_path\" specifies the starting path for the ROM browser. It can contain\nthe following special variables: $HOME, $EXEDIR. Additionally, variables\ndefined in the OS environment can be used.\n\n\"remember_path\" specifies whether BlastEm should remember the last path used in\nthe file browser. When it is set to \"on\", the last path will be remembered and\nused instead of \"initial_path\" in subsequent runs. If it is set to \"off\", \n\"initial_path\" will always be used.\n\n\"screenshot_path\" specifies the directory \"internal\" screenshots will be saved\nin. It accepts the same special variables as \"initial_path\".\n\n\"screenshot_template\" specifies a template for creating screenshot filenames.\nIt is specified as a format string for the C library function strftime\n\n\"save_path\" specifies the directory that savestates, SRAM and EEPROM data will\nbe saved in for a given game. It can contain the following special variables:\n$HOME, $EXEDIR, $USERDATA, $ROMNAME. Like \"initial_path\" it can also reference\nvariables from the environment.\n\n\"extensions\" specifies the file extensions that should be displayed in the file\nbrowser.\n\n\"state_format\" specifies the preferred format for saving save states. Valid\nvalues are \"native\" (the default) and \"gst\". \"native\" save states do a better\njob of preserving the state of the emulated system, but \"gst\" save states are\ncompatible with other emulators like Kega and Gens. This setting has no effect\nfor systems other than the Genesis/Mega Drive\n\nPath Variables\n--------------\n\nThis section explains the meaning of the special path variables referenced\nin the previous section.\n\n$HOME      The home directory of the current user. On most Unix variants, it\n           will be a subdirectory of /home. On Windows it will typically be a \n           subdirectory of C:\\Users\n$EXEDIR    The directory the BlastEm executable is located in\n$USERDATA  This is an OS-specific path used for storing application specific\n           user data. On Unix variants, it will be  $HOME/.local/share/blastem\n           On Windows it will be %LOCALDATA%/blastem\n$ROMNAME   The name of the currently loaded ROM file without the extension\n\nSystem\n------\n\n\"ram_init\" determines how the RAM in the emulated system is initialized. The\ndefault value of \"zero\" will cause all RAM to be zeroed out before the system\nis started. Alternatively, \"random\" can be used to initialize RAM with values\nfrom a pseudo-random number generator. This option is mostly useful for\ndevelopers that want to debug initialization issues in their code.\n\n\"default_region\" determines the console region that will be used when region\ndetection fails and when there are multiple valid regions. The default of 'U'\nspecifies a 60Hz \"foreign\" console. \n\nDebugger\n--------\n\nBlastEm has an integrated command-line debugger loosely based on GDB's\ninterface. The interface is very rough at the moment. Available commands in the\n68K debugger are:\n    b ADDRESS            - Set a breakpoint at ADDRESS\n    d BREAKPOINT         - Delete a 68K breakpoint\n    co BREAKPOINT        - Run a list of debugger commands each time\n                           BREAKPOINT is hit\n    a ADDRESS            - Advance to address\n    n                    - Advance to next instruction\n    o                    - Advance to next instruction ignoring branches to\n                           lower addresses (good for breaking out of loops)\n    s                    - Advance to next instruction (follows bsr/jsr)\n    c                    - Continue\n    bt                   - Print a backtrace\n    p[/(x|X|d|c)] VALUE  - Print a register or memory location\n    di[/(x|X|d|c)] VALUE - Print a register or memory location each time\n                           a breakpoint is hit\n    vs                   - Print VDP sprite list\n    vr                   - Print VDP register info\n    zb ADDRESS           - Set a Z80 breakpoint\n    zp[/(x|X|d|c)] VALUE - Display a Z80 value\n    q                    - Quit BlastEm\nAvailable commands in the Z80 debugger are:\n    b  ADDRESS           - Set a breakpoint at ADDRESS\n    de BREAKPOINT        - Delete a Z80 breakpoint\n    a  ADDRESS           - Advance to address\n    n                    - Advance to next instruction\n    c                    - Continue\n    p[/(x|X|d|c)] VALUE  - Print a register or memory location\n    di[/(x|X|d|c)] VALUE - Print a register or memory location each time\n                           a breakpoint is hit\n    q                    - Quit BlastEm\n\nThe -d flag can be used to cause BlastEm to start in the debugger.\nAlternatively, you can use the ui.enter_debugger action (mapped to the 'u' key\nby default) to enter the debugger while a game is running. To debug the menu\nROM, use the -dm flag.\n\nGDB Remote Debugging\n--------------------\n\nIn addition to the native debugger, BlastEm can also act as a GDB remote\ndebugging stub. To use this, you'll want to configure your Makefile to produce\nboth an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with\nthe ELF file. Once inside the gdb session, type:\n\n    target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D\n\nwhere BLASTEM_PATH is the relative or absolute path to your BlastEm\ninstallation and ROM_FILE.bin is the name of the raw binary for your program.\nBlastEm will halt at the beginning of your program's entry point and return\ncontrol to GDB. This will allow you to set breakpoints before your code runs.\n\nOn Windows, the procedure is slightly different. First run \n    blastem.exe ROM_FILE.bin -D\nThis will cause BlastEm to wait for a socket connection on port 1234. It will\nappear to be frozen until gdb connects to it. Now open the ELF file in gdb\nand type:\n\n    target remote :1234\n\nTrace points and watch points are not currently supported.\n\nIncluded Tools\n--------------\n\nBlastEm ships with a few small utilities that leverage portions of the emulator\ncode.\n    \n    dis       - 68K disassembler\n    zdis      - Z80 disassembler\n    vgmplay   - Very basic VGM player\n    stateview - GST save state viewer\n    \nVSync\n-----\n\nThis section includes information about using VSync with BlastEm. As mentioned\nabove, the code is currently designed to only sync to audio and has some issues\nwith VSync as a result. That said, if your computer is fast enough and you\ndon't care about turbo mode, it can generally made to work.\n\nThe native refresh rate of an NTSC Genesis is approximately 59.92 Hz which is\nprobably not the native refresh rate of your monitor. Fortunately, it is\nmost likely lower than your refresh rate. As long as this is true, VSync will\ngenerally work as long as your computer is fast enough to cope with the time\nlost waiting for VSync and the audio buffer is large enough to not run out of\nsamples during that delay. Latency will suffer a bit and you'll get a doubled\nframe every once and a while, but generally things will be fine.\n\nIf you enable VSync and you're getting audio dropouts, first try doubling the\naudio buffer setting. If you still experience dropouts, it's possible your\ncomputer is not fast enough or that your monitor's actual refresh rate is in\nfact lower than that of the emualted console. Not much can be done about the\nformer (apart from disabling VSync), but the latter can be dealt with by\nlowering the default speed slightly in the \"clocks\" section.\n\nA future release will support VSync in a less hacky fashion.\n\nSpecial Thanks\n--------------\n\nMy work has been made much easier by the contributions of those in the Genesis\ncommunity past and present. I'd like to thank the people below for their help.\n\nNemesis            - His work reverse engineering and documenting the VDP and\n                     YM-2612 has saved me an immeasurable amount of time. I've\n                     found both his sprite overflow test ROM and VDP FIFO\n                     Testing ROM to be quite helpful.\n\nCharles MacDonald  - While it hasn't been updated in a while, I still find his\n                     VDP document to be my favorite reference. His Genesis\n                     hardware document has also come in handy.\n\nEke-Eke            - Eke-Eke wrote a great document on the use of I2C EEPROM in\n                     Genesis games and also left some useful very helpful \n                     comments about problematic games in Genesis Plus GX\n\nBart Trzynadlowski - His documents on the Genecyst save-state format and the\n                     mapper used in Super Street Fighter 2 were definitely\n                     appreciated.\n                     \nKanedaFR           - Kaneda's SpritesMind forum is a great resource for the\n                     Sega development community.\n\t\t\t\t\t \nTitan              - Titan has created what are without a doubt the most\n                     impressive demos on the Megadrive. Additionally, I am very\n                     grateful for the documentation provided by Kabuto and the\n                     assistance of Kabuto, Sik and Jorge in getting Overdrive 2\n                     to run properly in BlastEm.\t\t\t\t\t \n\nI'd also like to thank the following people who have performed compatibility\ntesting or submitted helpful bug reports\n\nmicky, Sasha, lol-frank, Sik, Tim Lawrence, ComradeOj, Vladikcomper\n\nLicense\n-------\n\nBlastEm is free software distributed under the terms of the GNU General Public\nLicense version 3 or higher. This gives you the right to redistribute and/or\nmodify the program as long as you follow the terms of the license. See the file\nCOPYING for full license details.\n\nBinary releases of BlastEm are packaged with GLEW and SDL2 which have thier own\nlicenses. See GLEW-LICENSE and SDL-LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famatcoder%2Fblastem-gtk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famatcoder%2Fblastem-gtk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famatcoder%2Fblastem-gtk/lists"}